types

type AddDocumentOptions struct {
	CollectionName string      `json:"collection_name"`
	Documents      []*Document `json:"documents"`            // Documents to add (ID in Document will be used if provided, otherwise auto-generated)
	BatchSize      int         `json:"batch_size,omitempty"` // Batch size for bulk insert
	Timeout        int         `json:"timeout,omitempty"`    // Operation timeout in seconds
	Upsert         bool        `json:"upsert,omitempty"`     // If true, update existing documents with same ID

	// Vector operation mode - determines which vectors to insert/update
	VectorMode VectorMode `json:"vector_mode,omitempty"` // "dense_only", "sparse_only", "both", "auto" (default: "auto")

	// Named vector support (for collections with multiple vectors)
	VectorUsing      string `json:"vector_using,omitempty"`       // Named vector to use for document vectors (e.g., "dense", "sparse") - legacy field
	DenseVectorName  string `json:"dense_vector_name,omitempty"`  // Named vector for dense vectors (default: "dense")
	SparseVectorName string `json:"sparse_vector_name,omitempty"` // Named vector for sparse vectors (default: "sparse")
}

type AddNodesOptions struct {
	GraphName string       `json:"graph_name"`
	Nodes     []*GraphNode `json:"nodes"`
	BatchSize int          `json:"batch_size,omitempty"` // Batch size for bulk insert
	Upsert    bool         `json:"upsert,omitempty"`     // If true, update existing nodes with same ID
	Timeout   int          `json:"timeout,omitempty"`    // Operation timeout in seconds
}

type AddRelationshipsOptions struct {
	GraphName     string               `json:"graph_name"`
	Relationships []*GraphRelationship `json:"relationships"`
	BatchSize     int                  `json:"batch_size,omitempty"`
	Upsert        bool                 `json:"upsert,omitempty"`
	CreateNodes   bool                 `json:"create_nodes,omitempty"` // Create nodes if they don't exist
	Timeout       int                  `json:"timeout,omitempty"`
}

type BackupOptions struct {
	CollectionName string                 `json:"collection_name"`
	Compress       bool                   `json:"compress"`
	ExtraParams    map[string]interface{} `json:"extra_params,omitempty"`
}

type ChatMessage struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

type Chunk struct {
	ID       string       `json:"id,omitempty"`
	Text     string       `json:"text"`
	Type     ChunkingType `json:"type"` // Chunking type from ChunkingType enum
	ParentID string       `json:"parent_id,omitempty"`
	Depth    int          `json:"depth"`
	Leaf     bool         `json:"leaf"` // Whether the chunk is a leaf node
	Root     bool         `json:"root"` // Whether the chunk is a root node

	// Status and index
	Index  int            `json:"index"`  // Index of the chunk in the parent chunk
	Status ChunkingStatus `json:"status"` // Status of the chunk, for example, "pending", "processing", "completed", "failed"

	// Parents of the chunk
	Parents []Chunk `json:"parents"` // Parents of the chunk

	// Position information (only one should be populated based on content type)
	TextPos  *TextPosition  `json:"text_position,omitempty"`  // For text, code, etc.
	MediaPos *MediaPosition `json:"media_position,omitempty"` // For PDF, video, audio, etc.

	// Extracted text
	Extracted *ExtractionResult `json:"extracted,omitempty"` // Extracted text from the chunk

	// Metadata of the chunk
	Metadata map[string]interface{} `json:"metadata,omitempty"` // Metadata of the chunk
}

type Chunking interface {
	Chunk(ctx context.Context, text string, options *ChunkingOptions, callback ChunkingProgress) error
	ChunkFile(ctx context.Context, file string, options *ChunkingOptions, callback ChunkingProgress) error
	ChunkStream(ctx context.Context, stream io.ReadSeeker, options *ChunkingOptions, callback ChunkingProgress) error
}

type ChunkingOptions struct {
	Type            ChunkingType     `json:"type,omitempty"`   // Content type, auto-detected if not provided
	Size            int              `json:"size"`             // For text, PDF, Word, only, default is QA 300, Code 800,
	Overlap         int              `json:"overlap"`          // For text, PDF, Word, only, default is QA 20, Code 100,
	MaxDepth        int              `json:"max_depth"`        // For text, PDF, Word, only, default is 5
	SizeMultiplier  int              `json:"size_multiplier"`  // Base multiplier for chunk size calculation, default is 3
	MaxConcurrent   int              `json:"max_concurrent"`   // Maximum concurrent operations
	Separator       string           `json:"separator"`        // Custom separator pattern (regex supported)
	EnableDebug     bool             `json:"enable_debug"`     // Enable debug mode for detailed splitting information
	SemanticOptions *SemanticOptions `json:"semantic_options"` // For Semantic recognition, etc.
}

type ChunkingProgress func(chunk *Chunk) error

type ChunkingStatus string

type ChunkingType string

type Collection struct {
	ID               string                   `json:"id"`
	Metadata         map[string]interface{}   `json:"metadata"`
	VectorConfig     *VectorStoreConfig       `json:"vector_config"`     // Connection configuration
	CollectionConfig *CreateCollectionOptions `json:"collection_config"` // Collection creation configuration
	GraphStoreConfig *GraphStoreConfig        `json:"graph_store_config"`
}

type CollectionConfig struct {
	ID       string                   `json:"id"`
	Metadata map[string]interface{}   `json:"metadata"`
	Config   *CreateCollectionOptions `json:"config"`
}

type CollectionIDs struct {
	Vector string `json:"vector"` // Vector database collection ID
	Graph  string `json:"graph"`  // Graph database collection ID (uses Vector as prefix)
	Store  string `json:"store"`  // KV store database collection ID (uses Vector as prefix)
}

type CollectionInfo struct {
	ID       string                   `json:"id"`
	Metadata map[string]interface{}   `json:"metadata"`
	Config   *CreateCollectionOptions `json:"config"`
}

type Community struct {
	ID         string                 `json:"id"`
	Level      int                    `json:"level"`                // Hierarchy level (0 = leaf level)
	ParentID   string                 `json:"parent_id,omitempty"`  // Parent community ID
	Members    []string               `json:"members"`              // Node IDs in this community
	Size       int                    `json:"size"`                 // Number of members
	Title      string                 `json:"title,omitempty"`      // Community title/summary
	Summary    string                 `json:"summary,omitempty"`    // Community description
	Properties map[string]interface{} `json:"properties,omitempty"` // Additional properties
}

type CommunityDetectionOptions struct {
	GraphName  string                 `json:"graph_name"`           // Target graph name
	Algorithm  string                 `json:"algorithm"`            // "leiden", "louvain", "label_propagation"
	MaxLevels  int                    `json:"max_levels,omitempty"` // Maximum hierarchy levels
	Resolution float64                `json:"resolution,omitempty"` // Resolution parameter
	Randomness float64                `json:"randomness,omitempty"` // Randomness parameter
	Parameters map[string]interface{} `json:"parameters,omitempty"` // Algorithm-specific parameters
}

type Config struct {
	GraphStore  GraphStore  `json:"graph_store"`
	VectorStore VectorStore `json:"vector_store"`
	Embedding   Embedding   `json:"embedding_function"`

	// Community detection settings
	CommunityDetection CommunityDetectionOptions `json:"community_detection"`

	// Retrieval settings
	MaxSearchDepth int     `json:"max_search_depth"`
	VectorTopK     int     `json:"vector_top_k"`
	HybridWeight   float64 `json:"hybrid_weight"` // Balance between vector and graph search

	// LLM settings for text-to-query
	LLMModel       string `json:"llm_model"`
	PromptTemplate string `json:"prompt_template"`
}

type ConvertResult struct {
	Text     string                 `json:"text"`     // Converted text content
	Metadata map[string]interface{} `json:"metadata"` // Additional metadata from conversion (page mappings, structure info, etc.)
}

type Converter interface {
	Convert(ctx context.Context, file string, callback ...ConverterProgress) (*ConvertResult, error)                // Convert a file to plain text with metadata
	ConvertStream(ctx context.Context, stream io.ReadSeeker, callback ...ConverterProgress) (*ConvertResult, error) // Convert a stream to plain text with metadata
}

type ConverterPayload struct {
	Status   ConverterStatus `json:"status"`
	Message  string          `json:"message"`
	Progress float64         `json:"progress"`
}

type ConverterProgress func(status ConverterStatus, payload ConverterPayload)

type ConverterStatus string

type CreateCollectionOptions struct {
	// Collection Basic Configuration
	CollectionName string         `json:"collection_name" yaml:"collection_name"` // Collection/Table name
	Dimension      int            `json:"dimension" yaml:"dimension"`             // Vector dimension (e.g., 1536 for OpenAI embeddings)
	Distance       DistanceMetric `json:"distance" yaml:"distance"`               // Distance metric
	IndexType      IndexType      `json:"index_type" yaml:"index_type"`           // Index type

	// Index Parameters (for HNSW)
	M              int `json:"m,omitempty" yaml:"m,omitempty"`                             // Number of bidirectional links for each node (HNSW)
	EfConstruction int `json:"ef_construction,omitempty" yaml:"ef_construction,omitempty"` // Size of dynamic candidate list (HNSW)
	EfSearch       int `json:"ef_search,omitempty" yaml:"ef_search,omitempty"`             // Size of dynamic candidate list for search (HNSW)

	// Index Parameters (for IVF)
	NumLists  int `json:"num_lists,omitempty" yaml:"num_lists,omitempty"`   // Number of clusters (IVF)
	NumProbes int `json:"num_probes,omitempty" yaml:"num_probes,omitempty"` // Number of clusters to search (IVF)

	// Sparse Vector Configuration (for hybrid search)
	EnableSparseVectors bool   `json:"enable_sparse_vectors,omitempty" yaml:"enable_sparse_vectors,omitempty"` // Enable sparse vector support for hybrid retrieval
	DenseVectorName     string `json:"dense_vector_name,omitempty" yaml:"dense_vector_name,omitempty"`         // Named vector for dense vectors (default: "dense")
	SparseVectorName    string `json:"sparse_vector_name,omitempty" yaml:"sparse_vector_name,omitempty"`       // Named vector for sparse vectors (default: "sparse")

	// Storage Configuration
	PersistPath string `json:"persist_path,omitempty" yaml:"persist_path,omitempty"` // Path for persistent storage

	// Collection-specific settings
	ExtraParams map[string]interface{} `json:"extra_params,omitempty" yaml:"extra_params,omitempty"` // Collection-specific parameters
}

type CreateIndexOptions struct {
	GraphName   string                 `json:"graph_name"`
	IndexType   string                 `json:"index_type"`       // "BTREE", "FULLTEXT", "VECTOR", etc.
	Target      string                 `json:"target"`           // "NODE" or "RELATIONSHIP"
	Labels      []string               `json:"labels,omitempty"` // Node labels or relationship types
	Properties  []string               `json:"properties"`       // Properties to index
	Name        string                 `json:"name,omitempty"`   // Index name
	Config      map[string]interface{} `json:"config,omitempty"` // Index-specific configuration
	IfNotExists bool                   `json:"if_not_exists"`    // Don't error if index already exists
}

type DeleteDocumentOptions struct {
	CollectionName string                 `json:"collection_name"`
	IDs            []string               `json:"ids,omitempty"`    // Specific document IDs to delete
	Filter         map[string]interface{} `json:"filter,omitempty"` // Filter conditions for bulk delete
	DryRun         bool                   `json:"dry_run"`          // Preview what would be deleted
}

type DeleteNodesOptions struct {
	GraphName  string                 `json:"graph_name"`
	IDs        []string               `json:"ids,omitempty"`         // Specific node IDs
	Filter     map[string]interface{} `json:"filter,omitempty"`      // Filter for bulk delete
	DeleteRels bool                   `json:"delete_rels,omitempty"` // Whether to delete connected relationships
	DryRun     bool                   `json:"dry_run"`               // Preview what would be deleted
	BatchSize  int                    `json:"batch_size,omitempty"`
	Timeout    int                    `json:"timeout,omitempty"`
}

type DeleteRelationshipsOptions struct {
	GraphName string                 `json:"graph_name"`
	IDs       []string               `json:"ids,omitempty"`
	Filter    map[string]interface{} `json:"filter,omitempty"`
	DryRun    bool                   `json:"dry_run"`
	BatchSize int                    `json:"batch_size,omitempty"`
	Timeout   int                    `json:"timeout,omitempty"`
}

type DistanceMetric string

type Document struct {
	ID           string                 `json:"id,omitempty"`
	Content      string                 `json:"content"`
	Vector       []float64              `json:"vector,omitempty"`        // Dense vector (legacy field for backward compatibility)
	DenseVector  []float64              `json:"dense_vector,omitempty"`  // Dense embedding vector
	SparseVector *SparseVector          `json:"sparse_vector,omitempty"` // Sparse embedding vector
	Metadata     map[string]interface{} `json:"metadata,omitempty"`
}

type DocumentMetadataUpdate struct {
	DocumentID string                 `json:"document_id"`        // Document ID to update
	Metadata   map[string]interface{} `json:"metadata,omitempty"` // Specific metadata for this document (if provided, overrides defaultMetadata)
}

type DropIndexOptions struct {
	GraphName string `json:"graph_name"`
	Name      string `json:"name"`      // Index name
	IfExists  bool   `json:"if_exists"` // Don't error if index doesn't exist
}

type DynamicGraphSchema struct {
	NodeLabels        []string                  `json:"node_labels"`
	RelationshipTypes []string                  `json:"relationship_types"`
	NodeProperties    map[string][]PropertyInfo `json:"node_properties"` // label -> property info
	RelProperties     map[string][]PropertyInfo `json:"rel_properties"`  // type -> property info
	Constraints       []SchemaConstraint        `json:"constraints"`
	Indexes           []SchemaIndex             `json:"indexes"`
	Statistics        *GraphSchemaStats         `json:"statistics,omitempty"`
}

type Embedding interface {
	// EmbedDocuments embeds a list of documents
	EmbedDocuments(ctx context.Context, texts []string, callback ...EmbeddingProgress) (*EmbeddingResults, error)

	// EmbedQuery embeds a single query
	EmbedQuery(ctx context.Context, text string, callback ...EmbeddingProgress) (*EmbeddingResult, error)

	// GetDimension returns the dimension of the embedding vectors
	GetDimension() int

	// GetModel returns the model of the embedding function
	GetModel() string
}

type EmbeddingPayload struct {
	// Common fields
	Current int    `json:"current"` // Current progress count
	Total   int    `json:"total"`   // Total items to process
	Message string `json:"message"` // Status message

	// Document embedding specific
	DocumentIndex *int    `json:"document_index,omitempty"` // Index of current document being processed
	DocumentText  *string `json:"document_text,omitempty"`  // Text being processed (truncated if too long)

	// Error specific
	Error error `json:"error,omitempty"` // Error details when Status is StatusError
}

type EmbeddingProgress func(status EmbeddingStatus, payload EmbeddingPayload)

type EmbeddingResult struct {
	Usage     EmbeddingUsage `json:"usage"`               // Usage statistics
	Model     string         `json:"model"`               // Model used for embedding
	Type      EmbeddingType  `json:"type"`                // Type of embedding (dense/sparse)
	Embedding []float64      `json:"embedding,omitempty"` // Dense vector (for dense embeddings)
	Indices   []uint32       `json:"indices,omitempty"`   // Sparse vector indices (for sparse embeddings)
	Values    []float32      `json:"values,omitempty"`    // Sparse vector values (for sparse embeddings)
}

type EmbeddingResults struct {
	Usage            EmbeddingUsage    `json:"usage"`                       // Combined usage statistics
	Model            string            `json:"model"`                       // Model used for embedding
	Type             EmbeddingType     `json:"type"`                        // Type of embedding (dense/sparse)
	Embeddings       [][]float64       `json:"embeddings,omitempty"`        // Dense vectors (for dense embeddings)
	SparseEmbeddings []SparseEmbedding `json:"sparse_embeddings,omitempty"` // Sparse vectors (for sparse embeddings)
}

type EmbeddingStatus string

type EmbeddingType string

type EmbeddingUsage struct {
	TotalTokens  int `json:"total_tokens"`  // Total number of tokens processed
	PromptTokens int `json:"prompt_tokens"` // Number of tokens in the input
	TotalTexts   int `json:"total_texts"`   // Total number of texts processed
}

type Embeddings []*EmbeddingResult

type EntityDeduplicationResult struct {
	NormalizedID string   `json:"normalized_id"`
	DocIDs       []string `json:"doc_ids"`
	IsUpdate     bool     `json:"is_update"`
}

type EntityStatus string

type Extraction interface {
	ExtractDocuments(ctx context.Context, texts []string, callback ...ExtractionProgress) ([]*ExtractionResult, error)
	ExtractQuery(ctx context.Context, text string, callback ...ExtractionProgress) (*ExtractionResult, error)
}

type ExtractionMethod string

type ExtractionOptions struct {
	Use       Extraction `json:"use"`       // Use the extraction method
	Embedding Embedding  `json:"embedding"` // Embedding function to use for extraction
}

type ExtractionPayload struct {
	// Common fields
	Current int    `json:"current"` // Current progress count
	Total   int    `json:"total"`   // Total items to process
	Message string `json:"message"` // Status message

	// Document embedding specific
	DocumentIndex *int    `json:"document_index,omitempty"` // Index of current document being processed
	DocumentText  *string `json:"document_text,omitempty"`  // Text being processed (truncated if too long)

	// Error specific
	Error error `json:"error,omitempty"` // Error details when Status is StatusError
}

type ExtractionProgress func(status ExtractionStatus, payload ExtractionPayload)

type ExtractionResult struct {
	Usage         ExtractionUsage `json:"usage"`                   // Combined usage statistics
	Model         string          `json:"model"`                   // Model used for extraction
	Nodes         []Node          `json:"nodes,omitempty"`         // Extracted entities
	Relationships []Relationship  `json:"relationships,omitempty"` // Extracted relationships
}

type ExtractionStatus string

type ExtractionUsage struct {
	TotalTokens  int `json:"total_tokens"`  // Total number of tokens processed
	PromptTokens int `json:"prompt_tokens"` // Number of tokens in the input
	TotalTexts   int `json:"total_texts"`   // Total number of texts processed
}

type Fetcher interface {
	Fetch(ctx context.Context, url string, callback ...FetcherProgress) (string, string, error)
}

type FetcherPayload struct {
	Status   FetcherStatus `json:"status"`
	Message  string        `json:"message"`
	Progress float64       `json:"progress"`
	Bytes    int64         `json:"bytes"`
	URL      string        `json:"url"`
}

type FetcherProgress func(status FetcherStatus, payload FetcherPayload)

type FetcherStatus string

type FusionType string

type GetDocumentOptions struct {
	CollectionName string   `json:"collection_name"`
	Fields         []string `json:"fields,omitempty"` // Specific fields to retrieve
	IncludeVector  bool     `json:"include_vector"`   // Whether to include vector data
	IncludePayload bool     `json:"include_payload"`  // Whether to include payload/metadata
}

type GetNodesOptions struct {
	GraphName string                 `json:"graph_name"`
	IDs       []string               `json:"ids,omitempty"`    // Specific node IDs
	Labels    []string               `json:"labels,omitempty"` // Filter by labels
	Filter    map[string]interface{} `json:"filter,omitempty"` // Property filters

	// Return control
	IncludeProperties bool     `json:"include_properties"` // Whether to include properties
	IncludeMetadata   bool     `json:"include_metadata"`   // Whether to include metadata
	Fields            []string `json:"fields,omitempty"`   // Specific fields to retrieve
	Limit             int      `json:"limit,omitempty"`    // Maximum results
}

type GetRelationshipsOptions struct {
	GraphName string                 `json:"graph_name"`
	IDs       []string               `json:"ids,omitempty"`       // Specific relationship IDs
	Types     []string               `json:"types,omitempty"`     // Filter by relationship types
	NodeIDs   []string               `json:"node_ids,omitempty"`  // Filter by connected nodes
	Direction string                 `json:"direction,omitempty"` // "IN", "OUT", "BOTH"
	Filter    map[string]interface{} `json:"filter,omitempty"`    // Property filters

	// Return control
	IncludeProperties bool     `json:"include_properties"`
	IncludeMetadata   bool     `json:"include_metadata"`
	Fields            []string `json:"fields,omitempty"`
	Limit             int      `json:"limit,omitempty"`
}

type GraphAnalyticsOptions struct {
	Algorithm     string                 `json:"algorithm"` // "pagerank", "betweenness", "closeness", etc.
	Iterations    int                    `json:"iterations,omitempty"`
	DampingFactor float64                `json:"damping_factor,omitempty"`
	Parameters    map[string]interface{} `json:"parameters,omitempty"`
}

type GraphBackupOptions struct {
	GraphName   string                 `json:"graph_name"`
	Format      string                 `json:"format,omitempty"` // "json", "gexf", "graphml", "cypher", etc.
	Compress    bool                   `json:"compress"`
	Filter      map[string]interface{} `json:"filter,omitempty"` // Filter what to backup
	ExtraParams map[string]interface{} `json:"extra_params,omitempty"`
}

type GraphConfig struct {
	Description  string                 `json:"description,omitempty"`
	Properties   map[string]interface{} `json:"properties,omitempty"`
	IndexConfig  *GraphIndexConfig      `json:"index_config,omitempty"`
	SchemaConfig *GraphSchemaConfig     `json:"schema_config,omitempty"`
}

type GraphIndexConfig struct {
	AutoIndex      bool     `json:"auto_index"`                // Whether to automatically create indexes
	NodeIndexes    []string `json:"node_indexes,omitempty"`    // Properties to index for nodes
	RelIndexes     []string `json:"rel_indexes,omitempty"`     // Properties to index for relationships
	FullTextFields []string `json:"fulltext_fields,omitempty"` // Fields for full-text search
	VectorFields   []string `json:"vector_fields,omitempty"`   // Fields for vector similarity search
}

type GraphNode struct {
	ID         string                 `json:"id"`
	Labels     []string               `json:"labels"`
	Properties map[string]interface{} `json:"properties"`

	// Vector embedding support
	Embedding  []float64            `json:"embedding,omitempty"`  // Primary embedding vector
	Embeddings map[string][]float64 `json:"embeddings,omitempty"` // Multiple named embeddings

	// GraphRAG specific fields (simplified design)
	EntityType  string  `json:"entity_type,omitempty"` // Entity type
	Description string  `json:"description,omitempty"` // Entity description
	Confidence  float64 `json:"confidence,omitempty"`  // Confidence score
	Importance  float64 `json:"importance,omitempty"`  // Importance score (PageRank, etc.)

	// Metadata
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
	Version   int       `json:"version"`
}

type GraphOperation struct {
	Type       string                 `json:"type"` // "CREATE_NODE", "CREATE_REL", "UPDATE_NODE", etc.
	Data       interface{}            `json:"data"` // Operation data (Node, Relationship, etc.)
	Parameters map[string]interface{} `json:"parameters,omitempty"`
}

type GraphPath struct {
	Nodes         []GraphNode         `json:"nodes"`         // Nodes in the path
	Relationships []GraphRelationship `json:"relationships"` // Relationships in the path
	Length        int                 `json:"length"`        // Path length
}

type GraphQueryOptions struct {
	GraphName string `json:"graph_name"` // Target graph name

	// Query Type and Content
	QueryType string `json:"query_type"`      // "cypher", "traversal", "path", "analytics", "custom"
	Query     string `json:"query,omitempty"` // Query string (e.g., Cypher query)

	// Traversal-specific options (when QueryType is "traversal")
	TraversalOptions *GraphTraversalOptions `json:"traversal_options,omitempty"`

	// Analytics-specific options (when QueryType is "analytics")
	AnalyticsOptions *GraphAnalyticsOptions `json:"analytics_options,omitempty"`

	// General query parameters
	Parameters map[string]interface{} `json:"parameters,omitempty"` // Query parameters

	// Result control
	Limit      int      `json:"limit,omitempty"`
	Skip       int      `json:"skip,omitempty"`
	OrderBy    []string `json:"order_by,omitempty"`    // Fields to order by
	ReturnType string   `json:"return_type,omitempty"` // "nodes", "relationships", "paths", "records", "all"

	// Performance and safety
	Timeout  int  `json:"timeout,omitempty"`   // Query timeout in seconds
	ReadOnly bool `json:"read_only,omitempty"` // Whether this is a read-only query
	Explain  bool `json:"explain,omitempty"`   // Whether to return query execution plan
	Profile  bool `json:"profile,omitempty"`   // Whether to return detailed profiling info
}

type GraphRag interface {
	// Collection Management
	CreateCollection(ctx context.Context, config CollectionConfig) (string, error)                  // Create a new collection
	RemoveCollection(ctx context.Context, id string) (bool, error)                                  // Remove a collection
	CollectionExists(ctx context.Context, id string) (bool, error)                                  // Check if a collection exists
	GetCollection(ctx context.Context, id string) (*CollectionInfo, error)                          // Get a single collection by ID
	GetCollections(ctx context.Context, filter map[string]interface{}) ([]CollectionInfo, error)    // Get collections with optional metadata filtering
	UpdateCollectionMetadata(ctx context.Context, id string, metadata map[string]interface{}) error // Update collection metadata

	// Document Management
	AddFile(ctx context.Context, file string, options *UpsertOptions) (string, error)            // Add a file to a collection
	AddText(ctx context.Context, text string, options *UpsertOptions) (string, error)            // Add a text to a collection
	AddURL(ctx context.Context, url string, options *UpsertOptions) (string, error)              // Add a URL to a collection
	AddStream(ctx context.Context, stream io.ReadSeeker, options *UpsertOptions) (string, error) // Add a stream to a collection
	RemoveDocs(ctx context.Context, ids []string) (int, error)                                   // Remove documents by IDs

	// Segment Management
	AddSegments(ctx context.Context, docID string, segmentTexts []SegmentText, options *UpsertOptions) ([]string, error) // Add segments to a document manually, return segment IDs
	UpdateSegments(ctx context.Context, segmentTexts []SegmentText, options *UpsertOptions) (int, error)                 // Update segments manually, return updated count
	RemoveSegments(ctx context.Context, docID string, segmentIDs []string) (int, error)                                  // Remove segments by SegmentIDs, return removed count
	RemoveSegmentsByDocID(ctx context.Context, docID string) (int, error)                                                // Remove all segments of a document, return removed count
	GetSegments(ctx context.Context, docID string, segmentIDs []string) ([]Segment, error)                               // Get segments by IDs, return segments
	GetSegment(ctx context.Context, docID string, segmentID string) (*Segment, error)                                    // Get a single segment by ID, return segment
	GetSegmentParents(ctx context.Context, docID string, segmentID string) (*SegmentTree, error)                         // Get parent tree of a given segment, return hierarchical tree structure
	// ListSegments(ctx context.Context, docID string, options *ListSegmentsOptions) (*PaginatedSegmentsResult, error)      // List segments with pagination, return segments Deprecated
	ScrollSegments(ctx context.Context, docID string, options *ScrollSegmentsOptions) (*SegmentScrollResult, error) // Scroll segments with iterator-style pagination, return segments
	SegmentCount(ctx context.Context, docID string) (int, error)                                                    // Get segment count for a document

	// Segment Voting, Scoring, Weighting, Hit
	UpdateVotes(ctx context.Context, docID string, segments []SegmentVote, options ...UpdateVoteOptions) (int, error)       // Vote for segments, return updated count
	RemoveVotes(ctx context.Context, docID string, votes []VoteRemoval) (int, error)                                        // Remove votes by VoteID and update statistics, return removed count
	RemoveVotesBySegmentID(ctx context.Context, docID string, segmentID string) (int, error)                                // Remove all votes for a segment and clear statistics, return removed count
	ScrollVotes(ctx context.Context, docID string, options *ScrollVotesOptions) (*VoteScrollResult, error)                  // Scroll votes with pagination support
	GetVote(ctx context.Context, docID string, segmentID string, voteID string) (*SegmentVote, error)                       // Get a single vote by ID
	UpdateScores(ctx context.Context, docID string, segments []SegmentScore, options ...UpdateScoreOptions) (int, error)    // Score for segments, return updated count
	UpdateWeights(ctx context.Context, docID string, segments []SegmentWeight, options ...UpdateWeightOptions) (int, error) // Weight for segments, return updated count
	UpdateHits(ctx context.Context, docID string, segments []SegmentHit, options ...UpdateHitOptions) (int, error)          // Hit for segments, return updated count
	RemoveHits(ctx context.Context, docID string, hits []HitRemoval) (int, error)                                           // Remove hits by HitID, return removed count
	RemoveHitsBySegmentID(ctx context.Context, docID string, segmentID string) (int, error)                                 // Remove all hits for a segment and clear statistics, return removed count
	ScrollHits(ctx context.Context, docID string, options *ScrollHitsOptions) (*HitScrollResult, error)                     // Scroll hits with pagination support
	GetHit(ctx context.Context, docID string, segmentID string, hitID string) (*SegmentHit, error)                          // Get a single hit by ID

	// Segment Graph Management
	GetSegmentGraph(ctx context.Context, docID string, segmentID string) (*SegmentGraph, error)                                            // Get the graph (entities and relationships) for a specific segment
	GetSegmentEntities(ctx context.Context, docID string, segmentID string) ([]GraphNode, error)                                           // Get the entities for a specific segment
	GetSegmentRelationships(ctx context.Context, docID string, segmentID string) ([]GraphRelationship, error)                              // Get the relationships for a specific segment (filtered by segmentID in source_chunks)
	GetSegmentRelationshipsByEntities(ctx context.Context, docID string, segmentID string) ([]GraphRelationship, error)                    // Get all relationships connected to entities in this segment (regardless of relationship source_chunks)
	ExtractSegmentGraph(ctx context.Context, docID string, segmentID string, options *ExtractionOptions) (*SegmentExtractionResult, error) // Re-extract entities and relationships for a specific segment

	// Search Management
	Search(ctx context.Context, options *QueryOptions, callback ...SearcherProgress) ([]Segment, error)                  // Search for segments (vector + optional graph enrichment)
	MultiSearch(ctx context.Context, options []QueryOptions, callback ...SearcherProgress) (map[string][]Segment, error) // Multi-search for segments

	// Pure Vector Search (for application-side orchestration)
	SearchVector(ctx context.Context, options *VectorSearchOptions, callback ...SearcherProgress) (*VectorSearchResult, error) // Pure vector similarity search

	// Pure Graph Search (for application-side orchestration)
	SearchGraph(ctx context.Context, options *GraphSearchOptions, callback ...SearcherProgress) (*GraphSearchResult, error) // Pure graph/knowledge search

	// Collection Backup and Restore
	Backup(ctx context.Context, writer io.Writer, id string) error  // Backup a collection
	Restore(ctx context.Context, reader io.Reader, id string) error // Restore a collection
}

type GraphRelationship struct {
	ID         string                 `json:"id"`
	Type       string                 `json:"type"`
	StartNode  string                 `json:"start_node"`
	EndNode    string                 `json:"end_node"`
	Properties map[string]interface{} `json:"properties"`

	// Vector embedding support
	Embedding  []float64            `json:"embedding,omitempty"`  // Primary embedding vector
	Embeddings map[string][]float64 `json:"embeddings,omitempty"` // Multiple named embeddings

	// GraphRAG specific fields (simplified design)
	Description string  `json:"description,omitempty"` // Relationship description
	Confidence  float64 `json:"confidence,omitempty"`  // Confidence score
	Weight      float64 `json:"weight,omitempty"`      // Relationship weight

	// Metadata
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
	Version   int       `json:"version"`
}

type GraphRestoreOptions struct {
	GraphName   string                 `json:"graph_name"`
	Format      string                 `json:"format,omitempty"` // "json", "gexf", "graphml", "cypher", etc.
	Compress    bool                   `json:"compress"`         // whether to compress the backup file
	Force       bool                   `json:"force"`            // Whether to overwrite existing data
	CreateGraph bool                   `json:"create_graph"`     // Whether to create graph if it doesn't exist
	ExtraParams map[string]interface{} `json:"extra_params,omitempty"`
}

type GraphResult struct {
	Nodes         []Node         `json:"nodes,omitempty"`
	Relationships []Relationship `json:"relationships,omitempty"`
	Paths         []Path         `json:"paths,omitempty"`
	Records       []interface{}  `json:"records,omitempty"` // Raw query results
}

type GraphSchema struct {
	NodeLabels        []string            `json:"node_labels"`
	RelationshipTypes []string            `json:"relationship_types"`
	NodeProperties    map[string][]string `json:"node_properties"` // label -> property names
	RelProperties     map[string][]string `json:"rel_properties"`  // type -> property names
	Constraints       []SchemaConstraint  `json:"constraints"`
	Indexes           []SchemaIndex       `json:"indexes"`
}

type GraphSchemaConfig struct {
	Strict      bool                   `json:"strict"` // Whether to enforce strict schema
	NodeLabels  []string               `json:"node_labels,omitempty"`
	RelTypes    []string               `json:"rel_types,omitempty"`
	Constraints []SchemaConstraint     `json:"constraints,omitempty"`
	Defaults    map[string]interface{} `json:"defaults,omitempty"`
}

type GraphSchemaStats struct {
	TotalNodes         int64                  `json:"total_nodes"`
	TotalRelationships int64                  `json:"total_relationships"`
	NodeCounts         map[string]int64       `json:"node_counts"` // label -> count
	RelCounts          map[string]int64       `json:"rel_counts"`  // type -> count
	AvgDegree          float64                `json:"avg_degree"`
	MaxDegree          int                    `json:"max_degree"`
	Density            float64                `json:"density"`
	ExtraStats         map[string]interface{} `json:"extra_stats,omitempty"`
}

type GraphSearchOptions struct {
	CollectionID string `json:"collection_id"`         // Collection ID (required)
	DocumentID   string `json:"document_id,omitempty"` // Optional document ID filter

	// Query options - one of the following is required
	Query      string                 `json:"query,omitempty"`      // Natural language query (requires Extraction for entity extraction)
	Entities   []string               `json:"entities,omitempty"`   // Explicit entity names to search
	EntityIDs  []string               `json:"entity_ids,omitempty"` // Explicit entity IDs to search
	Cypher     string                 `json:"cypher,omitempty"`     // Custom Cypher query
	Parameters map[string]interface{} `json:"parameters,omitempty"` // Parameters for Cypher query

	// Traversal options
	MaxDepth      int      `json:"max_depth,omitempty"`      // Maximum traversal depth (default: 2)
	RelationTypes []string `json:"relation_types,omitempty"` // Filter by relationship types
	EntityTypes   []string `json:"entity_types,omitempty"`   // Filter by entity types
	Limit         int      `json:"limit,omitempty"`          // Maximum number of results

	// Entity extraction (required if Query is provided and Entities/EntityIDs are empty)
	Extraction         Extraction
	ExtractionProgress ExtractionProgress

	// Embedding for entity matching (optional, used when matching entities by semantic similarity)
	Embedding         Embedding
	EmbeddingProgress EmbeddingProgress
}

type GraphSearchResult struct {
	Nodes         []GraphNode         `json:"nodes"`         // Matched nodes/entities
	Relationships []GraphRelationship `json:"relationships"` // Related relationships
	Paths         []GraphPath         `json:"paths"`         // Matched paths (if path query)
	Segments      []Segment           `json:"segments"`      // Related segments (if segment IDs are found in nodes)
}

type GraphStats struct {
	TotalNodes         int64                  `json:"total_nodes"`
	TotalRelationships int64                  `json:"total_relationships"`
	NodeLabels         []string               `json:"node_labels"`
	RelationshipTypes  []string               `json:"relationship_types"`
	AvgDegree          float64                `json:"avg_degree"`
	MaxDegree          int                    `json:"max_degree"`
	Density            float64                `json:"density"`
	StorageSize        int64                  `json:"storage_size_bytes,omitempty"`
	MemoryUsage        int64                  `json:"memory_usage_bytes,omitempty"`
	IndexCount         int                    `json:"index_count,omitempty"`
	ExtraStats         map[string]interface{} `json:"extra_stats,omitempty"`
}

type GraphStore interface {
	// Connection Management
	Connect(ctx context.Context, config ...GraphStoreConfig) error
	Disconnect(ctx context.Context) error
	IsConnected() bool
	Close() error

	// Graph Management (similar to Collection Management in VectorStore)
	CreateGraph(ctx context.Context, graphName string) error
	DropGraph(ctx context.Context, graphName string) error
	GraphExists(ctx context.Context, graphName string) (bool, error)
	ListGraphs(ctx context.Context) ([]string, error)
	DescribeGraph(ctx context.Context, graphName string) (*GraphStats, error)

	// Node Operations (core functionality)
	AddNodes(ctx context.Context, opts *AddNodesOptions) ([]string, error) // Upsert option handles updates
	GetNodes(ctx context.Context, opts *GetNodesOptions) ([]*GraphNode, error)
	DeleteNodes(ctx context.Context, opts *DeleteNodesOptions) error

	// Relationship Operations
	AddRelationships(ctx context.Context, opts *AddRelationshipsOptions) ([]string, error) // Upsert option handles updates
	GetRelationships(ctx context.Context, opts *GetRelationshipsOptions) ([]*GraphRelationship, error)
	DeleteRelationships(ctx context.Context, opts *DeleteRelationshipsOptions) error

	// Save the extraction results and return the actual saved data
	SaveExtractionResults(ctx context.Context, graphName string, results []*ExtractionResult) (*SaveExtractionResultsResponse, error)

	// Query Operations (flexible query interface)
	Query(ctx context.Context, opts *GraphQueryOptions) (*GraphResult, error)               // General-purpose graph query with Cypher, traversal, etc.
	Communities(ctx context.Context, opts *CommunityDetectionOptions) ([]*Community, error) // Community detection and analysis

	// Schema Operations (optional - for databases that support schema)
	GetSchema(ctx context.Context, graphName string) (*DynamicGraphSchema, error)
	CreateIndex(ctx context.Context, opts *CreateIndexOptions) error
	DropIndex(ctx context.Context, opts *DropIndexOptions) error

	// Statistics and Maintenance
	GetStats(ctx context.Context, graphName string) (*GraphStats, error)
	Optimize(ctx context.Context, graphName string) error

	// Backup and Restore
	Backup(ctx context.Context, writer io.Writer, opts *GraphBackupOptions) error
	Restore(ctx context.Context, reader io.Reader, opts *GraphRestoreOptions) error
}

type GraphStoreConfig struct {
	// Basic Configuration
	StoreType   string `json:"store_type"`   // "neo4j", "kuzu", etc.
	DatabaseURL string `json:"database_url"` // Database connection URL

	// Performance Settings (common across all stores)
	BatchSize    int `json:"batch_size,omitempty"`    // Default batch size for operations
	QueryTimeout int `json:"query_timeout,omitempty"` // Query timeout in seconds

	// Business Logic Settings (common graph operations)
	DefaultGraphName string `json:"default_graph_name,omitempty"` // Default graph/namespace to use
	AutoCreateGraph  bool   `json:"auto_create_graph,omitempty"`  // Whether to auto-create graphs if they don't exist

	// Schema and Indexing (common across graph databases)
	AutoIndex      bool     `json:"auto_index,omitempty"`       // Whether to automatically create indexes
	IndexNodeProps []string `json:"index_node_props,omitempty"` // Node properties to auto-index (id, name, type, etc.)
	IndexRelProps  []string `json:"index_rel_props,omitempty"`  // Relationship properties to auto-index
	EnforceSchema  bool     `json:"enforce_schema,omitempty"`   // Whether to enforce strict schema validation

	// Transaction Settings (most graph DBs support transactions)
	AutoCommit      bool `json:"auto_commit,omitempty"`      // Whether to auto-commit single operations
	TransactionSize int  `json:"transaction_size,omitempty"` // Max operations per transaction (for batch)

	// Data Consistency (common business requirement)
	AllowDuplicates bool `json:"allow_duplicates,omitempty"`  // Whether to allow duplicate nodes/relationships
	MergeOnConflict bool `json:"merge_on_conflict,omitempty"` // Whether to merge when conflicts occur

	// Store-specific Configuration (delegated to individual drivers)
	DriverConfig map[string]interface{} `json:"driver_config,omitempty"` // Driver-specific configuration
}

type GraphTraversalOptions struct {
	MaxDepth    int                    `json:"max_depth,omitempty"`    // Maximum traversal depth
	MinDepth    int                    `json:"min_depth,omitempty"`    // Minimum traversal depth
	NodeFilter  map[string]interface{} `json:"node_filter,omitempty"`  // Node filtering criteria
	RelFilter   map[string]interface{} `json:"rel_filter,omitempty"`   // Relationship filtering criteria
	Direction   string                 `json:"direction,omitempty"`    // "INCOMING", "OUTGOING", "BOTH"
	ReturnPaths bool                   `json:"return_paths,omitempty"` // Whether to return full paths
	UniquePaths bool                   `json:"unique_paths,omitempty"` // Whether to ensure unique paths
	Limit       int                    `json:"limit,omitempty"`        // Maximum number of results
}

type HitRemoval struct {
	SegmentID string `json:"segment_id"` // Segment ID
	HitID     string `json:"hit_id"`     // Hit ID to remove
}

type HitScrollResult struct {
	Hits       []SegmentHit `json:"hits"`        // List of hits
	NextCursor string       `json:"next_cursor"` // Cursor for next page
	HasMore    bool         `json:"has_more"`    // Whether there are more hits
	Total      int          `json:"total"`       // Total count (if available)
}

type HybridSearchOptions struct {
	CollectionName string                 `json:"collection_name"`
	QueryVector    []float64              `json:"query_vector,omitempty"` // Dense vector query (optional if only using sparse vector search)
	QuerySparse    *SparseVector          `json:"query_sparse,omitempty"` // Sparse vector query (e.g., from BM25, TF-IDF)
	K              int                    `json:"k,omitempty"`            // Number of documents to return (ignored if using pagination)
	Filter         map[string]interface{} `json:"filter,omitempty"`       // Metadata filter

	// Pagination (optional - if not specified, returns top K results)
	Page     int    `json:"page,omitempty"`      // Page number (1-based), 0 means no pagination
	PageSize int    `json:"page_size,omitempty"` // Number of results per page (default: 10)
	Cursor   string `json:"cursor,omitempty"`    // Cursor for cursor-based pagination (alternative to page/pagesize)

	// Return control options
	IncludeVector   bool     `json:"include_vector"`   // Whether to include vector data in results
	IncludeMetadata bool     `json:"include_metadata"` // Whether to include document metadata
	IncludeContent  bool     `json:"include_content"`  // Whether to include document content
	Fields          []string `json:"fields,omitempty"` // Specific fields to retrieve
	IncludeTotal    bool     `json:"include_total"`    // Whether to calculate total count (expensive for pagination)

	// Hybrid search fusion configuration
	FusionType  FusionType `json:"fusion_type,omitempty"`  // Fusion algorithm: "rrf" (Reciprocal Rank Fusion) or "dbsf" (Distribution-Based Score Fusion)
	VectorUsing string     `json:"vector_using,omitempty"` // Named vector for dense vectors (e.g., "dense")
	SparseUsing string     `json:"sparse_using,omitempty"` // Named vector for sparse vectors (e.g., "sparse")

	// Legacy weight support (will be converted to appropriate fusion)
	VectorWeight  float64 `json:"vector_weight,omitempty"`  // Weight for vector similarity (0-1) - for backward compatibility
	KeywordWeight float64 `json:"keyword_weight,omitempty"` // Weight for keyword relevance (0-1) - for backward compatibility

	// Vector search parameters
	EfSearch    int  `json:"ef_search,omitempty"`   // Dynamic search parameter (HNSW)
	NumProbes   int  `json:"num_probes,omitempty"`  // Number of probes (IVF)
	Rescore     bool `json:"rescore,omitempty"`     // Whether to rescore results
	Approximate bool `json:"approximate,omitempty"` // Whether to use approximate search
	Timeout     int  `json:"timeout,omitempty"`     // Search timeout in milliseconds

	// Search engine specific options
	MinScore        float64  `json:"min_score,omitempty"`        // Minimum combined score
	MaxResults      int      `json:"max_results,omitempty"`      // Maximum total results to consider (default: 1000)
	SortBy          []string `json:"sort_by,omitempty"`          // Secondary sorting criteria
	FacetFields     []string `json:"facet_fields,omitempty"`     // Fields for faceted search
	HighlightFields []string `json:"highlight_fields,omitempty"` // Fields to highlight in results
}

type IndexType string

type LLMOptimizer struct {
	Connector string `json:"connector"` // Connector to use for extraction
}

type ListDocumentsOptions struct {
	CollectionName string                 `json:"collection_name"`
	Filter         map[string]interface{} `json:"filter,omitempty"`   // Metadata filter
	Limit          int                    `json:"limit,omitempty"`    // Number of documents per page (default: 100)
	Offset         int                    `json:"offset,omitempty"`   // Offset for pagination
	OrderBy        []string               `json:"order_by,omitempty"` // Fields to order by
	IncludeVector  bool                   `json:"include_vector"`     // Whether to include vector data
	IncludePayload bool                   `json:"include_payload"`    // Whether to include payload/metadata
	Fields         []string               `json:"fields,omitempty"`   // Specific fields to retrieve
}

type ListSegmentsOptions struct {
	Filter  map[string]interface{} `json:"filter,omitempty"`   // Metadata filter (vote, score, weight, etc.)
	Limit   int                    `json:"limit,omitempty"`    // Number of segments per page (default: 100)
	Offset  int                    `json:"offset,omitempty"`   // Offset for pagination
	OrderBy []string               `json:"order_by,omitempty"` // Fields to order by (score, weight, vote, created_at, etc.)
	Fields  []string               `json:"fields,omitempty"`   // Specific fields to retrieve

	// Include options
	IncludeNodes         bool `json:"include_nodes"`         // Whether to include graph nodes
	IncludeRelationships bool `json:"include_relationships"` // Whether to include graph relationships
	IncludeMetadata      bool `json:"include_metadata"`      // Whether to include segment metadata
}

type LoadState int

type Logger interface {
	Infof(format string, args ...interface{})
	Warnf(format string, args ...interface{})
	Errorf(format string, args ...interface{})
	Debugf(format string, args ...interface{})
}

type MMRSearchOptions struct {
	CollectionName string                 `json:"collection_name"`
	QueryVector    []float64              `json:"query_vector"`          // Query vector for similarity search
	K              int                    `json:"k,omitempty"`           // Number of documents to return (ignored if using pagination)
	FetchK         int                    `json:"fetch_k,omitempty"`     // Number of documents to fetch for MMR algorithm
	LambdaMult     float64                `json:"lambda_mult,omitempty"` // Diversity parameter (0-1, 0=max diversity, 1=max similarity)
	Filter         map[string]interface{} `json:"filter,omitempty"`      // Metadata filter

	// Pagination (optional - if not specified, returns top K results)
	Page     int    `json:"page,omitempty"`      // Page number (1-based), 0 means no pagination
	PageSize int    `json:"page_size,omitempty"` // Number of results per page (default: 10)
	Cursor   string `json:"cursor,omitempty"`    // Cursor for cursor-based pagination (alternative to page/pagesize)

	// Return control options
	IncludeVector   bool     `json:"include_vector"`   // Whether to include vector data in results
	IncludeMetadata bool     `json:"include_metadata"` // Whether to include document metadata
	IncludeContent  bool     `json:"include_content"`  // Whether to include document content
	Fields          []string `json:"fields,omitempty"` // Specific fields to retrieve
	IncludeTotal    bool     `json:"include_total"`    // Whether to calculate total count (expensive for pagination)

	// Search parameters
	EfSearch    int  `json:"ef_search,omitempty"`   // Dynamic search parameter
	NumProbes   int  `json:"num_probes,omitempty"`  // Number of probes
	Approximate bool `json:"approximate,omitempty"` // Whether to use approximate search
	Timeout     int  `json:"timeout,omitempty"`     // Search timeout in milliseconds

	// Search engine specific options
	MinScore    float64  `json:"min_score,omitempty"`    // Minimum similarity score to include
	MaxResults  int      `json:"max_results,omitempty"`  // Maximum total results to consider
	FacetFields []string `json:"facet_fields,omitempty"` // Fields for faceted search

	// Named vector support (for collections with multiple vectors)
	VectorUsing string `json:"vector_using,omitempty"` // Named vector to use for search (e.g., "dense", "sparse")
}

type MediaPosition struct {
	StartTime int `json:"start_time"` // Start time in seconds (for video/audio)
	EndTime   int `json:"end_time"`   // End time in seconds (for video/audio)
	Page      int `json:"page"`       // Page number (for PDF, Word, etc.)
}

type Node struct {
	ID         string                 `json:"id"`
	Name       string                 `json:"name"`                 // Entity name/title
	Type       string                 `json:"type"`                 // Entity type (Person, Organization, Location, etc.)
	Labels     []string               `json:"labels,omitempty"`     // Additional labels/categories
	Properties map[string]interface{} `json:"properties,omitempty"` // Entity properties

	// GraphRAG specific fields
	Description     string    `json:"description,omitempty"`      // Entity description/summary
	Confidence      float64   `json:"confidence,omitempty"`       // Extraction confidence score (0-1)
	EmbeddingVector []float64 `json:"embedding_vector,omitempty"` // Entity embedding for semantic search

	// Source tracking
	SourceDocuments  []string         `json:"source_documents,omitempty"`  // Document IDs where entity was found
	SourceChunks     []string         `json:"source_chunks,omitempty"`     // Chunk IDs where entity was extracted
	ExtractionMethod ExtractionMethod `json:"extraction_method,omitempty"` // Extraction method used

	// Neo4j internal fields (populated when reading from database)
	InternalID int64  `json:"internal_id,omitempty"` // Neo4j internal node ID
	ElementID  string `json:"element_id,omitempty"`  // Neo4j element ID (Neo4j 5.0+)

	// Timestamps
	CreatedAt int64 `json:"created_at,omitempty"` // Unix timestamp when entity was created
	UpdatedAt int64 `json:"updated_at,omitempty"` // Unix timestamp when entity was last updated

	// Version control
	Version int          `json:"version,omitempty"` // Node version number
	Status  EntityStatus `json:"status,omitempty"`  // Node lifecycle status
}

type NodeMetrics struct {
	NodeID                string  `json:"node_id"`
	PageRank              float64 `json:"pagerank,omitempty"`
	BetweennessCentrality float64 `json:"betweenness_centrality,omitempty"`
	ClosenessCentrality   float64 `json:"closeness_centrality,omitempty"`
	DegreeCentrality      float64 `json:"degree_centrality,omitempty"`
	ClusteringCoefficient float64 `json:"clustering_coefficient,omitempty"`
}

type Options struct {
	// VectorStore is the vector store to use for storing and searching documents
	VectorStore VectorStore

	// GraphStore is the graph store to use for storing and searching relationships (Optional)
	GraphStore GraphStore
}

type PaginatedDocumentsResult struct {
	Documents  []*Document `json:"documents"`
	Total      int64       `json:"total"`       // Total number of matching documents (if supported)
	HasMore    bool        `json:"has_more"`    // Whether there are more pages
	NextOffset int         `json:"next_offset"` // Offset for next page
}

type PaginatedSegmentsResult struct {
	Segments   []Segment `json:"segments"`
	Total      int64     `json:"total"`       // Total number of matching segments (if supported)
	HasMore    bool      `json:"has_more"`    // Whether there are more pages
	NextOffset int       `json:"next_offset"` // Offset for next page
}

type Pagination struct {
	// Offset-based pagination (traditional page/pagesize)
	Page     int `json:"page,omitempty"`      // Page number (1-based), 0 means no pagination
	PageSize int `json:"page_size,omitempty"` // Number of results per page (default: 10)

	// Cursor-based pagination (for better performance with large datasets)
	Cursor string `json:"cursor,omitempty"` // Cursor token for cursor-based pagination

	// Control options
	IncludeTotal bool `json:"include_total,omitempty"` // Whether to calculate total count (expensive for large datasets)
}

type PaginationResult struct {
	// Offset-based pagination info
	Page         int   `json:"page,omitempty"`          // Current page number (1-based)
	PageSize     int   `json:"page_size,omitempty"`     // Number of results per page
	Total        int64 `json:"total,omitempty"`         // Total number of matching documents (if IncludeTotal=true)
	TotalPages   int   `json:"total_pages,omitempty"`   // Total number of pages (if IncludeTotal=true)
	HasNext      bool  `json:"has_next,omitempty"`      // Whether there are more pages
	HasPrevious  bool  `json:"has_previous,omitempty"`  // Whether there are previous pages
	NextPage     int   `json:"next_page,omitempty"`     // Next page number (if HasNext=true)
	PreviousPage int   `json:"previous_page,omitempty"` // Previous page number (if HasPrevious=true)

	// Cursor-based pagination info
	Cursor     string `json:"cursor,omitempty"`      // Current cursor position
	NextCursor string `json:"next_cursor,omitempty"` // Cursor for next page (if HasNext=true)
	PrevCursor string `json:"prev_cursor,omitempty"` // Cursor for previous page (if HasPrevious=true)
}

type PaginationStrategy string

type Path struct {
	Nodes         []Node         `json:"nodes"`
	Relationships []Relationship `json:"relationships"`
	Length        int            `json:"length"`
}

type Position struct {
	StartPos int `json:"s"`
	EndPos   int `json:"e"`
}

type PropertyInfo struct {
	Name         string        `json:"name"`
	Type         string        `json:"type"` // "string", "int", "float", "bool", "array", "object"
	Nullable     bool          `json:"nullable"`
	SampleValues []interface{} `json:"sample_values,omitempty"`
	Count        int64         `json:"count,omitempty"`      // Number of entities with this property
	Uniqueness   float64       `json:"uniqueness,omitempty"` // Uniqueness ratio (0-1)
}

type QueryOptions struct {
	CollectionID string `json:"collection_id"`
	DocumentID   string `json:"document_id"`

	// Query is the query to use for searching documents
	Query string `json:"query"` // Query or History at least one of them is required

	// History is the history of messages to use for searching documents
	History []ChatMessage `json:"history"` // History or Query at least one of them is required

	// Filter is the filter to use for searching documents (Optional)
	Filter map[string]interface{} `json:"filter,omitempty"`

	// Embedding is the embedding model to use for embedding documents
	Embedding         Embedding
	EmbeddingProgress EmbeddingProgress // Embedding progress callback (Optional)

	// Extraction is the extraction model to use for extracting documents (Optional)
	Extraction         Extraction
	ExtractionProgress ExtractionProgress // Extraction progress callback (Optional)

	// ExtractionEmbedding is the embedding model to use for embedding extracted documents (Optional, default is the same as Embedding)
	ExtractionEmbedding         Embedding
	ExtractionEmbeddingProgress EmbeddingProgress // Extraction embedding progress callback (Optional)

	// Fetcher is the fetcher to use for fetching documents from URLs (Optional)
	Fetcher Fetcher

	// Converter is the converter to use for converting documents to text (Optional)
	Converter Converter

	// Reranker is the reranker to use for reranking documents (Optional)
	Reranker Reranker

	// Searcher is the searcher to use for searching documents (Optional)
	Searcher Searcher
}

type Relationship struct {
	ID         string                 `json:"id,omitempty"`
	Type       string                 `json:"type"`
	StartNode  string                 `json:"start_node"`           // Start node ID
	EndNode    string                 `json:"end_node"`             // End node ID
	Properties map[string]interface{} `json:"properties,omitempty"` // Relationship properties

	// GraphRAG specific fields
	Description     string    `json:"description,omitempty"`      // Relationship description
	Confidence      float64   `json:"confidence,omitempty"`       // Extraction confidence score (0-1)
	Weight          float64   `json:"weight,omitempty"`           // Relationship strength/weight
	EmbeddingVector []float64 `json:"embedding_vector,omitempty"` // Relationship embedding

	// Source tracking
	SourceDocuments  []string         `json:"source_documents,omitempty"`  // Document IDs where relationship was found
	SourceChunks     []string         `json:"source_chunks,omitempty"`     // Chunk IDs where relationship was extracted
	ExtractionMethod ExtractionMethod `json:"extraction_method,omitempty"` // Extraction method used

	// Neo4j internal fields (populated when reading from database)
	InternalID  int64  `json:"internal_id,omitempty"`   // Neo4j internal relationship ID
	ElementID   string `json:"element_id,omitempty"`    // Neo4j element ID (Neo4j 5.0+)
	StartNodeID int64  `json:"start_node_id,omitempty"` // Neo4j internal start node ID
	EndNodeID   int64  `json:"end_node_id,omitempty"`   // Neo4j internal end node ID

	// Timestamps
	CreatedAt int64 `json:"created_at,omitempty"` // Unix timestamp when relationship was created
	UpdatedAt int64 `json:"updated_at,omitempty"` // Unix timestamp when relationship was last updated

	// Version control
	Version int          `json:"version,omitempty"` // Relationship version number
	Status  EntityStatus `json:"status,omitempty"`  // Relationship lifecycle status
}

type RelationshipDeduplicationResult struct {
	NormalizedID string   `json:"normalized_id"`
	DocIDs       []string `json:"doc_ids"`
	IsUpdate     bool     `json:"is_update"`
}

type Reranker interface {
	Rerank(ctx context.Context, segments []Segment, callback ...RerankerProgress) ([]Segment, error)
	Name() string
}

type RerankerPayload struct {
	Status   RerankerStatus `json:"status"`
	Message  string         `json:"message"`
	Progress float64        `json:"progress"`
}

type RerankerProgress func(status RerankerStatus, payload RerankerPayload)

type RerankerStatus string

type RestoreOptions struct {
	CollectionName string                 `json:"collection_name,omitempty"` // For VectorStore (deprecated, use Name)
	GraphName      string                 `json:"graph_name,omitempty"`      // For GraphStore (deprecated, use Name)
	Name           string                 `json:"name"`                      // Unified name field for collection/graph
	Force          bool                   `json:"force"`
	ExtraParams    map[string]interface{} `json:"extra_params,omitempty"`
}

type RetrieverOptions struct {
	SearchType   string                 `json:"search_type,omitempty"`   // "similarity", "mmr", or "similarity_score_threshold"
	SearchKwargs map[string]interface{} `json:"search_kwargs,omitempty"` // Search-specific parameters
}

type SaveExtractionResultsResponse struct {
	SavedEntities      []GraphNode         `json:"saved_entities"`      // Actual entities saved (after deduplication)
	SavedRelationships []GraphRelationship `json:"saved_relationships"` // Actual relationships saved (with updated node IDs)
	EntitiesCount      int                 `json:"entities_count"`      // Number of entities saved
	RelationshipsCount int                 `json:"relationships_count"` // Number of relationships saved
	ProcessedCount     int                 `json:"processed_count"`     // Number of extraction results processed
}

type SchemaConstraint struct {
	Type       string   `json:"type"`       // "UNIQUE", "NOT_NULL", etc.
	Label      string   `json:"label"`      // Node label or relationship type
	Properties []string `json:"properties"` // Property names
}

type SchemaIndex struct {
	Type       string   `json:"type"`       // "BTREE", "FULLTEXT", "VECTOR", etc.
	Label      string   `json:"label"`      // Node label or relationship type
	Properties []string `json:"properties"` // Property names
}

type ScoreCompute interface {
	Compute(ctx context.Context, docID string, segmentID string, progress ...ScoreProgress) (float64, map[string]float64, error)
	Name() string
}

type ScorePayload struct {
	Status   ScoreStatus `json:"status"`
	Message  string      `json:"message"`
	Progress float64     `json:"progress"`
}

type ScoreProgress func(status ScoreStatus, payload ScorePayload)

type ScoreStatus string

type ScoreThresholdOptions struct {
	CollectionName string                 `json:"collection_name"`
	QueryVector    []float64              `json:"query_vector"`     // Query vector for similarity search
	ScoreThreshold float64                `json:"score_threshold"`  // Minimum relevance score threshold
	K              int                    `json:"k,omitempty"`      // Number of documents to return (ignored if using pagination)
	Filter         map[string]interface{} `json:"filter,omitempty"` // Metadata filter

	// Pagination (optional - if not specified, returns top K results)
	Page     int    `json:"page,omitempty"`      // Page number (1-based), 0 means no pagination
	PageSize int    `json:"page_size,omitempty"` // Number of results per page (default: 10)
	Cursor   string `json:"cursor,omitempty"`    // Cursor for cursor-based pagination (alternative to page/pagesize)

	// Return control options
	IncludeVector   bool     `json:"include_vector"`   // Whether to include vector data in results
	IncludeMetadata bool     `json:"include_metadata"` // Whether to include document metadata
	IncludeContent  bool     `json:"include_content"`  // Whether to include document content
	Fields          []string `json:"fields,omitempty"` // Specific fields to retrieve
	IncludeTotal    bool     `json:"include_total"`    // Whether to calculate total count (expensive for pagination)

	// Search parameters
	EfSearch    int  `json:"ef_search,omitempty"`   // Dynamic search parameter
	NumProbes   int  `json:"num_probes,omitempty"`  // Number of probes
	Approximate bool `json:"approximate,omitempty"` // Whether to use approximate search
	Timeout     int  `json:"timeout,omitempty"`     // Search timeout in milliseconds

	// Search engine specific options
	MaxResults      int      `json:"max_results,omitempty"`      // Maximum total results to consider
	SortBy          []string `json:"sort_by,omitempty"`          // Secondary sorting criteria
	FacetFields     []string `json:"facet_fields,omitempty"`     // Fields for faceted search
	HighlightFields []string `json:"highlight_fields,omitempty"` // Fields to highlight in results

	// Named vector support (for collections with multiple vectors)
	VectorUsing string `json:"vector_using,omitempty"` // Named vector to use for search (e.g., "dense", "sparse")
}

type ScrollHitsOptions struct {
	SegmentID string `json:"segment_id,omitempty"` // Filter by segment ID
	Source    string `json:"source,omitempty"`     // Filter by reaction source
	Scenario  string `json:"scenario,omitempty"`   // Filter by reaction scenario
	Limit     int    `json:"limit,omitempty"`      // Number of hits per page (default 20, max 100)
	Cursor    string `json:"cursor,omitempty"`     // Cursor for pagination
}

type ScrollOptions struct {
	CollectionName string                 `json:"collection_name"`
	Filter         map[string]interface{} `json:"filter,omitempty"`    // Metadata filter
	Limit          int                    `json:"limit,omitempty"`     // Number of documents per batch (default: 100)
	ScrollID       string                 `json:"scroll_id,omitempty"` // Scroll ID for continuing pagination
	OrderBy        []string               `json:"order_by,omitempty"`  // Fields to order by
	IncludeVector  bool                   `json:"include_vector"`      // Whether to include vector data
	IncludePayload bool                   `json:"include_payload"`     // Whether to include payload/metadata
	Fields         []string               `json:"fields,omitempty"`    // Specific fields to retrieve
}

type ScrollResult struct {
	Documents []*Document `json:"documents"`
	ScrollID  string      `json:"scroll_id,omitempty"` // ID for next scroll request
	HasMore   bool        `json:"has_more"`            // Whether there are more results
}

type ScrollSegmentsOptions struct {
	Filter   map[string]interface{} `json:"filter,omitempty"`    // Metadata filter (vote, score, weight, etc.)
	Limit    int                    `json:"limit,omitempty"`     // Number of segments per batch (default: 100)
	ScrollID string                 `json:"scroll_id,omitempty"` // Scroll ID for continuing pagination
	OrderBy  []string               `json:"order_by,omitempty"`  // Fields to order by (score, weight, vote, created_at, etc.)
	Fields   []string               `json:"fields,omitempty"`    // Specific fields to retrieve

	// Include options
	IncludeNodes         bool `json:"include_nodes"`         // Whether to include graph nodes
	IncludeRelationships bool `json:"include_relationships"` // Whether to include graph relationships
	IncludeMetadata      bool `json:"include_metadata"`      // Whether to include segment metadata
}

type ScrollVotesOptions struct {
	SegmentID string   `json:"segment_id,omitempty"` // Filter by segment ID
	VoteType  VoteType `json:"vote_type,omitempty"`  // Filter by vote type
	Source    string   `json:"source,omitempty"`     // Filter by reaction source
	Scenario  string   `json:"scenario,omitempty"`   // Filter by reaction scenario
	Limit     int      `json:"limit,omitempty"`      // Number of votes per page (default 20, max 100)
	Cursor    string   `json:"cursor,omitempty"`     // Cursor for pagination
}

type SearchEngineStats struct {
	TotalQueries     int64    `json:"total_queries"`     // Total number of queries processed
	AverageQueryTime float64  `json:"avg_query_time_ms"` // Average query time in milliseconds
	CacheHitRate     float64  `json:"cache_hit_rate"`    // Cache hit rate (0-1)
	PopularQueries   []string `json:"popular_queries"`   // Most popular queries
	SlowQueries      []string `json:"slow_queries"`      // Slowest queries
	ErrorRate        float64  `json:"error_rate"`        // Error rate (0-1)
	IndexSize        int64    `json:"index_size_bytes"`  // Total index size in bytes
	DocumentCount    int64    `json:"document_count"`    // Total number of documents
}

type SearchFacet struct {
	Field  string           `json:"field"`  // Metadata field name
	Values map[string]int64 `json:"values"` // Value -> count mapping
}

type SearchOptions struct {
	CollectionName string                 `json:"collection_name"`
	QueryVector    []float64              `json:"query_vector"`     // Query vector for similarity search
	K              int                    `json:"k,omitempty"`      // Number of documents to return (ignored if using pagination)
	Filter         map[string]interface{} `json:"filter,omitempty"` // Metadata filter

	// Pagination (optional - if not specified, returns top K results)
	Page     int    `json:"page,omitempty"`      // Page number (1-based), 0 means no pagination
	PageSize int    `json:"page_size,omitempty"` // Number of results per page (default: 10)
	Cursor   string `json:"cursor,omitempty"`    // Cursor for cursor-based pagination (alternative to page/pagesize)

	// Return control options
	IncludeVector   bool     `json:"include_vector"`   // Whether to include vector data in results
	IncludeMetadata bool     `json:"include_metadata"` // Whether to include document metadata
	IncludeContent  bool     `json:"include_content"`  // Whether to include document content
	Fields          []string `json:"fields,omitempty"` // Specific fields to retrieve
	IncludeTotal    bool     `json:"include_total"`    // Whether to calculate total count (expensive for pagination)

	// Search-specific parameters
	EfSearch    int  `json:"ef_search,omitempty"`   // Dynamic search parameter (HNSW)
	NumProbes   int  `json:"num_probes,omitempty"`  // Number of probes (IVF)
	Rescore     bool `json:"rescore,omitempty"`     // Whether to rescore results
	Approximate bool `json:"approximate,omitempty"` // Whether to use approximate search
	Timeout     int  `json:"timeout,omitempty"`     // Search timeout in milliseconds

	// Search engine specific options
	MinScore        float64  `json:"min_score,omitempty"`        // Minimum similarity score to include
	MaxResults      int      `json:"max_results,omitempty"`      // Maximum total results to consider (default: 1000)
	SortBy          []string `json:"sort_by,omitempty"`          // Secondary sorting criteria
	FacetFields     []string `json:"facet_fields,omitempty"`     // Fields for faceted search
	HighlightFields []string `json:"highlight_fields,omitempty"` // Fields to highlight in results

	// Named vector support (for collections with multiple vectors)
	VectorUsing string `json:"vector_using,omitempty"` // Named vector to use for search (e.g., "dense", "sparse")
}

type SearchOptionsInterface interface {
	GetType() SearchType
}

type SearchResult struct {
	// Results
	Documents []*SearchResultItem `json:"documents"` // Search results

	// Pagination metadata (embedded for backward compatibility)
	PaginationResult `json:",inline"`

	// Search engine features
	QueryTime   int64                   `json:"query_time_ms"`         // Query execution time in milliseconds
	Facets      map[string]*SearchFacet `json:"facets,omitempty"`      // Faceted search results
	Suggestions []string                `json:"suggestions,omitempty"` // Query suggestions for typos/alternatives
	MaxScore    float64                 `json:"max_score,omitempty"`   // Highest score in results
	MinScore    float64                 `json:"min_score,omitempty"`   // Lowest score in results
}

type SearchResultItem struct {
	Document Document `json:"document"`
	Score    float64  `json:"score"`
}

type SearchType string

type Searcher interface {
	Search(ctx context.Context, options *QueryOptions, callback ...SearcherProgress) ([]Segment, error) // Search for segments
	Type() SearcherType                                                                                 // Vector, Graph, Hybrid
	Name() string                                                                                       // Name of the searcher
}

type SearcherPayload struct {
	Status   SearcherStatus `json:"status"`
	Message  string         `json:"message"`
	Progress float64        `json:"progress"`
}

type SearcherProgress func(status SearcherStatus, payload SearcherPayload)

type SearcherStatus string

type SearcherType string

type Segment struct {
	CollectionID    string                 `json:"collection_id"`
	DocumentID      string                 `json:"document_id"`
	ID              string                 `json:"id"`
	Text            string                 `json:"text"`
	Nodes           []GraphNode            `json:"nodes"`
	Relationships   []GraphRelationship    `json:"relationships"`
	Parents         []string               `json:"parents"`
	Children        []string               `json:"children"`
	Metadata        map[string]interface{} `json:"metadata"`
	CreatedAt       time.Time              `json:"created_at"`
	UpdatedAt       time.Time              `json:"updated_at"`
	Version         int                    `json:"version"`
	Weight          float64                `json:"weight"`
	Score           float64                `json:"score"`
	ScoreDimensions map[string]float64     `json:"score_dimensions,omitempty"`
	Positive        int                    `json:"positive"` // Positive vote count
	Negative        int                    `json:"negative"` // Negative vote count
	Hit             int                    `json:"hit"`      // Hit count for the segment
}

type SegmentExtractionResult struct {
	DocID              string `json:"doc_id"`              // Document ID
	SegmentID          string `json:"segment_id"`          // Segment ID
	ExtractionModel    string `json:"extraction_model"`    // Model used for extraction
	EntitiesCount      int    `json:"entities_count"`      // Number of entities extracted
	RelationshipsCount int    `json:"relationships_count"` // Number of relationships extracted

}

type SegmentGraph struct {
	DocID         string              `json:"doc_id"`
	SegmentID     string              `json:"segment_id"`
	Entities      []GraphNode         `json:"entities"`
	Relationships []GraphRelationship `json:"relationships"`
}

type SegmentHit struct {
	ID    string `json:"id"`     // Segment ID
	HitID string `json:"hit_id"` // Unique hit ID
	*SegmentReaction
}

type SegmentReaction struct {
	Source    string                 `json:"source,omitempty"`    // Source of the reaction, e.g. "chat", "api", "bot", etc.
	Scenario  string                 `json:"scenario,omitempty"`  // Scenario of the reaction, e.g. "question", "search", "response", etc.
	Query     string                 `json:"query,omitempty"`     // Query of the reaction, e.g. "What is the capital of France?", etc.
	Candidate string                 `json:"candidate,omitempty"` // Candidate of the reaction, e.g. "Paris", etc.
	Context   map[string]interface{} `json:"context,omitempty"`   // Context of the reaction, e.g. {"user_id": "123", "session_id": "456", "rank": 1, "score": 0.95}
}

type SegmentScore struct {
	ID         string             `json:"id"`
	Score      float64            `json:"score,omitempty"`
	Dimensions map[string]float64 `json:"dimensions,omitempty"`
}

type SegmentScrollResult struct {
	Segments []Segment `json:"segments"`
	ScrollID string    `json:"scroll_id,omitempty"` // ID for next scroll request
	HasMore  bool      `json:"has_more"`            // Whether there are more results
}

type SegmentText struct {
	ID       string                 `json:"id,omitempty"`
	Text     string                 `json:"text"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type SegmentTree struct {
	Segment *Segment     `json:"segment"`          // The segment node
	Parent  *SegmentTree `json:"parent,omitempty"` // Parent node (only one in document hierarchy)
	Depth   int          `json:"depth"`            // Depth in the original document hierarchy (extracted from metadata)
}

type SegmentVote struct {
	ID     string   `json:"id"`               // Segment ID
	VoteID string   `json:"vote_id"`          // Unique vote ID
	Vote   VoteType `json:"vote"`             // Vote type, e.g. "positive", "negative"
	HitID  string   `json:"hit_id,omitempty"` // Optional: Hit ID to associate the vote with a specific hit
	*SegmentReaction
}

type SegmentWeight struct {
	ID     string  `json:"id"`
	Weight float64 `json:"weight,omitempty"`
}

type SemanticOptions struct {
	Connector     string `json:"connector"`      // For Semantic recognition, etc.
	ContextSize   int    `json:"context_size"`   // Context size for Semantic recognition. Default L1 Size (ChunkSize * 6)
	Options       string `json:"options"`        // Model options, for example, temperature, top_p, etc.
	Prompt        string `json:"prompt"`         // System prompt for Semantic recognition.
	Toolcall      bool   `json:"toolcall"`       // Whether to use toolcall for Semantic recognition.
	MaxRetry      int    `json:"max_retry"`      // Max retry times for Semantic recognition.
	MaxConcurrent int    `json:"max_concurrent"` // Max concurrent requests for Semantic recognition.
}

type SparseEmbedding struct {
	Indices []uint32  `json:"indices"` // Non-zero indices
	Values  []float32 `json:"values"`  // Non-zero values
}

type SparseVector struct {
	Indices []uint32  `json:"indices"` // Non-zero indices
	Values  []float32 `json:"values"`  // Non-zero values
}

type TextPosition struct {
	StartIndex int `json:"start_index"` // Character offset from beginning of text
	EndIndex   int `json:"end_index"`   // Character offset end position
	StartLine  int `json:"start_line"`  // Line number where chunk starts
	EndLine    int `json:"end_line"`    // Line number where chunk ends
}

type UpdateHitOptions struct {
	Reaction *SegmentReaction
}

type UpdateScoreOptions struct {
	Compute  ScoreCompute
	Progress ScoreProgress
}

type UpdateVoteOptions struct {
	Compute  VoteCompute
	Progress VoteProgress
	Reaction *SegmentReaction
}

type UpdateWeightOptions struct {
	Compute  WeightCompute
	Progress WeightProgress
}

type UpsertCallback struct {
	Converter  ConverterProgress
	Chunking   ChunkingProgress
	Embedding  EmbeddingProgress
	Extraction ExtractionProgress
	Fetcher    FetcherProgress
}

type UpsertOptions struct {
	// Chunking is the chunking model to use for chunking documents
	Chunking        Chunking
	ChunkingOptions *ChunkingOptions // Chunking options (Optional)

	// Embedding is the embedding model to use for embedding documents
	Embedding Embedding

	// Extraction is the extraction model to use for extracting documents (Optional)
	Extraction Extraction

	// Progress is the progress callback for the upsert
	Progress UpsertProgress

	// Fetcher is the fetcher to use for fetching documents from URLs (Optional)
	Fetcher Fetcher

	// Converter is the converter to use for converting documents to text (Optional)
	Converter Converter

	// CollectionID is the collection ID to use for storing the document (Optional)
	CollectionID string `json:"collection_id,omitempty"`

	// DocID is the document ID to use for tracking, if not provided, will auto-generate (Optional)
	DocID string `json:"doc_id,omitempty"`

	// Metadata is the metadata to use for the document (Optional)
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type UpsertProgress func(id string, status UpsertProgressType, payload UpsertProgressPayload)

type UpsertProgressPayload struct {
	ID       string                 `json:"id"`       // ID of the request
	Progress float64                `json:"progress"` // 0 - 100
	Type     UpsertProgressType     `json:"type"`     // "converter", "chunking", "embedding", "extraction", "fetcher"
	Data     map[string]interface{} `json:"data"`     // Data to display
}

type UpsertProgressType string

type VectorMode string

type VectorSearchOptions struct {
	CollectionID string    `json:"collection_id"`         // Collection ID (required)
	DocumentID   string    `json:"document_id,omitempty"` // Optional document ID filter
	Query        string    `json:"query"`                 // Query text (required if QueryVector is empty)
	QueryVector  []float64 // Pre-computed query vector (optional, if provided, Query is ignored)

	// Search parameters
	K        int                    `json:"k,omitempty"`         // Number of results to return (default: 10)
	Filter   map[string]interface{} `json:"filter,omitempty"`    // Metadata filter
	MinScore float64                `json:"min_score,omitempty"` // Minimum similarity score

	// Embedding (required if QueryVector is not provided)
	Embedding         Embedding
	EmbeddingProgress EmbeddingProgress

	// Optional reranking
	Reranker Reranker
}

type VectorSearchResult struct {
	Segments []Segment `json:"segments"` // Matched segments
	Total    int       `json:"total"`    // Total number of matches (if available)
}

type VectorStore interface {
	// Collection Management
	CreateCollection(ctx context.Context, opts *CreateCollectionOptions) error
	ListCollections(ctx context.Context) ([]string, error)
	DropCollection(ctx context.Context, collectionName string) error
	CollectionExists(ctx context.Context, collectionName string) (bool, error)
	DescribeCollection(ctx context.Context, collectionName string) (*VectorStoreStats, error)

	// Collection State Management (for databases like Milvus that support load/release)
	LoadCollection(ctx context.Context, collectionName string) error
	ReleaseCollection(ctx context.Context, collectionName string) error
	GetLoadState(ctx context.Context, collectionName string) (LoadState, error)

	// Document Operations (vector-focused)
	AddDocuments(ctx context.Context, opts *AddDocumentOptions) ([]string, error)
	GetDocuments(ctx context.Context, ids []string, opts *GetDocumentOptions) ([]*Document, error)
	DeleteDocuments(ctx context.Context, opts *DeleteDocumentOptions) error
	UpdateMetadata(ctx context.Context, collectionName string, updates []DocumentMetadataUpdate, defaultMetadata map[string]interface{}) error
	GetMetadata(ctx context.Context, collectionName string, documentID string) (map[string]interface{}, error)

	// Document Listing and Pagination
	ListDocuments(ctx context.Context, opts *ListDocumentsOptions) (*PaginatedDocumentsResult, error) // deprecated
	ScrollDocuments(ctx context.Context, opts *ScrollOptions) (*ScrollResult, error)
	Count(ctx context.Context, collectionName string, filter map[string]interface{}) (int64, error) // Count documents with filter

	// Vector Search Operations (core functionality)
	SearchSimilar(ctx context.Context, opts *SearchOptions) (*SearchResult, error)
	SearchMMR(ctx context.Context, opts *MMRSearchOptions) (*SearchResult, error)
	SearchWithScoreThreshold(ctx context.Context, opts *ScoreThresholdOptions) (*SearchResult, error)
	SearchHybrid(ctx context.Context, opts *HybridSearchOptions) (*SearchResult, error)
	SearchBatch(ctx context.Context, opts []SearchOptionsInterface) ([]*SearchResult, error)

	// Maintenance and Stats
	GetStats(ctx context.Context, collectionName string) (*VectorStoreStats, error)
	GetSearchEngineStats(ctx context.Context, collectionName string) (*SearchEngineStats, error)
	Optimize(ctx context.Context, collectionName string) error

	// Backup and Restore
	Backup(ctx context.Context, writer io.Writer, opts *BackupOptions) error
	Restore(ctx context.Context, reader io.Reader, opts *RestoreOptions) error

	// Connection Management
	Connect(ctx context.Context, config ...VectorStoreConfig) error
	Disconnect(ctx context.Context) error
	IsConnected() bool
	Close() error
}

type VectorStoreConfig struct {
	// Database Connection Configuration
	DatabaseURL    string                 `json:"database_url,omitempty"`    // Database connection URL
	ConnectionPool int                    `json:"connection_pool,omitempty"` // Connection pool size
	Timeout        int                    `json:"timeout,omitempty"`         // Operation timeout in seconds
	ExtraParams    map[string]interface{} `json:"extra_params,omitempty"`    // Database-specific parameters (host, port, api_key, etc.)
}

type VectorStoreStats struct {
	TotalVectors   int64                  `json:"total_vectors"`
	Dimension      int                    `json:"dimension"`
	IndexType      IndexType              `json:"index_type"`
	DistanceMetric DistanceMetric         `json:"distance_metric"`
	IndexSize      int64                  `json:"index_size_bytes,omitempty"`
	MemoryUsage    int64                  `json:"memory_usage_bytes,omitempty"`
	ExtraStats     map[string]interface{} `json:"extra_stats,omitempty"`
}

type VoteCompute interface {
	Compute(ctx context.Context, docID string, segmentIDs []string, context map[string]interface{}, progress ...VoteProgress) ([]VoteType, error)
	Name() string
}

type VoteOption struct {
	Model  string
	Reason string
	Vote   string
}

type VotePayload struct {
	Status   VoteStatus `json:"status"`
	Message  string     `json:"message"`
	Progress float64    `json:"progress"`
}

type VoteProgress func(status VoteStatus, payload VotePayload)

type VoteRemoval struct {
	SegmentID string `json:"segment_id"` // Segment ID
	VoteID    string `json:"vote_id"`    // Vote ID to remove
}

type VoteScrollResult struct {
	Votes      []SegmentVote `json:"votes"`       // List of votes
	NextCursor string        `json:"next_cursor"` // Cursor for next page
	HasMore    bool          `json:"has_more"`    // Whether there are more votes
	Total      int           `json:"total"`       // Total count (if available)
}

type VoteStatus string

type VoteType string

type WeightCompute interface {
	Compute(ctx context.Context, docID string, segmentID string, progress ...WeightProgress) (float64, error)
	Name() string
}

type WeightPayload struct {
	Status   WeightStatus `json:"status"`
	Message  string       `json:"message"`
	Progress float64      `json:"progress"`
}

type WeightProgress func(status WeightStatus, payload WeightPayload)

type WeightStatus string