<div align="center">
<p align="center">
<img src=".github/batuta-hero.svg" alt="batuta" width="800">
</p>
<h1 align="center">batuta</h1>
<p align="center">
<b>Sovereign AI orchestration — autonomous agents, ML serving, code analysis, and transpilation in pure Rust</b>
</p>
<p align="center">
<a href="https://github.com/paiml/batuta/actions/workflows/ci.yml"><img src="https://github.com/paiml/batuta/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://crates.io/crates/batuta"><img src="https://img.shields.io/crates/v/batuta.svg" alt="Crates.io"></a>
<a href="https://docs.rs/batuta"><img src="https://docs.rs/batuta/badge.svg" alt="Documentation"></a>
<a href="https://paiml.github.io/batuta/"><img src="https://img.shields.io/badge/📚_book-online-brightgreen" alt="Book"></a>
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License"></a>
</p>
</div>
---
## What It Does
Batuta is the CLI for the **Sovereign AI Stack** — a pure-Rust ecosystem for privacy-preserving ML infrastructure. Install it and immediately get:
```bash
# Analyze any codebase for quality, bugs, and technical debt
batuta analyze --tdg .
batuta bug-hunter analyze .
batuta falsify .
# Ask questions about the stack and get code examples
batuta oracle "How do I serve a Llama model locally?"
# Serve models with an OpenAI-compatible API
batuta serve ./model.gguf --port 8080
# Run autonomous agents (requires --features agents)
batuta agent run --manifest agent.toml --prompt "Summarize this codebase"
```
## Installation
```bash
cargo install batuta
```
For the autonomous agent runtime:
```bash
cargo install batuta --features agents
```
## Quick Start
### 1. Analyze a project
```bash
batuta analyze --tdg .
```
Output:
```
📊 Analysis Results
Files: 440 total, 98,000 lines
Languages: Rust (95%), TOML (3%), Markdown (2%)
TDG Score: 98.4 (Grade: A+)
```
### 2. Hunt for bugs
```bash
batuta bug-hunter analyze .
```
Finds unwraps, panics, unsafe blocks, error swallowing, and 20+ fault patterns across your codebase.
### 3. Query the stack oracle
```bash
batuta oracle "How do I train a random forest?"
```
Returns component recommendations with working code examples and test companions.
### 4. Serve a model
```bash
batuta serve ./model.gguf --port 8080
```
Starts an OpenAI-compatible server at `http://localhost:8080/v1/chat/completions`.
## Features
- **Code Analysis**: TDG scoring, bug hunting, Popperian falsification testing
- **Oracle Queries**: Natural language queries with RAG-based documentation search
- **Model Serving**: OpenAI-compatible endpoints with privacy tiers (Sovereign/Private/Standard)
- **Autonomous Agents**: Perceive-reason-act loop with 16 formal contract invariants (`--features agents`)
- **Stack Orchestration**: Version drift detection, publish-status, release pipelines for 15+ crates
- **Transpilation**: Python/Shell/C to Rust conversion via depyler/bashrs/decy
- **Playbooks**: Deterministic YAML pipelines with BLAKE3 content-addressed caching
## Agent Runtime
The agent runtime (`--features agents`) provides a full autonomous agent loop:
```bash
# Run with a single prompt
batuta agent run --manifest agent.toml --prompt "Analyze this code for security issues"
# Interactive chat
batuta agent chat --manifest agent.toml --stream
# Multi-agent fan-out
batuta agent pool --manifest agent1.toml --manifest agent2.toml --prompt "Review this PR"
```
Agents are configured via TOML manifests with capability-gated tools (shell, filesystem, network, browser, RAG, MCP), privacy enforcement, and circuit-breaker guards.
See the [Agent Runtime Book Chapter](https://paiml.github.io/batuta/part3/agent-runtime.html) for details.
## Stack Components
```
┌─────────────────────────────────────────────────────────────┐
│ batuta v0.7.0 │
│ (Orchestration Layer) │
├─────────────────────────────────────────────────────────────┤
│ realizar v0.8 │ pacha v0.2 │
│ (Inference Engine) │ (Model Registry) │
├──────────────────────────┴──────────────────────────────────┤
│ aprender v0.27 │ entrenar v0.7 │ alimentar v0.2 │
│ (ML Algorithms) │ (Training) │ (Data Loading) │
├─────────────────────────────────────────────────────────────┤
│ trueno v0.16 │ repartir v2.0 │ renacer v0.10 │
│ (SIMD/GPU Compute) │ (Distributed) │ (Syscall Tracing) │
└─────────────────────────────────────────────────────────────┘
```
| [trueno](https://crates.io/crates/trueno) | 0.16 | SIMD/GPU compute primitives (AVX2/AVX-512/NEON, wgpu) |
| [aprender](https://crates.io/crates/aprender) | 0.27 | ML algorithms: regression, trees, clustering, NAS |
| [entrenar](https://crates.io/crates/entrenar) | 0.7 | Training: autograd, LoRA/QLoRA, quantization |
| [realizar](https://crates.io/crates/realizar) | 0.8 | Inference engine for GGUF/SafeTensors/APR models |
| [pacha](https://crates.io/crates/pacha) | 0.2 | Model registry with Ed25519 signatures, encryption |
| [repartir](https://crates.io/crates/repartir) | 2.0 | Distributed compute (CPU/GPU/Remote executors) |
| [renacer](https://crates.io/crates/renacer) | 0.10 | Syscall tracing with semantic validation |
| [trueno-rag](https://crates.io/crates/trueno-rag) | 0.2 | RAG pipeline (chunking, BM25+vector, RRF) |
| [pmat](https://crates.io/crates/pmat) | latest | Project quality analysis and TDG scoring |
## CLI Reference
```
batuta analyze Analyze project structure, languages, TDG score
batuta bug-hunter Proactive bug hunting (fault patterns, mutation targets)
batuta falsify Popperian falsification checklist
batuta oracle Natural language queries about the Sovereign AI Stack
batuta serve ML model serving (OpenAI-compatible API)
batuta agent Autonomous agent runtime (--features agents)
batuta stack Stack version management, drift detection
batuta playbook Deterministic YAML pipeline runner
batuta transpile Code transpilation (Python/Shell/C → Rust)
batuta hf HuggingFace Hub integration
batuta pacha Model registry operations (sign, verify, encrypt)
```
## Privacy Tiers
| **Sovereign** | Blocks ALL external API calls | Healthcare, Government |
| **Private** | VPC/dedicated endpoints only | Financial services |
| **Standard** | Public APIs allowed | General deployment |
## Development
```bash
git clone https://github.com/paiml/batuta.git
cd batuta
cargo build --release # Build
cargo test --lib # Unit tests (5,641 tests)
cargo clippy -- -D warnings # Lint
make book # Build documentation
```
## Quality
- **5,641 tests**, 95%+ line coverage
- **TDG Score: 98.4 (A+)**
- Zero clippy warnings, zero SATD
- 16 formal contract invariants (design-by-contract)
- Pre-commit hooks with complexity gates
## MSRV
Minimum Supported Rust Version: **1.89**
## License
MIT License — see [LICENSE](LICENSE) for details.
## Documentation
- [The Batuta Book](https://paiml.github.io/batuta/) — Comprehensive guide
- [API Documentation](https://docs.rs/batuta) — Rust API reference
- [Sovereign AI Stack Book](https://paiml.github.io/sovereign-ai-stack-book/) — Full stack tutorial
---
**Batuta** — Orchestrating sovereign AI infrastructure.