cortexdb

type ActionApplyRequest struct {
	Action     string            `json:"action"`
	Parameters map[string]string `json:"parameters,omitempty"`
	// ValidateOnly checks parameters and submission criteria without
	// writing. Mutually exclusive with ReturnEdits, matching OSDK.
	ValidateOnly bool `json:"validate_only,omitempty"`
	// ReturnEdits includes the graph edits the action made.
	ReturnEdits bool `json:"return_edits,omitempty"`
	// Actor is recorded in the audit trail and resolves current_user value
	// sources.
	Actor string `json:"actor,omitempty"`
}

type ActionApplyResponse struct {
	Action  string       `json:"action"`
	Valid   bool         `json:"valid"`
	Applied bool         `json:"applied"`
	Errors  []string     `json:"errors,omitempty"`
	Edits   []ActionEdit `json:"edits,omitempty"`
}

type ActionEdit struct {
	Kind       string `json:"kind"`
	ObjectID   string `json:"object_id,omitempty"`
	ObjectType string `json:"object_type,omitempty"`
	LinkType   string `json:"link_type,omitempty"`
	FromID     string `json:"from_id,omitempty"`
	ToID       string `json:"to_id,omitempty"`
}

type ActionListRequest struct{}

type ActionListResponse struct {
	Actions []OntologyActionType `json:"actions"`
}

type ActionRuleKind string

type ApplyInferenceRequest struct {
	DocumentID     string          `json:"document_id,omitempty"`
	Rules          []InferenceRule `json:"rules"`
	DeleteExisting bool            `json:"delete_existing,omitempty"`
}

type ApplyInferenceResponse struct {
	CreatedEdgeIDs []string `json:"created_edge_ids"`
	DeletedEdgeIDs []string `json:"deleted_edge_ids,omitempty"`
}

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

type Config struct {
	Path         string              // Database file path
	Dimensions   int                 // Vector dimensions (0 for auto-detect)
	SimilarityFn core.SimilarityFunc // Similarity function (default: cosine)
	IndexType    core.IndexType      // Index type (HNSW, IVF, Flat)
}

type DB struct {
	KnowledgeMemoryReflector KnowledgeMemoryReflector
	// contains filtered or unexported fields
}

type DBInfo struct {
	Path           string                    `json:"path"`
	Dimensions     int                       `json:"dimensions"`
	IndexType      string                    `json:"indexType"`
	SimilarityFn   string                    `json:"similarityFn"`
	Embedder       string                    `json:"embedder,omitempty"`
	HNSW           core.HNSWConfig           `json:"hnsw,omitempty"`
	IVF            core.IVFConfig            `json:"ivf,omitempty"`
	TextSimilarity core.TextSimilarityConfig `json:"textSimilarity,omitempty"`
	Quantization   core.QuantizationConfig   `json:"quantization,omitempty"`
}

type Embedder interface {
	// Embed converts a single text string into a vector.
	Embed(ctx context.Context, text string) ([]float32, error)

	// EmbedBatch converts multiple texts into vectors in a single call.
	// This is optional but recommended for better performance with batch operations.
	EmbedBatch(ctx context.Context, texts []string) ([][]float32, error)

	// Dim returns the dimension of vectors produced by this embedder.
	Dim() int
}

type ExtractedRelation struct {
	From string `json:"from"`
	To   string `json:"to"`
	Type string `json:"type"`
}

type GraphEntity struct {
	Name string
	Type string
}

type GraphExtraction struct {
	Entities      []GraphEntity
	Relationships []GraphRelationship
}

type GraphListAllEdge struct {
	From string `json:"from"`
	To   string `json:"to"`
	Type string `json:"type,omitempty"`
}

type GraphListAllNode struct {
	ID    string `json:"id"`
	Label string `json:"label"`
	Type  string `json:"type,omitempty"`
	// Degree is how many meaningful edges touch this node. The caller ranks by
	// it when it has to show only part of a large graph.
	Degree int `json:"degree"`
}

type GraphListAllRequest struct {
	// Limit caps how many nodes come back (0 = defaultGraphListLimit). Edges are
	// then restricted to those between returned nodes, so the result is always a
	// self-consistent subgraph rather than one with dangling ends.
	Limit int `json:"limit,omitempty"`
}

type GraphListAllResponse struct {
	Nodes []GraphListAllNode `json:"nodes"`
	Edges []GraphListAllEdge `json:"edges"`
	// Truncated is true when Limit dropped nodes. A view that silently showed
	// part of a graph would look like the whole one.
	Truncated bool `json:"truncated,omitempty"`
	// TotalNodes is how many meaningful nodes exist, so a truncated caller can
	// report what it is not showing.
	TotalNodes int `json:"total_nodes"`
}

type GraphMaintenanceOptions struct {
	// DryRun reports what would change without writing anything.
	DryRun bool
	// Limit caps how many rows are processed (0 = all).
	Limit int
}

type GraphPruneReport struct {
	Scanned      int      `json:"scanned"`
	Pruned       int      `json:"pruned"`
	EdgesRemoved int      `json:"edges_removed"`
	DryRun       bool     `json:"dry_run"`
	Names        []string `json:"names,omitempty"`
}

type GraphRAGChunkResult struct {
	ID          string
	DocumentID  string
	Content     string
	Score       float64
	BaseScore   float64
	RerankScore float64
	Entities    []string
}

type GraphRAGDocument struct {
	ID       string
	Title    string
	Content  string
	Metadata map[string]string
}

type GraphRAGExtractor interface {
	Extract(ctx context.Context, text string) (*GraphExtraction, error)
}

type GraphRAGIngestOptions struct {
	Collection   string
	ChunkSize    int
	ChunkOverlap int
	Extractor    GraphRAGExtractor
}

type GraphRAGIngestResult struct {
	DocumentNodeID string
	ChunkNodeIDs   []string
	EntityNodeIDs  []string
}

type GraphRAGQueryOptions struct {
	Collection          string
	TopK                int
	MaxHops             int
	MaxRelatedChunks    int
	MaxContextChunks    int
	MaxContextChars     int
	PerDocumentLimit    int
	Rerank              bool
	DisableRerank       bool
	DiversityLambda     float64
	DisableGraph        bool
	RetrievalMode       string
	GraphLight          bool
	MaxExpansionSeeds   int
	MaxTraversalNodes   int
	MaxEntitiesPerChunk int
	Plan                *RetrievalPlan
	// EmbedText, when non-empty, is embedded for the vector query instead of the
	// raw query (HyDE). The raw query still drives lexical and graph scoring;
	// only the semantic seed vector comes from this hypothetical answer passage.
	EmbedText string
}

type GraphRAGQueryResult struct {
	Query    string
	Plan     RetrievalPlan
	Decision RetrievalDecision
	Chunks   []GraphRAGChunkResult
	Entities []string
	Context  string
}

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

type GraphReindexReport struct {
	Memories     int  `json:"memories"`
	Indexed      int  `json:"indexed"`
	Skipped      int  `json:"skipped"`
	EntitiesSeen int  `json:"entities_seen"`
	DryRun       bool `json:"dry_run"`
}

type GraphRelationship struct {
	From   string
	To     string
	Type   string
	Weight float64
}

type ImportAgentMemoryOptions struct {
	// Roots to scan for agent memory. When empty, defaults to the Claude Code
	// home (~/.claude). Add ~/.codex or a project dir to include those.
	Roots []string
	// Collection to store imported knowledge under (default "agent_memory").
	Collection string
	// IncludeInstructions also imports CLAUDE.md / AGENTS.md instruction files,
	// not just the file-based memory store.
	IncludeInstructions bool
	// DryRun scans and reports without writing anything.
	DryRun bool
}

type ImportAgentMemoryReport struct {
	FilesScanned int      `json:"files_scanned"`
	Imported     int      `json:"imported"`
	Skipped      int      `json:"skipped"`
	IDs          []string `json:"ids,omitempty"`
}

type InferenceRule struct {
	RuleID             string            `json:"rule_id"`
	Description        string            `json:"description,omitempty"`
	LeftRelationType   string            `json:"left_relation_type"`
	RightRelationType  string            `json:"right_relation_type"`
	ResultRelationType string            `json:"result_relation_type"`
	Weight             float64           `json:"weight,omitempty"`
	Metadata           map[string]string `json:"metadata,omitempty"`
}

type KnowledgeDeleteRequest struct {
	KnowledgeID string `json:"knowledge_id"`
}

type KnowledgeDeleteResponse struct {
	KnowledgeID string `json:"knowledge_id"`
	Deleted     bool   `json:"deleted"`
}

type KnowledgeGetRequest struct {
	KnowledgeID string `json:"knowledge_id"`
}

type KnowledgeGetResponse struct {
	Knowledge KnowledgeRecord `json:"knowledge"`
}

type KnowledgeGraphDeleteRequest struct {
	TripleIDs []string                     `json:"triple_ids,omitempty"`
	Triples   []KnowledgeGraphTriple       `json:"triples,omitempty"`
	Pattern   *KnowledgeGraphTriplePattern `json:"pattern,omitempty"`
}

type KnowledgeGraphDeleteResponse struct {
	Deleted int `json:"deleted"`
}

type KnowledgeGraphExportRequest struct {
	Format string `json:"format"`
}

type KnowledgeGraphExportResponse struct {
	Format  string `json:"format"`
	Content string `json:"content"`
}

type KnowledgeGraphFindRequest struct {
	Pattern KnowledgeGraphTriplePattern `json:"pattern"`
}

type KnowledgeGraphFindResponse struct {
	Triples []KnowledgeGraphTriple `json:"triples"`
}

type KnowledgeGraphImportRequest struct {
	Format  string `json:"format"`
	Content string `json:"content"`
}

type KnowledgeGraphImportResponse struct {
	Format string `json:"format"`
	Count  int    `json:"count"`
}

type KnowledgeGraphInferenceExplainMatchRequest struct {
	Pattern KnowledgeGraphTriplePattern `json:"pattern"`
	Depth   int                         `json:"depth,omitempty"`
}

type KnowledgeGraphInferenceExplainMatchResponse struct {
	Matches []KnowledgeGraphInferenceMatchExplanation `json:"matches"`
}

type KnowledgeGraphInferenceExplainRequest struct {
	TripleID string `json:"triple_id"`
	Depth    int    `json:"depth,omitempty"`
}

type KnowledgeGraphInferenceExplainResponse struct {
	Explanation KnowledgeGraphInferenceExplanation  `json:"explanation"`
	Trace       []KnowledgeGraphInferenceTraceEntry `json:"trace,omitempty"`
}

type KnowledgeGraphInferenceExplanation = graph.RDFSInferenceExplanation

type KnowledgeGraphInferenceMatchExplanation = graph.RDFSInferenceMatchExplanation

type KnowledgeGraphInferenceRefreshRequest struct {
	Mode      string                       `json:"mode,omitempty"`
	TripleIDs []string                     `json:"triple_ids,omitempty"`
	Triples   []KnowledgeGraphTriple       `json:"triples,omitempty"`
	Pattern   *KnowledgeGraphTriplePattern `json:"pattern,omitempty"`
}

type KnowledgeGraphInferenceRefreshResponse struct {
	Result KnowledgeGraphInferenceRefreshResult `json:"result"`
}

type KnowledgeGraphInferenceRefreshResult = graph.RDFSInferenceRefreshResult

type KnowledgeGraphInferenceSummary = graph.RDFSInferenceSummary

type KnowledgeGraphInferenceSummaryRequest struct{}

type KnowledgeGraphInferenceSummaryResponse struct {
	Result KnowledgeGraphInferenceSummary `json:"result"`
}

type KnowledgeGraphInferenceTraceEntry = graph.RDFSInferenceTraceEntry

type KnowledgeGraphNamespace = graph.Namespace

type KnowledgeGraphNamespaceListResponse struct {
	Namespaces []KnowledgeGraphNamespace `json:"namespaces"`
}

type KnowledgeGraphNamespaceUpsertRequest struct {
	Prefix string `json:"prefix"`
	URI    string `json:"uri"`
}

type KnowledgeGraphNamespaceUpsertResponse struct {
	Namespace KnowledgeGraphNamespace `json:"namespace"`
}

type KnowledgeGraphQueryRequest struct {
	Query string `json:"query"`
}

type KnowledgeGraphQueryResponse struct {
	Result KnowledgeGraphQueryResult `json:"result"`
}

type KnowledgeGraphQueryResult = graph.SPARQLResult

type KnowledgeGraphSHACLReport = graph.SHACLReport

type KnowledgeGraphSHACLValidateRequest struct {
	Shapes []KnowledgeGraphTriple `json:"shapes"`
}

type KnowledgeGraphSHACLValidateResponse struct {
	Report KnowledgeGraphSHACLReport `json:"report"`
}

type KnowledgeGraphTerm = graph.RDFTerm

type KnowledgeGraphTriple = graph.RDFTriple

type KnowledgeGraphTriplePattern = graph.TriplePattern

type KnowledgeGraphUpsertRequest struct {
	Triples []KnowledgeGraphTriple `json:"triples"`
}

type KnowledgeGraphUpsertResponse struct {
	TripleIDs []string `json:"triple_ids"`
	Count     int      `json:"count"`
}

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

type KnowledgeMemoryBuildContextPackRequest = KnowledgeMemoryRecallRequest

type KnowledgeMemoryBuildContextPackResponse = KnowledgeMemoryRecallResponse

type KnowledgeMemoryConsolidateRequest struct {
	Reflect            KnowledgeMemoryReflectRequest             `json:"reflect"`
	MemoryID           string                                    `json:"memory_id,omitempty"`
	UserID             string                                    `json:"user_id,omitempty"`
	SessionID          string                                    `json:"session_id,omitempty"`
	Scope              string                                    `json:"scope,omitempty"`
	Namespace          string                                    `json:"namespace,omitempty"`
	Role               string                                    `json:"role,omitempty"`
	Metadata           map[string]any                            `json:"metadata,omitempty"`
	Importance         float64                                   `json:"importance,omitempty"`
	TTLSeconds         int                                       `json:"ttl_seconds,omitempty"`
	PromoteToKnowledge bool                                      `json:"promote_to_knowledge,omitempty"`
	Promotion          *KnowledgeMemoryPromoteToKnowledgeRequest `json:"promotion,omitempty"`
}

type KnowledgeMemoryConsolidateResponse struct {
	Reflection KnowledgeMemoryReflection     `json:"reflection"`
	Recall     KnowledgeMemoryRecallResponse `json:"recall"`
	Memory     MemoryRecord                  `json:"memory"`
	Knowledge  *KnowledgeRecord              `json:"knowledge,omitempty"`
}

type KnowledgeMemoryContextPack struct {
	Query        string                          `json:"query"`
	Text         string                          `json:"text"`
	Sections     []KnowledgeMemoryContextSection `json:"sections,omitempty"`
	MemoryIDs    []string                        `json:"memory_ids,omitempty"`
	KnowledgeIDs []string                        `json:"knowledge_ids,omitempty"`
	ChunkIDs     []string                        `json:"chunk_ids,omitempty"`
	Entities     []string                        `json:"entities,omitempty"`
}

type KnowledgeMemoryContextSection struct {
	Kind      string   `json:"kind"`
	Title     string   `json:"title,omitempty"`
	Text      string   `json:"text"`
	SourceIDs []string `json:"source_ids,omitempty"`
}

type KnowledgeMemoryExpandEntityContextRequest struct {
	EntityIDs           []string `json:"entity_ids,omitempty"`
	EntityNames         []string `json:"entity_names,omitempty"`
	MaxHops             int      `json:"max_hops,omitempty"`
	EdgeTypes           []string `json:"edge_types,omitempty"`
	NodeTypes           []string `json:"node_types,omitempty"`
	Limit               int      `json:"limit,omitempty"`
	TopKChunks          int      `json:"top_k_chunks,omitempty"`
	MaxContextChunks    int      `json:"max_context_chunks,omitempty"`
	MaxContextChars     int      `json:"max_context_chars,omitempty"`
	PerDocumentLimit    int      `json:"per_document_limit,omitempty"`
	RetrievalMode       string   `json:"retrieval_mode,omitempty"`
	DisableGraph        bool     `json:"disable_graph,omitempty"`
	GraphLight          bool     `json:"graph_light,omitempty"`
	MaxEntitiesPerChunk int      `json:"max_entities_per_chunk,omitempty"`
}

type KnowledgeMemoryExpandEntityContextResponse struct {
	EntityNodeIDs []string                   `json:"entity_node_ids,omitempty"`
	Nodes         []*graph.GraphNode         `json:"nodes,omitempty"`
	Edges         []*graph.GraphEdge         `json:"edges,omitempty"`
	Chunks        []GraphRAGChunkResult      `json:"chunks,omitempty"`
	ContextPack   KnowledgeMemoryContextPack `json:"context_pack"`
}

type KnowledgeMemoryGraphFact struct {
	Subject   string `json:"subject"`
	Predicate string `json:"predicate"`
	Object    string `json:"object"`
	SubjectID string `json:"subject_id,omitempty"`
	ObjectID  string `json:"object_id,omitempty"`
}

type KnowledgeMemoryNeighborsRequest struct {
	NodeID     string   `json:"node_id,omitempty"`
	EntityName string   `json:"entity_name,omitempty"`
	MaxDepth   int      `json:"max_depth,omitempty"`
	EdgeTypes  []string `json:"edge_types,omitempty"`
	NodeTypes  []string `json:"node_types,omitempty"`
	Direction  string   `json:"direction,omitempty"`
	Limit      int      `json:"limit,omitempty"`
}

type KnowledgeMemoryNeighborsResponse struct {
	ResolvedNodeID string             `json:"resolved_node_id"`
	Neighbors      []*graph.GraphNode `json:"neighbors,omitempty"`
}

type KnowledgeMemoryPromoteToKnowledgeRequest struct {
	MemoryIDs    []string            `json:"memory_ids,omitempty"`
	KnowledgeID  string              `json:"knowledge_id,omitempty"`
	Title        string              `json:"title,omitempty"`
	SourceURL    string              `json:"source_url,omitempty"`
	Author       string              `json:"author,omitempty"`
	Collection   string              `json:"collection,omitempty"`
	ChunkSize    int                 `json:"chunk_size,omitempty"`
	ChunkOverlap int                 `json:"chunk_overlap,omitempty"`
	JoinWith     string              `json:"join_with,omitempty"`
	Metadata     map[string]string   `json:"metadata,omitempty"`
	Entities     []ToolEntityInput   `json:"entities,omitempty"`
	Relations    []ToolRelationInput `json:"relations,omitempty"`
}

type KnowledgeMemoryPromoteToKnowledgeResponse struct {
	Knowledge       KnowledgeRecord `json:"knowledge"`
	Memories        []MemoryRecord  `json:"memories,omitempty"`
	DocumentNodeID  string          `json:"document_node_id,omitempty"`
	EntityNodeIDs   []string        `json:"entity_node_ids,omitempty"`
	RelationEdgeIDs []string        `json:"relation_edge_ids,omitempty"`
}

type KnowledgeMemoryRecallRequest struct {
	Query               string         `json:"query"`
	UserID              string         `json:"user_id,omitempty"`
	SessionID           string         `json:"session_id,omitempty"`
	Scope               string         `json:"scope,omitempty"`
	Namespace           string         `json:"namespace,omitempty"`
	Collection          string         `json:"collection,omitempty"`
	TopKMemories        int            `json:"top_k_memories,omitempty"`
	TopKKnowledge       int            `json:"top_k_knowledge,omitempty"`
	MaxMemoryItems      int            `json:"max_memory_items,omitempty"`
	MaxMemoryChars      int            `json:"max_memory_chars,omitempty"`
	Keywords            []string       `json:"keywords,omitempty"`
	AlternateQueries    []string       `json:"alternate_queries,omitempty"`
	EntityNames         []string       `json:"entity_names,omitempty"`
	RetrievalMode       string         `json:"retrieval_mode,omitempty"`
	DisableMemory       bool           `json:"disable_memory,omitempty"`
	DisableKnowledge    bool           `json:"disable_knowledge,omitempty"`
	DisableGraph        bool           `json:"disable_graph,omitempty"`
	GraphLight          bool           `json:"graph_light,omitempty"`
	MaxHops             int            `json:"max_hops,omitempty"`
	MaxRelatedChunks    int            `json:"max_related_chunks,omitempty"`
	MaxContextChunks    int            `json:"max_context_chunks,omitempty"`
	MaxContextChars     int            `json:"max_context_chars,omitempty"`
	PerDocumentLimit    int            `json:"per_document_limit,omitempty"`
	MaxExpansionSeeds   int            `json:"max_expansion_seeds,omitempty"`
	MaxTraversalNodes   int            `json:"max_traversal_nodes,omitempty"`
	MaxEntitiesPerChunk int            `json:"max_entities_per_chunk,omitempty"`
	Plan                *RetrievalPlan `json:"plan,omitempty"`
}

type KnowledgeMemoryRecallResponse struct {
	Query             string                     `json:"query"`
	MemoryPlan        RetrievalPlan              `json:"memory_plan"`
	MemoryDecision    RetrievalDecision          `json:"memory_decision"`
	KnowledgePlan     RetrievalPlan              `json:"knowledge_plan"`
	KnowledgeDecision RetrievalDecision          `json:"knowledge_decision"`
	Memories          []MemorySearchHit          `json:"memories,omitempty"`
	Knowledge         []KnowledgeSearchHit       `json:"knowledge,omitempty"`
	Chunks            []GraphRAGChunkResult      `json:"chunks,omitempty"`
	Entities          []string                   `json:"entities,omitempty"`
	GraphFacts        []KnowledgeMemoryGraphFact `json:"graph_facts,omitempty"`
	ContextPack       KnowledgeMemoryContextPack `json:"context_pack"`
}

type KnowledgeMemoryReflectInput struct {
	Recall KnowledgeMemoryRecallResponse `json:"recall"`
}

type KnowledgeMemoryReflectRequest struct {
	Recall          KnowledgeMemoryRecallRequest `json:"recall"`
	Instructions    string                       `json:"instructions,omitempty"`
	MaxSummaryChars int                          `json:"max_summary_chars,omitempty"`
	MaxFacts        int                          `json:"max_facts,omitempty"`
	MaxThemes       int                          `json:"max_themes,omitempty"`
}

type KnowledgeMemoryReflectResponse struct {
	Reflection KnowledgeMemoryReflection     `json:"reflection"`
	Recall     KnowledgeMemoryRecallResponse `json:"recall"`
}

type KnowledgeMemoryReflection struct {
	Summary            string                     `json:"summary"`
	Themes             []string                   `json:"themes,omitempty"`
	Entities           []string                   `json:"entities,omitempty"`
	Facts              []string                   `json:"facts,omitempty"`
	SourceMemoryIDs    []string                   `json:"source_memory_ids,omitempty"`
	SourceKnowledgeIDs []string                   `json:"source_knowledge_ids,omitempty"`
	SourceChunkIDs     []string                   `json:"source_chunk_ids,omitempty"`
	ContextPack        KnowledgeMemoryContextPack `json:"context_pack"`
}

type KnowledgeMemoryReflector interface {
	Reflect(ctx context.Context, req KnowledgeMemoryReflectRequest, input KnowledgeMemoryReflectInput) (*KnowledgeMemoryReflection, error)
}

type KnowledgeMemoryRememberRequest = MemorySaveRequest

type KnowledgeMemoryRememberResponse = MemorySaveResponse

type KnowledgeMemoryShortestPathRequest struct {
	FromNodeID     string `json:"from_node_id,omitempty"`
	ToNodeID       string `json:"to_node_id,omitempty"`
	FromEntityName string `json:"from_entity_name,omitempty"`
	ToEntityName   string `json:"to_entity_name,omitempty"`
}

type KnowledgeMemoryShortestPathResponse struct {
	FromNodeID string            `json:"from_node_id"`
	ToNodeID   string            `json:"to_node_id"`
	Path       *graph.PathResult `json:"path,omitempty"`
}

type KnowledgeRecord struct {
	ID         string            `json:"id"`
	Title      string            `json:"title,omitempty"`
	Content    string            `json:"content,omitempty"`
	SourceURL  string            `json:"source_url,omitempty"`
	Author     string            `json:"author,omitempty"`
	Collection string            `json:"collection,omitempty"`
	Metadata   map[string]string `json:"metadata,omitempty"`
	ChunkIDs   []string          `json:"chunk_ids,omitempty"`
	Entities   []string          `json:"entities,omitempty"`
	CreatedAt  time.Time         `json:"created_at,omitempty"`
	UpdatedAt  time.Time         `json:"updated_at,omitempty"`
}

type KnowledgeSaveRequest struct {
	KnowledgeID  string              `json:"knowledge_id"`
	Title        string              `json:"title,omitempty"`
	Content      string              `json:"content"`
	SourceURL    string              `json:"source_url,omitempty"`
	Author       string              `json:"author,omitempty"`
	Collection   string              `json:"collection,omitempty"`
	ChunkSize    int                 `json:"chunk_size,omitempty"`
	ChunkOverlap int                 `json:"chunk_overlap,omitempty"`
	Metadata     map[string]string   `json:"metadata,omitempty"`
	Entities     []ToolEntityInput   `json:"entities,omitempty"`
	Relations    []ToolRelationInput `json:"relations,omitempty"`
}

type KnowledgeSaveResponse struct {
	Knowledge       KnowledgeRecord `json:"knowledge"`
	DocumentNodeID  string          `json:"document_node_id,omitempty"`
	EntityNodeIDs   []string        `json:"entity_node_ids,omitempty"`
	RelationEdgeIDs []string        `json:"relation_edge_ids,omitempty"`
}

type KnowledgeSearchHit struct {
	KnowledgeID string            `json:"knowledge_id"`
	Title       string            `json:"title,omitempty"`
	SourceURL   string            `json:"source_url,omitempty"`
	Author      string            `json:"author,omitempty"`
	Snippet     string            `json:"snippet,omitempty"`
	Score       float64           `json:"score"`
	ChunkIDs    []string          `json:"chunk_ids,omitempty"`
	Entities    []string          `json:"entities,omitempty"`
	Metadata    map[string]string `json:"metadata,omitempty"`
}

type KnowledgeSearchRequest struct {
	Query               string         `json:"query"`
	Collection          string         `json:"collection,omitempty"`
	TopK                int            `json:"top_k,omitempty"`
	MaxHops             int            `json:"max_hops,omitempty"`
	MaxRelatedChunks    int            `json:"max_related_chunks,omitempty"`
	MaxContextChunks    int            `json:"max_context_chunks,omitempty"`
	MaxContextChars     int            `json:"max_context_chars,omitempty"`
	PerDocumentLimit    int            `json:"per_document_limit,omitempty"`
	DiversityLambda     float64        `json:"diversity_lambda,omitempty"`
	DisableRerank       bool           `json:"disable_rerank,omitempty"`
	EntityNames         []string       `json:"entity_names,omitempty"`
	Keywords            []string       `json:"keywords,omitempty"`
	AlternateQueries    []string       `json:"alternate_queries,omitempty"`
	RetrievalMode       string         `json:"retrieval_mode,omitempty"`
	DisableGraph        bool           `json:"disable_graph,omitempty"`
	GraphLight          bool           `json:"graph_light,omitempty"`
	MaxExpansionSeeds   int            `json:"max_expansion_seeds,omitempty"`
	MaxTraversalNodes   int            `json:"max_traversal_nodes,omitempty"`
	MaxEntitiesPerChunk int            `json:"max_entities_per_chunk,omitempty"`
	Plan                *RetrievalPlan `json:"plan,omitempty"`
}

type KnowledgeSearchResponse struct {
	Query    string                `json:"query"`
	Plan     RetrievalPlan         `json:"plan"`
	Decision RetrievalDecision     `json:"decision"`
	Results  []KnowledgeSearchHit  `json:"results"`
	Chunks   []GraphRAGChunkResult `json:"chunks,omitempty"`
	Entities []string              `json:"entities,omitempty"`
	Context  string                `json:"context,omitempty"`
}

type KnowledgeUpdateRequest struct {
	KnowledgeID  string              `json:"knowledge_id"`
	Title        *string             `json:"title,omitempty"`
	Content      *string             `json:"content,omitempty"`
	SourceURL    *string             `json:"source_url,omitempty"`
	Author       *string             `json:"author,omitempty"`
	Collection   *string             `json:"collection,omitempty"`
	ChunkSize    *int                `json:"chunk_size,omitempty"`
	ChunkOverlap *int                `json:"chunk_overlap,omitempty"`
	Metadata     map[string]string   `json:"metadata,omitempty"`
	Entities     []ToolEntityInput   `json:"entities,omitempty"`
	Relations    []ToolRelationInput `json:"relations,omitempty"`
}

type MCPServerOptions struct {
	Implementation *mcp.Implementation
	Instructions   string
	Logger         *slog.Logger
}

type MemoryDeleteRequest struct {
	MemoryID string `json:"memory_id"`
}

type MemoryDeleteResponse struct {
	MemoryID string `json:"memory_id"`
	Deleted  bool   `json:"deleted"`
}

type MemoryGetRequest struct {
	MemoryID string `json:"memory_id"`
}

type MemoryGetResponse struct {
	Memory MemoryRecord `json:"memory"`
}

type MemoryListAllRequest struct {
	// Limit caps how many records come back (0 = defaultMemoryListLimit).
	// A brain with tens of thousands of memories should not be pulled into one
	// message by accident; a caller that wants them all raises this on purpose.
	Limit int `json:"limit,omitempty"`
}

type MemoryListAllResponse struct {
	Memories []MemoryRecord `json:"memories"`
	// Truncated is true when Limit cut the listing short. An export that
	// silently dropped records would look complete and not be.
	Truncated bool `json:"truncated,omitempty"`
}

type MemoryRecord struct {
	ID         string         `json:"id"`
	UserID     string         `json:"user_id,omitempty"`
	SessionID  string         `json:"session_id,omitempty"`
	Scope      string         `json:"scope,omitempty"`
	Namespace  string         `json:"namespace,omitempty"`
	Role       string         `json:"role,omitempty"`
	Content    string         `json:"content"`
	Metadata   map[string]any `json:"metadata,omitempty"`
	Importance float64        `json:"importance,omitempty"`
	TTLSeconds int            `json:"ttl_seconds,omitempty"`
	ExpiresAt  *time.Time     `json:"expires_at,omitempty"`
	CreatedAt  time.Time      `json:"created_at,omitempty"`
}

type MemorySaveRequest struct {
	MemoryID   string         `json:"memory_id"`
	UserID     string         `json:"user_id,omitempty"`
	SessionID  string         `json:"session_id,omitempty"`
	Scope      string         `json:"scope,omitempty"`
	Namespace  string         `json:"namespace,omitempty"`
	Role       string         `json:"role,omitempty"`
	Content    string         `json:"content"`
	Metadata   map[string]any `json:"metadata,omitempty"`
	Importance float64        `json:"importance,omitempty"`
	TTLSeconds int            `json:"ttl_seconds,omitempty"`
	// Supersedes names memories this one replaces. They stay stored and
	// exported, but recall stops presenting them as current — without this the
	// old wording keeps answering with stale facts in a confident voice, and
	// the only fix was hunting down its id and deleting history.
	Supersedes []string `json:"supersedes,omitempty"`
	// Entities and Relations let a caller record what this memory is ABOUT in
	// the same call that stores it, the way SaveKnowledge already can. Without
	// them the graph could only be filled by a separate extraction pass, which
	// is what made agent-written memories arrive with no graph presence.
	Entities  []ToolEntityInput   `json:"entities,omitempty"`
	Relations []ToolRelationInput `json:"relations,omitempty"`
}

type MemorySaveResponse struct {
	Memory MemoryRecord `json:"memory"`
}

type MemorySearchHit struct {
	Memory MemoryRecord `json:"memory"`
	Score  float64      `json:"score"`
}

type MemorySearchRequest struct {
	Query            string   `json:"query"`
	UserID           string   `json:"user_id,omitempty"`
	SessionID        string   `json:"session_id,omitempty"`
	Scope            string   `json:"scope,omitempty"`
	Namespace        string   `json:"namespace,omitempty"`
	TopK             int      `json:"top_k,omitempty"`
	Keywords         []string `json:"keywords,omitempty"`
	AlternateQueries []string `json:"alternate_queries,omitempty"`
	// EntityNames let recall reach a memory through the graph when the memory
	// never spells the entity the way the question does. Lexical search cannot
	// do that, so before memories had graph nodes this hint had nowhere to go.
	EntityNames   []string       `json:"entity_names,omitempty"`
	RetrievalMode string         `json:"retrieval_mode,omitempty"`
	Plan          *RetrievalPlan `json:"plan,omitempty"`
}

type MemorySearchResponse struct {
	Query    string            `json:"query"`
	Plan     RetrievalPlan     `json:"plan"`
	Decision RetrievalDecision `json:"decision"`
	Results  []MemorySearchHit `json:"results"`
}

type MemorySyncOptions struct {
	// Dir holds one Markdown file per memory, in the shape --export-memory
	// writes: YAML frontmatter carrying metadata.id, then the body. MEMORY.md is
	// the index and is skipped.
	Dir string
	// Prune deletes memories that the directory no longer contains. Off by
	// default: an import that only ever adds cannot lose anything, whereas a
	// prune against the wrong directory would empty the brain.
	Prune bool
}

type MemorySyncPlan struct {
	// Scanned counts memory files read from the directory.
	Scanned int
	// Create are memories in the directory that the store does not have — a file
	// written by hand, or one restored from a backup.
	Create []MemorySaveRequest
	// Update are memories whose file body differs from the stored content.
	Update []MemorySaveRequest
	// Delete are ids the store has and the directory does not. Empty unless
	// Prune is set.
	Delete []string
	// Unchanged counts files whose body already matches the store.
	Unchanged int
}

type MemorySyncReport struct {
	Created   int      `json:"created"`
	Updated   int      `json:"updated"`
	Deleted   int      `json:"deleted"`
	Unchanged int      `json:"unchanged"`
	IDs       []string `json:"ids,omitempty"`
}

type MemoryUpdateRequest struct {
	MemoryID   string         `json:"memory_id"`
	Content    *string        `json:"content,omitempty"`
	Metadata   map[string]any `json:"metadata,omitempty"`
	Importance *float64       `json:"importance,omitempty"`
	TTLSeconds *int           `json:"ttl_seconds,omitempty"`
}

type ObjectSet struct {
	Kind ObjectSetKind `json:"kind"`

	// base
	ObjectType string `json:"object_type,omitempty"`
	// interface_base
	InterfaceType string `json:"interface_type,omitempty"`
	// static
	ObjectIDs []string `json:"object_ids,omitempty"`
	// reference — a saved object set on the active schema
	Reference string `json:"reference,omitempty"`
	// filter / search_around
	Source *ObjectSet          `json:"source,omitempty"`
	Where  *ObjectSetPredicate `json:"where,omitempty"`
	// search_around: the link *side* api name to traverse
	Link string `json:"link,omitempty"`
	// union / intersect / subtract
	Operands []ObjectSet `json:"operands,omitempty"`
}

type ObjectSetKind string

type ObjectSetPredicate struct {
	Op       PredicateOp          `json:"op"`
	Property string               `json:"property,omitempty"`
	Value    string               `json:"value,omitempty"`
	Values   []string             `json:"values,omitempty"`
	Operands []ObjectSetPredicate `json:"operands,omitempty"`
	// K bounds a nearest_neighbors predicate. Foundry caps this at 100.
	K int `json:"k,omitempty"`
	// Vector is the query vector for nearest_neighbors. When empty the
	// resolver embeds Value instead, which is what agents will normally send.
	Vector []float32 `json:"vector,omitempty"`
}

type ObjectSetResolveRequest struct {
	ObjectSet ObjectSet `json:"object_set"`
	Limit     int       `json:"limit,omitempty"`
}

type ObjectSetResolveResponse struct {
	Objects []ResolvedObject `json:"objects"`
	Total   int              `json:"total"`
}

type OntologyActionParameter struct {
	APIName     string           `json:"api_name"`
	DisplayName string           `json:"display_name,omitempty"`
	Description string           `json:"description,omitempty"`
	DataType    OntologyDataType `json:"data_type"`
	Required    bool             `json:"required,omitempty"`
	// ObjectType marks this as an object reference parameter: its value is
	// the node ID, or the primary key, of an existing object of that type.
	ObjectType string `json:"object_type,omitempty"`
	// AllowedValues restricts the parameter to a fixed set.
	AllowedValues []string `json:"allowed_values,omitempty"`
}

type OntologyActionRule struct {
	Kind ActionRuleKind `json:"kind"`
	// object rules
	ObjectType string `json:"object_type,omitempty"`
	// Target names the object reference parameter identifying which object
	// to modify or delete.
	Target         string                         `json:"target,omitempty"`
	PropertyValues map[string]OntologyValueSource `json:"property_values,omitempty"`
	// link rules
	LinkType string              `json:"link_type,omitempty"`
	From     OntologyValueSource `json:"from,omitempty"`
	To       OntologyValueSource `json:"to,omitempty"`
}

type OntologyActionType struct {
	APIName            string                        `json:"api_name"`
	DisplayName        string                        `json:"display_name,omitempty"`
	Description        string                        `json:"description,omitempty"`
	Status             OntologyStatus                `json:"status,omitempty"`
	Parameters         []OntologyActionParameter     `json:"parameters,omitempty"`
	Rules              []OntologyActionRule          `json:"rules,omitempty"`
	SubmissionCriteria []OntologySubmissionCriterion `json:"submission_criteria,omitempty"`
}

type OntologyCardinality string

type OntologyChange struct {
	Kind     string `json:"kind"`
	Target   string `json:"target"`
	Detail   string `json:"detail"`
	Breaking bool   `json:"breaking"`
}

type OntologyDataKind string

type OntologyDataType struct {
	Kind      OntologyDataKind   `json:"kind"`
	ItemType  *OntologyDataType  `json:"item_type,omitempty"`
	Fields    []OntologyProperty `json:"fields,omitempty"`
	Dimension int                `json:"dimension,omitempty"`
}

type OntologyDeleteRequest struct {
	SchemaID string `json:"schema_id"`
}

type OntologyDeleteResponse struct {
	SchemaID string `json:"schema_id"`
	Deleted  bool   `json:"deleted"`
}

type OntologyDiff struct {
	Changes            []OntologyChange `json:"changes"`
	HasBreakingChanges bool             `json:"has_breaking_changes"`
}

type OntologyDiffRequest struct {
	SchemaID  string         `json:"schema_id"`
	Candidate OntologySchema `json:"candidate"`
}

type OntologyDiffResponse struct {
	Diff OntologyDiff `json:"diff"`
}

type OntologyEnforcement string

type OntologyGetRequest struct {
	SchemaID string `json:"schema_id"`
}

type OntologyGetResponse struct {
	Schema OntologySchema `json:"schema"`
}

type OntologyInterfaceType struct {
	APIName     string             `json:"api_name"`
	DisplayName string             `json:"display_name,omitempty"`
	Description string             `json:"description,omitempty"`
	Extends     []string           `json:"extends,omitempty"`
	Properties  []OntologyProperty `json:"properties,omitempty"`
}

type OntologyLinkSide struct {
	APIName           string `json:"api_name"`
	DisplayName       string `json:"display_name,omitempty"`
	ObjectTypeAPIName string `json:"object_type_api_name"`
	// Cardinality is how many objects a traversal starting at ObjectTypeAPIName
	// reaches. A ONE side is the side that carries the foreign key.
	Cardinality        OntologyCardinality `json:"cardinality"`
	ForeignKeyProperty string              `json:"foreign_key_property,omitempty"`
}

type OntologyLinkType struct {
	APIName     string           `json:"api_name"`
	Description string           `json:"description,omitempty"`
	Status      OntologyStatus   `json:"status,omitempty"`
	A           OntologyLinkSide `json:"a"`
	B           OntologyLinkSide `json:"b"`
}

type OntologyListRequest struct {
	ActiveOnly bool `json:"active_only,omitempty"`
}

type OntologyListResponse struct {
	Schemas []OntologySchema `json:"schemas"`
}

type OntologyNamedObjectSet struct {
	APIName     string    `json:"api_name"`
	Description string    `json:"description,omitempty"`
	Definition  ObjectSet `json:"definition"`
}

type OntologyObjectType struct {
	APIName           string             `json:"api_name"`
	DisplayName       string             `json:"display_name,omitempty"`
	PluralDisplayName string             `json:"plural_display_name,omitempty"`
	Description       string             `json:"description,omitempty"`
	Status            OntologyStatus     `json:"status,omitempty"`
	Visibility        OntologyVisibility `json:"visibility,omitempty"`
	Icon              string             `json:"icon,omitempty"`
	PrimaryKey        string             `json:"primary_key"`
	TitleProperty     string             `json:"title_property,omitempty"`
	Properties        []OntologyProperty `json:"properties,omitempty"`
	Implements        []string           `json:"implements,omitempty"`
	Aliases           []string           `json:"aliases,omitempty"`
}

type OntologyProperty struct {
	APIName     string           `json:"api_name"`
	DisplayName string           `json:"display_name,omitempty"`
	Description string           `json:"description,omitempty"`
	DataType    OntologyDataType `json:"data_type"`
	Required    bool             `json:"required,omitempty"`
	// Searchable routes the property value into FTS5 so ObjectSet text
	// predicates can match on it.
	Searchable bool `json:"searchable,omitempty"`
	// Vectorized routes the property value into the vector index so
	// ObjectSet nearest-neighbour predicates can match on it.
	Vectorized bool `json:"vectorized,omitempty"`
}

type OntologySaveRequest struct {
	Schema     OntologySchema `json:"schema"`
	Activate   bool           `json:"activate,omitempty"`
	Deactivate bool           `json:"deactivate,omitempty"`
}

type OntologySaveResponse struct {
	Schema OntologySchema `json:"schema"`
}

type OntologySchema struct {
	SchemaID    string `json:"schema_id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Version     int    `json:"version"`
	Active      bool   `json:"active"`
	// StrictActions closes the generic upsert tools once action types are
	// defined, making actions the only write path. Defaults to false.
	StrictActions bool `json:"strict_actions,omitempty"`
	// Enforcement chooses between rejecting non-conforming writes ("strict",
	// the default) and treating the schema as a non-gating vocabulary
	// ("vocabulary"). See the OntologyEnforcement constants.
	Enforcement      OntologyEnforcement      `json:"enforcement,omitempty"`
	Metadata         map[string]string        `json:"metadata,omitempty"`
	ObjectTypes      []OntologyObjectType     `json:"object_types,omitempty"`
	LinkTypes        []OntologyLinkType       `json:"link_types,omitempty"`
	InterfaceTypes   []OntologyInterfaceType  `json:"interface_types,omitempty"`
	SharedProperties []OntologyProperty       `json:"shared_properties,omitempty"`
	ActionTypes      []OntologyActionType     `json:"action_types,omitempty"`
	ObjectSets       []OntologyNamedObjectSet `json:"object_sets,omitempty"`
	CreatedAt        time.Time                `json:"created_at"`
	UpdatedAt        time.Time                `json:"updated_at"`
}

type OntologyStatus string

type OntologySubmissionCriterion struct {
	Parameter      string      `json:"parameter"`
	Op             PredicateOp `json:"op,omitempty"`
	Value          string      `json:"value,omitempty"`
	Values         []string    `json:"values,omitempty"`
	Regex          string      `json:"regex,omitempty"`
	FailureMessage string      `json:"failure_message,omitempty"`
}

type OntologyToolGenOptions struct {
	// IncludeObjectTypes also emits one list tool per object type.
	IncludeObjectTypes bool `json:"include_object_types,omitempty"`
	// MaxTools caps the number of generated tools. Zero uses the default.
	MaxTools int `json:"max_tools,omitempty"`
}

type OntologyValueSource struct {
	Kind ValueSourceKind `json:"kind"`
	// parameter
	Parameter string `json:"parameter,omitempty"`
	// object_property: read Property off the object the named parameter points at
	Property string `json:"property,omitempty"`
	// static
	Static string `json:"static,omitempty"`
}

type OntologyVisibility string

type Option func(*DB)

type PredicateOp string

type QueryCondition struct {
	Field     string   `json:"field"`
	Op        string   `json:"op,omitempty"`
	Value     string   `json:"value,omitempty"`
	Values    []string `json:"values,omitempty"`
	Number    float64  `json:"number,omitempty"`
	HasNumber bool     `json:"has_number,omitempty"`
}

type QueryFieldBoost struct {
	Field    string  `json:"field"`
	Equals   string  `json:"equals,omitempty"`
	Contains string  `json:"contains,omitempty"`
	Weight   float64 `json:"weight"`
}

type QueryFilter struct {
	Must    []QueryCondition `json:"must,omitempty"`
	Should  []QueryCondition `json:"should,omitempty"`
	MustNot []QueryCondition `json:"must_not,omitempty"`
}

type QueryNumericBoost struct {
	Field    string  `json:"field"`
	Weight   float64 `json:"weight"`
	MaxValue float64 `json:"max_value,omitempty"`
}

type QueryPrefetch struct {
	Name             string    `json:"name,omitempty"`
	Kind             string    `json:"kind,omitempty"`
	Query            string    `json:"query,omitempty"`
	QueryVector      []float32 `json:"query_vector,omitempty"`
	EntityNames      []string  `json:"entity_names,omitempty"`
	Weight           float64   `json:"weight,omitempty"`
	Limit            int       `json:"limit,omitempty"`
	MaxHops          int       `json:"max_hops,omitempty"`
	Keywords         []string  `json:"keywords,omitempty"`
	AlternateQueries []string  `json:"alternate_queries,omitempty"`
}

type QueryRequest struct {
	Collection  string             `json:"collection,omitempty"`
	Query       string             `json:"query,omitempty"`
	QueryVector []float32          `json:"query_vector,omitempty"`
	EntityNames []string           `json:"entity_names,omitempty"`
	Prefetch    []QueryPrefetch    `json:"prefetch,omitempty"`
	Fusion      string             `json:"fusion,omitempty"`
	Filter      *QueryFilter       `json:"filter,omitempty"`
	Formula     *QueryScoreFormula `json:"formula,omitempty"`
	Limit       int                `json:"limit,omitempty"`
	RRFK        float64            `json:"rrf_k,omitempty"`
	IncludeRaw  bool               `json:"include_raw,omitempty"`
}

type QueryResponse struct {
	Query      string        `json:"query,omitempty"`
	Fusion     string        `json:"fusion"`
	Results    []QueryResult `json:"results"`
	Prefetches []string      `json:"prefetches,omitempty"`
}

type QueryResult struct {
	ID           string             `json:"id"`
	Collection   string             `json:"collection,omitempty"`
	Content      string             `json:"content,omitempty"`
	DocID        string             `json:"doc_id,omitempty"`
	Metadata     map[string]string  `json:"metadata,omitempty"`
	Score        float64            `json:"score"`
	BaseScore    float64            `json:"base_score,omitempty"`
	SourceRanks  map[string]int     `json:"source_ranks,omitempty"`
	SourceScores map[string]float64 `json:"source_scores,omitempty"`
}

type QueryScoreFormula struct {
	BaseWeight    float64             `json:"base_weight,omitempty"`
	FieldBoosts   []QueryFieldBoost   `json:"field_boosts,omitempty"`
	NumericBoosts []QueryNumericBoost `json:"numeric_boosts,omitempty"`
}

type QueryTransform struct {
	AlternateQueries     []string
	Keywords             []string
	HypotheticalDocument string
}

type QueryTransformer interface {
	// TransformQuery returns rewrite signals for query. Returning a nil result
	// (or an error) leaves retrieval on the raw query — it must never make
	// retrieval fail.
	TransformQuery(ctx context.Context, query string) (*QueryTransform, error)
}

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

type ReembedOptions struct {
	// Limit caps how many rows are processed (0 = all of them).
	Limit int
	// BatchSize is how many texts go to the embedder per call (0 = 16).
	BatchSize int
	// DryRun reports what would change without writing anything.
	DryRun bool
}

type ReembedReport struct {
	TargetDim  int  `json:"targetDim"`
	Candidates int  `json:"candidates"`
	Reembedded int  `json:"reembedded"`
	Failed     int  `json:"failed"`
	DryRun     bool `json:"dryRun"`
	// Collections whose declared dimension was brought in line with their contents.
	Reconciled int      `json:"reconciled"`
	Errors     []string `json:"errors,omitempty"`
}

type RerankItem struct {
	ID       string   // caller's identifier (carried through, opaque to Rerank)
	Text     string   // primary content scored against the query
	Score    float64  // base retrieval score (any scale; min-max normalized internally)
	Entities []string // optional: entity strings for the entity-overlap signal
	GroupKey string   // optional: diversity/dedup group (e.g. a document id)

	// RerankScore is the blended relevance, filled in by Rerank.
	RerankScore float64
}

type RerankOptions struct {
	TopN            int     // keep at most N results (0 = keep all)
	DiversityLambda float64 // 0..1: relevance vs. novelty in MMR selection (default 0.75)
	BaseWeight      float64 // weight of the normalized base score (default 0.60)
	TermWeight      float64 // weight of query/text term overlap (default 0.25)
	EntityWeight    float64 // weight of query/item entity overlap (default 0.15)
}

type Reranker interface {
	// Rerank returns one relevance score per document, in the same order as
	// documents (score[i] corresponds to documents[i]). Higher is more relevant;
	// the scale is arbitrary (the retrieval path normalizes before blending).
	Rerank(ctx context.Context, query string, documents []string) ([]float64, error)
}

type ResolvedObject struct {
	ObjectID   string            `json:"object_id"`
	ObjectType string            `json:"object_type"`
	Title      string            `json:"title,omitempty"`
	Properties map[string]string `json:"properties,omitempty"`
}

type RetrievalDecision struct {
	RequestedMode string `json:"requested_mode"`
	EffectiveMode string `json:"effective_mode"`
	UseGraph      bool   `json:"use_graph"`
	Reason        string `json:"reason,omitempty"`
}

type RetrievalFilters struct {
	Collection  string   `json:"collection,omitempty"`
	DocumentIDs []string `json:"document_ids,omitempty"`
	UserID      string   `json:"user_id,omitempty"`
	SessionID   string   `json:"session_id,omitempty"`
	Scope       string   `json:"scope,omitempty"`
	Namespace   string   `json:"namespace,omitempty"`
}

type RetrievalPlan struct {
	Query            string   `json:"query,omitempty"`
	Keywords         []string `json:"keywords,omitempty"`
	AlternateQueries []string `json:"alternate_queries,omitempty"`
	EntityNames      []string `json:"entity_names,omitempty"`
	RetrievalMode    string   `json:"retrieval_mode,omitempty"`
	// Collection is shorthand for Filters.Collection.
	//
	// `collection` is a top-level parameter of the same call and also lives at
	// `plan.filters.collection`, so a model reaches for `plan.collection` — and with
	// additionalProperties:false that was a hard schema rejection, costing a whole model round trip on
	// every scoped search before it guessed the longer spelling. Accepting it is cheaper than being
	// right about it. Filters.Collection is the more specific spelling and wins.
	Collection string            `json:"collection,omitempty"`
	Filters    *RetrievalFilters `json:"filters,omitempty"`
}

type TextSearchOptions struct {
	Collection       string
	TopK             int
	Threshold        float64
	Keywords         []string
	AlternateQueries []string

	// Authorize, when set, is a retrieval-layer security gate: it is applied to
	// every candidate and only authorized rows count toward TopK. The search
	// over-fetches internally so the caller still receives up to TopK authorized
	// results. This pushes access control (RBAC/ABAC) into the retrieval boundary
	// instead of leaving it to post-filtering in application code.
	Authorize func(core.ScoredEmbedding) bool

	// Reranker, when set, re-scores and reorders the authorized candidate set
	// (typically a cross-encoder or LLM) before MinScore filtering and TopK
	// truncation — the standard recall→precision second stage.
	Reranker core.Reranker

	// MinScore, when > 0, drops candidates whose (possibly reranked) Score is
	// below the threshold — a relevance floor that prevents weak tail matches
	// from being surfaced.
	MinScore float64
}

type ToolBuildContextRequest struct {
	ChunkIDs            []string `json:"chunk_ids"`
	MaxContextChunks    int      `json:"max_context_chunks,omitempty"`
	MaxContextChars     int      `json:"max_context_chars,omitempty"`
	PerDocumentLimit    int      `json:"per_document_limit,omitempty"`
	RetrievalMode       string   `json:"retrieval_mode,omitempty"`
	DisableGraph        bool     `json:"disable_graph,omitempty"`
	GraphLight          bool     `json:"graph_light,omitempty"`
	MaxEntitiesPerChunk int      `json:"max_entities_per_chunk,omitempty"`
}

type ToolBuildContextResponse struct {
	Chunks  []GraphRAGChunkResult `json:"chunks"`
	Context string                `json:"context"`
}

type ToolChunk struct {
	ID         string            `json:"id"`
	DocumentID string            `json:"document_id,omitempty"`
	Content    string            `json:"content"`
	Score      float64           `json:"score,omitempty"`
	Metadata   map[string]string `json:"metadata,omitempty"`
	Entities   []string          `json:"entities,omitempty"`
}

type ToolDefinition struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	InputSchema map[string]any `json:"input_schema"`
}

type ToolDeleteDocumentGraphRequest struct {
	DocumentID string `json:"document_id"`
	// DryRun reports what would be removed without removing it.
	DryRun bool `json:"dry_run,omitempty"`
}

type ToolDeleteDocumentGraphResponse struct {
	// EntityNodesDeleted counts entities whose only source was this document.
	EntityNodesDeleted int `json:"entity_nodes_deleted"`
	// EntityNodesDetached counts entities other documents also assert: this
	// document's claim was removed, the entity stays.
	EntityNodesDetached  int  `json:"entity_nodes_detached"`
	ChunkNodesDeleted    int  `json:"chunk_nodes_deleted"`
	DocumentNodeDeleted  bool `json:"document_node_deleted"`
	RelationEdgesDeleted int  `json:"relation_edges_deleted"`
	DryRun               bool `json:"dry_run,omitempty"`
}

type ToolDeleteEntitiesRequest struct {
	// Names are entity names or full node ids ("entity:foo"). Names are
	// resolved the same way upsert_entities resolves them, so a caller can pass
	// back exactly what it saw.
	Names []string `json:"names"`
	// DryRun reports what would be removed without removing it. Deletion is not
	// reversible, so a caller that is guessing should look first.
	DryRun bool `json:"dry_run,omitempty"`
}

type ToolDeleteEntitiesResponse struct {
	Deleted []string `json:"deleted,omitempty"`
	// NotFound names nothing was stored under, so a typo surfaces instead of
	// being reported as a successful deletion of nothing.
	NotFound     []string `json:"not_found,omitempty"`
	EdgesRemoved int      `json:"edges_removed"`
	DryRun       bool     `json:"dry_run,omitempty"`
}

type ToolEntityInput struct {
	ID          string            `json:"id,omitempty"`
	Name        string            `json:"name"`
	Type        string            `json:"type,omitempty"`
	Description string            `json:"description,omitempty"`
	ChunkIDs    []string          `json:"chunk_ids,omitempty"`
	Metadata    map[string]string `json:"metadata,omitempty"`
}

type ToolExpandGraphRequest struct {
	NodeIDs   []string `json:"node_ids"`
	MaxHops   int      `json:"max_hops,omitempty"`
	EdgeTypes []string `json:"edge_types,omitempty"`
	NodeTypes []string `json:"node_types,omitempty"`
	Limit     int      `json:"limit,omitempty"`
}

type ToolExpandGraphResponse struct {
	Nodes []*graph.GraphNode `json:"nodes"`
	Edges []*graph.GraphEdge `json:"edges"`
}

type ToolExtractConversationRequest struct {
	// Text is the conversation content to analyze. If empty, SessionID is used
	// to load the session's messages.
	Text string `json:"text,omitempty"`
	// SessionID loads and concatenates that session's messages when Text is empty.
	SessionID string `json:"session_id,omitempty"`
	// Persist writes the extracted entities/relations into the knowledge graph
	// and the summary into durable knowledge.
	Persist bool `json:"persist,omitempty"`
	// Collection for the persisted summary (default "conversations").
	Collection string `json:"collection,omitempty"`
	// MaxEntities caps extracted entities (default 30).
	MaxEntities int `json:"max_entities,omitempty"`
}

type ToolExtractConversationResponse struct {
	Summary     string              `json:"summary"`
	Themes      []string            `json:"themes,omitempty"`
	Entities    []string            `json:"entities,omitempty"`
	Relations   []ExtractedRelation `json:"relations,omitempty"`
	Persisted   bool                `json:"persisted"`
	KnowledgeID string              `json:"knowledge_id,omitempty"`
}

type ToolFindNodesRequest struct {
	Names []string `json:"names"`
	// Optional filter, e.g. []string{"Concept"}. Empty means any type.
	NodeTypes []string `json:"node_types,omitempty"`
	// Per-name cap. Zero means the default.
	Limit int `json:"limit,omitempty"`
}

type ToolFindNodesResponse struct {
	Matches []ToolNodeNameMatch `json:"matches"`
}

type ToolGetChunksRequest struct {
	ChunkIDs            []string `json:"chunk_ids"`
	RetrievalMode       string   `json:"retrieval_mode,omitempty"`
	DisableGraph        bool     `json:"disable_graph,omitempty"`
	GraphLight          bool     `json:"graph_light,omitempty"`
	MaxEntitiesPerChunk int      `json:"max_entities_per_chunk,omitempty"`
}

type ToolGetChunksResponse struct {
	Chunks []ToolChunk `json:"chunks"`
}

type ToolGetNodesRequest struct {
	NodeIDs []string `json:"node_ids"`
}

type ToolGetNodesResponse struct {
	Nodes []*graph.GraphNode `json:"nodes"`
}

type ToolIngestDocumentRequest struct {
	DocumentID   string            `json:"document_id"`
	Title        string            `json:"title,omitempty"`
	Content      string            `json:"content"`
	Collection   string            `json:"collection,omitempty"`
	ChunkSize    int               `json:"chunk_size,omitempty"`
	ChunkOverlap int               `json:"chunk_overlap,omitempty"`
	Metadata     map[string]string `json:"metadata,omitempty"`
}