Orama Core Client for Rust

A comprehensive Rust client for Orama Core and Orama Cloud.

Installation

Add this to your Cargo.toml:

[dependencies]
oramacore-client = "1.2.0"
tokio = { version = "1.0", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }

Quick Start

use oramacore_client::{
    collection::{CollectionManager, CollectionManagerConfig},
    types::{SearchParams, SearchMode},
    error::Result,
};
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Document {
    id: String,
    title: String,
    content: String,
}

#[tokio::main]
async fn main() -> Result<()> {
    // Initialize the client
    let config = CollectionManagerConfig::new("your-collection-id", "your-api-key");
    let client = CollectionManager::new(config).await?;

    // Perform a search
    let search_params = SearchParams::new("artificial intelligence")
        .with_mode(SearchMode::Hybrid)
        .with_limit(10);

    let results = client.search::<Document>(&search_params).await?;
    println!("Found {} documents", results.hits.len());

    for hit in results.hits {
        println!("- {} (score: {:.4})", hit.document.title, hit.score);
    }

    Ok(())
}

Core Concepts

Collections and Documents

Collections are containers for your documents. Each collection can have multiple indexes for different types of searches:

use oramacore_client::collection::{CollectionManager, CreateIndexParams};

// Create an index
let create_params = CreateIndexParams {
    id: Some("articles".to_string()),
    embeddings: Some(serde_json::json!("automatic")),
};

client.index.create(create_params).await?;

// Insert documents
let index = client.index.set("articles".to_string());
index.insert_documents(documents).await?;

Search Modes

The client supports three search modes:

• Fulltext: Traditional keyword-based search
• Vector: Semantic search using embeddings
• Hybrid: Combines both approaches for best results

use oramacore_client::types::{SearchParams, SearchMode};

// Vector search for semantic similarity
let vector_search = SearchParams::new("machine learning concepts")
    .with_mode(SearchMode::Vector)
    .with_limit(5);

// Hybrid search for comprehensive results
let hybrid_search = SearchParams::new("deep learning")
    .with_mode(SearchMode::Hybrid)
    .with_threshold(0.8);

AI-Powered Features

Create AI sessions for natural language interactions:

use oramacore_client::stream_manager::{AnswerConfig, CreateAiSessionConfig};
use oramacore_client::types::{LlmConfig, LlmProvider};

// Create an AI session
let session_config = CreateAiSessionConfig::new()
    .with_llm_config(LlmConfig {
        provider: LlmProvider::OpenAI,
        model: "gpt-4".to_string(),
    });

let ai_session = client.ai.create_ai_session().await?;

// Get an AI-powered answer
let answer_config = AnswerConfig::new("Explain quantum computing")
    .with_max_documents(5);

let answer = ai_session.answer(answer_config).await?;
println!("AI Response: {}", answer);

Streaming Responses

For real-time AI interactions, use streaming:

use futures::StreamExt;

let stream_config = AnswerConfig::new("What is the future of AI?");
let mut answer_stream = ai_session.answer_stream(stream_config).await?;

while let Some(chunk_result) = answer_stream.next().await {
    match chunk_result {
        Ok(chunk) => print!("{}", chunk),
        Err(e) => eprintln!("Stream error: {}", e),
    }
}

Authentication

The client supports two authentication methods:

API Key Authentication

For regular API keys:

let config = CollectionManagerConfig::new("collection-id", "your-api-key");

JWT Authentication

For private API keys (starting with "p_"):

let config = CollectionManagerConfig::new("collection-id", "p_your-private-key")
    .with_auth_jwt_url("https://your-auth-endpoint.com");

Cloud Integration

For Orama Cloud projects:

use oramacore_client::cloud::{OramaCloud, ProjectManagerConfig, CloudSearchParams};

let cloud_config = ProjectManagerConfig::new("project-id", "api-key");
let cloud_client = OramaCloud::new(cloud_config).await?;

// Cloud-specific search with datasources
let search_params = CloudSearchParams::new(
    "search query",
    vec!["datasource1".to_string(), "datasource2".to_string()]
);

let results = cloud_client.search::<Document>(&search_params).await?;

Collection Management

Create and manage collections programmatically:

use oramacore_client::manager::{OramaCoreManager, CreateCollectionParams};
use oramacore_client::types::{Language, EmbeddingsModel};

let manager_config = OramaCoreManagerConfig {
    url: "https://api.orama.com".to_string(),
    master_api_key: "your-master-key".to_string(),
};

let manager = OramaCoreManager::new(manager_config).await?;

// Create a new collection
let collection_params = CreateCollectionParams::new("my-collection")
    .with_description("My new collection")
    .with_language(Language::English)
    .with_embeddings_model(EmbeddingsModel::BgeBase);

let new_collection = manager.collection.create(collection_params).await?;

Advanced Features

System Prompts

Manage AI system prompts:

// Get all system prompts
let prompts = client.system_prompts.get_all().await?;

// Get a specific prompt
let prompt = client.system_prompts.get("prompt-id").await?;

Tools Integration

Execute custom tools:

use oramacore_client::collection::ExecuteToolsBody;

let tools_body = ExecuteToolsBody {
    tool_ids: Some(vec!["tool1".to_string()]),
    messages: vec![/* your messages */],
    llm_config: None,
};

let result = client.tools.execute::<serde_json::Value>(tools_body).await?;

Hooks Management

Manage collection hooks:

use oramacore_client::collection::AddHookConfig;
use oramacore_client::types::Hook;

let hook_config = AddHookConfig {
    name: Hook::BeforeInsert,
    code: "// Your hook code".to_string(),
};

let hook_response = client.hooks.insert(hook_config).await?;

Examples

The repository includes comprehensive examples:

• basic_search.rs - Simple search operations
• document_management.rs - CRUD operations
• ai_session.rs - AI-powered features and streaming
• server_app.rs - Complete application example

Run an example:

cargo run --example basic_search

Error Handling

The client provides detailed error types:

use oramacore_client::error::{OramaError, Result};

match client.search(&params).await {
    Ok(results) => println!("Found {} results", results.hits.len()),
    Err(OramaError::Auth(msg)) => eprintln!("Authentication error: {}", msg),
    Err(OramaError::Api { status, message }) => {
        eprintln!("API error {}: {}", status, message);
    }
    Err(e) => eprintln!("Other error: {}", e),
}

Configuration

Environment Variables

You can configure the client using environment variables:

export ORAMA_MASTER_API_KEY="your-master-key"
export ORAMA_PROJECT_ID="your-project-id"
export ORAMA_COLLECTION_API_KEY="your-collection-key"

Custom Cluster Configuration

For custom deployments:

use oramacore_client::collection::ClusterConfig;

let config = CollectionManagerConfig::new("collection-id", "api-key")
    .with_cluster(
        ClusterConfig::new()
            .with_read_url("https://your-reader.com")
            .with_writer_url("https://your-writer.com")
    );

Performance

The client is designed for high-performance applications:

• Connection Pooling: Reuses HTTP connections
• Async Operations: Non-blocking I/O with Tokio
• Concurrent Requests: Execute multiple operations simultaneously
• Streaming: Real-time data processing
• Type Safety: Zero-cost abstractions with compile-time guarantees

Testing

Run the test suite:

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_search_operations

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to the main repository.

Support

• Documentation: docs.rs/oramacore-client
• Issues: GitHub Issues
• Orama Documentation: docs.orama.com