Documentation
¶
Overview ¶
Package gokamy provides an SDK for interfacing with OpenAI's API, offering agents that process inputs, manage tool execution, and maintain memory.
Index ¶
- Constants
- func GenerateRawSchema(v any) (json.RawMessage, error)
- type Agent
- type AgentBuilder
- func (b *AgentBuilder) AddTool(tool Tool) *AgentBuilder
- func (b *AgentBuilder) Build() (*BaseAgent, error)
- func (b *AgentBuilder) SetClient(client LLMClient) *AgentBuilder
- func (b *AgentBuilder) SetConfigPrompt(prompt string) *AgentBuilder
- func (b *AgentBuilder) SetJSONResponseFormat(schemaName string, structSchema any) *AgentBuilder
- func (b *AgentBuilder) SetMemory(memory Memory) *AgentBuilder
- func (b *AgentBuilder) SetModel(model string) *AgentBuilder
- func (b *AgentBuilder) SetName(name string) *AgentBuilder
- func (b *AgentBuilder) SetTemperature(temperature float32) *AgentBuilder
- type BaseAgent
- type ChatCompletionRequest
- type ChatCompletionResponse
- type Choice
- type DataType
- type DeepseekR1Client
- type Definition
- type Embedder
- type EmbedderBuilder
- type JSONSchema
- type LLMClient
- type Memory
- type Message
- type OpenAIClient
- type Orchestrator
- type OrchestratorBuilder
- type PromptBuilder
- func (pb *PromptBuilder) AddListItem(sectionName, item string) *PromptBuilder
- func (pb *PromptBuilder) AddListItemF(sectionName string, value interface{}) *PromptBuilder
- func (pb *PromptBuilder) AddSubSection(childName, parentName string) *PromptBuilder
- func (pb *PromptBuilder) AddText(sectionName, text string) *PromptBuilder
- func (pb *PromptBuilder) AddTextF(sectionName string, value interface{}) *PromptBuilder
- func (pb *PromptBuilder) Build() string
- func (pb *PromptBuilder) CreateSection(name string) *PromptBuilder
- type ResponseFormat
- type Section
- type SimpleMemory
- type Tool
- type ToolCall
- type ToolDefinition
- type Usage
Constants ¶
const ( RoleSystem = "system" RoleDeveloper = "developer" RoleUser = "user" RoleAssistant = "assistant" RoleTool = "tool" )
Role constants define standard message roles across different providers
const ( FinishReasonStop = "stop" FinishReasonLength = "length" FinishReasonToolCalls = "tool_calls" )
FinishReason constants define standard reasons for completion.
Variables ¶
This section is empty.
Functions ¶
func GenerateRawSchema ¶ added in v1.1.0
func GenerateRawSchema(v any) (json.RawMessage, error)
GenerateRawSchema wraps GenerateSchema and returns the JSON marshalled schema.
Types ¶
type Agent ¶
type Agent interface { Process(ctx context.Context, userName string, input string, additionalMessages ...[]Message) (string, error) AddTool(tool Tool) SetConfigPrompt(prompt string) GetName() string }
Agent defines the interface for processing inputs and managing tools. Implementations of Agent should support processing messages, adding tools, configuring prompts, and providing a name identifier.
type AgentBuilder ¶
type AgentBuilder struct {
// contains filtered or unexported fields
}
AgentBuilder provides a fluent, modular way to configure and construct an Agent.
func NewAgentBuilder ¶
func NewAgentBuilder() *AgentBuilder
NewAgentBuilder initializes and returns a new instance of AgentBuilder.
func (*AgentBuilder) AddTool ¶
func (b *AgentBuilder) AddTool(tool Tool) *AgentBuilder
AddTool adds a tool to the agent's configuration, making it available during processing.
func (*AgentBuilder) Build ¶
func (b *AgentBuilder) Build() (*BaseAgent, error)
Build constructs and returns an Agent based on the current configuration. It returns an error if any issues occurred during the builder setup.
func (*AgentBuilder) SetClient ¶
func (b *AgentBuilder) SetClient(client LLMClient) *AgentBuilder
SetClient sets the LLMClient to be used by the agent.
func (*AgentBuilder) SetConfigPrompt ¶ added in v0.3.0
func (b *AgentBuilder) SetConfigPrompt(prompt string) *AgentBuilder
SetConfigPrompt sets the system prompt that configures the agent's behavior.
func (*AgentBuilder) SetJSONResponseFormat ¶
func (b *AgentBuilder) SetJSONResponseFormat(schemaName string, structSchema any) *AgentBuilder
SetJSONResponseFormat configures the agent to use a JSON schema for response formatting, generating the schema from a provided sample type.
func (*AgentBuilder) SetMemory ¶
func (b *AgentBuilder) SetMemory(memory Memory) *AgentBuilder
SetMemory sets the memory implementation for the agent.
func (*AgentBuilder) SetModel ¶
func (b *AgentBuilder) SetModel(model string) *AgentBuilder
SetModel configures the model to be used by the agent.
func (*AgentBuilder) SetName ¶
func (b *AgentBuilder) SetName(name string) *AgentBuilder
SetName sets the name identifier for the agent.
func (*AgentBuilder) SetTemperature ¶
func (b *AgentBuilder) SetTemperature(temperature float32) *AgentBuilder
SetTemperature sets the temperature parameter for the agent's responses.
type BaseAgent ¶
type BaseAgent struct {
// contains filtered or unexported fields
}
BaseAgent holds the common implementation of the Agent interface, including the OpenAI client, system prompt, tools, memory, model configuration, and concurrency control.
func (*BaseAgent) Process ¶
func (b *BaseAgent) Process(ctx context.Context, userName, input string, additionalMessages ...[]Message) (string, error)
Process takes the user input along with optional additional messages, adds the initial user message to memory, and initiates processing with available tools.
func (*BaseAgent) SetConfigPrompt ¶ added in v0.3.0
SetConfigPrompt sets the system prompt for the agent, which can be used to configure behavior.
type ChatCompletionRequest ¶ added in v1.0.0
type ChatCompletionRequest struct { Model string // The model identifier to use (e.g. "gpt-4"). Messages []Message // Conversational messages. Tools []ToolDefinition // Optional tools available to the agent. Temperature float32 // Sampling temperature. ResponseFormat *ResponseFormat // Optional format for the response. }
ChatCompletionRequest represents a unified chat completion request.
type ChatCompletionResponse ¶ added in v1.0.0
type ChatCompletionResponse struct { Choices []Choice // One or more response choices. Usage Usage // Token usage statistics. }
ChatCompletionResponse represents a unified response structure from the LLM.
type Choice ¶ added in v1.0.0
type Choice struct { Message Message // The message produced by the LLM. FinishReason string // Reason why generation stopped (e.g. "stop", "length"). }
Choice represents a single completion option.
type DeepseekR1Client ¶ added in v1.0.0
type DeepseekR1Client struct {
// contains filtered or unexported fields
}
DeepseekR1Client implementa LLMClient usando el SDK de DeepseekR1.
func (*DeepseekR1Client) CreateChatCompletion ¶ added in v1.0.0
func (d *DeepseekR1Client) CreateChatCompletion(ctx context.Context, req ChatCompletionRequest) (ChatCompletionResponse, error)
CreateChatCompletion envía la solicitud de chat a DeepseekR1. Se ignoran tools y ResponseFormat, ya que DeepseekR1 no los soporta.
type Definition ¶
type Definition struct { Type DataType `json:"type,omitempty"` Description string `json:"description,omitempty"` Enum []string `json:"enum,omitempty"` Properties map[string]Definition `json:"properties,omitempty"` Required []string `json:"required,omitempty"` Items *Definition `json:"items,omitempty"` AdditionalProperties any `json:"additionalProperties,omitempty"` }
Definition is a struct for describing a JSON Schema. It includes type, description, enumeration values, properties, required fields, and additional items.
func (*Definition) MarshalJSON ¶
func (d *Definition) MarshalJSON() ([]byte, error)
MarshalJSON provides custom JSON marshalling for the Definition type. It ensures that the Properties map is initialized before marshalling.
type Embedder ¶
type Embedder struct {
// contains filtered or unexported fields
}
Embedder is responsible for generating embeddings using the OpenAI API.
func (*Embedder) GenerateEmbedding ¶
func (e *Embedder) GenerateEmbedding(ctx context.Context, data string, model ...openai.EmbeddingModel) ([]float32, error)
GenerateEmbedding generates an embedding for the provided data string. It accepts an optional embedding model; if provided, that model overrides the default. Returns a slice of float32 representing the embedding vector or an error if any.
type EmbedderBuilder ¶
type EmbedderBuilder struct {
// contains filtered or unexported fields
}
EmbedderBuilder provides a fluent API to configure and build an Embedder instance.
func NewEmbedderBuilder ¶
func NewEmbedderBuilder() *EmbedderBuilder
NewEmbedderBuilder initializes a new EmbedderBuilder with default settings.
func (*EmbedderBuilder) Build ¶
func (b *EmbedderBuilder) Build() (*Embedder, error)
Build constructs the Embedder instance based on the current configuration. Returns an error if the required OpenAI client is not configured.
func (*EmbedderBuilder) SetClient ¶
func (b *EmbedderBuilder) SetClient(client *openai.Client) *EmbedderBuilder
SetClient configures the OpenAI client for the Embedder.
func (*EmbedderBuilder) SetModel ¶
func (b *EmbedderBuilder) SetModel(model openai.EmbeddingModel) *EmbedderBuilder
SetModel configures the embedding model to be used by the Embedder.
type JSONSchema ¶ added in v1.0.0
type JSONSchema struct { Name string Schema json.RawMessage // The raw JSON schema. Strict bool // Indicates whether strict validation is enforced. }
JSONSchema defines the structure for responses in JSON.
type LLMClient ¶ added in v1.0.0
type LLMClient interface {
CreateChatCompletion(ctx context.Context, req ChatCompletionRequest) (ChatCompletionResponse, error)
}
LLMClient defines the interface for interacting with LLM providers.
func NewDeepseekR1Client ¶ added in v1.0.0
NewDeepseekR1Client crea un nuevo cliente para DeepseekR1. Recibe la API key y el baseURL (por ejemplo, "https://models.inference.ai.azure.com/").
func NewOpenAIAzureClient ¶ added in v1.0.0
NewOpenAIAzureClient creates an LLMClient for Azure using the provided API key and endpoint. It configures the client with Azure-specific settings.
func NewOpenAIClient ¶ added in v1.0.0
NewOpenAIClient creates a new LLMClient using the provided API key with the standard OpenAI endpoint.
type Memory ¶
type Memory interface { // Add appends a complete ChatCompletionMessage to the memory. Add(message Message) // Get returns a copy of all stored chat messages. Get() []Message // Clear removes all stored chat messages from memory. Clear() }
Memory defines the interface for managing a history of chat messages. It provides methods for adding messages, retrieving the complete history, and clearing the history.
func NewSimpleMemory ¶
func NewSimpleMemory() Memory
NewSimpleMemory creates and returns a new instance of SimpleMemory. It initializes the internal message slice and ensures the memory is ready for use.
type Message ¶ added in v1.0.0
type Message struct { Role string // One of RoleSystem, RoleUser, RoleAssistant, or RoleTool. Content string // The textual content of the message. Name string // Optional identifier for the sender. ToolCalls []ToolCall // Optional tool calls made by the assistant. ToolID string // For tool responses, references the original tool call. }
Message represents a chat message with standardized fields.
type OpenAIClient ¶ added in v1.0.0
type OpenAIClient struct {
// contains filtered or unexported fields
}
OpenAIClient implements the LLMClient interface using the OpenAI SDK. It wraps the official OpenAI client and provides a consistent interface for making chat completion requests.
func (*OpenAIClient) CreateChatCompletion ¶ added in v1.0.0
func (o *OpenAIClient) CreateChatCompletion(ctx context.Context, req ChatCompletionRequest) (ChatCompletionResponse, error)
CreateChatCompletion sends a chat completion request to the OpenAI API using the provided request parameters. It converts internal messages and tool definitions to OpenAI formats, sends the request, and maps the response back into the SDK's unified structure.
type Orchestrator ¶
type Orchestrator struct {
// contains filtered or unexported fields
}
Orchestrator manages multiple agents, maintains a global conversation history, and optionally defines an execution sequence (pipeline) for agents.
func NewOrchestrator ¶
func NewOrchestrator() *Orchestrator
NewOrchestrator creates and returns a new Orchestrator with default settings. It initializes the agents map and the global history with a simple in-memory implementation.
func (*Orchestrator) GetAgent ¶
func (o *Orchestrator) GetAgent(name string) (Agent, bool)
GetAgent retrieves a registered agent by its name in a thread-safe manner.
func (*Orchestrator) Process ¶
func (o *Orchestrator) Process(ctx context.Context, agentName, userName, input string) (string, error)
Process executes a specific agent by combining the global history with the agent's internal memory. It retrieves the target agent, merges global messages with the agent's own messages (if applicable), processes the input, and then updates the global history with both the user input and the agent's response.
func (*Orchestrator) ProcessSequence ¶
ProcessSequence executes a pipeline of agents as defined in the orchestrator's sequence. The output of each agent is used as the input for the next agent in the sequence. It returns the final output from the last agent or an error if processing fails.
type OrchestratorBuilder ¶
type OrchestratorBuilder struct {
// contains filtered or unexported fields
}
OrchestratorBuilder provides a fluent interface for constructing an Orchestrator. It allows developers to configure agents, set a custom global history, and define an execution sequence.
func NewOrchestratorBuilder ¶
func NewOrchestratorBuilder() *OrchestratorBuilder
NewOrchestratorBuilder initializes a new OrchestratorBuilder with default values. It creates an empty agents map, an empty sequence, and a default global history.
func (*OrchestratorBuilder) AddAgent ¶
func (b *OrchestratorBuilder) AddAgent(agent Agent) *OrchestratorBuilder
AddAgent registers an agent with the orchestrator using the agent's name as the key.
func (*OrchestratorBuilder) Build ¶
func (b *OrchestratorBuilder) Build() *Orchestrator
Build constructs and returns an Orchestrator instance based on the current configuration.
func (*OrchestratorBuilder) SetGlobalHistory ¶
func (b *OrchestratorBuilder) SetGlobalHistory(history Memory) *OrchestratorBuilder
SetGlobalHistory sets a custom global conversation history for the orchestrator.
func (*OrchestratorBuilder) SetSequence ¶
func (b *OrchestratorBuilder) SetSequence(seq []string) *OrchestratorBuilder
SetSequence defines the execution order (pipeline) of agents. For example: []string{"agent1", "agent2", "agent3"}.
type PromptBuilder ¶
type PromptBuilder struct {
// contains filtered or unexported fields
}
PromptBuilder facilitates the construction of a prompt by organizing content into sections and subsections.
func NewPromptBuilder ¶
func NewPromptBuilder() *PromptBuilder
NewPromptBuilder creates and initializes a new PromptBuilder instance.
func (*PromptBuilder) AddListItem ¶
func (pb *PromptBuilder) AddListItem(sectionName, item string) *PromptBuilder
AddListItem adds a numbered list item to the specified section or subsection. The item is trimmed for any unnecessary whitespace.
func (*PromptBuilder) AddListItemF ¶
func (pb *PromptBuilder) AddListItemF(sectionName string, value interface{}) *PromptBuilder
AddListItemF is a helper method that converts any value to its string representation (using JSON marshaling if necessary) and adds it as a numbered list item to the specified section.
func (*PromptBuilder) AddSubSection ¶
func (pb *PromptBuilder) AddSubSection(childName, parentName string) *PromptBuilder
AddSubSection creates a new subsection (child) under the specified parent section. If the parent section does not exist, it is created as a top-level section.
func (*PromptBuilder) AddText ¶
func (pb *PromptBuilder) AddText(sectionName, text string) *PromptBuilder
AddText adds a line of text to the specified section or subsection. It trims any extra whitespace before appending.
func (*PromptBuilder) AddTextF ¶
func (pb *PromptBuilder) AddTextF(sectionName string, value interface{}) *PromptBuilder
AddTextF is a helper method that converts any value to its string representation (using JSON marshaling if necessary) and adds it as a text line to the specified section.
func (*PromptBuilder) Build ¶
func (pb *PromptBuilder) Build() string
Build generates the final prompt by concatenating all top-level sections and their nested subsections. It returns the fully formatted prompt as a single string.
func (*PromptBuilder) CreateSection ¶
func (pb *PromptBuilder) CreateSection(name string) *PromptBuilder
CreateSection adds a new top-level section with the given name to the prompt. If a section with the same name already exists, it is not created again.
type ResponseFormat ¶ added in v1.0.0
type ResponseFormat struct { Type string // For example, "json_schema". JSONSchema *JSONSchema // The JSON schema that defines the expected response format. }
ResponseFormat specifies how the LLM should format its response.
type Section ¶
type Section struct { Name string // Name of the section. Lines []string // Lines of text contained in the section. SubSections []*Section // Nested subsections within this section. // contains filtered or unexported fields }
Section represents a block of content that may include text lines and nested subsections. It is used by the PromptBuilder to structure and format the final prompt.
type SimpleMemory ¶
type SimpleMemory struct {
// contains filtered or unexported fields
}
SimpleMemory implements a basic in-memory storage for chat messages. It uses a slice to store messages and a RWMutex for safe concurrent access.
func (*SimpleMemory) Add ¶
func (s *SimpleMemory) Add(message Message)
Add appends a complete chat message to the SimpleMemory.
func (*SimpleMemory) Clear ¶
func (s *SimpleMemory) Clear()
Clear removes all stored messages from the memory.
func (*SimpleMemory) Get ¶
func (s *SimpleMemory) Get() []Message
Get returns a copy of all stored chat messages to avoid data races. A copy of the messages slice is returned to ensure that external modifications do not affect the internal state.
type Tool ¶
type Tool interface { GetDefinition() ToolDefinition Execute(args json.RawMessage) (interface{}, error) }
Tool defines the interface for executable tools.
type ToolCall ¶ added in v1.0.0
type ToolCall struct { ID string // Unique identifier for the tool call. Name string // The name of the tool to be invoked. Args json.RawMessage // Arguments for the tool, encoded in JSON. }
ToolCall represents a tool invocation request.
type ToolDefinition ¶ added in v1.0.0
type ToolDefinition struct { Name string // Name of the tool. Description string // A short description of what the tool does. Parameters json.RawMessage // JSON Schema defining the parameters for the tool. }
ToolDefinition describes a tool's capabilities.