pulsedb/
lib.rs

1//! # PulseDB
2//!
3//! Embedded database for agentic AI systems - collective memory for multi-agent coordination.
4//!
5//! PulseDB provides persistent storage for AI agent experiences, enabling semantic
6//! search, context retrieval, and knowledge sharing between agents.
7//!
8//! ## Quick Start
9//!
10//! ```rust
11//! # fn main() -> pulsedb::Result<()> {
12//! # let dir = tempfile::tempdir().unwrap();
13//! use pulsedb::{PulseDB, Config, NewExperience};
14//!
15//! // Open or create a database
16//! let db = PulseDB::open(dir.path().join("test.db"), Config::default())?;
17//!
18//! // Create a collective (isolated namespace)
19//! let collective = db.create_collective("my-project")?;
20//!
21//! // Record an experience
22//! db.record_experience(NewExperience {
23//!     collective_id: collective,
24//!     content: "Always validate user input before processing".to_string(),
25//!     importance: 0.8,
26//!     embedding: Some(vec![0.1f32; 384]),
27//!     ..Default::default()
28//! })?;
29//!
30//! // Search for relevant experiences
31//! let query_embedding = vec![0.1f32; 384];
32//! let results = db.search_similar(collective, &query_embedding, 10)?;
33//!
34//! // Clean up
35//! db.close()?;
36//! # Ok(())
37//! # }
38//! ```
39//!
40//! ## Key Concepts
41//!
42//! ### Collective
43//!
44//! A **collective** is an isolated namespace for experiences, typically one per project.
45//! Each collective has its own vector index and can have different embedding dimensions.
46//!
47//! ### Experience
48//!
49//! An **experience** is a unit of learned knowledge. It contains:
50//! - Content (text description of the experience)
51//! - Embedding (vector representation for semantic search)
52//! - Metadata (type, importance, confidence, tags)
53//!
54//! ### Embedding Providers
55//!
56//! PulseDB supports two modes for embeddings:
57//!
58//! - **External** (default): You provide pre-computed embeddings from your own service
59//!   (OpenAI, Cohere, etc.)
60//! - **Builtin**: PulseDB generates embeddings using a bundled ONNX model
61//!   (requires `builtin-embeddings` feature)
62//!
63//! ## Features
64//!
65//! - `builtin-embeddings` - Enable built-in ONNX embedding generation
66//!
67//! ## Thread Safety
68//!
69//! `PulseDB` is `Send + Sync` and can be shared across threads using `Arc`.
70//! The database uses MVCC for concurrent reads with exclusive write locking.
71//!
72//! ## Feature Flags
73//!
74//! | Feature | Description |
75//! |---------|-------------|
76//! | `builtin-embeddings` | Bundles ONNX runtime with all-MiniLM-L6-v2 for local embedding generation. Without this feature, you must supply pre-computed embeddings. |
77
78#![cfg_attr(docsrs, feature(doc_cfg))]
79#![warn(missing_docs)]
80#![warn(rustdoc::missing_crate_level_docs)]
81#![deny(unsafe_op_in_unsafe_fn)]
82
83// ============================================================================
84// Module declarations
85// ============================================================================
86
87mod config;
88mod db;
89mod error;
90mod types;
91
92pub mod embedding;
93pub mod storage;
94
95// Domain modules
96mod activity;
97mod collective;
98mod experience;
99mod insight;
100mod relation;
101mod search;
102mod watch;
103
104/// SubstrateProvider async trait for agent framework integration.
105pub mod substrate;
106
107/// Vector index module for HNSW-based approximate nearest neighbor search.
108pub mod vector;
109
110// ============================================================================
111// Public API re-exports
112// ============================================================================
113
114// Main database interface
115pub use db::PulseDB;
116
117// Configuration
118pub use config::{
119    ActivityConfig, Config, EmbeddingDimension, EmbeddingProvider, HnswConfig, SyncMode,
120    WatchConfig,
121};
122
123// Error handling
124pub use error::{NotFoundError, PulseDBError, Result, StorageError, ValidationError};
125
126// Core types
127pub use types::{
128    AgentId, CollectiveId, Embedding, ExperienceId, InsightId, RelationId, TaskId, Timestamp,
129    UserId,
130};
131
132// Domain types
133pub use collective::{Collective, CollectiveStats};
134pub use experience::{Experience, ExperienceType, ExperienceUpdate, NewExperience, Severity};
135
136// Relations
137pub use relation::{ExperienceRelation, NewExperienceRelation, RelationDirection, RelationType};
138
139// Insights
140pub use insight::{DerivedInsight, InsightType, NewDerivedInsight};
141
142// Activities
143pub use activity::{Activity, NewActivity};
144
145// Search & Context
146pub use search::{ContextCandidates, ContextRequest, SearchFilter, SearchResult};
147
148// Watch (real-time notifications + cross-process change detection)
149pub use watch::{ChangePoller, WatchEvent, WatchEventType, WatchFilter, WatchLock, WatchStream};
150
151// Substrate (async agent framework integration)
152pub use substrate::{PulseDBSubstrate, SubstrateProvider};
153
154// Storage (for advanced users)
155pub use storage::DatabaseMetadata;
156
157// ============================================================================
158// Prelude module for convenient imports
159// ============================================================================
160
161/// Convenient imports for common PulseDB usage.
162///
163/// ```rust
164/// use pulsedb::prelude::*;
165/// ```
166pub mod prelude {
167    pub use crate::config::{Config, EmbeddingDimension, SyncMode};
168    pub use crate::db::PulseDB;
169    pub use crate::error::{PulseDBError, Result};
170    pub use crate::experience::{Experience, ExperienceType, NewExperience};
171    pub use crate::search::{ContextCandidates, ContextRequest, SearchFilter, SearchResult};
172    pub use crate::substrate::{PulseDBSubstrate, SubstrateProvider};
173    pub use crate::types::{CollectiveId, ExperienceId, Timestamp};
174    pub use crate::watch::{ChangePoller, WatchEvent, WatchEventType, WatchFilter, WatchLock};
175}
pulsedb/lib.rs

pulsedb/
lib.rs
