agent

type AdHocAgent struct {
	Name    string
	Handler func(ctx context.Context, args map[string]interface{}) (string, error)
}

type AddArgs struct {
	Database string         `json:"database,omitempty" example:"dev_db"`
	Store    string         `json:"store" binding:"required" example:"users"`
	Key      any            `json:"key" binding:"required" example:"user_123"`
	Value    map[string]any `json:"value" binding:"required"`
}

type AskRequest struct {
	// Query is the user's input question or command
	Query string

	// Session holds the current session state including transactions, variables, and database context
	Session *ai.SessionPayload

	// Executor is the tool executor for running tool calls during ReAct loops
	Executor ai.ToolExecutor

	// Generator optionally overrides the default LLM provider
	Generator ai.Generator

	// ProviderOverride optionally provides runtime provider configuration (provider, model, API key, base URL)
	ProviderOverride *ProviderDetails

	// Database optionally overrides the session's current database
	Database *database.Database

	// Writer is the output destination for streaming responses
	Writer io.Writer

	// EventStreamer receives structured events during reasoning (tool calls, progress, etc.)
	EventStreamer func(eventType string, data any)

	// ProgressSink receives progress messages during execution
	ProgressSink func(message string)

	// ScriptRecorder captures executed script steps for playback or audit
	ScriptRecorder ai.ScriptRecorder

	// DefaultFormat sets the default output format for tools (csv, json, etc.)
	DefaultFormat string

	// Options carries additional configuration from ConfigMap
	Options *ai.ConfigMap
}

type AskResponse struct {
	// FinalText is the assistant's answer to the user
	FinalText string

	// UpdatedSession contains any session state changes (updated transactions, variables, etc.)
	UpdatedSession *ai.SessionPayload

	// CarryoverState holds provider-specific continuation state for next Ask
	CarryoverState *ai.CarryoverState

	// ToolCalls lists all tools executed during the Ask for audit/logging
	ToolCalls []ai.ToolCall

	// OutcomeFacts contains compact grounded facts safe to carry into MRU continuity
	OutcomeFacts []string

	// OutcomeRecipes contains learned patterns distilled from this Ask
	OutcomeRecipes []ai.LearnedRecipe
}

type BaselineReActEngine struct {
	Agent *CopilotAgent
}

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

type BulkAddArgs struct {
	Database        string          `json:"database,omitempty" example:"dev_db"`
	Store           string          `json:"store" binding:"required" example:"users"`
	Items           []BulkItem      `json:"items" binding:"required"`
	TransactionID   string          `json:"transaction_id,omitempty"` // Use existing transaction
	TransactionMode TransactionMode `json:"transaction_mode,omitempty" default:"auto_batch" enums:"auto_batch,explicit,single"`
	BatchSize       int             `json:"batch_size,omitempty" default:"100" example:"250"`
}

type BulkDeleteArgs struct {
	Database        string          `json:"database,omitempty" example:"dev_db"`
	Store           string          `json:"store" binding:"required" example:"users"`
	Keys            []any           `json:"keys" binding:"required"`
	TransactionID   string          `json:"transaction_id,omitempty"`
	TransactionMode TransactionMode `json:"transaction_mode,omitempty" default:"auto_batch" enums:"auto_batch,explicit,single"`
	BatchSize       int             `json:"batch_size,omitempty" default:"100" example:"250"`
}

type BulkDeleteCategoriesArgs struct {
	Database        string          `json:"database,omitempty" example:"dev_db"`
	KBName          string          `json:"kb_name" binding:"required" example:"Notes"`
	CategoryIDs     []sop.UUID      `json:"category_ids" binding:"required"`
	TransactionID   string          `json:"transaction_id,omitempty"`
	TransactionMode TransactionMode `json:"transaction_mode,omitempty" default:"single" enums:"single,explicit"`
}

type BulkDeleteItemsArgs struct {
	Database        string          `json:"database,omitempty" example:"dev_db"`
	KBName          string          `json:"kb_name" binding:"required" example:"Notes"`
	CategoryID      sop.UUID        `json:"category_id" binding:"required"`
	ItemIDs         []sop.UUID      `json:"item_ids" binding:"required"`
	TransactionID   string          `json:"transaction_id,omitempty"`
	TransactionMode TransactionMode `json:"transaction_mode,omitempty" default:"single" enums:"single,explicit"`
}

type BulkItem struct {
	Key   any            `json:"key" binding:"required" example:"user_123"`
	Value map[string]any `json:"value" binding:"required"`
}

type BulkOperationError struct {
	Index   int    `json:"index"`
	Key     any    `json:"key,omitempty"`
	Message string `json:"message"`
}

type BulkOperationMetrics struct {
	TotalItems      int           `json:"total_items"`
	BatchesExecuted int           `json:"batches_executed"`
	AvgBatchTime    time.Duration `json:"avg_batch_time"`
	ItemsPerSecond  float64       `json:"items_per_second"`
}

type BulkOperationResult struct {
	Success                bool                 `json:"success"`
	Processed              int                  `json:"processed"`
	Failed                 int                  `json:"failed"`
	Duration               time.Duration        `json:"duration"`
	Errors                 []BulkOperationError `json:"errors,omitempty"`
	Metrics                BulkOperationMetrics `json:"metrics"`
	TransactionsCreated    int                  `json:"transactions_created"`     // For auto_batch mode
	TransactionsCommitted  int                  `json:"transactions_committed"`   // For auto_batch mode
	TransactionsRolledBack int                  `json:"transactions_rolled_back"` // On error
}

type BulkUpdateArgs struct {
	Database        string          `json:"database,omitempty" example:"dev_db"`
	Store           string          `json:"store" binding:"required" example:"users"`
	Items           []BulkItem      `json:"items" binding:"required"`
	TransactionID   string          `json:"transaction_id,omitempty"`
	TransactionMode TransactionMode `json:"transaction_mode,omitempty" default:"auto_batch" enums:"auto_batch,explicit,single"`
	BatchSize       int             `json:"batch_size,omitempty" default:"100" example:"250"`
}

type BulkUpsertCategoriesArgs struct {
	Database        string                       `json:"database,omitempty" example:"dev_db"`
	KBName          string                       `json:"kb_name" binding:"required" example:"Notes"`
	Parameters      []memory.UpsertCategoryParam `json:"parameters" binding:"required"`
	TransactionID   string                       `json:"transaction_id,omitempty"`
	TransactionMode TransactionMode              `json:"transaction_mode,omitempty" default:"single" enums:"single,explicit"`
}

type BulkUpsertItemsArgs struct {
	Database        string                                   `json:"database,omitempty" example:"dev_db"`
	KBName          string                                   `json:"kb_name" binding:"required" example:"Notes"`
	Parameters      []memory.UpsertItemParam[map[string]any] `json:"parameters" binding:"required"`
	TransactionID   string                                   `json:"transaction_id,omitempty"`
	TransactionMode TransactionMode                          `json:"transaction_mode,omitempty" default:"single" enums:"single,explicit"`
}

type BulkVectorizeCategoriesArgs struct {
	Database    string     `json:"database,omitempty" example:"dev_db"`
	KBName      string     `json:"kb_name" binding:"required" example:"Notes"`
	CategoryIDs []sop.UUID `json:"category_ids" binding:"required"`
	BatchSize   int        `json:"batch_size,omitempty" default:"100" example:"250"`
}

type BulkVectorizeItemsArgs struct {
	Database   string     `json:"database,omitempty" example:"dev_db"`
	KBName     string     `json:"kb_name" binding:"required" example:"Notes"`
	CategoryID *sop.UUID  `json:"category_id,omitempty"`
	ItemIDs    []sop.UUID `json:"item_ids,omitempty"`
	BatchSize  int        `json:"batch_size,omitempty" default:"100" example:"250"`
}

type CachedScript struct {
	Script CompiledScript
	Hash   string
}

type CategoryListResult struct {
	Categories []memory.Category `json:"categories"`
	Total      int               `json:"total"`
}

type CompiledScript func(ctx context.Context, e *ScriptEngine) error

type Config struct {
	ID                    string            `json:"id"`
	Type                  string            `json:"type,omitempty"` // "standard" (default), "copilot", "policy", etc.
	Name                  string            `json:"name"`
	Description           string            `json:"description"`
	UserPrompt            string            `json:"user_prompt,omitempty"`    // Optional: Custom prompt for the interactive loop (e.g. "Patient> ")
	AssistantName         string            `json:"assistant_name,omitempty"` // Optional: Custom name for the assistant (e.g. "AI Doctor")
	Synonyms              map[string]string `json:"synonyms"`
	SystemPrompt          string            `json:"system_prompt"`
	Policies              []PolicyConfig    `json:"policies"`
	ETL                   ETLConfig         `json:"etl,omitempty"`                     // Configuration for the ETL/Curator pipeline
	Embedder              EmbedderConfig    `json:"embedder,omitempty"`                // Configuration for the embedder
	Generator             GeneratorConfig   `json:"generator,omitempty"`               // Configuration for the LLM generator
	Data                  []DataItem        `json:"data"`                              // For seeding (MVP)
	StoragePath           string            `json:"storage_path,omitempty"`            // Optional: Override default storage path. Will be converted to absolute path.
	DBType                string            `json:"db_type,omitempty"`                 // Optional: "standalone" (default) or "clustered"
	ContentSize           string            `json:"content_size,omitempty"`            // Optional: "small", "medium", "big". Defaults to "medium".
	SkipDeduplication     bool              `json:"skip_deduplication,omitempty"`      // Optional: Skip deduplication phase
	EnableIngestionBuffer bool              `json:"enable_ingestion_buffer,omitempty"` // Optional: Enable Stage 0 buffering for faster ingestion
	Verbose               bool              `json:"verbose,omitempty"`                 // Optional: Enable verbose output (e.g. tool instructions)
	// Cognitive Memory Consolidation (STM to LTM)
	SleepCycleIntervalHours int            `json:"sleep_cycle_interval_hours,omitempty"` // e.g. 1 (run every X hours on the clock). 0 disables hourly.
	IdleSleepTimeoutMinutes int            `json:"idle_sleep_timeout_minutes,omitempty"` // e.g. 5 (run cycle after X minutes of avatar inactivity).
	StubMode                bool           `json:"stub_mode,omitempty"`                  // Optional: If true, tools will return success without executing (for debugging LLM output)
	Agents                  []Config       `json:"agents,omitempty"`                     // Optional: Define agents locally to be referenced by ID
	Pipeline                []PipelineStep `json:"pipeline,omitempty"`                   // Optional: Define a chain of agents
	Params                  map[string]any `json:"params,omitempty"`                     // Type-specific configuration parameters
}

type ConversationRole string

type ConversationThread struct {
	ID         sop.UUID `json:"id"`
	RootPrompt string   `json:"root_prompt"` // The seed sentence that started this thread

	// Transcribed Context (Managed by LLM)
	Label        string `json:"label"`         // Short Topic Name (e.g. "Defining Client")
	Category     string `json:"category"`      // e.g. "Business Logic", "Clarification"
	ContextNotes string `json:"context_notes"` // Important notes/context for the LLM

	// The linear exchange of Q&A within this topic
	Exchanges []Interaction `json:"exchanges"`

	// Termination
	Conclusion string `json:"conclusion"` // Summary or Agreement
	Status     string `json:"status"`     // "active", "concluded"
}

type CopilotAgent struct {
	Config Config

	// Encapsulated memory and context boundaries
	Memory *memory.MemoryUnit

	// StoreOpener allows mocking the store creation (e.g. for testing)
	StoreOpener func(ctx context.Context, dbOpts sop.DatabaseOptions, storeName string, tx sop.Transaction) (jsondb.StoreAccessor, error)
	// contains filtered or unexported fields
}

type CreateSpaceArgs struct {
	Database string `json:"database,omitempty" example:"dev_db"`
	KBName   string `json:"kb_name" binding:"required" example:"Notes"`
}

type CuratorConfig struct {
	Type    string         `json:"type"`              // "ollama", "agent"
	ID      string         `json:"id,omitempty"`      // ID of the agent to use (if type="agent")
	Options map[string]any `json:"options,omitempty"` // e.g. {"model": "llama3"}
	Prompt  string         `json:"prompt,omitempty"`  // The instruction for curation
}

type DataItem struct {
	ID          string         `json:"id"`
	Text        string         `json:"text"`
	Description string         `json:"description"`
	Category    string         `json:"category,omitempty"`
	Payload     map[string]any `json:"payload,omitempty"` // Generic payload for structured data (e.g. JSON objects)
}

type Database interface {
	BeginTransaction(ctx context.Context, mode sop.TransactionMode, maxTime ...time.Duration) (sop.Transaction, error)
	Config() sop.DatabaseOptions
}

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

type DeleteArgs struct {
	Database string `json:"database,omitempty" example:"dev_db"`
	Store    string `json:"store" binding:"required" example:"users"`
	Key      any    `json:"key" binding:"required" example:"user_123"`
}

type DeleteCategoryArgs struct {
	Database      string   `json:"database,omitempty" example:"dev_db"`
	KBName        string   `json:"kb_name" binding:"required" example:"Notes"`
	CategoryID    sop.UUID `json:"category_id" binding:"required"`
	TransactionID string   `json:"transaction_id,omitempty"`
}

type DeleteItemArgs struct {
	Database      string   `json:"database,omitempty" example:"dev_db"`
	KBName        string   `json:"kb_name" binding:"required" example:"Notes"`
	CategoryID    sop.UUID `json:"category_id" binding:"required"`
	ItemID        sop.UUID `json:"item_id" binding:"required"`
	TransactionID string   `json:"transaction_id,omitempty"`
}

type DeleteSpaceArgs struct {
	Database string `json:"database,omitempty" example:"dev_db"`
	KBName   string `json:"kb_name" binding:"required" example:"Notes"`
}

type Dependencies struct {
	AgentRegistry map[string]ai.Agent[map[string]any]
	SystemDB      *database.Database
	Databases     map[string]sop.DatabaseOptions
}

type ETLConfig struct {
	Curator CuratorConfig `json:"curator,omitempty"`
}

type EmbedderConfig struct {
	Type        string         `json:"type"`              // "simple" (default), "agent", "ollama", "gemini", or "local"
	AgentID     string         `json:"agent_id"`          // For "agent" type: ID of the agent to use
	Instruction string         `json:"instruction"`       // For "agent" type: Instruction for the agent
	Options     map[string]any `json:"options,omitempty"` // For "local" type: model_path, provider, gpu_layers
}

type EnrichSpaceArgs struct {
	Database string `json:"database,omitempty" example:"dev_db"`
	KBName   string `json:"kb_name" binding:"required" example:"Notes"`
}

type ErrorResponse struct {
	Error   string `json:"error" example:"store is required"`
	Code    string `json:"code,omitempty" example:"INVALID_REQUEST"`
	Details any    `json:"details,omitempty"`
}

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

type ExecuteScriptArgs struct {
	Database string              `json:"database,omitempty" example:"dev_db"`
	Script   []ScriptInstruction `json:"script" binding:"required"`
}

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

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

type Flusher interface {
	Flush()
}

type GeneratorConfig struct {
	Type    string         `json:"type"`              // "ollama", "gemini", "chatgpt"
	Options map[string]any `json:"options,omitempty"` // Generator-specific options (model, api_key, etc.)
}

type Interaction struct {
	Role      ConversationRole `json:"role"`
	Content   string           `json:"content"`
	Timestamp int64            `json:"timestamp"`
	Entity    string           `json:"entity,omitempty"`    // OMNI or Avatar name
	ActiveKB  string           `json:"active_kb,omitempty"` // The target KB evaluated in this sequence
}

type ItemListResult struct {
	Items []memory.Item[map[string]any] `json:"items"`
	Total int                           `json:"total"`
}

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

type JoinArgs struct {
	Database        string         `json:"database,omitempty" example:"dev_db"`
	LeftStore       string         `json:"left_store" binding:"required" example:"users"`
	RightStore      string         `json:"right_store" binding:"required" example:"orders"`
	LeftJoinFields  []string       `json:"left_join_fields" binding:"required" example:"user_id"`
	RightJoinFields []string       `json:"right_join_fields" binding:"required" example:"user_id"`
	JoinType        string         `json:"join_type,omitempty" default:"inner" enums:"inner,left,right"`
	Fields          []string       `json:"fields,omitempty"`
	Limit           int            `json:"limit,omitempty" default:"10"`
	Direction       string         `json:"direction,omitempty" enums:"asc,desc"`
	Action          string         `json:"action,omitempty" enums:"delete_left,update_left"`
	UpdateValues    map[string]any `json:"update_values,omitempty"`
}

type JoinPlan struct {
	Strategy     int
	IndexFields  []string // Ordered list of fields in the Index
	PrefixFields []string // Fields from ON clause that match the Index Prefix
	IsComposite  bool     // True if the Store uses a Map Key (Composite)
	Ascending    bool     // True if the first prefix field is Ascending
}

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

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

type KnowledgeChunk struct {
	Category string `json:"category"`
	Title    string `json:"title"`
	Content  string `json:"content"`
}

type LayerInfo struct {
	Name string   `json:"name"`
	CRUD []string `json:"crud"`
}

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

type ListCategoriesArgs struct {
	Database      string `json:"database,omitempty" example:"dev_db"`
	KBName        string `json:"kb_name" binding:"required" example:"Notes"`
	Limit         int    `json:"limit,omitempty" default:"100" example:"50"`
	Offset        int    `json:"offset,omitempty" default:"0" example:"0"`
	ParentPath    string `json:"parent_path,omitempty" example:"Root/SubCategory"`
	TransactionID string `json:"transaction_id,omitempty"`
}

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

type ListItemsArgs struct {
	Database      string   `json:"database,omitempty" example:"dev_db"`
	KBName        string   `json:"kb_name" binding:"required" example:"Notes"`
	CategoryID    sop.UUID `json:"category_id,omitempty"`
	Limit         int      `json:"limit,omitempty" default:"100" example:"50"`
	Offset        int      `json:"offset,omitempty" default:"0" example:"0"`
	TransactionID string   `json:"transaction_id,omitempty"`
}

type MRUItem struct {
	Category     string
	LastAccessed int64
	Context      string
	Source       string
	Scope        string
}

type MintToSpaceArgs struct {
	KBName   string `json:"kb_name" binding:"required" example:"Notes"`
	Content  string `json:"content" binding:"required"`
	Category string `json:"category,omitempty" example:"General"`
}

type MockItem struct {
	Key   any
	Value any
}

type MockStore struct {
	Name  string
	Items []MockItem
	// contains filtered or unexported fields
}

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

type NativeReActEngine struct {
	EnableObfuscation bool
	MaxTokens         int
}

type OrderedFieldsProvider interface {
	GetOrderedFields() []string
}

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

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

type PendingUserConfirmation struct {
	Kind         string
	SpaceName    string
	DatabaseName string
}

type PipelineAgent struct {
	ID     string
	Config *Config
}

type PipelineStep struct {
	Agent    PipelineAgent `json:"agent"`
	OutputTo string        `json:"output_to,omitempty"` // "context", "next_step" (default)
}

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

type PolicyConfig struct {
	ID         string `json:"id,omitempty"` // Optional: ID for referencing in pipeline
	Type       string `json:"type"`         // e.g. "profanity"
	MaxStrikes int    `json:"max_strikes"`  // e.g. 3
}

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

type ProjectionField struct {
	Src string
	Dst string
}

type PromptBudgetProfile struct {
	TotalChars            int
	ComponentCharBudgets  map[PromptComponent]int
	TrimPriorityLowToHigh []PromptComponent
}

type PromptBudgetReport struct {
	OriginalTotalChars int                         `json:"original_total_chars"`
	FinalTotalChars    int                         `json:"final_total_chars"`
	ComponentStats     []PromptComponentBudgetStat `json:"component_stats"`
}

type PromptComponent string

type PromptComponentBudgetStat struct {
	Component     PromptComponent `json:"component"`
	OriginalChars int             `json:"original_chars"`
	FinalChars    int             `json:"final_chars"`
}

type PromptElement struct {
	Component PromptComponent `json:"component"`
	Content   string          `json:"content"`
}

type ProviderDetails struct {
	// Provider specifies which LLM provider to use (e.g., "gemini", "chatgpt", "claude")
	Provider string

	// Model optionally specifies a specific model within the provider (e.g., "gemini-2.0-flash-thinking-exp")
	Model string

	// APIKey provides a transient API key override for the provider
	APIKey string

	// BaseURL provides a transient base URL override for the provider
	BaseURL string
}

type ReadSpaceConfigArgs struct {
	Database string `json:"database,omitempty" example:"dev_db"`
	KBName   string `json:"kb_name" binding:"required" example:"Notes"`
}

type RecipeItem struct {
	ID          string
	Kind        string
	Scope       string
	Domain      string
	Topic       string
	Trigger     string
	Protocol    []string
	Invariants  []string
	AntiPattern []string
	Tags        []string
	Confidence  float64
	Source      string
}

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

type RefinementProposal struct {
	ScriptName     string
	Category       string
	OriginalScript ai.Script
	NewScript      ai.Script
	Description    string   // The new summary description
	NewParams      []string // List of new parameters
	Replacements   []string // Human readable list of replacements
}

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

type ReproMockTransaction struct {
	sop.Transaction
	Stores map[string]jsondb.StoreAccessor
}

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

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

type RunnerSession struct {
	Playback              bool // True if a script is currently being executed
	AutoSave              bool // If true, the draft is saved to DB after every step
	CurrentScript         *ai.Script
	CurrentScriptName     string // Name of the script being drafted
	CurrentScriptCategory string // Category for the script being drafted
	// TODO: Transaction has to be revisited, specially the interplay to SessionPayload.Transaction.
	Transaction sop.Transaction
	CurrentDB   string         // The database the transaction is bound to
	Variables   map[string]any // Session-scoped variables (e.g. cached stores)
	// Verbose is a temporary bridge for carried runtime state between asks when the caller does not
	// provide a hydrated SessionPayload. The durable preference should move through LTM -> MRU ->
	// SessionPayload instead of living here as a storage authority.
	Verbose  bool
	LastStep *ai.ScriptStep
	// LastInteractionSteps tracks the number of steps added/executed in the last user interaction.
	LastInteractionSteps int
	// LastInteractionToolCalls buffers the tool calls from the last interaction for refactoring.
	LastInteractionToolCalls []ai.ScriptStep

	// Contextual Working Memory for the Session
	MRU                 []MRUItem
	MRUMu               sync.RWMutex
	ConversationHistory string

	// PendingRefinement holds the proposed changes for a script from /script refine
	PendingRefinement *RefinementProposal
	// PendingConfirmation holds a user confirmation gate for destructive actions.
	PendingConfirmation *PendingUserConfirmation

	// Memory holds the structured Short-Term Memory of the session.
	// It replaces the flat History slice with threaded topics.
	Memory *ShortTermMemory
	// contains filtered or unexported fields
}

type ScriptContext struct {
	Variables      map[string]any
	Transactions   map[string]sop.Transaction
	TxToDB         map[sop.Transaction]Database // Mapping from Transaction to its Database
	Stores         map[string]jsondb.StoreAccessor
	Databases      map[string]Database
	LastUpdatedVar string // helper to track the prioritization of variable draining
}

type ScriptCursor interface {
	Next(ctx context.Context) (any, bool, error)
	Close() error
}

type ScriptEngine struct {
	Context         *ScriptContext
	ResolveDatabase func(name string) (Database, error)
	FunctionHandler func(ctx context.Context, name string, args map[string]any) (any, error)
	LastResult      any
	ReturnValue     any
	HasReturned     bool
	StoreOpener     func(ctx context.Context, dbOpts sop.DatabaseOptions, storeName string, tx sop.Transaction) (jsondb.StoreAccessor, error)
	Deferred        []func(context.Context, *ScriptEngine) error
}

type ScriptInstruction struct {
	Name      string         `json:"name"`       // User-defined name for the step
	Op        string         `json:"op"`         // Operation name
	Args      map[string]any `json:"args"`       // Arguments
	InputVar  string         `json:"input_var"`  // Variable to use as input (optional)
	ResultVar string         `json:"result_var"` // Variable to store result (optional)
}

type ScriptRunContext struct {
	// JSONStreamer handles streaming JSON array elements for script execution output
	JSONStreamer *JSONStreamer

	// SuppressInternalStepStart suppresses step_start events in streamed output
	SuppressInternalStepStart bool

	// StepIndex tracks the current step number in script execution
	StepIndex int

	// Verbose enables detailed logging and progress reporting for script steps
	Verbose bool

	// UseNDJSON indicates whether to use newline-delimited JSON format instead of JSON array
	UseNDJSON bool

	// CurrentScriptCategory tracks the category of the currently executing script
	CurrentScriptCategory string

	// StringBuilderMutex protects concurrent writes to the script output string builder
	StringBuilderMutex *sync.Mutex
}

type SearchItemsByPathArgs struct {
	Database      string                   `json:"database,omitempty" example:"dev_db"`
	KBName        string                   `json:"kb_name" binding:"required" example:"Notes"`
	Parameters    []memory.PathSearchParam `json:"parameters" binding:"required"`
	TransactionID string                   `json:"transaction_id,omitempty"`
}

type SelectArgs struct {
	Database     string         `json:"database,omitempty" example:"dev_db"`
	Store        string         `json:"store" binding:"required" example:"users"`
	Key          any            `json:"key,omitempty"`
	KeyMatch     any            `json:"key_match,omitempty"`
	Value        map[string]any `json:"value,omitempty"`
	Filter       map[string]any `json:"filter,omitempty"`
	Fields       []string       `json:"fields,omitempty"`
	Limit        int            `json:"limit,omitempty" default:"10"`
	OrderBy      string         `json:"order_by,omitempty"`
	Direction    string         `json:"direction,omitempty" enums:"asc,desc"`
	Action       string         `json:"action,omitempty" enums:"delete,update"`
	UpdateValues map[string]any `json:"update_values,omitempty"`
}

type Service struct {
	EnableObfuscation bool
	// Feature Flags
	EnableHistoryInjection bool
	EnableShortTermMemory  bool
	// contains filtered or unexported fields
}

type ServiceAskOptions struct {
	// Database to use for this query (overrides session default)
	Database *database.Database

	// Payload contains session state: current DB, selected KBs, transaction, variables, etc.
	Payload *ai.SessionPayload

	// Executor for running tool calls during ReAct loops (commands, queries, scripts)
	Executor ai.ToolExecutor

	// Writer for streaming output in real-time (optional)
	Writer io.Writer

	// Recorder captures script steps for playback or audit (optional)
	Recorder ai.ScriptRecorder

	// DefaultFormat for query results: "csv", "json", "table", etc.
	DefaultFormat string

	// EventStreamer receives structured events: tool calls, progress, errors (optional)
	EventStreamer func(string, any)

	// ProgressSink receives progress messages during long operations (optional)
	ProgressSink func(string)

	// Generator optionally overrides the default LLM provider
	Generator ai.Generator

	// ProviderDetails for runtime provider configuration (API key, base URL, model)
	ProviderDetails *ProviderDetails

	// IsNewTopic indicates this query starts a new conversation topic
	IsNewTopic bool

	// ForcedDBName overrides database selection logic (internal use)
	ForcedDBName string
}

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

type SessionMode int

type ShortTermMemory struct {
	Threads            map[sop.UUID]*ConversationThread
	Order              []sop.UUID // Maintains the sequence of threads
	CurrentThreadID    sop.UUID   // The currently active thread
	LastRoutingState   *TaskContextClassification
	LastMRUSnapshot    []MRUItem
	LastRecipeSnapshot []RecipeItem
	LastCarryoverState *ai.CarryoverState
}

type SpaceBulkOperationError struct {
	Index   int      `json:"index"`
	ID      sop.UUID `json:"id,omitempty"`
	Message string   `json:"message"`
}

type SpaceBulkOperationMetrics struct {
	TotalItems     int           `json:"total_items"`
	ItemsPerSecond float64       `json:"items_per_second"`
	AvgItemTime    time.Duration `json:"avg_item_time"`
}

type SpaceBulkOperationResult struct {
	Success   bool                      `json:"success"`
	Processed int                       `json:"processed"`
	Failed    int                       `json:"failed"`
	Duration  time.Duration             `json:"duration"`
	Errors    []SpaceBulkOperationError `json:"errors,omitempty"`
	Metrics   SpaceBulkOperationMetrics `json:"metrics"`
}

type SpecProvider interface {
	GetIndexSpecs() map[string]*jsondb.IndexSpecification
}

type StepExecutionResult struct {
	Type    string `json:"type"`
	Command string `json:"command,omitempty"`
	Prompt  string `json:"prompt,omitempty"`
	// Use Payload for generic message/label if needed, but Command/Prompt cover most.
	// We might want to add "Name" explicitly if strictly needed,
	// but currently the code equates Command field to the label.
	StepIndex int    `json:"step_index"`
	Result    any    `json:"result,omitempty"`
	Record    any    `json:"record,omitempty"`
	Error     string `json:"error,omitempty"`
}

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

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

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

type TaskContextClassification struct {
	Entity          string      `json:"entity"`
	Domain          string      `json:"domain"`
	DBArtifacts     []string    `json:"db_artifacts"`
	StoresArtifacts []string    `json:"stores_artifacts,omitempty"`
	SpacesArtifacts []string    `json:"spaces_artifacts,omitempty"`
	Layers          []LayerInfo `json:"layers"`
	ScriptAuthoring bool        `json:"-"`
	RoutingGate     string      `json:"-"`
	// KB Search Results (for specialized KB routing)
	KBSearchResults string `json:"-"`
	KBMatchCount    int    `json:"-"`
	LLMInstruction  string `json:"-"`
	CleanQuery      string `json:"-"` // Query without :llm meta-token
	DirectDisplay   bool   `json:"-"`
}

type ToolDefinition struct {
	Name             string
	Description      string
	ShortDescription string
	ArgsSchema       string // JSON schema or description of args
	Handler          ToolHandler
	Hidden           bool
}

type ToolExecutionContext struct {
	// Session holds the current session state for tools that need access to variables or state
	Session *ai.SessionPayload

	// Executor is the tool executor (may be nested/chained)
	Executor ai.ToolExecutor

	// Recorder captures script steps during execution for playback/audit
	Recorder ai.ScriptRecorder

	// Writer is the output destination for streaming tool results
	Writer io.Writer

	// ResultStreamer enables structured streaming output for tools (BeginArray, WriteItem, EndArray)
	ResultStreamer ai.ResultStreamer

	// NativeToolHints indicates this is native Ask-loop tool execution that can consume structured hints
	NativeToolHints bool

	// Database is the target database for script/tool execution
	Database *database.Database

	// EventStreamer receives structured events during tool execution
	EventStreamer func(eventType string, data any)

	// ProgressSink receives progress messages
	ProgressSink func(message string)
}

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

type ToolProvider interface {
	Execute(ctx context.Context, toolName string, args map[string]any) (string, error)
}

type TopicAssessment struct {
	IsNewTopic    bool   `json:"is_new_topic"`
	TopicUUID     string `json:"topic_uuid,omitempty"` // If not new, the UUID of the existing graph
	NewTopicLabel string `json:"new_topic_label,omitempty"`
	Reasoning     string `json:"reasoning"`
}

type TransactionArgs struct {
	Database string `json:"database,omitempty" example:"dev_db"`
	Mode     string `json:"mode" binding:"required" enums:"read,write" default:"read"`
}

type TransactionCommitArgs struct {
	TransactionID string `json:"transaction_id" binding:"required"`
}

type TransactionHandle struct {
	ID       string    `json:"id"`       // Unique transaction ID
	Database string    `json:"database"` // Database name
	Mode     string    `json:"mode"`     // "read" or "write"
	Started  time.Time `json:"started"`  // When transaction began
}

type TransactionMode string

type TransactionRollbackArgs struct {
	TransactionID string `json:"transaction_id" binding:"required"`
}

type UpdateArgs struct {
	Database string         `json:"database,omitempty" example:"dev_db"`
	Store    string         `json:"store" binding:"required" example:"users"`
	Key      any            `json:"key" binding:"required" example:"user_123"`
	Value    map[string]any `json:"value" binding:"required"`
}

type UpdateSpaceConfigArgs struct {
	Database string                     `json:"database,omitempty" example:"dev_db"`
	KBName   string                     `json:"kb_name" binding:"required" example:"Notes"`
	Config   memory.KnowledgeBaseConfig `json:"config" binding:"required"`
}

type UpsertCategoryArgs struct {
	Database      string                     `json:"database,omitempty" example:"dev_db"`
	KBName        string                     `json:"kb_name" binding:"required" example:"Notes"`
	Parameter     memory.UpsertCategoryParam `json:"parameter" binding:"required"`
	TransactionID string                     `json:"transaction_id,omitempty"`
}

type UpsertItemArgs struct {
	Database      string                                 `json:"database,omitempty" example:"dev_db"`
	KBName        string                                 `json:"kb_name" binding:"required" example:"Notes"`
	Parameter     memory.UpsertItemParam[map[string]any] `json:"parameter" binding:"required"`
	TransactionID string                                 `json:"transaction_id,omitempty"`
}

type VectorizeSpaceArgs struct {
	Database  string `json:"database,omitempty" example:"dev_db"`
	KBName    string `json:"kb_name" binding:"required" example:"Notes"`
	BatchSize int    `json:"batch_size,omitempty" default:"100" example:"250"`
}