traitclaw 1.0.0

Build AI agents in Rust with 5 lines of code. TraitClaw provides type-safe tools, streaming responses, persistent memory, multi-agent teams, reasoning strategies, and MCP integration — all with zero-cost abstractions and no garbage collector.

use traitclaw::prelude::*;
use traitclaw_openai_compat::OpenAiCompatProvider;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let agent = Agent::builder()
        .provider(OpenAiCompatProvider::openai("gpt-4o-mini", api_key))
        .system("You are a helpful assistant")
        .build()?;

    let output = agent.run("Hello!").await?;
    println!("{}", output.text());
    Ok(())
}

Why TraitClaw?

• 🧩 Composable Trait Architecture — 8 core traits (Provider, Tool, Memory, Guard, Hint, Tracker, ContextManager, OutputTransformer) compose into any agent topology
• 🔧 Type-Safe Tool Calling — #[derive(Tool)] generates JSON schemas from Rust structs at compile time
• 🧠 Multi-Strategy Reasoning — Built-in ReAct, Chain-of-Thought, and MCTS strategies via AgentStrategy trait
• 👥 Multi-Agent Teams — Teams, routers, delegation, and verification chains out of the box
• 🔌 MCP Integration — Native Model Context Protocol client for tool discovery
• 📡 First-Class Streaming — async Stream with typed events, not string concatenation
• 🔒 Production Observability — tracing integration for structured logging and OpenTelemetry
• 🦀 Zero-Cost Abstractions — No GC, no runtime, single static binary

Quick Start

cargo add traitclaw traitclaw-openai-compat tokio anyhow

Feature Matrix

Features

🔧 Type-Safe Tool Calling

#[derive(Tool)]
#[tool(description = "Search the web")]
struct WebSearch { query: String }

🎯 Structured Output

#[derive(Deserialize, JsonSchema)]
struct Review { title: String, rating: u8 }

let review: Review = agent.run_structured("Review Inception").await?;

📡 Real-Time Streaming

let mut stream = agent.stream("Tell me a story");
while let Some(Ok(StreamEvent::TextDelta(text))) = stream.next().await {
    print!("{text}");
}

🛡️ Steering — Guards, Hints & Trackers

use traitclaw_steering::Steering;
let steering = Steering::auto(); // One-liner: guards + hints + tracking

💾 Persistent Memory

use traitclaw_memory_sqlite::SqliteMemory;
let memory = SqliteMemory::new("./agent.db")?;

👥 Multi-Agent Teams

use traitclaw_team::{Team, AgentRole};
let team = Team::new("research")
    .add_role(AgentRole::new("researcher", "Research topics"))
    .add_role(AgentRole::new("writer", "Write summaries"));

🔌 MCP Integration

use traitclaw_mcp::McpServer;
let server = McpServer::stdio("npx", &["-y", "@mcp/server-filesystem", "."]).await?;

🧠 Reasoning Strategies

use traitclaw_strategies::ReActStrategy;
let strategy = ReActStrategy::builder().max_steps(10).build();

🏗️ Architecture Overview

TraitClaw follows a layered trait architecture:

┌─────────────────────────────────────────────────────────┐
│                    traitclaw (meta-crate)                │
│  Re-exports everything. One dependency, full power.     │
├─────────────────────────────────────────────────────────┤
│  Extension Crates                                       │
│  ┌──────────┐ ┌──────────┐ ┌───────┐ ┌──────┐         │
│  │ steering │ │ sqlite   │ │ mcp   │ │ team │ ...     │
│  └──────────┘ └──────────┘ └───────┘ └──────┘         │
├─────────────────────────────────────────────────────────┤
│  Provider Crates                                        │
│  ┌──────────────┐ ┌────────────┐ ┌──────────────────┐  │
│  │ openai-compat│ │ anthropic  │ │ openai (native)  │  │
│  └──────────────┘ └────────────┘ └──────────────────┘  │
├─────────────────────────────────────────────────────────┤
│  traitclaw-core (foundation)                            │
│  Agent · Provider · Tool · Memory · Guard · Hint ·      │
│  Tracker · ContextManager · OutputTransformer ·          │
│  ExecutionStrategy · AgentStrategy · AgentHook           │
└─────────────────────────────────────────────────────────┘

The Agent Loop

1. Context Hydration — Retrieve past dialogue from Memory, append user prompt
2. Provider Generation — LLM evaluates context, returns text or tool call
3. Tool Resolution — Parse arguments, execute Rust function, append result
4. Recursive Reasoning — Repeat steps 2–3 until task is complete
5. Memory Commit — Save final trajectory back to Memory

⚙️ Feature Flags

[dependencies]
traitclaw = { version = "1.0", features = ["full"] }

📦 Crate Ecosystem

📚 Examples

cd examples/01-hello-agent && cargo run

🔒 Stability Policies

Semantic Versioning

TraitClaw follows Semantic Versioning 2.0.0:

MSRV (Minimum Supported Rust Version)

• Current: Rust 1.75
• Bumped only in minor releases, never in patches
• Always documented in CHANGELOG.md
• Maintains a minimum 6-month lag from the latest Rust stable release

Deprecation Policy

• Deprecated items are marked with #[deprecated(since = "1.x", note = "Use Y instead")]
• Items remain available for a minimum of 2 minor versions after deprecation
• Deprecated items are removed only in the next major version (v2.0.0)

🗺️ Roadmap

License

Licensed under either of Apache License, Version 2.0 or MIT License at your option.