ContextLite Rust Client

A high-performance, async Rust client for ContextLite - the ultra-fast context engine for retrieval and AI applications.

Quick Start

Add this to your Cargo.toml:

[dependencies]
contextlite-client = "1.0"

Basic usage:

use contextlite_client::{ContextLiteClient, ClientConfig, Document, SearchQuery};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a client with default configuration
    let client = ContextLiteClient::new()?;
    
    // Add a document
    let document = Document::new("example.txt", "This is an example document");
    let doc_id = client.add_document(&document).await?;
    
    // Search for documents
    let query = SearchQuery::new("example").with_limit(10);
    let results = client.search(&query).await?;
    
    println!("Found {} documents", results.documents.len());
    
    Ok(())
}

Features

• High Performance: Built on Tokio for blazing-fast async operations
• Type Safety: Comprehensive type definitions with builder patterns
• Connection Pooling: HTTP connection pooling for optimal performance
• Error Handling: Rich error types with proper error chaining
• Authentication: Bearer token authentication support
• Validation: Client-side validation for better error messages
• Flexible API: Builder patterns for easy configuration

Supported Operations

✓ Health Checks - Server status and SMT solver information
✓ Document Management - Add, search, and delete documents
✓ Context Assembly - SMT-optimized context compilation
✓ Authentication - Bearer token security
✓ Error Handling - Comprehensive error types and retry logic

Example Usage

Document Operations

use contextlite_client::{Document, ContextLiteClient};

let client = ContextLiteClient::new()?;

// Add a document with metadata
let document = Document::new("tutorial.md", "Rust programming tutorial")
    .with_metadata(serde_json::json!({
        "type": "tutorial",
        "language": "rust",
        "difficulty": "beginner"
    }));

let doc_id = client.add_document(&document).await?;

// Update the document
let updated_doc = Document::new("tutorial.md", "Updated Rust programming tutorial");
client.update_document(&doc_id, &updated_doc).await?;

// Get the document
let retrieved = client.get_document(&doc_id).await?;

// Delete the document
client.delete_document(&doc_id).await?;

Advanced Search

use contextlite_client::{SearchQuery, ContextLiteClient};

let client = ContextLiteClient::new()?;

let query = SearchQuery::new("rust programming")
    .with_limit(20)
    .with_offset(10)
    .with_filters(serde_json::json!({
        "difficulty": "beginner"
    }));

let results = client.search(&query).await?;

for doc_ref in results.documents {
    println!("{}: {:.3}", doc_ref.path, doc_ref.score.unwrap_or(0.0));
    if let Some(snippet) = doc_ref.snippet {
        println!("  \"{}\"", snippet);
    }
}

Context Assembly

use contextlite_client::{ContextRequest, ContextLiteClient};

let client = ContextLiteClient::new()?;

let request = ContextRequest::new("explain rust ownership")
    .with_budget(2000)        // Token budget
    .with_max_results(5)      // Max documents
    .with_metadata(true);     // Include metadata

let context = client.assemble_context(&request).await?;

println!("Assembled context ({} tokens):", context.token_count.unwrap_or(0));
println!("{}", context.context);

Configuration

Client Configuration

use contextlite_client::ClientConfig;

let config = ClientConfig::new("http://localhost:8083")
    .with_auth_token("your-bearer-token")
    .with_timeout(30)                      // 30 second timeout
    .with_connection_pool(true, 100);      // Enable pooling, max 100 connections

let client = ContextLiteClient::with_config(config)?;

Environment Variables

The client respects these environment variables:

• CONTEXTLITE_URL: Default server URL
• CONTEXTLITE_TOKEN: Default authentication token
• CONTEXTLITE_TIMEOUT: Default timeout in seconds

Error Handling

The client provides comprehensive error handling with detailed error messages:

use contextlite_client::{ContextLiteClient, ContextLiteError};

match client.health().await {
    Ok(health) => println!("Server is healthy: {}", health.status),
    Err(ContextLiteError::AuthError { message }) => {
        eprintln!("Authentication failed: {}", message);
    },
    Err(ContextLiteError::ServerError { status, message }) => {
        eprintln!("Server error {}: {}", status, message);
    },
    Err(ContextLiteError::TimeoutError { seconds }) => {
        eprintln!("Request timed out after {} seconds", seconds);
    },
    Err(err) => eprintln!("Error: {}", err),
}

Installation

Install ContextLite server:

# Via Cargo
cargo install contextlite

# Via Homebrew (macOS/Linux)
brew install contextlite

# Via npm
npm install -g contextlite

# Via Python pip
pip install contextlite

Then add the client to your project:

cargo add contextlite-client

Documentation

• Website: contextlite.com
• API Docs: docs.rs/contextlite-client
• GitHub: github.com/Michael-A-Kuykendall/contextlite
• Examples: Check the examples/ directory in the repository

Testing

Run the tests (requires a running ContextLite server):

# Start ContextLite server on port 8083
contextlite server --port 8083

# Run tests
cargo test

Performance

The Rust client is designed for high performance:

• Connection Pooling: Reuses HTTP connections for better throughput
• Async I/O: Non-blocking operations using Tokio
• Zero-Copy: Minimal data copying where possible
• Efficient Serialization: Fast JSON processing with serde

License

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

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for your changes
4. Ensure all tests pass
5. Submit a pull request

Built with care by the ContextLite Team