### Python Quick Start

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Example of how to install and use the EmbedVec library in a Python project.

```APIDOC
## Python Quick Start

### Installation

```bash
pip install embedvec-py
```

### Example Usage

```python
import embedvec_py
import numpy as np

# Create database with E8 quantization
db = embedvec_py.EmbedVec(
    dim=768,
    metric="cosine",
    m=32,
    ef_construction=200,
    quantization="e8-10bit",  # or None, "e8-8bit", "e8-12bit"
    persist_path=None,         # or "/tmp/embedvec.db"
)

# Add vectors (numpy array or list-of-lists)
vectors = np.random.randn(50000, 768).tolist()
payloads = [{"doc_id": str(i), "tag": "news" if i % 3 == 0 else "blog"} 
            for i in range(50000)]

db.add_many(vectors, payloads)

# Search with filter
query = np.random.randn(768).tolist()
hits = db.search(
    query_vector=query,
    k=10,
    ef_search=128,
    filter={"tag": "news"}  # simple exact-match shorthand
)

for hit in hits:
    print(f"score: {hit['score']:.4f}  id: {hit['id']}  {hit['payload']}")
```
```

--------------------------------

### Development Environment Setup

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/CONTRIBUTING.md

Commands to install Rust, build the project, run tests, and compile Python bindings.

```bash
# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone and build
git clone https://github.com/embedvec/embedvec.git
cd embedvec
cargo build

# Run tests
cargo test

# Run benchmarks
cargo bench

# Build Python bindings (requires maturin)
pip install maturin
cd embedvec-py
maturin develop
```

--------------------------------

### Rust Quick Start

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Example of how to set up and use the EmbedVec library in a Rust project.

```APIDOC
## Rust Quick Start

### Dependencies

```toml
[dependencies]
embedvec = "0.5"
tokio = { version = "1.0", features = ["rt-multi-thread", "macros"] }
serde_json = "1.0"
```

### Example Usage

```rust
use embedvec::{Distance, EmbedVec, FilterExpr, Quantization};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create in-memory index with E8 quantization
    let mut db = EmbedVec::builder()
        .dimension(768)
        .metric(Distance::Cosine)
        .m(32)                              // HNSW connections per layer
        .ef_construction(200)               // Build-time beam width
        .quantization(Quantization::e8_default())  // 4-6× memory savings
        .build()
        .await?;

    // Add vectors with metadata
    let vectors = vec![
        vec![0.1; 768],
        vec![0.2; 768],
    ];
    let payloads = vec![
        serde_json::json!({{"doc_id": "123", "category": "finance", "timestamp": 1737400000}}),
        serde_json::json!({{"doc_id": "456", "category": "tech", "timestamp": 1737500000}})
    ];

    db.add_many(&vectors, payloads).await?;

    // Search with metadata filter
    let filter = FilterExpr::eq("category", "finance")
        .and(FilterExpr::gt("timestamp", 1730000000));

    let results = db.search(
        &vec![0.15; 768],  // query vector
        10,                 // k
        128,                // ef_search
        Some(filter)
    ).await?;

    for hit in results {
        println!("id: {{}}, score: {{:.4}}, payload: {{}}", hit.id, hit.score, hit.payload);
    }

    Ok(())
}
```
```

--------------------------------

### Install Criterion for Benchmarking

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Install the Criterion.rs benchmarking framework globally using Cargo.

```bash
# Install criterion
cargo install cargo-criterion
```

--------------------------------

### Python Quick Start: Adding Vectors and Searching with Filters

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Installs the embedvec-py library and demonstrates creating a vector database with E8 quantization, adding a large number of vectors with associated payloads, and performing a search using a simple filter.

```bash
pip install embedvec-py
```

```python
import embedvec_py
import numpy as np

# Create database with E8 quantization
db = embedvec_py.EmbedVec(
    dim=768,
    metric="cosine",
    m=32,
    ef_construction=200,
    quantization="e8-10bit",  # or None, "e8-8bit", "e8-12bit"
    persist_path=None,         # or "/tmp/embedvec.db"
)

# Add vectors (numpy array or list-of-lists)
vectors = np.random.randn(50000, 768).tolist()
payloads = [{"doc_id": str(i), "tag": "news" if i % 3 == 0 else "blog"} 
            for i in range(50000)]

db.add_many(vectors, payloads)

# Search with filter
query = np.random.randn(768).tolist()
hits = db.search(
    query_vector=query,
    k=10,
    ef_search=128,
    filter={"tag": "news"}  # simple exact-match shorthand
)

for hit in hits:
    print(f"score: {hit['score']:.4f}  id: {hit['id']}  {hit['payload']}")
```

--------------------------------

### Quick Start: Create, Add, and Search Vectors

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec-py/README.md

Demonstrates the basic usage of embedvec-py: creating a database with specified dimensions and metrics, adding multiple vectors with associated payloads, and performing a search with optional filtering.

```python
import embedvec_py
import numpy as np

# Create database
db = embedvec_py.EmbedVec(
    dim=768,
    metric="cosine",           # "cosine", "euclidean", or "dot"
    m=32,                      # HNSW connections per layer
    ef_construction=200,       # HNSW build parameter
    quantization="e8p-10bit",  # Optional: "e8p-8bit", "e8p-10bit", "e8p-12bit"
    persist_path=None,         # Optional: path for persistence
)

# Add vectors
vectors = np.random.randn(10000, 768).tolist()
payloads = [{"doc_id": str(i), "category": "news" if i % 2 == 0 else "blog"} 
            for i in range(10000)]

db.add_many(vectors, payloads)

# Search
query = np.random.randn(768).tolist()
hits = db.search(
    query_vector=query,
    k=10,
    ef_search=128,
    filter={"category": "news"}  # Optional filter
)

for hit in hits:
    print(f"Score: {hit['score']:.4f} | ID: {hit['id']} | {hit['payload']}")
```

--------------------------------

### Rust Quick Start: In-memory Index with E8 Quantization

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Demonstrates creating an in-memory EmbedVec index with E8 quantization, adding vectors and payloads, and performing a search with a metadata filter. Ensure Tokio is set up for async operations.

```toml
[dependencies]
embedvec = "0.5"
tokio = { version = "1.0", features = ["rt-multi-thread", "macros"] }
serde_json = "1.0"
```

```rust
use embedvec::{Distance, EmbedVec, FilterExpr, Quantization};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create in-memory index with E8 quantization
    let mut db = EmbedVec::builder()
        .dimension(768)
        .metric(Distance::Cosine)
        .m(32)                              // HNSW connections per layer
        .ef_construction(200)               // Build-time beam width
        .quantization(Quantization::e8_default())  // 4-6× memory savings
        .build()
        .await?;

    // Add vectors with metadata
    let vectors = vec![
        vec![0.1; 768],
        vec![0.2; 768],
    ];
    let payloads = vec![
        serde_json::json!({"doc_id": "123", "category": "finance", "timestamp": 1737400000}),
        serde_json::json!({"doc_id": "456", "category": "tech", "timestamp": 1737500000}),
    ];

    db.add_many(&vectors, payloads).await?;

    // Search with metadata filter
    let filter = FilterExpr::eq("category", "finance")
        .and(FilterExpr::gt("timestamp", 1730000000));

    let results = db.search(
        &vec![0.15; 768],  // query vector
        10,                 // k
        128,                // ef_search
        Some(filter)
    ).await?;

    for hit in results {
        println!("id: {}, score: {:.4}, payload: {:?}", hit.id, hit.score, hit.payload);
    }

    Ok(())
}
```

--------------------------------

### Memory Profiling with jemalloc

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Run benchmarks with jemalloc enabled for memory profiling. Ensure jemalloc is installed on your system.

```bash
# Memory profiling (requires jemalloc)
cargo bench --features "jemalloc"
```

--------------------------------

### Install embedvec-py

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec-py/README.md

Install the embedvec-py library using pip. This is the first step to using the vector database in your Python projects.

```bash
pip install embedvec-py
```

--------------------------------

### Run Benchmarks with Criterion

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Execute benchmarks using the installed cargo-criterion tool.

```bash
# Run benchmarks
cargo criterion
```

--------------------------------

### Enable pgvector Extension in PostgreSQL

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Ensure the pgvector extension is installed and enabled in your PostgreSQL database before connecting.

```sql
CREATE EXTENSION vector;
```

--------------------------------

### FilterExpr API

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Examples of constructing complex filters for targeted searches.

```APIDOC
## FilterExpr — Composable Filters

```rust
// Equality
FilterExpr::eq("category", "finance")

// Comparisons
FilterExpr::gt("timestamp", 1730000000)
FilterExpr::gte("score", 0.5)
FilterExpr::lt("price", 100)
FilterExpr::lte("count", 10)

// String operations
FilterExpr::contains("name", "test")
FilterExpr::starts_with("path", "/api")

// Membership
FilterExpr::in_values("status", vec!["active", "pending"])

// Existence
FilterExpr::exists("optional_field")

// Boolean composition
FilterExpr::eq("a", 1)
    .and(FilterExpr::eq("b", 2))
    .or(FilterExpr::not(FilterExpr::eq("c", 3)))
```
```

--------------------------------

### Rust FilterExpr for Metadata Filtering

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Provides examples of constructing complex filter expressions using FilterExpr for searching vectors based on their associated metadata. Supports equality, comparisons, string operations, membership, existence, and boolean logic.

```rust
// Equality
FilterExpr::eq("category", "finance")

// Comparisons
FilterExpr::gt("timestamp", 1730000000)
FilterExpr::gte("score", 0.5)
FilterExpr::lt("price", 100)
FilterExpr::lte("count", 10)

// String operations
FilterExpr::contains("name", "test")
FilterExpr::starts_with("path", "/api")

// Membership
FilterExpr::in_values("status", vec!["active", "pending"])

// Existence
FilterExpr::exists("optional_field")

// Boolean composition
FilterExpr::eq("a", 1)
    .and(FilterExpr::eq("b", 2))
    .or(FilterExpr::not(FilterExpr::eq("c", 3)))
```

--------------------------------

### Configure E8 Lattice Quantization

Source: https://context7.com/weaveitmeta/embedvec/llms.txt

Demonstrates various configurations for E8 lattice quantization, from default settings to custom bit depths and preprocessing options. Shows how to check compression statistics after setting up quantization.

```rust
use embedvec::{Distance, EmbedVec, Quantization};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // No quantization - full f32 precision (32 bits/dim, ~3.1KB per 768d vector)
    let quant = Quantization::None;

    // E8 with default settings (10-bit, Hadamard preprocessing)
    // ~1.25 bits/dim, ~220 bytes per 768d vector, 96-99% recall
    let quant = Quantization::e8_default();

    // E8 8-bit - maximum compression, lower quality
    // ~1.0 bits/dim, ~170 bytes per 768d vector, 92-97% recall
    let quant = Quantization::e8(8, true, 0xcafef00d);

    // E8 10-bit - balanced (recommended)
    let quant = Quantization::e8(10, true, 0xcafef00d);

    // E8 12-bit - higher quality, less compression
    // ~1.5 bits/dim, ~280 bytes per 768d vector, 98-99% recall
    let quant = Quantization::e8(12, true, 0xcafef00d);

    // Create database with quantization
    let db = EmbedVec::builder()
        .dimension(768)
        .metric(Distance::Cosine)
        .quantization(Quantization::e8_default())
        .build()
        .await?;

    // Check compression stats
    let bits_per_dim = db.quantization().bits_per_dim();
    let bytes_per_vector = db.quantization().bytes_per_vector(768);
    let compression_ratio = db.quantization().compression_ratio(768);

    println!("Bits per dimension: {:.2}", bits_per_dim);       // 1.25
    println!("Bytes per vector: {}", bytes_per_vector);        // ~124
    println!("Compression ratio: {:.1}x", compression_ratio);  // ~24.8x

    Ok(())
}

```

--------------------------------

### Configure and Use PostgreSQL/pgvector Backend

Source: https://context7.com/weaveitmeta/embedvec/llms.txt

Demonstrates setting up the pgvector backend for Embedvec, including specifying connection details, table name, and index type (HNSW or IVFFlat). Shows how to insert vectors with metadata, perform native searches, and manage data.

```rust
use embedvec::persistence::{BackendConfig, PgVectorBackend};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure pgvector backend
    let config = BackendConfig::pgvector(
        "postgresql://user:password@localhost/mydb",
        768  // vector dimension
    )
    .table_name("my_vectors")      // default: "embedvec_vectors"
    .index_type("hnsw");           // "hnsw" (default) or "ivfflat"

    // Connect (auto-creates table and vector index)
    let backend = PgVectorBackend::connect(&config).await?;

    // Insert vectors with JSONB metadata
    let embedding = vec![0.1; 768];
    let id = backend.insert_vector(
        "doc_123",
        &embedding,
        Some(json!({"category": "tech", "author": "alice"}))
    ).await?;
    println!("Inserted with ID: {}", id);

    // Native vector search (executed in PostgreSQL)
    let query = vec![0.15; 768];
    let results = backend.search_vectors(
        &query,
        10,           // k
        Some(128)     // ef_search for HNSW
    ).await?;

    for (id, external_id, similarity, metadata) in results {
        println!("{}: {} (score: {:.4}) {{:?}}", id, external_id, similarity, metadata);
    }

    // Other operations
    let count = backend.count().await?;
    println!("Total vectors: {}", count);

    backend.delete_vector("doc_123").await?;
    backend.clear().await?;

    Ok(())
}

```

--------------------------------

### Configure Sled and RocksDB Persistence Backends

Source: https://context7.com/weaveitmeta/embedvec/llms.txt

Shows how to initialize Embedvec with the default Sled backend and configure the RocksDB backend for higher performance, including setting a cache size.

```rust
use embedvec::{Distance, EmbedVec, BackendConfig, BackendType};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Sled backend (default) - pure Rust, good for most use cases
    let db = EmbedVec::with_persistence(
        "/tmp/embedvec_sled",
        768,
        Distance::Cosine,
        32,
        200
    ).await?;

    // Explicit Sled configuration
    let config = BackendConfig::new("/tmp/embedvec_sled")
        .backend(BackendType::Sled);
    let db = EmbedVec::with_backend(config, 768, Distance::Cosine, 32, 200).await?;

    // RocksDB backend - higher performance for write-heavy workloads
    // Requires feature: persistence-rocksdb
    let config = BackendConfig::new("/tmp/embedvec_rocksdb")
        .backend(BackendType::RocksDb)
        .cache_size(256 * 1024 * 1024);  // 256MB cache
    let db = EmbedVec::with_backend(config, 768, Distance::Cosine, 32, 200).await?;

    Ok(())
}

```

--------------------------------

### Run Benchmarks

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Execute the project's benchmark suite using Cargo.

```bash
# Run benchmarks
cargo bench
```

--------------------------------

### Configure and Connect to pgvector Backend

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Set up the pgvector backend configuration with your database connection string and vector dimension. The backend will auto-create the table and index on connection.

```rust
use embedvec::{BackendConfig, BackendType};
use embedvec::persistence::PgVectorBackend;

// Configure pgvector backend
let config = BackendConfig::pgvector(
    "postgresql://user:password@localhost/mydb",
    768  // vector dimension
)
.table_name("my_vectors")      // optional, default: "embedvec_vectors"
.index_type("hnsw");           // "hnsw" (default) or "ivfflat"

// Connect (auto-creates table and index)
let backend = PgVectorBackend::connect(&config).await?;
```

--------------------------------

### Configure RocksDB Persistence

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Enable the RocksDB feature and configure the backend for high-performance storage.

```toml
[dependencies]
embedvec = { version = "0.5", features = ["persistence-rocksdb", "async"] }
```

```rust
use embedvec::{EmbedVec, Distance, BackendConfig, BackendType};

// Configure RocksDB backend
let config = BackendConfig::new("/path/to/db")
    .backend(BackendType::RocksDb)
    .cache_size(256 * 1024 * 1024);  // 256MB cache

let db = EmbedVec::with_backend(config, 768, Distance::Cosine, 32, 200).await?;
```

--------------------------------

### Create EmbedVec Database

Source: https://context7.com/weaveitmeta/embedvec/llms.txt

Initialize an EmbedVec database using direct instantiation, the builder pattern, or with persistent storage.

```rust
use embedvec::{Distance, EmbedVec, Quantization};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Simple in-memory database
    let db = EmbedVec::new(768, Distance::Cosine, 32, 200).await?;

    // Using builder pattern with E8 quantization for memory efficiency
    let db = EmbedVec::builder()
        .dimension(768)                           // Vector dimension (required)
        .metric(Distance::Cosine)                 // Distance metric
        .m(32)                                    // HNSW connections per layer
        .ef_construction(200)                     // HNSW build parameter
        .quantization(Quantization::e8_default()) // 4-6x memory savings
        .build()
        .await?;

    // With persistence (uses Sled by default)
    let db = EmbedVec::with_persistence(
        "/path/to/db",
        768,
        Distance::Cosine,
        32,
        200
    ).await?;

    println!("Database created with dimension: {}", db.dimension());
    Ok(())
}
```

--------------------------------

### Configure distance metrics in Rust

Source: https://context7.com/weaveitmeta/embedvec/llms.txt

Shows how to initialize EmbedVec with different distance metrics and perform direct distance computations.

```rust
use embedvec::{Distance, EmbedVec};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Cosine similarity (default) - best for normalized embeddings
    // Lower score = more similar (1 - cos(θ))
    let db = EmbedVec::new(768, Distance::Cosine, 32, 200).await?;

    // Euclidean distance (L2 norm) - best for spatial data
    // Lower score = more similar
    let db = EmbedVec::new(768, Distance::Euclidean, 32, 200).await?;

    // Dot product (inner product) - best for unnormalized embeddings
    // Higher raw score = more similar (internally negated for min-heap)
    let db = EmbedVec::new(768, Distance::DotProduct, 32, 200).await?;

    // Direct distance computation
    let a = vec![1.0, 0.0, 0.0];
    let b = vec![0.0, 1.0, 0.0];

    let cosine_dist = Distance::Cosine.compute(&a, &b);
    println!("Cosine distance (orthogonal): {:.4}", cosine_dist); // 1.0

    let euclidean_dist = Distance::Euclidean.compute(&a, &b);
    println!("Euclidean distance: {:.4}", euclidean_dist); // 1.4142

    let dot_dist = Distance::DotProduct.compute(&a, &b);
    println!("Dot product distance: {:.4}", dot_dist); // 0.0 (negated)

    Ok(())
}
```

--------------------------------

### Initialize Sled Persistence

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Use the default Sled backend for path-based persistence in Rust.

```rust
use embedvec::{EmbedVec, Distance, BackendConfig, BackendType};

// Simple path-based persistence (uses Sled)
let db = EmbedVec::with_persistence("/path/to/db", 768, Distance::Cosine, 32, 200).await?;

// Or via builder
let db = EmbedVec::builder()
    .dimension(768)
    .persistence("/path/to/db")
    .build()
    .await?;
```

--------------------------------

### Run All Tests

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Execute all unit and integration tests for the project using Cargo.

```bash
# Run all tests
cargo test
```

--------------------------------

### Configure HNSW Index Parameters in Rust

Source: https://context7.com/weaveitmeta/embedvec/llms.txt

Demonstrates configuring HNSW index parameters (M, ef_construction, ef_search) for different performance profiles: low latency, balanced, and high recall. Use these parameters to tune the recall-speed tradeoff for your specific application.

```rust
use embedvec::{Distance, EmbedVec};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // HNSW parameters explained:
    // - m: Connections per layer (16-64 typical)
    //   Higher = better recall, more memory, slower insert
    // - ef_construction: Build-time beam width (100-500 typical)
    //   Higher = better graph quality, slower build
    // - ef_search: Query-time beam width (set per search)
    //   Higher = better recall, slower query

    // Low latency configuration (faster, lower recall)
    let db = EmbedVec::new(768, Distance::Cosine, 16, 100).await?;

    // Balanced configuration (recommended)
    let db = EmbedVec::new(768, Distance::Cosine, 32, 200).await?;

    // High recall configuration (slower, better accuracy)
    let db = EmbedVec::new(768, Distance::Cosine, 64, 500).await?;

    // Search with different ef_search values
    let query = vec![0.5; 768];

    // Fast search (ef_search=32): ~3ms, lower recall
    let results = db.search(&query, 10, 32, None).await?;

    // Balanced search (ef_search=128): ~16ms, good recall
    let results = db.search(&query, 10, 128, None).await?;

    // High recall search (ef_search=256): ~23ms, best recall
    let results = db.search(&query, 10, 256, None).await?;

    Ok(())
}
```

--------------------------------

### Rust EmbedVec Builder Configuration

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Shows how to configure an EmbedVec index using the builder pattern, specifying dimensions, distance metric, HNSW parameters, quantization, and optional disk persistence.

```rust
EmbedVec::builder()
    .dimension(768)                    // Vector dimension (required)
    .metric(Distance::Cosine)          // Distance metric
    .m(32)                             // HNSW M parameter
    .ef_construction(200)              // HNSW build parameter
    .quantization(Quantization::None)  // Or E8 for compression
    .persistence("path/to/db")         // Optional disk persistence
    .build()
    .await?;
```

--------------------------------

### Utility Methods

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec-py/README.md

Methods for database management and monitoring.

```APIDOC
## Utility Methods

- **len()** - Returns the number of vectors in the database.
- **clear()** - Removes all vectors from the database.
- **memory_bytes()** - Returns current memory usage in bytes.
- **compression_ratio()** - Returns the compression ratio compared to FP32.
```

--------------------------------

### EmbedVec Python Bindings with Quantization and Filtering

Source: https://context7.com/weaveitmeta/embedvec/llms.txt

Shows how to create an EmbedVec database in Python using PyO3, including E8 quantization for memory efficiency. Demonstrates adding vectors, performing searches with simple filters, and inspecting database properties.

```python
import embedvec_py
import numpy as np

# Create database with E8 quantization for memory efficiency
db = embedvec_py.EmbedVec(
    dim=768,
    metric="cosine",           # "cosine", "euclidean", or "dot"
    m=32,                      # HNSW connections per layer
    ef_construction=200,       # HNSW build parameter
    quantization="e8-10bit",   # None, "e8-8bit", "e8-10bit", "e8-12bit"
    persist_path=None,         # Optional: "/tmp/embedvec.db"
)

# Add vectors (numpy array or list-of-lists)
vectors = np.random.randn(10000, 768).astype(np.float32).tolist()
payloads = [
    {"doc_id": str(i), "category": "news" if i % 2 == 0 else "blog", "score": i / 100.0}
    for i in range(10000)
]
db.add_many(vectors, payloads)

# Add single vector
db.add([0.1] * 768, {"doc_id": "special", "category": "featured"})

# Search with optional simple filter (key-value matching)
query = np.random.randn(768).astype(np.float32).tolist()
hits = db.search(
    query_vector=query,
    k=10,
    ef_search=128,
    filter={"category": "news"}  # Simple exact-match filter
)

for hit in hits:
    print(f"ID: {hit['id']}, Score: {hit['score']:.4f}, Payload: {hit['payload']}")

# Database info
print(f"Vectors: {len(db)}")
print(f"Dimension: {db.dimension}")
print(f"Metric: {db.metric}")
print(f"Memory: {db.memory_bytes() / 1024:.1f} KB")
print(f"Compression ratio: {db.compression_ratio():.1f}x")

# Clear database
db.clear()
```

--------------------------------

### Inspect EmbedVec Database State in Rust

Source: https://context7.com/weaveitmeta/embedvec/llms.txt

Shows how to use utility methods in Rust to inspect the state of an EmbedVec database, including vector count, emptiness, dimension, distance metric, and quantization details. Also demonstrates clearing the database.

```rust
use embedvec::{Distance, EmbedVec, Quantization};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut db = EmbedVec::builder()
        .dimension(768)
        .metric(Distance::Cosine)
        .quantization(Quantization::e8_default())
        .build()
        .await?;

    // Add some vectors
    for i in 0..1000 {
        let vector: Vec<f32> = (0..768).map(|j| (i + j) as f32 / 1000.0).collect();
        db.add(&vector, json!({"id": i})).await?;
    }

    // Inspect database state
    let count = db.len().await;
    let is_empty = db.is_empty().await;
    let dimension = db.dimension();
    let distance = db.distance();

    println!("Vector count: {}", count);           // 1000
    println!("Is empty: {}", is_empty);            // false
    println!("Dimension: {}", dimension);          // 768
    println!("Distance metric: {:?}", distance);   // Cosine

    // Quantization info
    let quant = db.quantization();
    println!("Quantization enabled: {}", quant.is_enabled());
    println!("Bits per dimension: {:.2}", quant.bits_per_dim());
    println!("Bytes per vector: {}", quant.bytes_per_vector(768));
    println!("Compression ratio: {:.1}x", quant.compression_ratio(768));

    // Clear all data
    db.clear().await?;
    assert!(db.is_empty().await);

    Ok(())
}
```

--------------------------------

### EmbedVec Constructor Parameters

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec-py/README.md

Defines the parameters for initializing the EmbedVec database, including vector dimension, distance metric, HNSW configuration, quantization, and persistence options.

```python
db = embedvec_py.EmbedVec(
    dim: int,                    # Vector dimension
    metric: str = "cosine",      # Distance metric
    m: int = 32,                 # HNSW M parameter
    ef_construction: int = 200,  # HNSW build parameter
    quantization: str = None,    # Quantization mode
    persist_path: str = None,    # Persistence path
)
```

--------------------------------

### EmbedVec Initialization

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec-py/README.md

Initializes a new EmbedVec database instance with specified dimensions, metrics, and HNSW parameters.

```APIDOC
## EmbedVec Constructor

### Description
Initializes the vector database instance.

### Parameters
- **dim** (int) - Required - Vector dimension.
- **metric** (str) - Optional - Distance metric: "cosine", "euclidean", or "dot". Default: "cosine".
- **m** (int) - Optional - HNSW connections per layer. Default: 32.
- **ef_construction** (int) - Optional - HNSW build parameter. Default: 200.
- **quantization** (str) - Optional - Quantization mode: "e8p-8bit", "e8p-10bit", "e8p-12bit".
- **persist_path** (str) - Optional - Path for on-disk persistence.
```

--------------------------------

### E8 Lattice Quantization Details

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Technical details on the E8 lattice quantization implementation.

```APIDOC
## E8 Lattice Quantization

embedvec implements state-of-the-art E8 lattice quantization based on QuIP#/NestQuant/QTIP research (2024-2025):

1. **Hadamard Preprocessing**: Fast Walsh-Hadamard transform + random signs makes coordinates more Gaussian/i.i.d.
2. **Block-wise Quantization**: Split vectors into 8D blocks, quantize each to nearest E8 lattice point
3. **Asymmetric Search**: Query remains FP32, database vectors decoded on-the-fly during HNSW traversal
4. **Compact Storage**: ~2-2.5 bits per dimension effective
```

--------------------------------

### Configure EmbedVec Dependencies

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Add the library to your Cargo.toml with specific features enabled.

```toml
[dependencies]
embedvec = { version = "0.5", features = ["persistence-sled", "async"] }
```

--------------------------------

### Rust Quantization Modes Configuration

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Illustrates how to configure quantization for EmbedVec, including no quantization, E8 with different bit depths and Hadamard preprocessing, and the default E8 convenience constructor.

```rust
// No quantization (full f32)
Quantization::None

// E8 with Hadamard preprocessing (recommended)
Quantization::E8 {
    bits_per_block: 10,
    use_hadamard: true,
    random_seed: 0xcafef00d,
}

// Convenience constructor
Quantization::e8_default()  // 10-bit with Hadamard
```

--------------------------------

### Basic Backend Operations

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Perform common operations such as counting vectors, deleting a specific vector, or clearing the entire backend.

```rust
// Other operations
let count = backend.count().await?;
backend.delete_vector("doc_123").await?;
backend.clear().await?;
```

--------------------------------

### Filter metadata with FilterExpr in Rust

Source: https://context7.com/weaveitmeta/embedvec/llms.txt

Demonstrates how to use FilterExpr for equality, comparison, string operations, and boolean logic when searching vectors.

```rust
use embedvec::{Distance, EmbedVec, FilterExpr};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut db = EmbedVec::new(768, Distance::Cosine, 32, 200).await?;

    // Add vectors with rich metadata
    for i in 0..1000 {
        let vector: Vec<f32> = (0..768).map(|_| rand::random::<f32>()).collect();
        db.add(&vector, json!({
            "doc_id": format!("doc_{}", i),
            "category": ["finance", "tech", "health"][i % 3],
            "timestamp": 1730000000 + i * 1000,
            "score": (i as f32) / 100.0,
            "path": format!("/api/docs/{}", i)
        })).await?;
    }

    // Equality filter
    let filter = FilterExpr::eq("category", "finance");

    // Comparison filters
    let filter = FilterExpr::gt("timestamp", 1730500000);
    let filter = FilterExpr::gte("score", 5.0);
    let filter = FilterExpr::lt("timestamp", 1731000000);
    let filter = FilterExpr::lte("score", 8.0);

    // String operations
    let filter = FilterExpr::contains("doc_id", "doc_5");
    let filter = FilterExpr::starts_with("path", "/api");
    let filter = FilterExpr::ends_with("doc_id", "_99");

    // Membership test
    let filter = FilterExpr::in_values("category", vec![
        json!("finance"),
        json!("tech")
    ]);

    // Field existence
    let filter = FilterExpr::exists("optional_field");

    // Boolean composition (AND, OR, NOT)
    let filter = FilterExpr::eq("category", "finance")
        .and(FilterExpr::gt("timestamp", 1730500000))
        .and(FilterExpr::not(FilterExpr::eq("score", 0.0)));

    let filter = FilterExpr::eq("category", "finance")
        .or(FilterExpr::eq("category", "tech"));

    // Search with filter
    let query = vec![0.5; 768];
    let results = db.search(&query, 10, 128, Some(filter)).await?;

    for hit in results {
        println!("ID: {}, Category: {}", hit.id, hit.payload["category"]);
    }

    Ok(())
}
```

--------------------------------

### Run Tests with Specific Features

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Execute tests while enabling specific features of the embedvec crate, such as 'persistence'.

```bash
# Run with specific features
cargo test --features "persistence"
```

--------------------------------

### Quantization Modes

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Overview of available quantization modes and their impact on memory and recall.

```APIDOC
## Quantization Modes

| Mode | Bits/Dim | Memory/Vector (768d) | Recall@10 |
|------|----------|----------------------|-----------|
| `None` | 32 | ~3.1 KB | 100% |
| `E8 8-bit` | ~1.0 | ~170 B | 92–97% |
| `E8 10-bit` | ~1.25 | ~220 B | 96–99% |
| `E8 12-bit` | ~1.5 | ~280 B | 98–99% |

```rust
// No quantization (full f32)
Quantization::None

// E8 with Hadamard preprocessing (recommended)
Quantization::E8 {
    bits_per_block: 10,
    use_hadamard: true,
    random_seed: 0xcafef00d,
}

// Convenience constructor
Quantization::e8_default()  // 10-bit with Hadamard
```
```

--------------------------------

### EmbedVec Builder API

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Configuration options for building an EmbedVec index.

```APIDOC
## EmbedVec Builder

```rust
EmbedVec::builder()
    .dimension(768)                    // Vector dimension (required)
    .metric(Distance::Cosine)          // Distance metric
    .m(32)                             // HNSW M parameter
    .ef_construction(200)              // HNSW build parameter
    .quantization(Quantization::None)  // Or E8 for compression
    .persistence("path/to/db")         // Optional disk persistence
    .build()
    .await?;
```
```

--------------------------------

### Perform Native Vector Search

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Execute vector similarity searches directly within PostgreSQL using the configured backend. Results include similarity scores.

```rust
// Native vector search (executed in PostgreSQL)
let results = backend.search_vectors(&query, 10, Some(128)).await?;
for (id, external_id, similarity, metadata) in results {
    println!("{}: {} (score: {:.4})", id, external_id, similarity);
}
```

--------------------------------

### Core Operations

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Key methods for interacting with the EmbedVec database.

```APIDOC
## Core Operations

| Method | Description |
|--------|-------------|
| `add(vector, payload)` | Add single vector with metadata |
| `add_many(vectors, payloads)` | Batch add vectors |
| `search(query, k, ef_search, filter)` | Find k nearest neighbors |
| `len()` | Number of vectors |
| `clear()` | Remove all vectors |
| `flush()` | Persist to disk (if enabled) |
```

--------------------------------

### Insert Vectors with Metadata

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Insert vectors into the pgvector backend, optionally including JSONB metadata for advanced querying.

```rust
// Insert vectors with JSONB metadata
backend.insert_vector(
    "doc_123", 
    &embedding, 
    Some(json!({"category": "tech", "author": "alice"}))
).await?;
```

--------------------------------

### Vector Operations

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec-py/README.md

Methods for adding vectors and performing similarity searches.

```APIDOC
## add_many(vectors, payloads)

### Description
Adds a batch of vectors and their associated metadata to the database.

### Parameters
- **vectors** (list) - Required - List of vectors to add.
- **payloads** (list) - Required - List of metadata dictionaries corresponding to the vectors.

## search(query_vector, k, ef_search, filter)

### Description
Performs a k-nearest neighbor search with optional metadata filtering.

### Parameters
- **query_vector** (list) - Required - The vector to search for.
- **k** (int) - Required - Number of nearest neighbors to return.
- **ef_search** (int) - Required - Search depth parameter.
- **filter** (dict) - Optional - Metadata filter criteria.
```

--------------------------------

### Add embedvec Dependency for pgvector

Source: https://github.com/weaveitmeta/embedvec/blob/master/embedvec/README.md

Include the embedvec crate with the 'persistence-pgvector' and 'async' features in your Cargo.toml file.

```toml
[dependencies]
embedvec = { version = "0.5", features = ["persistence-pgvector", "async"] }
```

--------------------------------

### Search Vectors in EmbedVec

Source: https://context7.com/weaveitmeta/embedvec/llms.txt

Perform approximate nearest neighbor searches with configurable ef_search parameters.

```rust
use embedvec::{Distance, EmbedVec};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut db = EmbedVec::new(768, Distance::Cosine, 32, 200).await?;

    // Add sample vectors
    for i in 0..100 {
        let vector: Vec<f32> = (0..768).map(|j| (i * j) as f32 / 1000.0).collect();
        db.add(&vector, json!({"id": i, "category": if i % 2 == 0 { "even" } else { "odd" }})).await?;
    }

    // Search for k nearest neighbors
    let query = vec![0.5; 768];
    let results = db.search(
        &query,
        10,      // k: number of results
        128,     // ef_search: higher = better recall, slower
        None     // no filter
    ).await?;

    for hit in results {
        println!(
            "ID: {}, Score: {:.4}, Payload: {:?}",
            hit.id, hit.score, hit.payload
        );
    }
    // Output:
    // ID: 50, Score: 0.0012, Payload: {"category": "even", "id": 50}
    // ID: 51, Score: 0.0015, Payload: {"category": "odd", "id": 51}
    // ...

    Ok(())
}
```

--------------------------------

### Add Vectors to EmbedVec

Source: https://context7.com/weaveitmeta/embedvec/llms.txt

Insert single or batch vectors with associated JSON metadata payloads into the database.

```rust
use embedvec::{Distance, EmbedVec};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut db = EmbedVec::new(768, Distance::Cosine, 32, 200).await?;

    // Add single vector with metadata
    let vector = vec![0.1; 768];
    let payload = json!({
        "doc_id": "doc_001",
        "category": "finance",
        "timestamp": 1737400000,
        "tags": ["quarterly", "report"]
    });
    let id = db.add(&vector, payload).await?;
    println!("Inserted vector with ID: {}", id);

    // Batch add multiple vectors
    let vectors = vec![
        vec![0.2; 768],
        vec![0.3; 768],
        vec![0.4; 768],
    ];
    let payloads = vec![
        json!({"doc_id": "doc_002", "category": "tech"}),
        json!({"doc_id": "doc_003", "category": "finance"}),
        json!({"doc_id": "doc_004", "category": "tech"}),
    ];
    db.add_many(&vectors, payloads).await?;

    println!("Database now contains {} vectors", db.len().await);
    Ok(())
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.