vectorless 0.1.29

// Copyright (c) 2026 vectorless developers
// SPDX-License-Identifier: Apache-2.0

//! Public API types for the client module.
//!
//! This module contains all types exposed in the public API.

use serde::{Deserialize, Serialize};
use std::path::PathBuf;

use crate::document::DocumentTree;
use crate::index::parse::DocumentFormat;
use crate::metrics::IndexMetrics;

// ============================================================
// Document Types
// ============================================================

/// An indexed document with its tree structure and metadata.
#[derive(Debug, Clone)]
pub struct IndexedDocument {
    /// Unique document identifier.
    pub id: String,

    /// Document format.
    pub format: DocumentFormat,

    /// Document name/title.
    pub name: String,

    /// Document description (generated by LLM).
    pub description: Option<String>,

    /// Source file path.
    pub source_path: Option<PathBuf>,

    /// Page count (for PDFs).
    pub page_count: Option<usize>,

    /// The document tree structure.
    pub tree: Option<DocumentTree>,

    /// Per-page content (for PDFs).
    pub pages: Vec<PageContent>,

    /// Indexing pipeline metrics.
    pub metrics: Option<IndexMetrics>,

    /// Pre-computed reasoning index for retrieval acceleration.
    pub reasoning_index: Option<crate::document::ReasoningIndex>,
}

impl IndexedDocument {
    /// Create a new indexed document.
    pub fn new(id: impl Into<String>, format: DocumentFormat) -> Self {
        Self {
            id: id.into(),
            format,
            name: String::new(),
            description: None,
            source_path: None,
            page_count: None,
            tree: None,
            pages: Vec::new(),
            metrics: None,
            reasoning_index: None,
        }
    }

    /// Set the document name.
    pub fn with_name(mut self, name: impl Into<String>) -> Self {
        self.name = name.into();
        self
    }

    /// Set the document description.
    pub fn with_description(mut self, desc: impl Into<String>) -> Self {
        self.description = Some(desc.into());
        self
    }

    /// Set the source path.
    pub fn with_source_path(mut self, path: impl Into<PathBuf>) -> Self {
        self.source_path = Some(path.into());
        self
    }

    /// Set the page count.
    pub fn with_page_count(mut self, count: usize) -> Self {
        self.page_count = Some(count);
        self
    }

    /// Set the document tree.
    pub fn with_tree(mut self, tree: DocumentTree) -> Self {
        self.tree = Some(tree);
        self
    }

    /// Set the indexing metrics.
    pub fn with_metrics(mut self, metrics: IndexMetrics) -> Self {
        self.metrics = Some(metrics);
        self
    }
}

/// Content for a single page.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PageContent {
    /// Page number (1-based).
    pub page: usize,

    /// Page text content.
    pub content: String,
}

// ============================================================
// Partial Success
// ============================================================

/// A failed item in a batch operation.
#[derive(Debug, Clone)]
pub struct FailedItem {
    /// Source description (file path, content name, or doc ID).
    pub source: String,
    /// Error message.
    pub error: String,
}

impl FailedItem {
    /// Create a new failed item.
    pub fn new(source: impl Into<String>, error: impl Into<String>) -> Self {
        Self {
            source: source.into(),
            error: error.into(),
        }
    }
}

// ============================================================
// Index Types
// ============================================================

/// Document indexing behavior mode.
///
/// Controls how the indexer handles existing documents and re-indexing.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum IndexMode {
    /// Default mode - skip if already indexed.
    ///
    /// If a document with the same source has already been indexed,
    /// the operation is skipped and the existing document ID is returned.
    #[default]
    Default,

    /// Force re-indexing.
    ///
    /// Always re-index the document, even if it has been indexed before.
    /// A new document ID is generated.
    Force,

    /// Incremental mode - only re-index changed files.
    ///
    /// Re-index only if the file has been modified since the last index.
    /// For content/bytes sources, this behaves like [`IndexMode::Default`].
    Incremental,
}

/// Options for indexing a document.
#[derive(Debug, Clone)]
pub struct IndexOptions {
    /// Indexing mode.
    pub mode: IndexMode,

    /// Whether to generate summaries using LLM.
    pub generate_summaries: bool,

    /// Whether to include node text in the tree.
    pub include_text: bool,

    /// Whether to generate node IDs.
    pub generate_ids: bool,

    /// Whether to generate document description.
    pub generate_description: bool,

    /// Whether to expand keywords with LLM-generated synonyms
    /// during reasoning index construction. Improves recall for
    /// queries that use different wording than the document.
    pub enable_synonym_expansion: bool,
}

impl Default for IndexOptions {
    fn default() -> Self {
        Self {
            mode: IndexMode::Default,
            generate_summaries: true,
            include_text: true,
            generate_ids: true,
            generate_description: false,
            enable_synonym_expansion: true,
        }
    }
}

impl IndexOptions {
    /// Create new index options with defaults.
    pub fn new() -> Self {
        Self::default()
    }

    /// Enable summary generation.
    pub fn with_summaries(mut self) -> Self {
        self.generate_summaries = true;
        self
    }

    /// Enable document description generation.
    pub fn with_description(mut self) -> Self {
        self.generate_description = true;
        self
    }

    /// Set the indexing mode.
    ///
    /// # Modes
    ///
    /// - [`IndexMode::Default`] - Skip if already indexed
    /// - [`IndexMode::Force`] - Always re-index
    /// - [`IndexMode::Incremental`] - Only re-index changed files
    pub fn with_mode(mut self, mode: IndexMode) -> Self {
        self.mode = mode;
        self
    }
}

// ============================================================
// Index Result Types
// ============================================================

/// Result of a document indexing operation.
#[derive(Debug, Clone)]
pub struct IndexResult {
    /// Successfully indexed items.
    pub items: Vec<IndexItem>,

    /// Items that failed to index (partial success).
    pub failed: Vec<FailedItem>,
}

impl IndexResult {
    /// Create a new index result.
    pub fn new(items: Vec<IndexItem>) -> Self {
        Self {
            items,
            failed: Vec::new(),
        }
    }

    /// Create with both successes and failures.
    pub fn with_partial(items: Vec<IndexItem>, failed: Vec<FailedItem>) -> Self {
        Self { items, failed }
    }

    /// Get the single document ID (convenience for single-document indexing).
    pub fn doc_id(&self) -> Option<&str> {
        if self.items.len() == 1 {
            Some(&self.items[0].doc_id)
        } else {
            None
        }
    }

    /// Check if the result is empty.
    pub fn is_empty(&self) -> bool {
        self.items.is_empty()
    }

    /// Get the number of indexed items.
    pub fn len(&self) -> usize {
        self.items.len()
    }

    /// Whether any items failed.
    pub fn has_failures(&self) -> bool {
        !self.failed.is_empty()
    }

    /// Total number of sources (success + failed).
    pub fn total(&self) -> usize {
        self.items.len() + self.failed.len()
    }
}

/// A single indexed document item.
#[derive(Debug, Clone)]
pub struct IndexItem {
    /// The unique document ID.
    pub doc_id: String,
    /// The document name.
    pub name: String,
    /// The document format.
    pub format: DocumentFormat,
    /// Document description (from root summary).
    pub description: Option<String>,
    /// Source file path (if indexed from a file).
    pub source_path: Option<String>,
    /// Page count (for PDFs).
    pub page_count: Option<usize>,
    /// Indexing pipeline metrics (timing, LLM usage, node stats).
    pub metrics: Option<IndexMetrics>,
}

impl IndexItem {
    /// Create a new index item.
    pub fn new(
        doc_id: impl Into<String>,
        name: impl Into<String>,
        format: DocumentFormat,
        description: Option<String>,
        page_count: Option<usize>,
    ) -> Self {
        Self {
            doc_id: doc_id.into(),
            name: name.into(),
            format,
            description,
            source_path: None,
            page_count,
            metrics: None,
        }
    }

    /// Set the source file path.
    pub fn with_source_path(mut self, path: impl Into<String>) -> Self {
        self.source_path = Some(path.into());
        self
    }

    /// Set the indexing metrics.
    pub fn with_metrics(mut self, metrics: IndexMetrics) -> Self {
        self.metrics = Some(metrics);
        self
    }

    /// Set the indexing metrics (optional).
    pub fn with_metrics_opt(mut self, metrics: Option<IndexMetrics>) -> Self {
        self.metrics = metrics;
        self
    }
}

// ============================================================
// Query Types
// ============================================================

/// A single document's query result.
#[derive(Debug, Clone)]
pub struct QueryResultItem {
    /// The document ID.
    pub doc_id: String,

    /// Matching node IDs.
    pub node_ids: Vec<String>,

    /// Retrieved content.
    pub content: String,

    /// Relevance score.
    pub score: f32,
}

/// Result of a document query.
///
/// Contains results from one or more documents. For single-document queries,
/// `items` has one entry. For multi-document or workspace queries, it has
/// one entry per document that matched.
#[derive(Debug, Clone)]
pub struct QueryResult {
    /// Query results per document.
    pub items: Vec<QueryResultItem>,

    /// Documents that failed during multi-doc query.
    pub failed: Vec<FailedItem>,
}

impl QueryResult {
    /// Create a new query result (empty).
    pub fn new() -> Self {
        Self {
            items: Vec::new(),
            failed: Vec::new(),
        }
    }

    /// Create a query result with a single item.
    pub fn from_single(item: QueryResultItem) -> Self {
        Self {
            items: vec![item],
            failed: Vec::new(),
        }
    }

    /// Create with both successes and failures.
    pub fn with_partial(items: Vec<QueryResultItem>, failed: Vec<FailedItem>) -> Self {
        Self { items, failed }
    }

    /// Check if the result is empty.
    pub fn is_empty(&self) -> bool {
        self.items.is_empty()
    }

    /// Get the number of result items.
    pub fn len(&self) -> usize {
        self.items.len()
    }

    /// Get the first (single-doc) result item, if any.
    pub fn single(&self) -> Option<&QueryResultItem> {
        self.items.first()
    }

    /// Whether any documents failed.
    pub fn has_failures(&self) -> bool {
        !self.failed.is_empty()
    }
}

impl Default for QueryResult {
    fn default() -> Self {
        Self::new()
    }
}

// ============================================================
// Document Info Types
// ============================================================

/// Document info for listing.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DocumentInfo {
    /// Document ID.
    pub id: String,

    /// Document name.
    pub name: String,

    /// Document format.
    pub format: String,

    /// Document description.
    pub description: Option<String>,

    /// Source file path.
    pub source_path: Option<String>,

    /// Page count (for PDFs).
    pub page_count: Option<usize>,

    /// Line count (for text files).
    pub line_count: Option<usize>,
}

impl DocumentInfo {
    /// Create a new document info.
    pub fn new(id: impl Into<String>, name: impl Into<String>) -> Self {
        Self {
            id: id.into(),
            name: name.into(),
            format: String::new(),
            description: None,
            source_path: None,
            page_count: None,
            line_count: None,
        }
    }

    /// Set the format.
    pub fn with_format(mut self, format: impl Into<String>) -> Self {
        self.format = format.into();
        self
    }
}

// ============================================================
// Error Types
// ============================================================

/// Client error types.
#[derive(Debug, Clone, thiserror::Error)]
pub enum ClientError {
    /// Document not found.
    #[error("Document not found: {0}")]
    NotFound(String),

    /// Invalid operation.
    #[error("Invalid operation: {0}")]
    InvalidOperation(String),

    /// Configuration error.
    #[error("Configuration error: {0}")]
    Config(String),

    /// Timeout error.
    #[error("Operation timed out")]
    Timeout,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_indexed_document() {
        let doc = IndexedDocument::new("doc-1", DocumentFormat::Markdown)
            .with_name("Test Document")
            .with_description("A test document");

        assert_eq!(doc.id, "doc-1");
        assert_eq!(doc.name, "Test Document");
        assert!(doc.tree.is_none());
    }

    #[test]
    fn test_index_options() {
        let options = IndexOptions::new()
            .with_summaries()
            .with_mode(IndexMode::Force);

        assert!(options.generate_summaries);
        assert_eq!(options.mode, IndexMode::Force);
    }

    #[test]
    fn test_query_result() {
        let result = QueryResult::new();
        assert!(result.is_empty());
        assert_eq!(result.len(), 0);
    }

    #[test]
    fn test_query_result_single() {
        let item = QueryResultItem {
            doc_id: "doc-1".into(),
            node_ids: vec!["n1".into()],
            content: "content".into(),
            score: 0.9,
        };
        let result = QueryResult::from_single(item);
        assert!(!result.is_empty());
        assert_eq!(result.len(), 1);
        assert!(result.single().is_some());
        assert_eq!(result.single().unwrap().doc_id, "doc-1");
    }

    #[test]
    fn test_document_info() {
        let info = DocumentInfo::new("doc-1", "Test").with_format("markdown");

        assert_eq!(info.id, "doc-1");
        assert_eq!(info.format, "markdown");
    }

    #[test]
    fn test_index_result() {
        let item = IndexItem::new("doc-1", "Test", DocumentFormat::Markdown, None, None);
        let result = IndexResult::new(vec![item]);

        assert_eq!(result.doc_id(), Some("doc-1"));
        assert_eq!(result.len(), 1);
        assert!(!result.is_empty());
    }

    #[test]
    fn test_index_result_empty() {
        let result = IndexResult::new(vec![]);
        assert!(result.is_empty());
        assert_eq!(result.doc_id(), None);
    }

    #[test]
    fn test_index_result_multiple() {
        let items = vec![
            IndexItem::new("doc-1", "A", DocumentFormat::Markdown, None, None),
            IndexItem::new("doc-2", "B", DocumentFormat::Pdf, None, None),
        ];
        let result = IndexResult::new(items);
        assert_eq!(result.len(), 2);
        assert_eq!(result.doc_id(), None);
    }

    #[test]
    fn test_partial_success() {
        let items = vec![IndexItem::new(
            "doc-1",
            "A",
            DocumentFormat::Markdown,
            None,
            None,
        )];
        let failed = vec![FailedItem::new("missing.pdf", "File not found")];
        let result = IndexResult::with_partial(items, failed);

        assert_eq!(result.len(), 1);
        assert!(result.has_failures());
        assert_eq!(result.total(), 2);
        assert_eq!(result.failed[0].source, "missing.pdf");
    }
}