cortexdb

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 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 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 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"`
}

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"`
	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 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 OntologyDeleteRequest struct {
	SchemaID string `json:"schema_id"`
}

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

type OntologyEntityType struct {
	Name               string   `json:"name"`
	Description        string   `json:"description,omitempty"`
	RequiredProperties []string `json:"required_properties,omitempty"`
}

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

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

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

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

type OntologyRelationType struct {
	Name               string   `json:"name"`
	Description        string   `json:"description,omitempty"`
	AllowedFromTypes   []string `json:"allowed_from_types,omitempty"`
	AllowedToTypes     []string `json:"allowed_to_types,omitempty"`
	RequiredProperties []string `json:"required_properties,omitempty"`
}

type OntologySaveRequest struct {
	SchemaID      string                 `json:"schema_id"`
	Name          string                 `json:"name,omitempty"`
	Description   string                 `json:"description,omitempty"`
	Version       int                    `json:"version,omitempty"`
	Activate      bool                   `json:"activate,omitempty"`
	Deactivate    bool                   `json:"deactivate,omitempty"`
	Metadata      map[string]string      `json:"metadata,omitempty"`
	EntityTypes   []OntologyEntityType   `json:"entity_types,omitempty"`
	RelationTypes []OntologyRelationType `json:"relation_types,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"`
	Metadata      map[string]string      `json:"metadata,omitempty"`
	EntityTypes   []OntologyEntityType   `json:"entity_types,omitempty"`
	RelationTypes []OntologyRelationType `json:"relation_types,omitempty"`
	CreatedAt     time.Time              `json:"created_at"`
	UpdatedAt     time.Time              `json:"updated_at"`
}

type Option func(*DB)

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 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 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"`
	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 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 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"`
}

type ToolIngestDocumentResponse struct {
	DocumentNodeID string   `json:"document_node_id"`
	ChunkNodeIDs   []string `json:"chunk_node_ids"`
	Collection     string   `json:"collection"`
}

type ToolRelationInput struct {
	From           string            `json:"from"`
	To             string            `json:"to"`
	Type           string            `json:"type,omitempty"`
	Weight         float64           `json:"weight,omitempty"`
	ChunkIDs       []string          `json:"chunk_ids,omitempty"`
	Metadata       map[string]string `json:"metadata,omitempty"`
	Inferred       bool              `json:"inferred,omitempty"`
	Provenance     string            `json:"provenance,omitempty"`
	RuleID         string            `json:"rule_id,omitempty"`
	SupportEdgeIDs []string          `json:"support_edge_ids,omitempty"`
}

type ToolSearchChunksByEntitiesRequest struct {
	EntityNames []string `json:"entity_names"`
	TopK        int      `json:"top_k,omitempty"`
	MaxHops     int      `json:"max_hops,omitempty"`
}

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

type ToolSearchGraphRAGLexicalRequest 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"`
	DisableRerank       bool           `json:"disable_rerank,omitempty"`
	DiversityLambda     float64        `json:"diversity_lambda,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 ToolSearchTextRequest struct {
	Query               string         `json:"query"`
	Collection          string         `json:"collection,omitempty"`
	TopK                int            `json:"top_k,omitempty"`
	Threshold           float64        `json:"threshold,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"`
	MaxEntitiesPerChunk int            `json:"max_entities_per_chunk,omitempty"`
	Plan                *RetrievalPlan `json:"plan,omitempty"`
}

type ToolSearchTextResponse struct {
	Plan     RetrievalPlan     `json:"plan"`
	Decision RetrievalDecision `json:"decision"`
	Chunks   []ToolChunk       `json:"chunks"`
}

type ToolUpsertEntitiesRequest struct {
	DocumentID string            `json:"document_id,omitempty"`
	Entities   []ToolEntityInput `json:"entities"`
}

type ToolUpsertEntitiesResponse struct {
	EntityNodeIDs    []string `json:"entity_node_ids"`
	MentionEdgeCount int      `json:"mention_edge_count"`
}

type ToolUpsertRelationsRequest struct {
	DocumentID string              `json:"document_id,omitempty"`
	Relations  []ToolRelationInput `json:"relations"`
}

type ToolUpsertRelationsResponse struct {
	EdgeIDs []string `json:"edge_ids"`
}