syndicate

package module
v0.2.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 8, 2025 License: Apache-2.0 Imports: 12 Imported by: 0

README

Syndicate SDK Logo

Go Report Card GitHub Workflow Status codecov GoDoc Release

Syndicate

A Go SDK for building and orchestrating intelligent AI agents that seamlessly connect to LLMs, tools, and workflows without the complexity of direct API management.

🚀 Project Status

Current status: Beta - Stable API but under active development
Version: v0.2.0
Go Version: 1.24+

🤔 Why Syndicate?

Comparison Syndicate Direct API Calls Other Solutions
Modularity ✅ Fully modular architecture ❌ Code coupled to a provider ⚠️ Varies by implementation
Multi-agent ✅ Native support for orchestrating multiple agents ❌ Requires manual implementation ⚠️ Limited or complex
Memory Management ✅ Customizable and thread-safe ❌ Not included ⚠️ Generally basic
Tool Integration ✅ Automatic with schema validation ❌ Manual ⚠️ Often limited
Overhead ✅ Minimal, built for performance ✅ None ❌ Often significant

📊 LLM Compatibility

Provider Status Supported Models
OpenAI ✅ Complete GPT-4o, GPT-4, o3, etc.
Azure OpenAI ✅ Complete All Azure OpenAI models
Deepseek ✅ Basic DeepseekR1
Claude 🔄 In development -

📚 Documentation

For a complete overview of the SDK features, see our Quick Guide.

📦 Installation

go get github.com/Dieg0Code/syndicate-go

🔑 Key Features

🤖 Agent Management

Create AI entities with distinct personalities, knowledge bases, and toolsets. Agents can work independently or together in pipelines to handle complex workflows.

🧠 Prompt Engineering

Create structured, detailed prompts that guide agent behavior with consistent responses. The SDK includes utilities for building and managing sophisticated prompts.

🛠️ Tool Integration

Connect agents with external tools and services using automatically generated JSON schemas from Go structures, complete with validation.

💾 Memory Management

Implement customizable memory systems to maintain context across conversations, with support for various storage backends from in-memory to databases.

🔄 Workflow Orchestration

Build multi-agent pipelines that process information sequentially, enabling complex conversational workflows that mirror real-world processes.

🔍 Quick Example

package main

import (
    "context"
    "fmt"

    syndicate "github.com/Dieg0Code/syndicate-go"
    openai "github.com/sashabaranov/go-openai"
)

func main() {
    // Initialize OpenAI client
    client := syndicate.NewOpenAIClient("YOUR_API_KEY")

    // Create an order processing agent
    orderAgent, _ := syndicate.NewAgent().
        SetClient(client).
        SetName("OrderAgent").
        SetConfigPrompt("You process customer orders.").
        SetModel(openai.GPT4).
        Build()

    // Create a summary agent
    summaryAgent, _ := syndicate.NewAgent().
        SetClient(client).
        SetName("SummaryAgent").
        SetConfigPrompt("You summarize order details.").
        SetModel(openai.GPT4).
        Build()

    // Create a pipeline with both agents
    system := syndicate.NewSyndicate().
        RecruitAgent(orderAgent).
        RecruitAgent(summaryAgent).
        DefinePipeline([]string{"OrderAgent", "SummaryAgent"}).
        Build()

    // Process user input
    response, _ := system.ExecutePipeline(
        context.Background(),
        "User",
        "I'd like to order two pizzas for delivery to 123 Main St."
    )

    fmt.Println(response)
}

For a complete step-by-step guide with tool integration and custom memory implementation, see our detailed examples.

🛠️ Advanced Features

Config Prompt Builder

The Config Prompt Builder helps create structured agent configuration prompts using a fluent API:

configPrompt := syndicate.NewPromptBuilder().
  CreateSection("Introduction").
  AddText("Introduction", "You are a customer service agent.").
  CreateSection("Capabilities").
  AddListItem("Capabilities", "Answer product questions.").
  AddListItem("Capabilities", "Handle order inquiries.").
  Build()

📦 Dependencies

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests on GitHub.

📜 License

This project is licensed under Apache License 2.0 - See the LICENSE file for details.

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

View Source 
const (
	RoleSystem    = "system"
	RoleDeveloper = "developer"
	RoleUser      = "user"
	RoleAssistant = "assistant"
	RoleTool      = "tool"
)

Role constants define standard message roles across different providers

View Source 
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) AddTool 

func (b *BaseAgent) AddTool(tool Tool)

AddTool adds a tool to the agent. AddTool adds a tool to the agent.

func (*BaseAgent) GetName 

func (b *BaseAgent) GetName() string

GetName returns the name identifier of the agent.

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 

func (b *BaseAgent) SetConfigPrompt(prompt string)

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 

type ChatCompletionResponse struct {
	Choices []Choice `json:"choices"`
	Usage   Usage    `json:"usage"`
}

ChatCompletionResponse represents a unified response structure from the LLM.

type Choice 

type Choice struct {
	Message      Message `json:"message"`
	FinishReason string  `json:"finish_reason"`
}

Choice represents a single completion option.

type DataType 

type DataType string

DataType represents a JSON data type in the generated schema. 

const (
	Object  DataType = "object"
	Number  DataType = "number"
	Integer DataType = "integer"
	String  DataType = "string"
	Array   DataType = "array"
	Null    DataType = "null"
	Boolean DataType = "boolean"
)

Supported JSON data types.

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 

func NewDeepseekR1Client(apiKey, baseURL string) LLMClient

NewDeepseekR1Client crea un nuevo cliente para DeepseekR1. Recibe la API key y el baseURL (por ejemplo, "https://models.inference.ai.azure.com/").

func NewOpenAIAzureClient 

func NewOpenAIAzureClient(apiKey string) LLMClient

NewOpenAIAzureClient creates an LLMClient for Azure using Azure provider-specific settings. It configures the client with Azure-specific settings.

func NewOpenAIClient 

func NewOpenAIClient(apiKey string) LLMClient

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 

func (s *Syndicate) ExecutePipeline(ctx context.Context, userName, input string) (string, error)

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.

func (*Syndicate) FindAgent added in v0.2.0 

func (s *Syndicate) FindAgent(name string) (Agent, bool)

FindAgent retrieves a registered agent by its name in a thread-safe manner.

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.

type Usage 

type Usage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

Usage provides token usage statistics.

Source Files

View all Source files

Directories

Path Synopsis
examples

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.