avocado-core 2.2.0

Core engine for AvocadoDB - deterministic context compilation for AI agents
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

//! AvocadoDB Core Engine
//!
//! The deterministic context compiler that fixes RAG.
//!
//! AvocadoDB replaces traditional vector databases' chaotic "top-k" retrieval
//! with deterministic, citation-backed context generation using span-based
//! compilation.
//!
//! # Key Features
//!
//! - **100% Deterministic**: Same query → same context, every time
//! - **Citation-Backed**: Every piece of context has exact line number citations
//! - **Token Efficient**: 95%+ token budget utilization (vs 60-70% in RAG)
//! - **Fast**: < 500ms for 8K token context
//!
//! # Architecture
//!
//! ```text
//! Query → Embed → [Semantic Search + Lexical Search] → Hybrid Fusion
//!       → MMR Diversification → Token Packing → Deterministic Sort → WorkingSet
//! ```

#![warn(missing_docs)]

pub mod types;
pub mod span;
pub mod embedding;
pub mod compiler;
pub mod db;
pub mod index;
pub mod session;
pub mod approx;
pub mod eval;
pub mod diff;
pub mod storage;

// Re-export commonly used types
pub use types::{
    Artifact, Citation, CompilerConfig, Error, Result, ScoredSpan, Span, WorkingSet,
    Session, Message, MessageRole, SessionWorkingSet,
    // New types for enhanced determinism and explainability
    Manifest, ChunkingParams, IndexParams,
    ExplainPlan, ExplainCandidate, ExplainTiming, ExplainThresholds,
    IngestAction,
    GoldenQuery, EvalResult, EvalSummary,
    WorkingSetDiff, DiffEntry, RerankEntry,
    // Multi-agent orchestration types
    Agent, Stance, AgentRelation, AgentMessageMeta, AgentRelationSummary, AgentRelationEntry,
};

pub use session::{SessionManager, SessionManagerGeneric, SessionReplay, SessionTurn};

// Re-export compiler functions
pub use compiler::{compile, compile_with_backend, compile_with_backend_options};

// Re-export storage module types
pub use storage::{
    StorageBackend, StorageConfig, SqliteBackend,
    VectorSearchProvider, VectorSearchResult,
    create_backend, create_backend_from_env,
};

/// The version of AvocadoDB
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

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

    #[test]
    fn test_version() {
        assert!(!VERSION.is_empty());
    }

    #[test]
    fn test_working_set_hash_determinism() {
        let ws1 = WorkingSet {
            text: "Hello, world!".to_string(),
            spans: vec![],
            citations: vec![],
            tokens_used: 3,
            query: "test".to_string(),
            compilation_time_ms: 100,
            manifest: None,
            explain: None,
        };

        let ws2 = WorkingSet {
            text: "Hello, world!".to_string(),
            spans: vec![],
            citations: vec![],
            tokens_used: 3,
            query: "test".to_string(),
            compilation_time_ms: 200, // Different timing
            manifest: None,
            explain: None,
        };

        // Hash should be the same because it only depends on text
        assert_eq!(ws1.deterministic_hash(), ws2.deterministic_hash());
    }
}