ZeroEntropy Rust SDK

Rust client library for the ZeroEntropy API - a powerful semantic search and document retrieval service.

Features

This library provides a complete implementation of all ZeroEntropy API endpoints. It uses strong typing with comprehensive error handling and is built on Tokio for async operations. The client includes configurable retry logic with exponential backoff and provides an ergonomic API with builder patterns.

Installation

Add this to your Cargo.toml:

[dependencies]
zeroentropy-community = "0.1.1"
tokio = { version = "1.0", features = ["full"] }

Quick Start

use zeroentropy_community::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client from ZEROENTROPY_API_KEY environment variable
    let client = Client::from_env()?;

    // Create a collection
    client.collections().add("my_collection").await?;

    // Add a document
    client.documents().add_text(
        "my_collection",
        "doc1.txt",
        "Rust is a systems programming language.",
        None,
    ).await?;

    // Search documents
    let results = client.queries().top_snippets(
        "my_collection",
        "systems programming",
        10,
        None,
        None,
        None,
        None,
    ).await?;

    for result in results.results {
        println!("{}: {}", result.path, result.content);
    }

    Ok(())
}

Configuration

Environment Variables

• ZEROENTROPY_API_KEY - Your API key (required)
• ZEROENTROPY_BASE_URL - Custom API base URL (optional)

Client Builder

For advanced configuration, use the client builder:

use zeroentropy_community::Client;
use std::time::Duration;

let client = Client::builder()
    .api_key("your-api-key")
    .timeout(Duration::from_secs(30))
    .max_retries(3)
    .build()?;

Usage Examples

Collections

// Create a collection
client.collections().add("my_collection").await?;

// List all collections
let collections = client.collections().get_list().await?;
for name in collections.collection_names {
    println!("Collection: {}", name);
}

// Delete a collection
client.collections().delete("my_collection").await?;

Documents

Adding Text Documents

client.documents().add_text(
    "my_collection",
    "document.txt",
    "Your document text here",
    None,
).await?;

Adding Documents with Metadata

use std::collections::HashMap;
use zeroentropy_community::MetadataValue;

let mut metadata = HashMap::new();
metadata.insert(
    "category".to_string(),
    MetadataValue::String("tutorial".to_string()),
);

client.documents().add_text(
    "my_collection",
    "tutorial.txt",
    "Tutorial content",
    Some(metadata),
).await?;

Adding PDF Documents

// From base64 encoded data
client.documents().add_pdf(
    "my_collection",
    "document.pdf",
    base64_pdf_data,
    None,
).await?;

// Directly from file
client.documents().add_pdf_file(
    "my_collection",
    "document.pdf",
    "/path/to/file.pdf",
    None,
).await?;

Managing Documents

// Get document info
let info = client.documents().get_info(
    "my_collection",
    "document.txt",
    Some(true), // include content
).await?;

// Update document metadata
client.documents().update(
    "my_collection",
    "document.txt",
    Some(new_metadata),
    None,
).await?;

// Delete document
client.documents().delete(
    "my_collection",
    "document.txt",
).await?;

Queries

Top Documents

let results = client.queries().top_documents(
    "my_collection",
    "your search query",
    10, // number of results
    None, // filter
    Some(true), // include metadata
    None, // latency mode
    None, // reranker
).await?;

for doc in results.results {
    println!("{}: score {}", doc.path, doc.score);
}

Top Snippets

let results = client.queries().top_snippets(
    "my_collection",
    "your search query",
    10,
    None, // filter
    Some(true), // include document metadata
    Some(true), // precise responses (longer snippets)
    None, // reranker
).await?;

for snippet in results.results {
    println!("{}:\n{}\n", snippet.path, snippet.content);
}

Top Pages

let results = client.queries().top_pages(
    "my_collection",
    "your search query",
    10,
    None, // filter
    Some(true), // include content
    None, // latency mode
).await?;

for page in results.results {
    println!("Page {} of {}", page.page_index, page.path);
}

Filtering

Use metadata filters to narrow down search results:

use serde_json::json;

let filter = json!({
    "category": { "$eq": "tutorial" }
}).as_object().unwrap().clone();

let results = client.queries().top_snippets(
    "my_collection",
    "search query",
    10,
    Some(filter),
    None,
    None,
    None,
).await?;

Reranking

Improve search result quality with reranking:

use zeroentropy_community::RerankDocument;

let documents = vec![
    RerankDocument {
        id: "doc1".to_string(),
        text: "First document text".to_string(),
    },
    RerankDocument {
        id: "doc2".to_string(),
        text: "Second document text".to_string(),
    },
];

let results = client.models().rerank(
    "your query",
    documents,
    None, // model_id (uses default)
    Some(5), // top_k
).await?;

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

Error Handling

The SDK provides specific error types for different failure scenarios:

use zeroentropy_community::Error;

match client.collections().add("my_collection").await {
    Ok(_) => println!("Success!"),
    Err(Error::Conflict(msg)) => println!("Already exists: {}", msg),
    Err(Error::NotFound(msg)) => println!("Not found: {}", msg),
    Err(Error::AuthenticationError(msg)) => println!("Auth failed: {}", msg),
    Err(Error::RateLimitExceeded(msg)) => println!("Rate limited: {}", msg),
    Err(e) => println!("Error: {}", e),
}

Examples

Check out the examples directory for more complete examples:

• basic.rs - Complete workflow from collection creation to search
• arxiv_search.rs - Download and search arXiv papers with PDF support

Run an example:

export ZEROENTROPY_API_KEY="your-api-key"
cargo run --example basic
cargo run --example arxiv_search

API Documentation

For detailed API documentation, visit:

• ZeroEntropy API Docs
• Rust SDK Docs

Development

Building

cargo build

Running Tests

cargo test

Running Examples

export ZEROENTROPY_API_KEY="your-api-key"
cargo run --example basic

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

Support

• Documentation: docs.zeroentropy.dev
• Email: founders@zeroentropy.dev
• Issues: GitHub Issues

Related Projects

• Python SDK
• ZeroEntropy Cookbook