brainwires

Unified facade crate for the Brainwires Agent Framework — build any AI application in Rust.

Overview

brainwires is the single entry point for the entire framework. It re-exports 19 sub-crates as feature-gated modules and provides a prelude that pulls in the most commonly needed types. Add one dependency, enable the features you need, and you're ready to go.

brainwires-core (messages, tools, providers, tasks, errors) is always available — no feature flag required. Everything else is opt-in.

                             ┌─────────────┐
                             │  brainwires │  (facade)
                             └──────┬──────┘
           ┌──────────┬─────────┬───┴───┬─────────┬─────────┐
           │          │         │       │         │         │
    ┌──────▼──┐ ┌─────▼───┐ ┌───▼───┐ ┌─▼────┐ ┌──▼───┐ ┌───▼────┐
    │  core   │ │ tooling │ │ agents│ │ mcp  │ │ mdap │ │storage │
    │ (always)│ │         │ │       │ │      │ │      │ │        │
    └─────────┘ └─────────┘ └───────┘ └──────┘ └──────┘ └────────┘
           ┌──────────┬─────────┬───────┬─────────┬─────────┐
           │          │         │       │         │         │
    ┌──────▼──┐ ┌─────▼───┐ ┌───▼───┐ ┌─▼────┐ ┌──▼───┐ ┌───▼────┐
    │prompting│ │permiss- │ │  rag  │ │seal  │ │relay │ │provid- │
    │         │ │  ions   │ │       │ │      │ │      │ │  ers   │
    └─────────┘ └─────────┘ └───────┘ └──────┘ └──────┘ └────────┘
           ┌──────────┬─────────┬───────┬─────────┐
           │          │         │       │         │
    ┌──────▼──┐ ┌─────▼───┐ ┌───▼───┐ ┌─▼────┐ ┌──▼───┐
    │ skills  │ │  eval   │ │ proxy │ │ a2a  │ │ mesh │
    └─────────┘ └─────────┘ └───────┘ └──────┘ └──────┘

Quick Start

Add to your Cargo.toml:

[dependencies]
brainwires = "0.11"  # default features: tools + agents

Then import via the prelude:

use brainwires::prelude::*;

let messages = vec![
    Message::system("You are a helpful assistant."),
    Message::user("Hello!"),
];

let options = ChatOptions::deterministic(1024);
let response = provider.chat(&messages, None, &options).await?;

Features

Source of truth: Cargo.toml. Listed in rough capability order.

Local PEFT (LoRA / QLoRA / DoRA via Burn) and training-from-scratch live in the sibling rullama workspace as rullama-finetune and rullama-training. They had training-local / training-full facade features prior to v0.11 — depend on the rullama crates directly now.

Recommended profile

If you're unsure which features to pick, start with:

[dependencies]
brainwires = { version = "0.11", features = ["agent-full", "reasoning", "providers"] }

That gives you the full agent runtime (communication hub, validation loop, task manager), capability-based permissions, prompt generation, the reasoning scorers and strategy selector, and the Anthropic / OpenAI / Google / Ollama providers — the smallest feature set that ships a complete chat-agent app. Add storage + rag when you need persistence, mcp or a2a when you need interop, and seal + knowledge when you want self-improving behavior.

Convenience Features

Prelude

use brainwires::prelude::* brings in the most commonly needed types, grouped by subsystem:

Core (always available): Message, Role, ContentBlock, ChatResponse, StreamChunk, Usage, Tool, ToolUse, ToolResult, ToolContext, ToolInputSchema, Provider, ChatOptions, Task, TaskStatus, TaskPriority, PlanMetadata, PlanStatus, PermissionMode, EntityType, EdgeType, GraphNode, GraphEdge, EmbeddingProvider, VectorStore, WorkingSet, FrameworkError, FrameworkResult

Tools (tools feature): BashTool, FileOpsTool, GitTool, SearchTool, WebTool, ValidationTool, ToolRegistry, ToolCategory, ToolErrorCategory, RetryStrategy

Agents (agents feature): AgentRuntime, AgentExecutionResult, run_agent_loop, CommunicationHub, FileLockManager, TaskManager, TaskQueue, ValidationConfig, AccessControlManager, GitCoordinator, PlanExecutorAgent

Storage (storage feature): CachedEmbeddingProvider

Memory (memory feature): TieredMemory (re-exported from brainwires-memory)

MCP (mcp feature): McpClient, McpConfigManager, McpServerConfig

MDAP (mdap feature): Composer, MdapEstimate, MicroagentConfig, FirstToAheadByKVoter

Knowledge (knowledge feature): BehavioralKnowledgeCache, PersonalKnowledgeCache, BehavioralTruth, TruthCategory

Prompting (prompting feature): PromptGenerator, PromptingTechnique, TechniqueLibrary, TemperatureOptimizer, TaskClusterManager

Permissions (permissions feature): AgentCapabilities, PolicyEngine, TrustLevel, TrustManager, AuditLogger, PermissionsConfig

Usage Examples

Agent Workflow

[dependencies]
brainwires = { version = "0.11", features = ["agent-full"] }

use brainwires::prelude::*;

// Set up the agent runtime
let hub = CommunicationHub::new();
let lock_manager = FileLockManager::new();
let runtime = AgentRuntime::new(hub, lock_manager);

// Define validation checks
let validation = ValidationConfig {
    checks: vec![ValidationCheck::FileExistence, ValidationCheck::Syntax],
    working_directory: "/my/project".into(),
    max_retries: 3,
    enabled: true,
    working_set_files: vec![],
};

MCP Server with RAG

[dependencies]
brainwires = { version = "0.11", features = ["rag", "mcp-server"] }

use brainwires::rag::mcp_server::RagMcpServer;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    tracing_subscriber::fmt::init();
    RagMcpServer::serve_stdio().await?;
    Ok(())
}

RAG Pipeline

[dependencies]
brainwires = { version = "0.11", features = ["rag"] }

use brainwires::rag::RagClient;

let client = RagClient::new(None).await?;
client.index("/path/to/project", None, None).await?;

let results = client.query("authentication logic", 10, 0.7).await?;
for result in results {
    println!("{}: {:.2}", result.file_path, result.score);
}

Learning System

[dependencies]
brainwires = { version = "0.11", features = ["learning"] }

use brainwires::prelude::*;

let cache = BehavioralKnowledgeCache::new();
let truth = BehavioralTruth::new("always_use_async", TruthCategory::Pattern);
cache.store(truth);

License

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