core

type Agent struct {
	// ID is the unique identifier for the agent.
	ID string
	// Name is the display name of the agent.
	Name string
	// Type is the type of agent (e.g., "leader", "sub").
	Type string
	// Status is the current status of the agent.
	Status AgentStatus
	// SessionID is the associated session ID.
	SessionID string
	// Config is the agent configuration.
	Config map[string]interface{}
	// CreatedAt is the timestamp when the agent was created.
	CreatedAt int64
	// UpdatedAt is the timestamp when the agent was last updated.
	UpdatedAt int64
}

type AgentConfig struct {
	// ID is the unique identifier for the agent.
	ID string
	// Name is the display name of the agent.
	Name string
	// Type is the type of agent.
	Type string
	// Config is additional configuration parameters.
	Config map[string]interface{}
}

type AgentFilter struct {
	// Type filters by agent type.
	Type string
	// Status filters by agent status.
	Status AgentStatus
	// SessionID filters by session ID.
	SessionID string
	// Pagination represents pagination parameters.
	Pagination *PaginationRequest
}

type AgentRepository interface {
	// Create creates a new agent.
	// Args:
	// ctx - operation context.
	// agent - the agent to create.
	// Returns error if creation fails.
	Create(ctx context.Context, agent *Agent) error

	// Get retrieves an agent by ID.
	// Args:
	// ctx - operation context.
	// agentID - the agent identifier.
	// Returns the agent or error if not found.
	Get(ctx context.Context, agentID string) (*Agent, error)

	// Update updates an existing agent.
	// Args:
	// ctx - operation context.
	// agent - the agent to update.
	// Returns error if update fails.
	Update(ctx context.Context, agent *Agent) error

	// Delete deletes an agent by ID.
	// Args:
	// ctx - operation context.
	// agentID - the agent identifier.
	// Returns error if deletion fails.
	Delete(ctx context.Context, agentID string) error

	// List lists agents with optional filtering.
	// Args:
	// ctx - operation context.
	// filter - optional filter criteria.
	// Returns list of agents or error.
	List(ctx context.Context, filter *AgentFilter) ([]*Agent, error)
}

type AgentService interface {
	// CreateAgent creates a new agent with the given configuration.
	// Args:
	// ctx - operation context.
	// config - the agent configuration.
	// Returns the created agent or error.
	CreateAgent(ctx context.Context, config *AgentConfig) (*Agent, error)

	// GetAgent retrieves an agent by ID.
	// Args:
	// ctx - operation context.
	// agentID - the agent identifier.
	// Returns the agent or error if not found.
	GetAgent(ctx context.Context, agentID string) (*Agent, error)

	// UpdateAgent updates an existing agent.
	// Args:
	// ctx - operation context.
	// agentID - the agent identifier.
	// updates - the fields to update.
	// Returns the updated agent or error.
	UpdateAgent(ctx context.Context, agentID string, updates map[string]interface{}) (*Agent, error)

	// DeleteAgent deletes an agent and its associated data.
	// Args:
	// ctx - operation context.
	// agentID - the agent identifier.
	// Returns error if deletion fails.
	DeleteAgent(ctx context.Context, agentID string) error

	// ListAgents lists agents with optional filtering.
	// Args:
	// ctx - operation context.
	// filter - optional filter criteria.
	// Returns list of agents and pagination info, or error.
	ListAgents(ctx context.Context, filter *AgentFilter) ([]*Agent, *PaginationResponse, error)

	// ExecuteTask executes a task on an agent.
	// Args:
	// ctx - operation context.
	// task - the task to execute.
	// Returns the task result or error.
	ExecuteTask(ctx context.Context, task *Task) (*TaskResult, error)

	// GetTaskResult retrieves the result of a task.
	// Args:
	// ctx - operation context.
	// taskID - the task identifier.
	// Returns the task result or error if not found.
	GetTaskResult(ctx context.Context, taskID string) (*TaskResult, error)
}

type AgentStatus string

type BaseConfig struct {
	// RequestTimeout is the default timeout for API requests.
	RequestTimeout time.Duration
	// MaxRetries is the maximum number of retry attempts.
	MaxRetries int
	// RetryDelay is the delay between retry attempts.
	RetryDelay time.Duration
}

type DistilledTask struct {
	// TaskID is the unique identifier for the task.
	TaskID string
	// Input is the original input.
	Input string
	// Output is the generated output.
	Output string
	// Context is the context information.
	Context string
	// Summary is the task summary.
	Summary string
	// Tags are tags associated with the task.
	Tags []string
	// Embedding is the vector embedding of the task.
	Embedding []float32
	// CreatedAt is the timestamp when the task was distilled.
	CreatedAt time.Time
}

type EmbeddingRequest struct {
	// Input is the text to embed.
	Input string
	// Model is the model to use (overrides config).
	Model string
}

type EmbeddingResponse struct {
	// Embedding is the generated embedding vector.
	Embedding []float32
	// Model is the model used for embedding.
	Model string
	// Usage contains token usage information.
	Usage TokenUsage
}

type FunctionCall struct {
	// Name is the function name.
	Name string
	// Arguments is the function arguments as JSON string.
	Arguments string
}

type FunctionDefinition struct {
	// Name is the function name.
	Name string
	// Description is the function description.
	Description string
	// Parameters is the JSON schema for parameters.
	Parameters map[string]interface{}
}

type GenerateRequest struct {
	// Messages is the conversation messages.
	Messages []*LLMMessage
	// Model is the model to use (overrides config).
	Model string
	// Temperature controls randomness (overrides config).
	Temperature *float64
	// MaxTokens is the maximum tokens to generate (overrides config).
	MaxTokens *int
	// Stream enables streaming responses.
	Stream bool
	// Tools are available tools for function calling.
	Tools []Tool
}

type GenerateResponse struct {
	// Content is the generated text content.
	Content string
	// FinishReason is the reason the generation finished.
	FinishReason string
	// Usage contains token usage information.
	Usage TokenUsage
	// ToolCalls contains tool calls made by the model.
	ToolCalls []ToolCall
	// Model is the model used for generation.
	Model string
}

type KnowledgeFilter struct {
	// Source filters by source.
	Source string
	// Category filters by category.
	Category string
	// Tags filters by tags.
	Tags []string
	// Pagination represents pagination parameters.
	Pagination *PaginationRequest
}

type KnowledgeItem struct {
	// ID is the unique identifier for the item.
	ID string
	// TenantID is the tenant identifier.
	TenantID string
	// Content is the item content.
	Content string
	// Source is the source of the item.
	Source string
	// Category is the category of the item.
	Category string
	// Tags are tags associated with the item.
	Tags []string
	// Embedding is the vector embedding of the content.
	Embedding []float32
	// CreatedAt is the timestamp when the item was created.
	CreatedAt int64
	// UpdatedAt is the timestamp when the item was last updated.
	UpdatedAt int64
	// Metadata is optional metadata.
	Metadata Metadata
}

type LLMConfig struct {
	// Provider is the LLM provider.
	Provider LLMProvider
	// APIKey is the API key for authentication.
	APIKey string
	// BaseURL is the base URL for the LLM API.
	BaseURL string
	// Model is the model name.
	Model string
	// Timeout is the request timeout in seconds.
	Timeout int
	// Temperature controls randomness (0.0-2.0).
	Temperature float64
	// MaxTokens is the maximum number of tokens to generate.
	MaxTokens int
	// TopP is the nucleus sampling parameter.
	TopP float64
	// FrequencyPenalty penalizes frequent tokens.
	FrequencyPenalty float64
	// PresencePenalty penalizes new tokens.
	PresencePenalty float64
}

type LLMMessage struct {
	// Role is the message role (system, user, assistant, tool).
	Role string
	// Content is the message content.
	Content string
	// ToolCalls contains tool/function call information (for assistant messages).
	ToolCalls []ToolCall
	// ToolCallID contains the tool call ID (for tool messages).
	ToolCallID string
}

type LLMProvider string

type LLMRepository interface {
	// LogGeneration logs a generation request and response.
	// Args:
	// ctx - operation context.
	// request - the generation request.
	// response - the generation response.
	// Returns error if logging fails.
	LogGeneration(ctx context.Context, request *GenerateRequest, response *GenerateResponse) error

	// GetGenerationLog retrieves a generation log.
	// Args:
	// ctx - operation context.
	// logID - the log identifier.
	// Returns the log or error if not found.
	GetGenerationLog(ctx context.Context, logID string) (*GenerateRequest, *GenerateResponse, error)
}

type LLMService interface {
	// Generate generates text from the given messages.
	// Args:
	// ctx - operation context.
	// request - the generation request.
	// Returns the generation response or error.
	Generate(ctx context.Context, request *GenerateRequest) (*GenerateResponse, error)

	// GenerateSimple generates text from a simple prompt.
	// Args:
	// ctx - operation context.
	// prompt - the prompt text.
	// Returns the generated text or error.
	GenerateSimple(ctx context.Context, prompt string) (string, error)

	// GenerateEmbedding generates an embedding for the given text.
	// Args:
	// ctx - operation context.
	// request - the embedding request.
	// Returns the embedding response or error.
	GenerateEmbedding(ctx context.Context, request *EmbeddingRequest) (*EmbeddingResponse, error)

	// GetConfig returns the current LLM configuration.
	// Returns the LLM configuration.
	GetConfig() *LLMConfig

	// IsEnabled checks if the LLM service is properly configured and available.
	// Returns true if enabled, false otherwise.
	IsEnabled() bool

	// GetProvider returns the current LLM provider.
	// Returns the provider type.
	GetProvider() LLMProvider

	// GetModel returns the current model name.
	// Returns the model name.
	GetModel() string
}

type MemoryRepository interface {
	// CreateSession creates a new session.
	// Args:
	// ctx - operation context.
	// session - the session to create.
	// Returns error if creation fails.
	CreateSession(ctx context.Context, session *Session) error

	// GetSession retrieves a session by ID.
	// Args:
	// ctx - operation context.
	// sessionID - the session identifier.
	// Returns the session or error if not found.
	GetSession(ctx context.Context, sessionID string) (*Session, error)

	// UpdateSession updates an existing session.
	// Args:
	// ctx - operation context.
	// session - the session to update.
	// Returns error if update fails.
	UpdateSession(ctx context.Context, session *Session) error

	// DeleteSession deletes a session and all its messages.
	// Args:
	// ctx - operation context.
	// sessionID - the session identifier.
	// Returns error if deletion fails.
	DeleteSession(ctx context.Context, sessionID string) error

	// AddMessage adds a message to a session.
	// Args:
	// ctx - operation context.
	// message - the message to add.
	// Returns error if addition fails.
	AddMessage(ctx context.Context, message *Message) error

	// GetMessages retrieves messages from a session.
	// Args:
	// ctx - operation context.
	// sessionID - the session identifier.
	// pagination - pagination parameters.
	// Returns list of messages or error.
	GetMessages(ctx context.Context, sessionID string, pagination *PaginationRequest) ([]*Message, error)

	// StoreDistilledTask stores a distilled task.
	// Args:
	// ctx - operation context.
	// task - the distilled task to store.
	// Returns error if storage fails.
	StoreDistilledTask(ctx context.Context, task *DistilledTask) error

	// GetDistilledTask retrieves a distilled task by ID.
	// Args:
	// ctx - operation context.
	// taskID - the task identifier.
	// Returns the distilled task or error if not found.
	GetDistilledTask(ctx context.Context, taskID string) (*DistilledTask, error)

	// SearchSimilarTasks searches for similar tasks.
	// Args:
	// ctx - operation context.
	// query - the search query.
	// Returns list of search results or error.
	SearchSimilarTasks(ctx context.Context, query *SearchQuery) ([]*SearchResult, error)
}

type MemoryService interface {
	// CreateSession creates a new session with the given configuration.
	// Args:
	// ctx - operation context.
	// config - the session configuration.
	// Returns the session ID or error.
	CreateSession(ctx context.Context, config *SessionConfig) (string, error)

	// GetSession retrieves a session by ID.
	// Args:
	// ctx - operation context.
	// sessionID - the session identifier.
	// Returns the session or error if not found.
	GetSession(ctx context.Context, sessionID string) (*Session, error)

	// DeleteSession deletes a session and all its messages.
	// Args:
	// ctx - operation context.
	// sessionID - the session identifier.
	// Returns error if deletion fails.
	DeleteSession(ctx context.Context, sessionID string) error

	// AddMessage adds a message to a session.
	// Args:
	// ctx - operation context.
	// sessionID - the session identifier.
	// role - the message role.
	// content - the message content.
	// Returns error if addition fails.
	AddMessage(ctx context.Context, sessionID string, role MessageRole, content string) error

	// GetMessages retrieves messages from a session.
	// Args:
	// ctx - operation context.
	// sessionID - the session identifier.
	// pagination - pagination parameters.
	// Returns list of messages or error.
	GetMessages(ctx context.Context, sessionID string, pagination *PaginationRequest) ([]*Message, error)

	// DistillTask distills a task for future reference.
	// Args:
	// ctx - operation context.
	// taskID - the task identifier.
	// Returns the distilled task or error.
	DistillTask(ctx context.Context, taskID string) (*DistilledTask, error)

	// SearchSimilarTasks searches for similar tasks.
	// Args:
	// ctx - operation context.
	// query - the search query.
	// Returns list of search results or error.
	SearchSimilarTasks(ctx context.Context, query *SearchQuery) ([]*SearchResult, error)
}

type Message struct {
	// ID is the unique identifier for the message.
	ID string
	// SessionID is the session this message belongs to.
	SessionID string
	// Role is the role of the message sender.
	Role MessageRole
	// Content is the message content.
	Content string
	// Time is the timestamp when the message was created.
	Time time.Time
	// Metadata is optional metadata.
	Metadata Metadata
}

type MessageRole string

type Metadata map[string]interface{}

type PaginationRequest struct {
	// Page is the page number (1-indexed).
	Page int
	// PageSize is the number of items per page.
	PageSize int
	// Offset is the number of items to skip.
	Offset int
	// Limit is the maximum number of items to return.
	Limit int
}

type PaginationResponse struct {
	// Total is the total number of items.
	Total int64
	// Page is the current page number.
	Page int
	// PageSize is the number of items per page.
	PageSize int
	// TotalPages is the total number of pages.
	TotalPages int
	// HasMore indicates if there are more pages.
	HasMore bool
}

type RequestContext struct {
	// Context is the standard Go context.
	Context context.Context
	// Tenant is the tenant context.
	Tenant *TenantContext
	// Metadata is optional metadata.
	Metadata Metadata
}

type RetrievalConfig struct {
	// Mode is the retrieval mode to use.
	Mode RetrievalMode
	// TopK is the number of top results to return.
	TopK int
	// MinScore is the minimum similarity score threshold.
	MinScore float64
	// Rerank enables reranking of results.
	Rerank bool
	// Filters are optional filter criteria.
	Filters map[string]interface{}
}

type RetrievalMode string

type RetrievalRepository interface {
	// CreateKnowledge creates a new knowledge item.
	// Args:
	// ctx - operation context.
	// item - the knowledge item to create.
	// Returns error if creation fails.
	CreateKnowledge(ctx context.Context, item *KnowledgeItem) error

	// GetKnowledge retrieves a knowledge item by ID.
	// Args:
	// ctx - operation context.
	// itemID - the knowledge item identifier.
	// Returns the knowledge item or error if not found.
	GetKnowledge(ctx context.Context, itemID string) (*KnowledgeItem, error)

	// UpdateKnowledge updates an existing knowledge item.
	// Args:
	// ctx - operation context.
	// item - the knowledge item to update.
	// Returns error if update fails.
	UpdateKnowledge(ctx context.Context, item *KnowledgeItem) error

	// DeleteKnowledge deletes a knowledge item by ID.
	// Args:
	// ctx - operation context.
	// itemID - the knowledge item identifier.
	// Returns error if deletion fails.
	DeleteKnowledge(ctx context.Context, itemID string) error

	// SearchKnowledge searches for knowledge items.
	// Args:
	// ctx - operation context.
	// query - the search query.
	// Returns list of search results or error.
	SearchKnowledge(ctx context.Context, request *RetrievalRequest) ([]*RetrievalResult, error)

	// ListKnowledge lists knowledge items with optional filtering.
	// Args:
	// ctx - operation context.
	// tenantID - the tenant identifier.
	// filter - optional filter criteria.
	// Returns list of knowledge items or error.
	ListKnowledge(ctx context.Context, tenantID string, filter *KnowledgeFilter) ([]*KnowledgeItem, error)
}

type RetrievalRequest struct {
	// TenantID is the tenant identifier for isolation.
	TenantID string
	// Query is the search query text.
	Query string
	// Config is the retrieval configuration.
	Config *RetrievalConfig
}

type RetrievalResult struct {
	// ID is the unique identifier for the result.
	ID string
	// Content is the retrieved content.
	Content string
	// Source is the source of the content.
	Source string
	// SubSource is the sub-source or category.
	SubSource string
	// Score is the similarity score.
	Score float64
	// Metadata is optional metadata.
	Metadata Metadata
}

type RetrievalService interface {
	// Search performs a knowledge base search.
	// Args:
	// ctx - operation context.
	// tenantID - the tenant identifier.
	// query - the search query text.
	// Returns list of retrieval results or error.
	Search(ctx context.Context, tenantID, query string) ([]*RetrievalResult, error)

	// SearchWithConfig performs search with custom configuration.
	// Args:
	// ctx - operation context.
	// request - the retrieval request.
	// Returns list of retrieval results or error.
	SearchWithConfig(ctx context.Context, request *RetrievalRequest) ([]*RetrievalResult, error)

	// AddKnowledge adds a new knowledge item.
	// Args:
	// ctx - operation context.
	// item - the knowledge item to add.
	// Returns the created item or error.
	AddKnowledge(ctx context.Context, item *KnowledgeItem) (*KnowledgeItem, error)

	// GetKnowledge retrieves a knowledge item by ID.
	// Args:
	// ctx - operation context.
	// tenantID - the tenant identifier.
	// itemID - the knowledge item identifier.
	// Returns the knowledge item or error if not found.
	GetKnowledge(ctx context.Context, tenantID, itemID string) (*KnowledgeItem, error)

	// UpdateKnowledge updates an existing knowledge item.
	// Args:
	// ctx - operation context.
	// tenantID - the tenant identifier.
	// item - the knowledge item to update.
	// Returns the updated item or error.
	UpdateKnowledge(ctx context.Context, tenantID string, item *KnowledgeItem) (*KnowledgeItem, error)

	// DeleteKnowledge deletes a knowledge item.
	// Args:
	// ctx - operation context.
	// tenantID - the tenant identifier.
	// itemID - the knowledge item identifier.
	// Returns error if deletion fails.
	DeleteKnowledge(ctx context.Context, tenantID, itemID string) error

	// ListKnowledge lists knowledge items with optional filtering.
	// Args:
	// ctx - operation context.
	// tenantID - the tenant identifier.
	// filter - optional filter criteria.
	// Returns list of knowledge items and pagination info, or error.
	ListKnowledge(ctx context.Context, tenantID string, filter *KnowledgeFilter) ([]*KnowledgeItem, *PaginationResponse, error)
}

type SearchQuery struct {
	// Query is the search query text.
	Query string
	// Limit is the maximum number of results to return.
	Limit int
	// MinScore is the minimum similarity score.
	MinScore float64
	// Tags filters by tags.
	Tags []string
}

type SearchResult struct {
	// TaskID is the task identifier.
	TaskID string
	// Input is the original input.
	Input string
	// Output is the generated output.
	Output string
	// Context is the context information.
	Context string
	// Summary is the task summary.
	Summary string
	// Score is the similarity score.
	Score float64
	// Tags are tags associated with the task.
	Tags []string
}

type Session struct {
	// ID is the unique identifier for the session.
	ID string
	// UserID is the user this session belongs to.
	UserID string
	// TenantID is the tenant this session belongs to.
	TenantID string
	// Status is the session status.
	Status string
	// CreatedAt is the timestamp when the session was created.
	CreatedAt time.Time
	// UpdatedAt is the timestamp when the session was last updated.
	UpdatedAt time.Time
	// ExpiresAt is the timestamp when the session expires.
	ExpiresAt *time.Time
	// Metadata is optional metadata.
	Metadata Metadata
}

type SessionConfig struct {
	// UserID is the user identifier.
	UserID string
	// TenantID is the tenant identifier.
	TenantID string
	// ExpiresIn is the session expiration duration.
	ExpiresIn time.Duration
	// Metadata is optional metadata.
	Metadata Metadata
}

type Task struct {
	// ID is the unique identifier for the task.
	ID string
	// AgentID is the agent that should execute this task.
	AgentID string
	// Type is the type of task.
	Type string
	// Payload is the task payload/data.
	Payload map[string]interface{}
	// Priority is the task priority (higher = more important).
	Priority int
	// Status is the task status.
	Status string
	// CreatedAt is the timestamp when the task was created.
	CreatedAt int64
	// StartedAt is the timestamp when the task was started.
	StartedAt int64
	// CompletedAt is the timestamp when the task was completed.
	CompletedAt int64
}

type TaskResult struct {
	// TaskID is the ID of the task.
	TaskID string
	// AgentID is the ID of the agent that executed the task.
	AgentID string
	// Success indicates whether the task was successful.
	Success bool
	// Data is the result data.
	Data map[string]interface{}
	// Error is the error message if the task failed.
	Error string
	// CompletedAt is the timestamp when the task was completed.
	CompletedAt int64
}

type TenantContext struct {
	// TenantID is the unique identifier for the tenant.
	TenantID string
	// UserID is the unique identifier for the user within the tenant.
	UserID string
	// TraceID is the unique trace ID for distributed tracing.
	TraceID string
}

type TokenUsage struct {
	// PromptTokens is the number of tokens in the prompt.
	PromptTokens int
	// CompletionTokens is the number of tokens in the completion.
	CompletionTokens int
	// TotalTokens is the total number of tokens.
	TotalTokens int
}

type Tool struct {
	// Type is the tool type (e.g., "function").
	Type string
	// Function contains the function definition.
	Function FunctionDefinition
}

type ToolCall struct {
	// ID is the unique identifier for the tool call.
	ID string
	// Type is the type of tool call (e.g., "function").
	Type string
	// Function contains the function call details.
	Function FunctionCall
}