Rust SDK overview

use meerkat::{
    AgentFactory, Config, CreateSessionRequest, SessionService,
    SystemPromptOverride, build_persistent_service, open_realm_persistence_in,
    DeferredPromptPolicy,
};
use meerkat_core::service::InitialTurnPolicy;
use meerkat_store::RealmBackend;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Config::load().await?;
    let realms_root = std::env::current_dir()?.join(".rkat").join("realms");
    let (_manifest, persistence) = open_realm_persistence_in(
        &realms_root,
        "team-alpha",
        Some(RealmBackend::Sqlite),
        None,
    ).await?;
    let factory = AgentFactory::new(realms_root.clone()).runtime_root(realms_root);
    let service = build_persistent_service(factory, config, 64, persistence);

    let result = service.create_session(CreateSessionRequest {
        model: "claude-sonnet-4-6".into(),
        prompt: "What is the capital of France?".into(),
        system_prompt: SystemPromptOverride::Set("You are a helpful assistant.".into()),
        max_tokens: Some(1024),
        event_tx: None,
        initial_turn: InitialTurnPolicy::RunImmediately,
        deferred_prompt_policy: DeferredPromptPolicy::Discard,
        build: None,
        labels: None,
    }).await?;

    println!("Response: {}", result.text);
    println!("Session ID: {}", result.session_id);
    Ok(())
}

use meerkat::{
    CreateSessionRequest, DeferredPromptPolicy, SessionService,
    StartTurnRequest, StartTurnRuntimeSemantics, SystemPromptOverride,
};
use meerkat_core::service::InitialTurnPolicy;

// Turn 1: create session
let result = service.create_session(CreateSessionRequest {
    model: "claude-sonnet-4-6".into(),
    prompt: "My name is Alice.".into(),
    system_prompt: SystemPromptOverride::Set("You are a helpful assistant with memory.".into()),
    max_tokens: None,
    event_tx: None,
    initial_turn: InitialTurnPolicy::RunImmediately,
    deferred_prompt_policy: DeferredPromptPolicy::Discard,
    build: None,
    labels: None,
}).await?;

let session_id = result.session_id;

// Turn 2: agent remembers "Alice"
let result = service.start_turn(&session_id, StartTurnRequest {
    prompt: "What's my name?".into(),
    system_prompt: None,
    event_tx: None,
    runtime: StartTurnRuntimeSemantics::default(),
}).await?;

// Read session state
let view = service.read(&session_id).await?;
println!("Messages: {}", view.state.message_count);

// Archive when done
service.archive(&session_id).await?;

use meerkat::{
    CreateSessionRequest, DeferredPromptPolicy, SessionService,
    StartTurnRequest, StartTurnRuntimeSemantics, SystemPromptOverride,
};
use meerkat_core::service::InitialTurnPolicy;

let created = service.create_session(CreateSessionRequest {
    model: "claude-sonnet-4-6".into(),
    prompt: "Let's wait before we run.".into(),
    system_prompt: SystemPromptOverride::Set("You are the original prompt.".into()),
    max_tokens: None,
    event_tx: None,
    initial_turn: InitialTurnPolicy::Defer,
    deferred_prompt_policy: DeferredPromptPolicy::Stage,
    build: None,
    labels: None,
}).await?;

let result = service.start_turn(&created.session_id, StartTurnRequest {
    prompt: "Now run with the first-turn override.".into(),
    system_prompt: Some("You are the deferred first-turn override.".into()),
    event_tx: None,
    runtime: StartTurnRuntimeSemantics::default(),
}).await?;

use meerkat::SessionError;

match service.start_turn(&id, req).await {
    Ok(result) => println!("Response: {}", result.text),
    Err(SessionError::NotFound { id }) => println!("Session {} not found", id),
    Err(SessionError::Busy { id }) => println!("Session {} is busy, retry later", id),
    Err(e) => println!("Error: {}", e),
}

let result = agent.run("What is 2 + 2?".into()).await?;
println!("Answer: {}", result.text);

use tokio::sync::mpsc;
use meerkat::AgentEvent;

let (tx, mut rx) = mpsc::channel::<AgentEvent>(100);

tokio::spawn(async move {
    while let Some(event) = rx.recv().await {
        match event {
            AgentEvent::TextDelta { delta } => print!("{}", delta),
            AgentEvent::ToolExecutionStarted { name, .. } => {
                println!("[Calling {}...]", name);
            }
            AgentEvent::TurnCompleted { usage, .. } => {
                println!("\n[Tokens: {}]", usage.total_tokens());
            }
            _ => {}
        }
    }
});

let result = agent.run_with_events("Tell me a story".into(), tx).await?;

use meerkat::AgentError;

match agent.run("prompt".into()).await {
    Ok(result) => println!("Success: {}", result.text),
    Err(AgentError::Llm { provider, message, .. }) => {
        println!("LLM error ({}): {}", provider, message);
    }
    Err(AgentError::TokenBudgetExceeded { used, limit }) => {
        println!("Token budget exceeded: {} / {}", used, limit);
    }
    Err(e) => println!("Other error: {}", e),
}

use meerkat::{Message, UserMessage, BlockAssistantMessage, SystemMessage, ToolResult};
use meerkat_core::{ContentBlock, ImageData};

let system = Message::System(SystemMessage::new("You are helpful."));

// Text-only user message (convenience)
let user = Message::User(UserMessage::text("Hello!"));

// Multimodal user message with text and image
let user = Message::User(UserMessage::with_blocks(vec![
    ContentBlock::Text { text: "What is in this image?".to_string() },
    ContentBlock::Image {
        media_type: "image/png".to_string(),
        data: ImageData::Inline { data: base64_data },
    },
]));

use meerkat_core::ContentInput;

// Text-only (most common) — implements From<&str> and From<String>
let prompt: ContentInput = "What is Rust?".into();

// Multimodal — blocks with mixed content types
let prompt = ContentInput::Blocks(vec![
    ContentBlock::Text { text: "Describe this image.".to_string() },
    ContentBlock::Image {
        media_type: "image/jpeg".to_string(),
        data: ImageData::Inline { data: base64_data },
    },
]);

use meerkat::{ToolCall, ToolResult};

let tool_call = ToolCall {
    id: "tc_123".to_string(),
    name: "get_weather".to_string(),
    args: json!({"city": "Tokyo"}),
};

let result = ToolResult::new("tc_123".to_string(), "Sunny, 25C".to_string(), false);
let error = ToolResult::new("tc_123".to_string(), "City not found".to_string(), true);

let result: RunResult = agent.run("Hello".into()).await?;

println!("Response: {}", result.text);
println!("Session: {}", result.session_id);
println!("Tokens: {}", result.usage.total_tokens());
println!("Turns: {}", result.turns);
println!("Tool calls: {}", result.tool_calls);