genai

Documentation

Index

• Constants
• Variables
• type ChatService
• type Client
  • func NewClient(opts ...Option) (*Client, error)
  • func (c *Client) GeneratePrompt(system, user string) (string, error)
  • func (c *Client) GeneratePromptWithContext(ctx context.Context, system, user string) (string, error)
  • func (c *Client) GenerateThinkingWithMessages(ctx context.Context, messages []openai.ChatCompletionMessageParamUnion) (*ThinkingResponse, error)
  • func (c *Client) GenerateThinkingWithTools(ctx context.Context, messages []openai.ChatCompletionMessageParamUnion, ...) (*ThinkingToolCallResponse, error)
  • func (c *Client) GenerateWithMessages(ctx context.Context, messages []openai.ChatCompletionMessageParamUnion) (string, error)
  • func (c *Client) GenerateWithTools(ctx context.Context, messages []openai.ChatCompletionMessageParamUnion, ...) (*ToolCallResponse, error)
• type ClientInterface
• type FunctionCall
• type Option
  • func WithAPIKey(key string) Option
  • func WithDebugMode(enabled bool) Option
  • func WithMaxCompletionTokens(tokens int) Option
  • func WithMaxTokens(tokens int) Option
  • func WithModel(model string) Option
  • func WithStateDir(stateDir string) Option
  • func WithTemperature(temp float64) Option
• type Opts
• type ThinkingResponse
• type ThinkingToolCallResponse
• type ToolCall
• type ToolCallResponse

Constants

const (
	// DefaultTemperature is the default temperature setting for chat completions
	DefaultTemperature = 0.1
	// DefaultMaxCompletionTokens is the default maximum completion tokens for chat completions
	DefaultMaxCompletionTokens = 1000
)

Default configuration constants

Variables

var (
	ErrAPIKeyNotSet      = fmt.Errorf("API key not set")
	ErrNoChoicesReturned = fmt.Errorf("no choices returned from OpenAI API")
)

Error variables for better error handling

var DefaultModel = string(openai.ChatModelGPT4oMini)

DefaultModel is the default OpenAI model used for chat completions It's a variable so callers (e.g., main) can override the default globally.

Types

type ChatService

type ChatService interface {
	Create(ctx context.Context, body openai.ChatCompletionNewParams) (openai.ChatCompletion, error)
}

ChatService defines minimal interface for chat completions. Interface names should be descriptive and use proper Go naming conventions.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client wraps the OpenAI API client for prompt generation.

func NewClient

func NewClient(opts ...Option) (*Client, error)

NewClient initializes a new GenAI client using the provided options.

func (*Client) GeneratePrompt

func (c *Client) GeneratePrompt(system, user string) (string, error)

GeneratePrompt generates content based on provided system and user prompts. It uses the provided context for cancellation and timeout handling.

func (*Client) GeneratePromptWithContext

func (c *Client) GeneratePromptWithContext(ctx context.Context, system, user string) (string, error)

GeneratePromptWithContext generates content based on provided system and user prompts with context.

func (*Client) GenerateThinkingWithMessages

func (c *Client) GenerateThinkingWithMessages(ctx context.Context, messages []openai.ChatCompletionMessageParamUnion) (*ThinkingResponse, error)

GenerateThinkingWithMessages requests a structured response (thinking + content) from the model. This is implemented using an in-band JSON pattern until native structured outputs are available in the SDK for arbitrary schemas. The last user/system message context is appended with lightweight instructions that the assistant MUST respond ONLY with a compact JSON object {"thinking": "...", "content": "..."}. The returned Thinking segment is intended strictly for debug mode display and should not be sent to end users unless explicitly enabled.

func (*Client) GenerateThinkingWithTools

func (c *Client) GenerateThinkingWithTools(ctx context.Context, messages []openai.ChatCompletionMessageParamUnion, tools []openai.ChatCompletionToolParam) (*ThinkingToolCallResponse, error)

GenerateThinkingWithTools performs a chat completion with tools while asking the model to wrap its assistant message content in JSON {"thinking":"...","content":"..."}. This allows us to surface internal reasoning in debug mode while still leveraging native tool call outputs.

func (*Client) GenerateWithMessages

func (c *Client) GenerateWithMessages(ctx context.Context, messages []openai.ChatCompletionMessageParamUnion) (string, error)

GenerateWithMessages generates content using OpenAI's native multi-message format. This method supports full conversation history with proper role separation.

func (*Client) GenerateWithTools

func (c *Client) GenerateWithTools(ctx context.Context, messages []openai.ChatCompletionMessageParamUnion, tools []openai.ChatCompletionToolParam) (*ToolCallResponse, error)

GenerateWithTools generates content with the ability to call tools/functions. Returns either a text response or tool calls that need to be executed.

type ClientInterface

type ClientInterface interface {
	GeneratePrompt(system, user string) (string, error)
	GeneratePromptWithContext(ctx context.Context, system, user string) (string, error)
	GenerateWithMessages(ctx context.Context, messages []openai.ChatCompletionMessageParamUnion) (string, error)
	GenerateWithTools(ctx context.Context, messages []openai.ChatCompletionMessageParamUnion, tools []openai.ChatCompletionToolParam) (*ToolCallResponse, error)
	// GenerateThinkingWithMessages returns a structured response containing an internal "thinking" field
	// (model reasoning / chain-of-thought style summary) and a user-facing content field. The model
	// is prompted to emit JSON with keys: thinking, content. If parsing fails, the raw content is
	// returned as Content and Thinking is empty. Implementations should never error purely due to
	// JSON parse failure; they only error on transport/service issues.
	GenerateThinkingWithMessages(ctx context.Context, messages []openai.ChatCompletionMessageParamUnion) (*ThinkingResponse, error)
	// GenerateThinkingWithTools combines tool calling with structured thinking/content response.
	// The assistant is instructed to always place a JSON object {"thinking":"...","content":"..."}
	// in its message content even when issuing tool calls. Tool calls are returned separately via
	// OpenAI's tool call mechanism. RawContent preserves the exact content string (JSON) for
	// conversation continuity, while Content is the parsed user-facing portion.
	GenerateThinkingWithTools(ctx context.Context, messages []openai.ChatCompletionMessageParamUnion, tools []openai.ChatCompletionToolParam) (*ThinkingToolCallResponse, error)
}

ClientInterface defines the interface for GenAI clients to improve testability.

type FunctionCall

type FunctionCall struct {
	Name      string          `json:"name"`
	Arguments json.RawMessage `json:"arguments"`
}

FunctionCall represents a function call with name and arguments.

type Option

type Option func(*Opts)

Option defines a configuration option for the GenAI client.

func WithAPIKey

func WithAPIKey(key string) Option

WithAPIKey overrides the API key used by the GenAI client.

func WithDebugMode

func WithDebugMode(enabled bool) Option

WithDebugMode enables debug mode for API call logging.

func WithMaxCompletionTokens

func WithMaxCompletionTokens(tokens int) Option

WithMaxCompletionTokens overrides the max completion tokens used by the GenAI client.

func WithMaxTokens

func WithMaxTokens(tokens int) Option

WithMaxTokens overrides the max completion tokens (deprecated name kept for compatibility).

func WithModel

func WithModel(model string) Option

WithModel overrides the model used by the GenAI client.

func WithStateDir

func WithStateDir(stateDir string) Option

WithStateDir sets the state directory for debug log files.

func WithTemperature

func WithTemperature(temp float64) Option

WithTemperature overrides the temperature used by the GenAI client.

type Opts

type Opts struct {
	APIKey              string  // overrides OPENAI_API_KEY
	Model               string  // overrides default model
	Temperature         float64 // overrides default temperature
	MaxCompletionTokens int     // overrides default max completion tokens
	// Deprecated: MaxTokens kept for backward compatibility; use MaxCompletionTokens
	MaxTokens int
	DebugMode bool   // Enable debug mode for API call logging
	StateDir  string // State directory for debug log files
}

Opts holds configuration options for the GenAI client, including API key override. API key can be overridden via command-line options or environment variable.

type ThinkingResponse

type ThinkingResponse struct {
	Thinking string `json:"thinking"`
	Content  string `json:"content"`
}

ThinkingResponse represents a structured response separating model reasoning from user-facing content.

type ThinkingToolCallResponse

type ThinkingToolCallResponse struct {
	Thinking   string     `json:"thinking"`
	Content    string     `json:"content"`
	RawContent string     `json:"raw_content"`
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
}

ThinkingToolCallResponse is like ToolCallResponse but includes model thinking and raw content.

type ToolCall

type ToolCall struct {
	ID       string       `json:"id"`
	Type     string       `json:"type"`
	Function FunctionCall `json:"function"`
}

ToolCall represents a tool/function call made by the LLM.

type ToolCallResponse

type ToolCallResponse struct {
	Content   string     `json:"content"`
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`
}

ToolCallResponse represents a response that may contain tool calls.