ports

type CompletionChunk struct {
	Delta   string `json:"delta"`
	IsFinal bool   `json:"is_final"`
}

type CompletionRequest struct {
	// Messages is the conversation history.
	Messages []Message `json:"messages"`

	// Model is the identifier of the LLM model to use.
	Model string `json:"model"`

	// Temperature controls randomness in the response (0.0 to 1.0).
	Temperature float64 `json:"temperature,omitempty"`

	// MaxTokens is the maximum number of tokens to generate.
	MaxTokens int `json:"max_tokens,omitempty"`

	// TopP controls nucleus sampling (0.0 to 1.0).
	TopP float64 `json:"top_p,omitempty"`

	// Stop is a list of sequences where the LLM should stop generating.
	Stop []string `json:"stop,omitempty"`

	// PresencePenalty penalizes new tokens based on whether they appear in the text so far.
	PresencePenalty float64 `json:"presence_penalty,omitempty"`

	// FrequencyPenalty penalizes new tokens based on their frequency in the text so far.
	FrequencyPenalty float64 `json:"frequency_penalty,omitempty"`

	// User is an optional identifier representing the end-user.
	User string `json:"user,omitempty"`
}

type CompletionResponse struct {
	// ID is a unique identifier for this completion.
	ID string `json:"id"`

	// Model is the model that generated this completion.
	Model string `json:"model"`

	// Message is the generated message.
	Message Message `json:"message"`

	// ToolCalls contains any tool calls requested by the LLM.
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`

	// FinishReason indicates why the generation stopped.
	FinishReason string `json:"finish_reason"`

	// Usage contains token usage information.
	Usage UsageInfo `json:"usage"`

	// CreatedAt is the timestamp when this completion was created.
	CreatedAt time.Time `json:"created_at"`
}

type Event struct {
	// ID is a unique identifier for this event.
	ID string `json:"id"`

	// Type is the type of event.
	Type EventType `json:"type"`

	// Timestamp is when the event occurred.
	Timestamp time.Time `json:"timestamp"`

	// ExecutionID is the ID of the graph execution this event relates to.
	ExecutionID string `json:"execution_id"`

	// NodeID is the ID of the node this event relates to (if applicable).
	NodeID string `json:"node_id,omitempty"`

	// Data contains event-specific payload data.
	Data map[string]interface{} `json:"data,omitempty"`

	// Metadata contains additional event metadata.
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type EventBus interface {
	// Publish sends an event to a topic.
	Publish(ctx context.Context, topic string, event Event) error

	// Subscribe registers a handler for events on a topic.
	// The handler will be called for each event received.
	Subscribe(ctx context.Context, topic string, handler EventHandler) error

	// Unsubscribe removes a subscription from a topic.
	Unsubscribe(ctx context.Context, topic string) error

	// Close closes the event bus and cleans up resources.
	Close() error
}

type EventFilter struct {
	// Types filters events by type. If empty, all types are included.
	Types []EventType `json:"types,omitempty"`

	// ExecutionID filters events by execution ID.
	ExecutionID string `json:"execution_id,omitempty"`

	// NodeID filters events by node ID.
	NodeID string `json:"node_id,omitempty"`

	// Since filters events after this timestamp.
	Since time.Time `json:"since,omitempty"`

	// Until filters events before this timestamp.
	Until time.Time `json:"until,omitempty"`
}

type EventHandler func(ctx context.Context, event Event) error

type EventStore interface {
	// Store persists an event.
	Store(ctx context.Context, event Event) error

	// Query retrieves events matching the filter criteria.
	Query(ctx context.Context, filter EventFilter) ([]Event, error)

	// GetByID retrieves an event by its ID.
	GetByID(ctx context.Context, id string) (*Event, error)

	// GetByExecutionID retrieves all events for a specific execution.
	GetByExecutionID(ctx context.Context, executionID string) ([]Event, error)
}

type EventType string

type ExecutionMetadata struct {
	// ExecutionID is the unique identifier for this execution.
	ExecutionID string `json:"execution_id"`

	// GraphID is the ID of the graph being executed.
	GraphID string `json:"graph_id"`

	// Status is the current status of the execution.
	Status ExecutionStatus `json:"status"`

	// StartedAt is when the execution started.
	StartedAt time.Time `json:"started_at"`

	// CompletedAt is when the execution completed (if finished).
	CompletedAt *time.Time `json:"completed_at,omitempty"`

	// CurrentNodeID is the ID of the currently executing node.
	CurrentNodeID string `json:"current_node_id,omitempty"`

	// Error contains error information if the execution failed.
	Error string `json:"error,omitempty"`

	// Metadata contains additional execution-specific data.
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type ExecutionStatus string

type ExecutionStorage interface {
	// Save persists execution metadata.
	Save(ctx context.Context, metadata ExecutionMetadata) error

	// Load retrieves execution metadata.
	Load(ctx context.Context, executionID string) (*ExecutionMetadata, error)

	// UpdateStatus updates the status of an execution.
	UpdateStatus(ctx context.Context, executionID string, status ExecutionStatus) error

	// List returns all execution metadata, optionally filtered by status.
	List(ctx context.Context, status *ExecutionStatus) ([]ExecutionMetadata, error)

	// Delete removes execution metadata.
	Delete(ctx context.Context, executionID string) error
}

type GraphStorage interface {
	// Save persists a graph definition.
	Save(ctx context.Context, graphID string, graphData []byte) error

	// Load retrieves a graph definition.
	Load(ctx context.Context, graphID string) ([]byte, error)

	// Delete removes a graph definition.
	Delete(ctx context.Context, graphID string) error

	// Exists checks if a graph definition exists.
	Exists(ctx context.Context, graphID string) (bool, error)

	// List returns all stored graph IDs.
	List(ctx context.Context) ([]string, error)

	// ListVersions returns all versions of a graph (if versioning is supported).
	ListVersions(ctx context.Context, graphName string) ([]string, error)
}

type HealthCheck struct {
	// Name is the identifier for this health check.
	Name string `json:"name"`

	// Status indicates whether the component is healthy.
	Status HealthStatus `json:"status"`

	// Message provides additional details.
	Message string `json:"message,omitempty"`

	// LastChecked is when this health check was last performed.
	LastChecked time.Time `json:"last_checked"`
}

type HealthChecker interface {
	// Check performs a health check and returns the result.
	Check(ctx context.Context) HealthCheck

	// Name returns the name of this health check.
	Name() string
}

type HealthRegistry interface {
	// Register adds a health checker.
	Register(checker HealthChecker) error

	// Unregister removes a health checker.
	Unregister(name string) error

	// CheckAll runs all registered health checks.
	CheckAll(ctx context.Context) []HealthCheck

	// Check runs a specific health check by name.
	Check(ctx context.Context, name string) (*HealthCheck, error)
}

type HealthStatus string

type JSONSchema map[string]interface{}

type LLMClient interface {
	// Complete performs a standard text completion.
	Complete(ctx context.Context, req CompletionRequest) (*CompletionResponse, error)

	// CompleteWithTools performs a completion with tool calling support.
	// The LLM can request tool executions via ToolCall objects in the response.
	CompleteWithTools(ctx context.Context, req CompletionRequest, tools []Tool) (*CompletionResponse, error)

	// CompleteStructured performs a completion with guaranteed JSON schema conformance.
	// The response will be validated against the provided schema.
	CompleteStructured(ctx context.Context, req CompletionRequest, schema JSONSchema) (*StructuredResponse, error)

	// GenerateCompletion performs a generation using domain.LLMRequest (compatibility method).
	GenerateCompletion(ctx context.Context, req interface{}) (interface{}, error)
}

type Message struct {
	// Role is the role of the message sender (e.g., "system", "user", "assistant").
	Role string `json:"role"`

	// Content is the text content of the message.
	Content string `json:"content"`

	// Name is an optional name for the message sender.
	Name string `json:"name,omitempty"`
}

type MetricsCollector interface {

	// IncGraphsSubmitted increments the count of submitted graphs.
	IncGraphsSubmitted(labels map[string]string)

	// IncGraphsCompleted increments the count of completed graphs.
	IncGraphsCompleted(labels map[string]string)

	// IncGraphsFailed increments the count of failed graphs.
	IncGraphsFailed(labels map[string]string)

	// IncNodesExecuted increments the count of executed nodes.
	IncNodesExecuted(nodeType string, labels map[string]string)

	// IncNodesFailed increments the count of failed nodes.
	IncNodesFailed(nodeType string, labels map[string]string)

	// IncToolExecutions increments the count of tool executions.
	IncToolExecutions(toolName string, labels map[string]string)

	// IncToolFailures increments the count of tool failures.
	IncToolFailures(toolName string, labels map[string]string)

	// IncLLMCalls increments the count of LLM API calls.
	IncLLMCalls(model string, labels map[string]string)

	// IncLLMTokens increments the count of LLM tokens used.
	IncLLMTokens(model string, tokenType string, count int, labels map[string]string)

	// SetWorkerCount sets the current number of workers for a node type.
	SetWorkerCount(nodeType string, count int)

	// SetQueueDepth sets the current depth of the execution queue.
	SetQueueDepth(queueName string, depth int)

	// SetActiveExecutions sets the number of currently active executions.
	SetActiveExecutions(count int)

	// ObserveGraphDuration records the duration of a graph execution.
	ObserveGraphDuration(duration time.Duration, labels map[string]string)

	// ObserveNodeDuration records the duration of a node execution.
	ObserveNodeDuration(nodeType string, duration time.Duration, labels map[string]string)

	// ObserveToolDuration records the duration of a tool execution.
	ObserveToolDuration(toolName string, duration time.Duration, labels map[string]string)

	// ObserveLLMLatency records the latency of an LLM API call.
	ObserveLLMLatency(model string, duration time.Duration, labels map[string]string)

	// ObserveQueueWaitTime records how long an execution waited in the queue.
	ObserveQueueWaitTime(duration time.Duration, labels map[string]string)

	// RecordGraphSubmitted records a graph submission (compatibility method).
	RecordGraphSubmitted(status string)

	// RecordGraphCompleted records a graph completion (compatibility method).
	RecordGraphCompleted(status string, duration time.Duration)

	// RecordNodeExecuted records a node execution (compatibility method).
	RecordNodeExecuted(status string, duration time.Duration)

	// RecordWorkerPoolStatus records worker pool status (compatibility method).
	RecordWorkerPoolStatus(idle, busy, stopped int)
}

type MetricsConfig struct {
	// Enabled controls whether metrics collection is active.
	Enabled bool `json:"enabled"`

	// Port is the HTTP port for the metrics endpoint.
	Port int `json:"port"`

	// Path is the HTTP path for the metrics endpoint (e.g., "/metrics").
	Path string `json:"path"`

	// Namespace is a prefix for all metric names.
	Namespace string `json:"namespace"`

	// Subsystem is a secondary prefix for metric names.
	Subsystem string `json:"subsystem"`
}

type StateStorage interface {
	// Save persists the state for an execution.
	Save(ctx context.Context, executionID string, state state.State) error

	// Load retrieves the state for an execution.
	Load(ctx context.Context, executionID string) (state.State, error)

	// Delete removes the state for an execution.
	Delete(ctx context.Context, executionID string) error

	// Exists checks if state exists for an execution.
	Exists(ctx context.Context, executionID string) (bool, error)

	// SetTTL sets a time-to-live for state data.
	// After the TTL expires, the state will be automatically deleted.
	SetTTL(ctx context.Context, executionID string, ttl time.Duration) error

	// List returns all execution IDs that have stored state.
	List(ctx context.Context) ([]string, error)

	// SaveState persists graph state (compatibility method).
	SaveState(ctx context.Context, state interface{}) error

	// GetState retrieves graph state (compatibility method).
	GetState(ctx context.Context, graphID string) (interface{}, error)
}

type StructuredResponse struct {
	// Data contains the structured data conforming to the provided schema.
	Data map[string]interface{} `json:"data"`

	// Usage contains token usage information.
	Usage UsageInfo `json:"usage"`

	// CreatedAt is the timestamp when this response was created.
	CreatedAt time.Time `json:"created_at"`
}

type Tool struct {
	// Name is the unique identifier for the tool.
	Name string `json:"name"`

	// Description explains what the tool does.
	Description string `json:"description"`

	// Parameters is a JSON schema defining the tool's input parameters.
	Parameters map[string]interface{} `json:"parameters"`
}

type ToolCall struct {
	// ID is a unique identifier for this tool call.
	ID string `json:"id"`

	// Name is the name of the tool to call.
	Name string `json:"name"`

	// Arguments contains the tool call arguments as a JSON object.
	Arguments map[string]interface{} `json:"arguments"`
}

type ToolConfig struct {
	// Timeout is the maximum execution time for tools.
	Timeout time.Duration `json:"timeout"`

	// MaxRetries is the number of retry attempts on failure.
	MaxRetries int `json:"max_retries"`

	// RetryDelay is the delay between retry attempts.
	RetryDelay time.Duration `json:"retry_delay"`

	// Sandbox enables sandboxed execution for security.
	Sandbox bool `json:"sandbox"`

	// Environment contains environment variables for tool execution.
	Environment map[string]string `json:"environment,omitempty"`
}

type ToolExecutor interface {
	// Execute runs the tool with the given parameters.
	Execute(ctx context.Context, params map[string]interface{}) (*ToolResult, error)

	// Schema returns the tool's schema definition.
	Schema() *ToolSchema

	// Type returns the type of this tool.
	Type() ToolType

	// Validate checks if the given parameters are valid for this tool.
	Validate(params map[string]interface{}) error
}

type ToolRegistry interface {
	// Register adds a tool executor to the registry.
	Register(name string, executor ToolExecutor) error

	// Get retrieves a tool executor by name.
	Get(name string) (ToolExecutor, error)

	// List returns all registered tool names.
	List() []string

	// Unregister removes a tool executor from the registry.
	Unregister(name string) error

	// GetByType returns all tools of a specific type.
	GetByType(toolType ToolType) []ToolExecutor
}

type ToolResult struct {
	// Success indicates whether the tool executed successfully.
	Success bool `json:"success"`

	// Output contains the tool's output data.
	Output map[string]interface{} `json:"output,omitempty"`

	// Error contains error information if the tool failed.
	Error string `json:"error,omitempty"`

	// ExecutionTime is the duration of the tool execution.
	ExecutionTime time.Duration `json:"execution_time"`

	// Metadata contains additional execution metadata.
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type ToolSchema struct {
	// Name is the unique identifier for the tool.
	Name string `json:"name"`

	// Description explains what the tool does.
	Description string `json:"description"`

	// InputSchema is a JSON schema defining the tool's input parameters.
	InputSchema map[string]interface{} `json:"input_schema"`

	// OutputSchema is a JSON schema defining the tool's output format.
	OutputSchema map[string]interface{} `json:"output_schema,omitempty"`
}

type ToolType string

type UsageInfo struct {
	// PromptTokens is the number of tokens in the prompt.
	PromptTokens int `json:"prompt_tokens"`

	// CompletionTokens is the number of tokens in the completion.
	CompletionTokens int `json:"completion_tokens"`

	// TotalTokens is the total number of tokens used.
	TotalTokens int `json:"total_tokens"`
}

type WorkerFilter struct {
	// Types filters workers by type. If empty, all types are included.
	Types []WorkerType `json:"types,omitempty"`

	// Statuses filters workers by status. If empty, all statuses are included.
	Statuses []WorkerStatus `json:"statuses,omitempty"`

	// HealthyOnly if true, only returns workers with recent heartbeats.
	HealthyOnly bool `json:"healthy_only,omitempty"`
}

type WorkerInfo struct {
	// ID is the unique identifier for this worker.
	ID string `json:"id"`

	// Type is the type of worker (executor or router).
	Type WorkerType `json:"type"`

	// Status is the current status of the worker.
	Status WorkerStatus `json:"status"`

	// RegisteredAt is when the worker was first registered.
	RegisteredAt time.Time `json:"registered_at"`

	// LastHeartbeat is the timestamp of the last heartbeat received.
	LastHeartbeat time.Time `json:"last_heartbeat"`

	// CurrentTask is the ID of the task currently being processed (if any).
	CurrentTask string `json:"current_task,omitempty"`

	// PendingTasks is the number of tasks pending in this worker's queue.
	PendingTasks int `json:"pending_tasks"`

	// Version is the worker's software version.
	Version string `json:"version,omitempty"`

	// Metadata contains additional worker-specific information.
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type WorkerRegistry interface {
	// Register registers a new worker in the system.
	// This should be called when a worker starts up.
	Register(ctx context.Context, worker WorkerInfo) error

	// Unregister removes a worker from the registry.
	// This should be called when a worker shuts down gracefully.
	Unregister(ctx context.Context, workerID string) error

	// Heartbeat updates the last heartbeat timestamp for a worker.
	// This should be called periodically (e.g., every 5-10 seconds) to indicate
	// that the worker is still alive.
	Heartbeat(ctx context.Context, workerID string, status WorkerStatus, currentTask string) error

	// GetWorker retrieves information about a specific worker.
	GetWorker(ctx context.Context, workerID string) (*WorkerInfo, error)

	// ListWorkers retrieves all workers matching the filter criteria.
	ListWorkers(ctx context.Context, filter WorkerFilter) ([]WorkerInfo, error)

	// GetWorkerStats returns aggregate statistics about workers.
	GetWorkerStats(ctx context.Context, workerType WorkerType) (*WorkerStats, error)

	// CleanupStaleWorkers removes workers that haven't sent a heartbeat
	// within the specified timeout duration.
	// This is typically called periodically by the orchestrator.
	CleanupStaleWorkers(ctx context.Context, timeout time.Duration) (int, error)
}

type WorkerStats struct {
	// Type is the worker type these stats refer to.
	Type WorkerType `json:"type"`

	// TotalWorkers is the total number of registered workers.
	TotalWorkers int `json:"total_workers"`

	// IdleWorkers is the number of workers in idle status.
	IdleWorkers int `json:"idle_workers"`

	// BusyWorkers is the number of workers in busy status.
	BusyWorkers int `json:"busy_workers"`

	// UnhealthyWorkers is the number of workers in unhealthy status.
	UnhealthyWorkers int `json:"unhealthy_workers"`

	// TotalPendingTasks is the total number of pending tasks across all workers.
	TotalPendingTasks int `json:"total_pending_tasks"`
}

type WorkerStatus string

type WorkerType string