Documentation
¶
Overview ¶
Package syndicate 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)
- func ValidateDefinition(def *Definition) error
- type Agent
- type AgentBuilder
- func (b *AgentBuilder) Build() (*BaseAgent, error)
- func (b *AgentBuilder) EquipTool(tool Tool) *AgentBuilder
- func (b *AgentBuilder) SetClient(client LLMClient) *AgentBuilder
- func (b *AgentBuilder) SetConfigPrompt(prompt string) *AgentBuilder
- func (b *AgentBuilder) SetDescription(description 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 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 Syndicate
- type SyndicateBuilder
- 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 ¶
func GenerateRawSchema(v any) (json.RawMessage, error)
GenerateRawSchema wraps GenerateSchema and returns the JSON marshalled schema. Before marshalling, it validates the generated schema using ValidateDefinition.
func ValidateDefinition ¶
func ValidateDefinition(def *Definition) error
ValidateDefinition recursively validates the generated JSON Schema definition. It ensures that required fields exist, arrays have items defined, that enum values are not empty, and that if AdditionalProperties is set, it conforms to accepted types (bool, Definition, or *Definition).
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 NewAgent ¶ added in v0.2.0
func NewAgent() *AgentBuilder
NewAgentBuilder initializes and returns a new instance of AgentBuilder.
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) EquipTool ¶ added in v0.2.0
func (b *AgentBuilder) EquipTool(tool Tool) *AgentBuilder
EquipTool adds a tool to the operative's configuration, making it available during processing.
func (*AgentBuilder) SetClient ¶
func (b *AgentBuilder) SetClient(client LLMClient) *AgentBuilder
SetClient sets the LLMClient to be used by the agent.
func (*AgentBuilder) SetConfigPrompt ¶
func (b *AgentBuilder) SetConfigPrompt(prompt string) *AgentBuilder
SetConfigPrompt sets the system prompt that configures the agent's behavior.
func (*AgentBuilder) SetDescription ¶ added in v0.2.1
func (b *AgentBuilder) SetDescription(description string) *AgentBuilder
SetDescription sets the description for the agent.
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 ¶
SetConfigPrompt sets the system prompt for the agent, which can be used to configure behavior.
type ChatCompletionRequest ¶
type ChatCompletionRequest struct { Model string `json:"model"` Messages []Message `json:"messages"` Tools []ToolDefinition `json:"tools,omitempty"` Temperature float32 `json:"temperature"` ResponseFormat *ResponseFormat `json:"response_format,omitempty"` }
ChatCompletionRequest represents a unified chat completion request.
type ChatCompletionResponse ¶
ChatCompletionResponse represents a unified response structure from the LLM.
type DeepseekR1Client ¶
type DeepseekR1Client struct {
// contains filtered or unexported fields
}
DeepseekR1Client implementa LLMClient usando el SDK de DeepseekR1.
func (*DeepseekR1Client) CreateChatCompletion ¶
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 ¶
type JSONSchema struct { Name string `json:"name"` Schema json.RawMessage `json:"schema"` Strict bool `json:"strict"` }
JSONSchema defines the structure for responses in JSON.
type LLMClient ¶
type LLMClient interface {
CreateChatCompletion(ctx context.Context, req ChatCompletionRequest) (ChatCompletionResponse, error)
}
LLMClient defines the interface for interacting with LLM providers.
func NewDeepseekR1Client ¶
NewDeepseekR1Client crea un nuevo cliente para DeepseekR1. Recibe la API key y el baseURL (por ejemplo, "https://models.inference.ai.azure.com/").
func NewOpenAIAzureClient ¶
NewOpenAIAzureClient creates an LLMClient for Azure using Azure provider-specific settings. It configures the client with Azure-specific settings.
func NewOpenAIClient ¶
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 ¶
type Message struct { Role string `json:"role"` Content string `json:"content"` Name string `json:"name,omitempty"` ToolCalls []ToolCall `json:"tool_calls,omitempty"` ToolCallID string `json:"tool_call_id,omitempty"` }
Message represents a chat message with standardized fields.
type OpenAIClient ¶
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 ¶
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 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 ¶
type ResponseFormat struct { Type string `json:"type"` JSONSchema *JSONSchema `json:"json_schema,omitempty"` }
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 Syndicate ¶ added in v0.2.0
type Syndicate struct {
// contains filtered or unexported fields
}
Syndicate manages multiple agents, maintains a global conversation history, and optionally defines an execution pipeline for agents.
func (*Syndicate) ExecuteAgent ¶ added in v0.2.0
func (s *Syndicate) ExecuteAgent(ctx context.Context, agentName, userName, input string) (string, error)
ExecuteAgent runs 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 (*Syndicate) ExecutePipeline ¶ added in v0.2.0
ExecutePipeline runs a sequence of agents as defined in the syndicate's pipeline. The output of each agent is used as the input for the next agent in the pipeline. It returns the final output from the last agent or an error if processing fails.
type SyndicateBuilder ¶ added in v0.2.0
type SyndicateBuilder struct {
// contains filtered or unexported fields
}
SyndicateBuilder provides a fluent interface for constructing a Syndicate. It allows developers to configure agents, set a custom global history, and define an execution pipeline.
func NewSyndicate ¶ added in v0.2.0
func NewSyndicate() *SyndicateBuilder
NewSyndicateBuilder initializes a new SyndicateBuilder with default values and a simple in-memory history. It creates an empty agents map, an empty pipeline, and a default global history.
func (*SyndicateBuilder) Build ¶ added in v0.2.0
func (b *SyndicateBuilder) Build() *Syndicate
Build constructs and returns a Syndicate instance based on the current configuration.
func (*SyndicateBuilder) DefinePipeline ¶ added in v0.2.0
func (b *SyndicateBuilder) DefinePipeline(pipeline []string) *SyndicateBuilder
DefinePipeline defines the execution order (pipeline) of agents. For example: []string{"agent1", "agent2", "agent3"}.
func (*SyndicateBuilder) RecruitAgent ¶ added in v0.2.0
func (b *SyndicateBuilder) RecruitAgent(agent Agent) *SyndicateBuilder
RecruitAgent registers an agent with the syndicate using the agent's name as the key.
func (*SyndicateBuilder) SetGlobalHistory ¶ added in v0.2.0
func (b *SyndicateBuilder) SetGlobalHistory(history Memory) *SyndicateBuilder
SetGlobalHistory sets a custom global conversation history for the syndicate.
type Tool ¶
type Tool interface { GetDefinition() ToolDefinition Execute(args json.RawMessage) (interface{}, error) }
Tool defines the interface for executable tools.
type ToolCall ¶
type ToolCall struct { ID string `json:"id"` Name string `json:"name"` Args json.RawMessage `json:"args"` }
ToolCall represents a tool invocation request.
type ToolDefinition ¶
type ToolDefinition struct { Name string `json:"name"` Description string `json:"description"` Parameters any `json:"parameters"` }
ToolDefinition describes a tool's capabilities.