brain

type Brain interface {
	// Chat generates a plain text response for a given prompt.
	// Best used for simple questions, greetings, or summarization.
	Chat(ctx context.Context, prompt string) (string, error)

	// Analyze performs structured analysis and returns the result in the target struct.
	// The target must be a pointer to a struct that can be unmarshaled from JSON.
	// Useful for intent routing, safety checks, and complex data extraction.
	Analyze(ctx context.Context, prompt string, target any) error
}

type BudgetConfig struct {
	Enabled         bool      // Enable budget tracking
	Period          string    // Budget period: "daily", "weekly", "monthly"
	Limit           float64   // Budget limit in USD
	EnableHardLimit bool      // Block requests when budget exceeded
	AlertThresholds []float64 // Alert at these percentages (e.g., [0.5, 0.8, 0.9])
}

type BudgetControlledBrain interface {
	Brain

	// GetBudgetTracker returns the budget tracker for a session.
	GetBudgetTracker(sessionID string) *llm.BudgetTracker

	// GetBudgetManager returns the budget manager.
	GetBudgetManager() *llm.BudgetManager
}

type CacheConfig struct {
	Enabled bool // Enable response caching
	Size    int  // Maximum cache entries
}

type CircuitBreakerConfig struct {
	Enabled     bool          // Enable circuit breaker
	MaxFailures int           // Failures before opening circuit
	Timeout     time.Duration // Time before attempting to close circuit
	Interval    time.Duration // Interval for resetting failure count
}

type CompressionConfig struct {
	Enabled          bool          `json:"enabled"`            // Master switch for compression
	TokenThreshold   int           `json:"token_threshold"`    // Trigger compression at this token count (default: 8000)
	TargetTokenCount int           `json:"target_token_count"` // Target tokens after compression (default: 2000)
	PreserveTurns    int           `json:"preserve_turns"`     // Number of recent turns to keep intact (default: 5)
	MaxSummaryTokens int           `json:"max_summary_tokens"` // Max tokens for summary (default: 500)
	CompressionRatio float64       `json:"compression_ratio"`  // Target compression ratio 0.0-1.0 (default: 0.25)
	SessionTTL       time.Duration `json:"session_ttl"`        // Session memory TTL (default: 24h)
	CleanupInterval  time.Duration `json:"cleanup_interval"`   // Background cleanup interval (default: 1h)
}

type Config struct {
	// Enabled is automatically determined based on APIKey presence.
	Enabled bool
	// Model is the model configuration.
	Model ModelConfig
	// Cache is the cache configuration.
	Cache CacheConfig
	// Retry is the retry configuration.
	Retry RetryConfig
	// Metrics is the metrics configuration.
	Metrics MetricsConfig
	// Cost is the cost configuration.
	Cost CostConfig
	// RateLimit is the rate limit configuration.
	RateLimit RateLimitConfig
	// Router is the router configuration.
	Router RouterConfig
	// CircuitBreaker is the circuit breaker configuration.
	CircuitBreaker CircuitBreakerConfig
	// Failover is the failover configuration.
	Failover FailoverConfig
	// Budget is the budget configuration.
	Budget BudgetConfig
	// Priority is the priority configuration.
	Priority PriorityConfig
	// IntentRouter is the intent router feature configuration.
	IntentRouter IntentRouterFeatureConfig
	// Memory is the memory compression feature configuration.
	Memory MemoryCompressionConfig
	// Guard is the safety guard feature configuration.
	Guard SafetyGuardFeatureConfig
}

type ConfigIntent struct {
	Action     string                 `json:"action"` // "get", "set", "list"
	Target     string                 `json:"target"` // "model", "provider", "limit", etc.
	Value      string                 `json:"value"`  // New value for "set" actions
	Extra      map[string]interface{} `json:"extra"`  // Additional context
	Confidence float64                `json:"confidence"`
}

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

type CostConfig struct {
	Enabled      bool // Enable cost tracking
	EnableBudget bool // Enable budget enforcement
}

type FailoverConfig struct {
	Enabled        bool                 // Enable failover
	Providers      []llm.ProviderConfig // Backup providers
	EnableAuto     bool                 // Enable automatic failover
	EnableFailback bool                 // Enable automatic failback when primary recovers
	Cooldown       time.Duration        // Cooldown period before failback
}

type GuardConfig struct {
	Enabled            bool          `json:"enabled"`              // Master switch for all guard features
	InputGuardEnabled  bool          `json:"input_guard_enabled"`  // Enable input validation (pattern + AI)
	OutputGuardEnabled bool          `json:"output_guard_enabled"` // Enable output sanitization (redact secrets)
	Chat2ConfigEnabled bool          `json:"chat2config_enabled"`  // Allow config changes via natural language (security risk)
	MaxInputLength     int           `json:"max_input_length"`     // Reject inputs exceeding this length (DoS protection)
	ScanDepth          int           `json:"scan_depth"`           // Reserved for nested context scanning
	Sensitivity        string        `json:"sensitivity"`          // Detection sensitivity: "low" (pattern-only), "medium", "high" (aggressive AI)
	BanPatterns        []string      `json:"ban_patterns"`         // Regex patterns for prompt injection, jailbreak, etc.
	AdminUsers         []string      `json:"admin_users"`          // User IDs with elevated privileges
	AdminChannels      []string      `json:"admin_channels"`       // Channel IDs with elevated privileges
	ResponseTimeout    time.Duration `json:"response_timeout"`     // Timeout for Brain API calls during analysis
	// Rate limiting for CheckInput calls (per-user)
	RateLimitRPS   float64 `json:"rate_limit_rps"`   // Requests per second per user (0 = disabled)
	RateLimitBurst int     `json:"rate_limit_burst"` // Burst capacity per user
}

type GuardResult struct {
	Safe           bool        `json:"safe"`                      // true if no threat detected or successfully sanitized
	ThreatLevel    ThreatLevel `json:"threat_level"`              // Severity classification
	ThreatType     string      `json:"threat_type,omitempty"`     // e.g., "prompt_injection", "sensitive_data_detected"
	Reason         string      `json:"reason,omitempty"`          // Human-readable explanation
	MatchedPattern string      `json:"matched_pattern,omitempty"` // The regex that matched (for debugging)
	Action         string      `json:"action,omitempty"`          // "allow", "block", or "sanitize"
	SanitizedInput string      `json:"sanitized_input,omitempty"` // Redacted version when Action == "sanitize"
}

type HealthStatus = llm.HealthStatus

type IntentResult struct {
	Type       IntentType `json:"type"`
	Confidence float64    `json:"confidence"`
	Response   string     `json:"response,omitempty"`
	Reason     string     `json:"reason,omitempty"`
}

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

type IntentRouterConfig struct {
	Enabled             bool
	ConfidenceThreshold float64
	CacheSize           int
}

type IntentRouterFeatureConfig struct {
	Enabled             bool    `json:"enabled"`              // Enable intent routing
	ConfidenceThreshold float64 `json:"confidence_threshold"` // Minimum confidence for classification
	CacheSize           int     `json:"cache_size"`           // Cache size for classification results
}

type IntentType string

type MemoryCompressionConfig struct {
	Enabled          bool    // Enable context compression
	TokenThreshold   int     // Trigger compression at this token count
	TargetTokenCount int     // Target tokens after compression
	PreserveTurns    int     // Recent turns to preserve during compression
	MaxSummaryTokens int     // Maximum tokens for summary
	CompressionRatio float64 // Target compression ratio (0.0-1.0)
	SessionTTL       string  // Session time-to-live (e.g., "24h")
}

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

type MetricsConfig struct {
	Enabled        bool          // Enable metrics collection
	ServiceName    string        // Service name for metrics identification
	Endpoint       string        // Metrics export endpoint (e.g., OTLP collector)
	ExportInterval time.Duration // Interval for periodic metric export
}

type ModelConfig struct {
	Provider string // LLM provider: "openai", "anthropic", "google"
	Model    string // Model name: "gpt-4o-mini", "claude-3-haiku", etc.
	Endpoint string // Custom API endpoint (optional, for self-hosted)
	TimeoutS int    // Request timeout in seconds
}

type ObservableBrain interface {
	Brain

	// GetMetrics returns current metrics statistics.
	GetMetrics() llm.MetricsStats

	// GetCostCalculator returns the cost calculator.
	GetCostCalculator() *llm.CostCalculator
}

type PriorityBrain interface {
	Brain

	// GetPriorityScheduler returns the priority scheduler.
	GetPriorityScheduler() *llm.PriorityScheduler

	// SubmitWithPriority submits a request with specified priority.
	SubmitWithPriority(ctx context.Context, prompt string, priority llm.Priority) (string, error)
}

type PriorityConfig struct {
	Enabled               bool // Enable priority queuing
	MaxQueueSize          int  // Maximum queued requests
	EnableLowPriorityDrop bool // Drop low-priority requests when queue full
	HighPriorityReserve   int  // Reserved slots for high-priority requests
}

type RateLimitConfig struct {
	Enabled      bool          // Enable rate limiting
	RPS          float64       // Requests per second limit
	Burst        int           // Burst capacity (token bucket)
	QueueSize    int           // Queue size for waiting requests
	QueueTimeout time.Duration // Max wait time in queue
	PerModel     bool          // Apply limit per-model instead of global
}

type ResilientBrain interface {
	Brain

	// GetCircuitBreaker returns the circuit breaker.
	GetCircuitBreaker() *llm.CircuitBreaker

	// GetFailoverManager returns the failover manager.
	GetFailoverManager() *llm.FailoverManager

	// ResetCircuitBreaker manually resets the circuit breaker.
	ResetCircuitBreaker()

	// ManualFailover manually switches to a specific provider.
	ManualFailover(providerName string) error
}

type RetryConfig struct {
	Enabled     bool // Enable retry mechanism
	MaxAttempts int  // Maximum retry attempts
	MinWaitMs   int  // Minimum wait between retries (milliseconds)
	MaxWaitMs   int  // Maximum wait between retries (milliseconds)
}

type RoutableBrain interface {
	Brain

	// ChatWithModel generates a response using a specific model.
	ChatWithModel(ctx context.Context, model string, prompt string) (string, error)

	// AnalyzeWithModel performs analysis using a specific model.
	AnalyzeWithModel(ctx context.Context, model string, prompt string, target any) error
}

type RouterConfig struct {
	Enabled      bool              // Enable model routing
	DefaultStage string            // Default routing strategy: "cost_priority", "latency_priority"
	Models       []llm.ModelConfig // Available models with cost/latency info
}

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

type SafetyGuardFeatureConfig struct {
	Enabled            bool          // Enable safety guard
	InputGuardEnabled  bool          // Enable input validation
	OutputGuardEnabled bool          // Enable output sanitization
	Chat2ConfigEnabled bool          // Enable natural language config changes (security risk)
	MaxInputLength     int           // Maximum input length
	ScanDepth          int           // Depth for nested context scanning
	Sensitivity        string        // Detection sensitivity: "low", "medium", "high"
	AdminUsers         []string      // User IDs with admin privileges
	AdminChannels      []string      // Channel IDs with admin privileges
	ResponseTimeout    time.Duration // Timeout for Brain API calls
	RateLimitRPS       float64       // Requests per second per user (0 = disabled)
	RateLimitBurst     int           // Burst capacity per user
}

type SessionHistory struct {
	SessionID   string `json:"session_id"`
	Turns       []Turn `json:"turns"`
	TotalTokens int    `json:"total_tokens"`
	Compressed  bool   `json:"compressed"`
	Summary     string `json:"summary,omitempty"`
}

type StreamingBrain interface {
	Brain

	// ChatStream returns a channel that streams tokens as they are generated.
	// The channel is closed when the stream completes or an error occurs.
	// Best used for long responses, real-time UI updates, or progressive rendering.
	ChatStream(ctx context.Context, prompt string) (<-chan string, error)
}

type ThreatLevel string

type Turn struct {
	Role       string    `json:"role"` // "user" or "assistant"
	Content    string    `json:"content"`
	Timestamp  time.Time `json:"timestamp"`
	TokenCount int       `json:"token_count"`
}