Rice Rust SDK

Rust SDK for Rice - Unified Storage and State Management.

Installation

Add the following to your Cargo.toml:

[dependencies]
rice = { package = "rice-sdk", version = "0.1.4" }
tokio = { version = "1.0", features = ["full"] }

Quick Start

The SDK provides a unified Client to access both Storage and State services.

use rice::{Client, RiceConfig};
use rice::rice_state::proto::Trace;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load config from rice.config.toml/json/yaml and env vars
    let config = RiceConfig::new()?;
    let mut client = Client::new(config).await?;

    // --- Storage ---
    if let Some(mut storage) = client.storage {
        // Insert data
        storage.insert(
            1, // ID (u64)
            "Information stored in Rice".to_string(), // Text
            vec![], // Metadata (bytes)
            1, // User ID
            None // Session ID
        ).await?;

        // Search
        let results = storage.search(
            "information".to_string(),
            1, // User ID
            5, // K (limit)
            None, // Session ID
            None // Filter
        ).await?;
        println!("Results: {:?}", results);
    }

    // --- State (AI Agent Memory) ---
    if let Some(mut state) = client.state {
        let run_id = "my-agent-run".to_string();

        // Focus on a context/task
        state.focus("User asking about Rust".to_string(), run_id.clone()).await?;

        // Store a long-term memory (commit)
        let trace = Trace {
            input: "User question".to_string(),
            outcome: "Answer provided".to_string(),
            action: "reply".to_string(),
            agent_id: "assistant".to_string(),
            reasoning: "Provided examples".to_string(),
            embedding: vec![],
            run_id: run_id.clone(),
        };
        state.commit(trace).await?;

        // Recall relevant memories
        let memories = state.reminisce(
            vec![], // Query embedding (empty if using text)
            5,      // Limit
            "Rust questions".to_string(), // Query text
            run_id
        ).await?;
        println!("Memories: {:?}", memories);
    }

    Ok(())
}

Configuration

The SDK uses the config crate to load settings from rice.config.{toml,json,yaml} files and environment variables.

1. Configuration File (rice.config.toml)

Control which services are enabled.

[storage]
enabled = true

[state]
enabled = true

2. Environment Variables (.env)

Configure connection details and authentication.

# --- Storage ---
# URL of your Storage instance (default: localhost:50051)
# Supports both gRPC and HTTP (auto-detected)
STORAGE_INSTANCE_URL=http://localhost:50051
# Auth token
STORAGE_AUTH_TOKEN=my-secret-token
# User for auto-login
STORAGE_USER=admin

# --- State ---
# URL of your State instance
STATE_INSTANCE_URL=http://localhost:50051
# Auth token
STATE_AUTH_TOKEN=my-secret-token

State Features

The State service provides comprehensive AI agent memory and cognition capabilities.

Core Memory Operations

// Focus - Store in short-term working memory
state.focus("Context".to_string(), run_id.clone()).await?;

// Drift - Read current working memory
let items = state.drift(run_id.clone()).await?;

// Commit - Store in long-term episodic memory
state.commit(Trace { /* ... */ }).await?;

// Reminisce - Recall relevant memories
let memories = state.reminisce(vec![], 5, "query".to_string(), run_id.clone()).await?;

Working Memory (Structured Variables)

Store and manage structured state variables.

// Set variable (value must be a JSON string)
state.set_variable(
    run_id.clone(),
    "user_name".to_string(),
    serde_json::json!("Alice").to_string(),
    "explicit".to_string()
).await?;

// Get variable
let var = state.get_variable(run_id.clone(), "user_name".to_string()).await?;

// List variables
let all_vars = state.list_variables(run_id.clone()).await?;

// Delete variable
state.delete_variable(run_id.clone(), "user_name".to_string()).await?;

Goals

Manage hierarchical goals.

// Add a goal
let goal = state.add_goal(
    run_id.clone(),
    "Complete project".to_string(),
    "high".to_string(), // priority
    None // parent_id
).await?;

// Update goal status
state.update_goal(run_id.clone(), goal.id, "achieved".to_string()).await?;

// List goals
let goals = state.list_goals(run_id.clone(), None).await?;

Concepts

Define structured concepts (Level 4 Agency).

let schema = serde_json::json!({
    "type": "object",
    "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" }
    }
});

state.define_concept(
    run_id.clone(),
    "User".to_string(),
    schema.to_string()
).await?;

let concepts = state.list_concepts(run_id.clone()).await?;

Actions & Decision Cycles

Track actions and run decision loops.

// Submit an action
state.submit_action(
    run_id.clone(),
    "agent-1".to_string(),
    "reason".to_string(),
    serde_json::json!({"thought": "analyzing"}).to_string()
).await?;

// Run decision cycle
let candidates = vec![/* ActionCandidate ... */];
let result = state.run_cycle(
    run_id.clone(),
    "agent-1".to_string(),
    candidates
).await?;

Pub/Sub (Real-time Events)

Subscribe to real-time events from the State service, such as variable updates or memory commits. This is useful for multi-agent coordination.

// Subscribe to variable updates
let mut stream = state.subscribe(
    run_id.clone(),
    vec!["VariableUpdate".to_string()]
).await?;

while let Some(event) = stream.message().await? {
    println!("Received event: {:?}", event);
    if event.r#type == "VariableUpdate" {
        // Handle update
    }
}

AI Tool Definitions

The SDK provides pre-built tool definitions (JSON schemas) for integration with LLMs.

use rice::rice_tools::{openai, anthropic};

// Get OpenAI-compatible function definitions
let tools = openai::state_tools();

// Get Anthropic-compatible tool definitions
let tools = anthropic::state_tools();

License

Proprietary. All Rights Reserved.