type Result struct {
    Content      string
    Model        string
    FinishReason string
    Usage        Usage
    ToolCalls    []ToolCallResult
    Reasoning    []ReasoningStep
    Cost         float64
    FromCache    bool
    CacheAge     time.Duration
}

type Usage struct {
    InputTokens  int
    OutputTokens int
    TotalTokens  int
}

type Callbacks struct {
    OnStart    func()
    OnComplete func(result *Result)
    OnError    func(err error)
}

func NewGenerateBuilder(
    ctx context.Context,
    llm LLMManager,
    logger forge.Logger,
    metrics forge.Metrics,
) *GenerateBuilder

func (b *GenerateBuilder) WithPrompt(prompt string) *GenerateBuilder
func (b *GenerateBuilder) WithSystemMessage(msg string) *GenerateBuilder
func (b *GenerateBuilder) WithModel(model string) *GenerateBuilder
func (b *GenerateBuilder) WithTemperature(temp float64) *GenerateBuilder
func (b *GenerateBuilder) WithMaxTokens(tokens int) *GenerateBuilder
func (b *GenerateBuilder) WithTopP(topP float64) *GenerateBuilder
func (b *GenerateBuilder) WithTopK(topK int) *GenerateBuilder
func (b *GenerateBuilder) WithStop(stop []string) *GenerateBuilder
func (b *GenerateBuilder) WithTools(tools []llm.ToolDefinition) *GenerateBuilder
func (b *GenerateBuilder) WithGuardrails(guard *GuardrailManager) *GenerateBuilder
func (b *GenerateBuilder) WithCache(cache *SemanticCache) *GenerateBuilder
func (b *GenerateBuilder) WithCost(tracker *CostTracker) *GenerateBuilder
func (b *GenerateBuilder) OnStart(fn func()) *GenerateBuilder
func (b *GenerateBuilder) OnComplete(fn func(*Result)) *GenerateBuilder
func (b *GenerateBuilder) OnError(fn func(error)) *GenerateBuilder
func (b *GenerateBuilder) Execute() (*Result, error)

func NewGenerateObjectBuilder[T any](
    ctx context.Context,
    llm LLMManager,
    logger forge.Logger,
    metrics forge.Metrics,
) *GenerateObjectBuilder[T]

func (b *GenerateObjectBuilder[T]) WithPrompt(prompt string) *GenerateObjectBuilder[T]
func (b *GenerateObjectBuilder[T]) WithModel(model string) *GenerateObjectBuilder[T]
func (b *GenerateObjectBuilder[T]) WithValidator(v Validator) *GenerateObjectBuilder[T]
func (b *GenerateObjectBuilder[T]) WithMaxRetries(retries int) *GenerateObjectBuilder[T]
func (b *GenerateObjectBuilder[T]) Execute() (*T, error)

func NewStreamBuilder(
    ctx context.Context,
    llm LLMManager,
    logger forge.Logger,
    metrics forge.Metrics,
) *StreamBuilder

func (b *StreamBuilder) WithPrompt(prompt string) *StreamBuilder
func (b *StreamBuilder) WithReasoning(enable bool) *StreamBuilder
func (b *StreamBuilder) OnToken(fn func(string)) *StreamBuilder
func (b *StreamBuilder) OnReasoning(fn func(string)) *StreamBuilder
func (b *StreamBuilder) OnToolCall(fn func(*ToolCallResult)) *StreamBuilder
func (b *StreamBuilder) Stream() (*Result, error)

func NewMultiModalBuilder(
    ctx context.Context,
    llm LLMManager,
    logger forge.Logger,
    metrics forge.Metrics,
) *MultiModalBuilder

func (b *MultiModalBuilder) WithText(text string) *MultiModalBuilder
func (b *MultiModalBuilder) WithImageFile(path string) *MultiModalBuilder
func (b *MultiModalBuilder) WithImageURL(url string) *MultiModalBuilder
func (b *MultiModalBuilder) WithImage(data, mimeType string) *MultiModalBuilder
func (b *MultiModalBuilder) WithAudioFile(path string) *MultiModalBuilder
func (b *MultiModalBuilder) WithVideoFile(path string) *MultiModalBuilder
func (b *MultiModalBuilder) Execute() (*Result, error)

func NewAgent(
    id string,
    llm LLMManager,
    logger forge.Logger,
    metrics forge.Metrics,
    opts *AgentOptions,
) *Agent

func (a *Agent) Execute(ctx context.Context, input string) (*Result, error)
func (a *Agent) RegisterTool(tool *Tool) error
func (a *Agent) AddMessage(msg AgentMessage)
func (a *Agent) GetHistory() []AgentMessage
func (a *Agent) ClearHistory()
func (a *Agent) SetStateData(key string, value interface{})
func (a *Agent) GetStateData(key string) interface{}

type AgentOptions struct {
    Model          string
    Temperature    float64
    MaxHistory     int
    SystemMessage  string
    StateStore     StateStore
    OnToolCall     func(*Tool, interface{})
    OnComplete     func(*Result)
    OnError        func(error)
}

func NewSelfHealingAgent(
    agent *Agent,
    config SelfHealingConfig,
    logger forge.Logger,
    metrics forge.Metrics,
) *SelfHealingAgent

func (s *SelfHealingAgent) Process(ctx context.Context, input string) (*Result, error)
func (s *SelfHealingAgent) RegisterStrategy(name string, strategy RecoveryStrategy)
func (s *SelfHealingAgent) GetRecoveryStats() RecoveryStats

func NewRAG(
    llm LLMManager,
    vectorStore VectorStore,
    logger forge.Logger,
    metrics forge.Metrics,
    config RAGConfig,
) *RAG

func (r *RAG) IndexDocument(ctx context.Context, docID, content string) error
func (r *RAG) Search(ctx context.Context, query string, topK int) ([]Document, error)
func (r *RAG) GenerateWithContext(ctx context.Context, query string) (*Result, error)

type RAGConfig struct {
    ChunkSize     int
    ChunkOverlap  int
    ChunkStrategy ChunkStrategy
    TopK          int
    EnableRerank  bool
    RerankTopK    int
}

func NewMemoryManager(
    vectorStore VectorStore,
    logger forge.Logger,
    metrics forge.Metrics,
    config MemoryConfig,
) *MemoryManager

func (m *MemoryManager) Store(ctx context.Context, memory *Memory) error
func (m *MemoryManager) Recall(ctx context.Context, query string, limit int) ([]*Memory, error)
func (m *MemoryManager) Promote(ctx context.Context, id string, tier MemoryTier) error
func (m *MemoryManager) GetStats() MemoryStats

type Memory struct {
    ID         string
    Content    string
    Importance float64
    Tags       []string
    Metadata   map[string]interface{}
    Tier       MemoryTier
    CreatedAt  time.Time
}

type MemoryConfig struct {
    WorkingCapacity   int
    ShortTermTTL      time.Duration
    LongTermThreshold float64
    EnableEpisodic    bool
}

func NewToolRegistry(
    logger forge.Logger,
    metrics forge.Metrics,
) *ToolRegistry

func (r *ToolRegistry) RegisterTool(tool *Tool) error
func (r *ToolRegistry) ExecuteTool(ctx context.Context, name string, args map[string]interface{}) (interface{}, error)
func (r *ToolRegistry) ListTools() []*Tool
func (r *ToolRegistry) SearchTools(ctx context.Context, query string) ([]*Tool, error)

type Tool struct {
    Name        string
    Description string
    Version     string
    Parameters  map[string]interface{}
    Handler     ToolHandler
}

type ToolHandler func(ctx context.Context, args map[string]interface{}) (interface{}, error)

func NewWorkflowEngine(
    logger forge.Logger,
    metrics forge.Metrics,
) *WorkflowEngine

func (w *WorkflowEngine) AddNode(id string, agent *Agent, deps []string) error
func (w *WorkflowEngine) Execute(ctx context.Context, input interface{}) (interface{}, error)
func (w *WorkflowEngine) GetState() WorkflowState

func NewCostTracker(
    logger forge.Logger,
    metrics forge.Metrics,
) *CostTracker

func (c *CostTracker) TrackRequest(ctx context.Context, entry CostEntry)
func (c *CostTracker) GetTotalCost() float64
func (c *CostTracker) SetMonthlyBudget(amount float64)
func (c *CostTracker) GetBudgetStatus() BudgetStatus
func (c *CostTracker) GetOptimizationRecommendations() []Recommendation

type CostEntry struct {
    Model        string
    InputTokens  int
    OutputTokens int
    Provider     string
    Timestamp    time.Time
}

func NewCircuitBreaker(
    logger forge.Logger,
    metrics forge.Metrics,
    config CircuitBreakerConfig,
) *CircuitBreaker

func (c *CircuitBreaker) Execute(ctx context.Context, fn func() (interface{}, error)) (interface{}, error)
func (c *CircuitBreaker) GetState() State

func NewRetry(
    logger forge.Logger,
    metrics forge.Metrics,
    config RetryConfig,
) *Retry

func (r *Retry) Execute(ctx context.Context, fn func() (interface{}, error)) (interface{}, error)

func NewRateLimiter(
    logger forge.Logger,
    metrics forge.Metrics,
    config RateLimiterConfig,
) *RateLimiter

func (r *RateLimiter) Execute(ctx context.Context, fn func() (interface{}, error)) (interface{}, error)

func NewSemanticCache(
    vectorStore VectorStore,
    cacheStore CacheStore,
    logger forge.Logger,
    metrics forge.Metrics,
    config SemanticCacheConfig,
) *SemanticCache

func (c *SemanticCache) Get(ctx context.Context, query string, embedding []float64) (*CacheEntry, error)
func (c *SemanticCache) Set(ctx context.Context, query string, embedding []float64, response *Result)
func (c *SemanticCache) GetStats() CacheStats

func NewBatchProcessor(
    llm LLMManager,
    logger forge.Logger,
    metrics forge.Metrics,
    config BatchConfig,
) *BatchProcessor

func (b *BatchProcessor) Submit(ctx context.Context, req BatchRequest)
func (b *BatchProcessor) SubmitAndWait(ctx context.Context, req BatchRequest) (*Result, error)
func (b *BatchProcessor) GetStats() BatchStats

func NewPluginSystem(
    logger forge.Logger,
    metrics forge.Metrics,
) *PluginSystem

func (p *PluginSystem) RegisterPlugin(plugin Plugin) error
func (p *PluginSystem) ExecutePlugin(ctx context.Context, name string, input interface{}) (interface{}, error)
func (p *PluginSystem) ListPlugins() []Plugin

type Plugin interface {
    Name() string
    Version() string
    Description() string
    Init(ctx context.Context, config map[string]interface{}) error
    Execute(ctx context.Context, input interface{}) (interface{}, error)
    Cleanup(ctx context.Context) error
    HealthCheck(ctx context.Context) error
}

type LLMManager interface {
    Chat(ctx context.Context, req llm.ChatRequest) (*llm.ChatResponse, error)
    ChatStream(ctx context.Context, req llm.ChatRequest) (<-chan llm.ChatStreamEvent, error)
    Embed(ctx context.Context, text string) ([]float64, error)
}

type VectorStore interface {
    Upsert(ctx context.Context, vectors []Vector) error
    Query(ctx context.Context, vector []float64, topK int) ([]VectorMatch, error)
    Delete(ctx context.Context, id string) error
}

type StateStore interface {
    Save(ctx context.Context, state *AgentState) error
    Load(ctx context.Context, id string) (*AgentState, error)
    Delete(ctx context.Context, id string) error
    List(ctx context.Context) ([]*AgentState, error)
}

type CacheStore interface {
    Get(ctx context.Context, key string) (interface{}, error)
    Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error
    Delete(ctx context.Context, key string) error
}

var (
    ErrRateLimited         = errors.New("rate limit exceeded")
    ErrInvalidRequest      = errors.New("invalid request")
    ErrProviderError       = errors.New("provider error")
    ErrCircuitOpen         = errors.New("circuit breaker is open")
    ErrBudgetExceeded      = errors.New("budget exceeded")
    ErrCacheMiss           = errors.New("cache miss")
    ErrBulkheadFull        = errors.New("bulkhead full")
    ErrUnsupportedFormat   = errors.New("unsupported format")
    ErrFileTooLarge        = errors.New("file too large")
)

const (
    // Memory tiers
    Working   MemoryTier = "working"
    ShortTerm MemoryTier = "short_term"
    LongTerm  MemoryTier = "long_term"
    Episodic  MemoryTier = "episodic"
    
    // Circuit breaker states
    StateClosed    State = "closed"
    StateOpen      State = "open"
    StateHalfOpen  State = "half_open"
    
    // Content types
    ContentTypeText      = "text"
    ContentTypeImageURL  = "image_url"
    ContentTypeImageData = "image_data"
    ContentTypeAudioURL  = "audio_url"
    ContentTypeAudioData = "audio_data"
    ContentTypeVideoURL  = "video_url"
    ContentTypeVideoData = "video_data"
)