llmrix-rust-sdk

Official Rust SDK for llmrix — AI Agent Platform.

• Rust 1.75+ (MSRV)
• Async/await with tokio runtime
• SSE streaming via reqwest + futures-util
• Fully typed with serde serialization
• thiserror-based error hierarchy

Installation

Add to your Cargo.toml:

[dependencies]
llmrix-rust-sdk = "1.0"
tokio = { version = "1", features = ["full"] }

Quick Start

use llmrix_sdk::{
    LlmrixClient,
    model::ConversationCreateRequest,
    streaming::event::StreamEvent,
};

#[tokio::main]
async fn main() -> llmrix_sdk::error::Result<()> {
    // 1. Build the client (cheap to clone — shares the connection pool)
    let client = LlmrixClient::builder()
        .base_url("https://www.llmrix.com")
        .api_key("sk-xxx")
        .build()?;

    // 2. Create a conversation
    let conv = client
        .conversations()
        .create(ConversationCreateRequest {
            title: "My Chat".into(),
            agent_id: None,
        })
        .await?;

    // 3. Stream a chat turn
    client
        .chat(&conv.id)
        .send("Hello, llmrix!", |event| {
            if let StreamEvent::MessageChunk(e) = event {
                print!("{}", e.content);
            }
            Ok(())
        })
        .await?;

    Ok(())
}

API Reference

LlmrixClient

LlmrixClient::builder()
    .base_url("https://www.llmrix.com")   // required
    .api_key("sk-xxx")                    // optional
    .timeout(std::time::Duration::from_secs(60)) // optional, default 60 s
    .build()?

LlmrixClient is Clone and cheap to clone — the inner reqwest::Client shares its connection pool across all clones.

ConversationsResource

Obtained via client.conversations().

Cursor pagination:

let mut page = client.conversations().list(0, 20).await?;
while page.has_more {
    let last = page.items.last().unwrap();
    page = client.conversations().list(last.seq, 20).await?;
}

ChatResource

Obtained via client.chat(conv_id).

Stream handler

type StreamHandler = impl FnMut(StreamEvent) -> Result<()>;

Returning Err(...) from the handler aborts the stream.

Stream Event Types

use llmrix_sdk::streaming::event::StreamEvent;

client.chat(&conv.id).send("Search for cats", |event| {
    match event {
        StreamEvent::MessageChunk(e) => print!("{}", e.content),
        StreamEvent::ToolStart(e) => println!("\n[tool] {}", e.name),
        StreamEvent::HitlInterrupt(e) => {
            // submit decision...
        }
        StreamEvent::RunEnd(_) => {}
        StreamEvent::Error(e) => eprintln!("error: {}", e.message),
        _ => {}
    }
    Ok(())
}).await?;

Error Handling

use llmrix_sdk::error::{LlmrixError, Result};

match client.conversations().get("bad-id").await {
    Err(LlmrixError::Api { status, body }) => {
        eprintln!("HTTP {}: {}", status, body);
    }
    Err(LlmrixError::Auth { status, body }) => {
        eprintln!("Auth failed ({}): {}", status, body);
    }
    Err(e) => eprintln!("SDK error: {}", e),
    Ok(conv) => println!("Got: {}", conv.id),
}

Advanced Usage

HITL (Human-in-the-Loop)

use llmrix_sdk::model::HitlDecision;

let chat = client.chat(&conv.id);
chat.send("Delete old backups", |event| {
    if let StreamEvent::HitlInterrupt(e) = event {
        println!("Approve '{}'? (y/n)", e.action_name);
        let mut ans = String::new();
        std::io::stdin().read_line(&mut ans).unwrap();
        let decision = if ans.trim() == "y" {
            HitlDecision::approve()
        } else {
            HitlDecision::reject("user declined")
        };
        // Note: use tokio::task::block_in_place or restructure as needed
        // for true async decide
        println!("Decision recorded: {:?}", decision);
    }
    Ok(())
}).await?;

Collecting the full response

async fn run_to_completion(
    client: &LlmrixClient,
    conv_id: &str,
    message: &str,
) -> Result<String> {
    let mut output = String::new();
    client.chat(conv_id).send(message, |event| {
        if let StreamEvent::MessageChunk(e) = event {
            output.push_str(&e.content);
        }
        Ok(())
    }).await?;
    Ok(output)
}

Building from Source

git clone https://github.com/llmrix/llmrix-rust-sdk.git
cd llmrix-rust-sdk
cargo build
cargo test

Generate documentation:

cargo doc --open

Contributing

Contributions are welcome! Please read CONTRIBUTING.md first.

License

Apache License 2.0 — see the LICENSE file.