Metadata-Version: 2.4
Name: srvdb
Version: 0.1.6
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Summary: Zero-Gravity Embedded Vector Database - Offline-first, RAM-efficient vector search
Keywords: vector,database,embedding,search,quantization
License: MIT OR Apache-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/Srinivas26k/svdb
Project-URL: Repository, https://github.com/Srinivas26k/svdb
Project-URL: Documentation, https://github.com/Srinivas26k/svdb/blob/main/README.md

# 🚀 SvDB - Zero-Gravity Embedded Vector Database

**"All the intelligence, none of the weight."**

SvDB is a high-performance embedded vector database designed for offline-first, mobile-ready, and RAM-efficient applications. Built in Rust with sub-millisecond search speeds.

[![Rust](https://img.shields.io/badge/rust-1.92%2B-orange.svg)](https://www.rust-lang.org/)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE)

## ✨ Key Features

- **🔌 Offline-First**: No network calls, no latency, no cloud bills
- **💾 RAM-Efficient**: Uses `mmap` for zero-copy vector access, OS manages memory
- **⚡ Blazing Fast**: Sub-5ms search on 100k vectors using binary quantization
- **📱 Mobile-Ready**: Designed for embedded systems, iOS, Android, and IoT
- **🎯 Simple API**: Clean Rust trait interface with minimal complexity

## 🏗️ Architecture

### Dual-File System
- **`vectors.bin`**: Memory-mapped binary quantized vectors (1 bit/dimension)
- **`metadata.db`**: Embedded key-value store (redb) for metadata

### Search Pipeline
1. **Coarse Search**: Hamming distance via XOR/popcount (parallelized with rayon)
2. **Fine Rescore**: Optional exact similarity for top-k candidates (future)

## 📦 Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
svdb = "1.0.0"
```

## 🚀 Quick Start

```rust
use svdb::{SvDB, Vector, VectorEngine};
use anyhow::Result;

fn main() -> Result<()> {
    // Initialize database
    let mut db = SvDB::new("./my_vectors")?;

    // Add a vector (1536 dimensions for OpenAI embeddings)
    let vec = Vector::new(vec![0.1; 1536]);
    let id = db.add(&vec, r#"{"title": "example"}"#)?;

    // Search for similar vectors
    let results = db.search(&vec, 10)?;
    
    for result in results {
        println!("ID: {}, Score: {:.4}", result.id, result.score);
    }

    // Persist to disk
    db.persist()?;
    
    Ok(())
}
```

## 📊 Performance

- **Latency**: < 5ms for 100k vectors (standard mobile CPU)
- **Memory**: < 50MB baseline overhead
- **Binary Size**: < 10MB (stripped release build)
- **Storage**: 192 bytes per vector (1536 dimensions)

## 🛠️ Tech Stack

- **Storage**: `memmap2` for vectors, `redb` for metadata
- **Parallelism**: `rayon` for multi-threaded search
- **Quantization**: Binary quantization (1 bit per dimension)
- **Error Handling**: `anyhow` + `thiserror`

## 📖 Examples

Run the basic example:

```bash
cargo run --example basic
```

## 🧪 Testing

```bash
# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run benchmarks (when implemented)
cargo bench
```

## 🎯 Use Cases

- **Mobile AI**: On-device semantic search without cloud dependency
- **IoT Devices**: Lightweight vector search on resource-constrained hardware  
- **Offline Apps**: RAG systems that work without internet
- **Edge Computing**: Vector search at the edge with minimal latency

## 📝 API Reference

### `VectorEngine` Trait

```rust
pub trait VectorEngine {
    fn new(path: &str) -> Result<Self>;
    fn add(&mut self, vec: &Vector, meta: &str) -> Result<u64>;
    fn search(&self, query: &Vector, k: usize) -> Result<Vec<SearchResult>>;
    fn get_metadata(&self, id: u64) -> Result<Option<String>>;
    fn persist(&mut self) -> Result<()>;
}
```

### Types

```rust
pub struct Vector {
    pub data: Vec<f32>,  // 1536 dimensions
}

pub struct SearchResult {
    pub id: u64,
    pub score: f32,           // 0.0 to 1.0
    pub metadata: Option<String>,
}
```

## 🗺️ Roadmap

- [x] MVP: Binary quantization + Hamming search
- [ ] Product quantization for better accuracy
- [ ] HNSW graph index for faster search
- [ ] ARM NEON SIMD optimizations
- [ ] C FFI bindings for mobile (iOS/Android)
- [ ] Incremental indexing (hot updates)
- [ ] Metadata filtering (WHERE clause)

## 🤝 Contributing

Contributions welcome! Please check the [issues](https://github.com/yourusername/svdb/issues) page.

## 📄 License

Licensed under either of:

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))

at your option.

## 🙏 Acknowledgments

Built following the principles from the PRD for constraint-driven AI development.

---

**Made with ⚡ and 🦀 by the SvDB team**

