Introduction

“Batuta orchestrates sovereign AI infrastructure — autonomous agents, ML serving, code analysis, and transpilation pipelines in pure Rust.”

Welcome to The Batuta Book

This book is your comprehensive guide to Batuta, the orchestration framework for the Sovereign AI Stack. Batuta provides autonomous agent runtimes, ML model serving, proactive bug hunting, and transpilation pipelines that convert Python/C/Shell to Rust with semantic preservation.

The Sovereign AI Stack is built on a foundation of peer-reviewed research—over 30 academic citations across component specifications—ensuring every design decision is grounded in proven computer science and manufacturing principles.

What is Batuta?

Batuta (Spanish for “conductor’s baton”) orchestrates the 22-component Sovereign AI Stack from Pragmatic AI Labs to convert, optimize, and validate code migrations:

Layer 0: Compute Primitives

• Trueno v0.16 - SIMD/GPU compute primitives with zero-copy operations
• Trueno-DB v0.3 - Vector database with HNSW indexing ([Malkov 2020])
• Trueno-Graph v0.1 - Graph analytics and lineage DAG tracking
• Trueno-Viz v0.2 - SIMD/GPU/WASM visualization
• Trueno-RAG v0.2 - RAG pipeline: semantic chunking, BM25+dense hybrid retrieval ([Lewis 2020]), cross-encoder reranking

Layer 1: ML Algorithms

• Aprender v0.27 - First-principles ML in pure Rust

Layer 2: Training & Inference

• Entrenar v0.7 - Training with autograd, LoRA, quantization, DP-SGD
• Realizar v0.8 - LLM inference (GGUF, safetensors, transformers)

Layer 3: Transpilers

• Depyler - Python → Rust with type inference
• Decy - C/C++ → Rust with ownership inference
• Bashrs v6.57 - Rust → Shell (bootstrap scripts)
• Ruchy v4.1 - Script → Rust (systems scripting)

Layer 4: Orchestration

• Batuta v0.7 - Orchestration, agents, serving, analysis
• Repartir v2.0 - Distributed computing primitives
• pforge v0.1.4 - MCP server framework (rust-mcp-sdk)

Layer 5: Quality

• Certeza - Quality validation framework
• PMAT - AI context & code quality
• Renacer v0.10 - Syscall tracing & golden traces
• Provable Contracts - YAML → Kani formal verification for ML kernels
• Tiny Model Ground Truth - Popperian model conversion parity tests

Layer 6: Data & MLOps

• Alimentar - Data loading with .ald AES-256-GCM encryption
• Pacha - Model/Data/Recipe Registry with BLAKE3 content-addressing, Model Cards ([Mitchell 2019]), Datasheets ([Gebru 2021]), W3C PROV-DM provenance

The Philosophy

Batuta is built on three core principles, each deeply integrated throughout the stack.

1. Toyota Way Manufacturing

We apply Lean Manufacturing principles systematically across all 22 components. This isn’t marketing—every specification includes Toyota Way Review sections that audit designs against these principles:

Muda (Waste Elimination)

The seven wastes, applied to software:

“By removing dependency hell, we eliminate the waste of waiting and waste of processing associated with complex environments.” — Trueno-RAG Spec

Jidoka (Built-in Quality)

Stop the line when defects occur. In Batuta:

• Chunking: Semantic chunking stops based on meaning, not arbitrary size—reducing downstream correction waste
• Validation gates: Each phase must pass quality checks before proceeding
• Andon signals: Immediate visualization of problems via PMAT quality scoring

“Fixed-size chunking is prone to defects (cutting semantic context). Semantic chunking stops the chunk based on quality rather than an arbitrary quota.” — Trueno-RAG Spec

Kaizen (Continuous Improvement)

Incremental refinement through:

• Model lineage tracking in Pacha enables iterative improvement
• Experiment comparison identifies what works
• Golden trace evolution captures behavioral improvements over time

Heijunka (Level Scheduling)

Balance load to avoid overburdening:

• HNSW parameters tuned to balance indexing speed with search accuracy
• Batch processing in Realizar avoids GPU memory spikes
• Distributed workloads via Repartir prevent node overload

Genchi Genbutsu (Go and See)

Process data where it resides:

• Local inference eliminates waste of transport (sending data to external APIs)
• Edge deployment brings computation to the data
• Sovereign processing keeps data within your infrastructure

Nemawashi (Consensus Decision Making)

Make decisions slowly by consensus, implement rapidly:

• Hybrid retrieval uses Reciprocal Rank Fusion (RRF) to integrate diverse “perspectives” (dense and sparse)
• Multi-query retrieval pulls more relevant information based on user intent
• Cross-encoder reranking ([Nogueira 2019]) refines results through pairwise scoring

“Reciprocal Rank Fusion acts as a consensus mechanism, integrating diverse perspectives to make a better decision. This aligns with making decisions slowly by consensus, then implementing rapidly.” — Trueno-RAG Spec

One-Piece Flow (Continuous Flow)

Reduce batch sizes to minimize waiting:

• Streaming retrieval delivers results the moment they become available
• Incremental chunking processes documents as they arrive
• Async pipelines eliminate blocking operations

“Streaming results implements continuous flow, reducing the batch size to one. This eliminates the waste of waiting for the user, delivering value the moment it is created.” — Trueno-RAG Spec

2. Semantic Preservation

Code migration is NOT a lossy transformation. Batuta ensures behavioral equivalence through multiple verification layers:

Source Code (Python/C/Shell)
        │
        ▼
┌───────────────────┐
│   IR Analysis     │  ← Abstract semantic representation
└───────────────────┘
        │
        ▼
┌───────────────────┐
│   Transpilation   │  ← Idiomatic Rust generation
└───────────────────┘
        │
        ▼
┌───────────────────┐
│   Validation      │  ← Syscall tracing (Renacer)
└───────────────────┘
        │
        ▼
┌───────────────────┐
│ Golden Trace Diff │  ← Behavioral equivalence proof
└───────────────────┘

3. First Principles Thinking

Rather than blindly translating code, Batuta rebuilds from fundamental truths:

• What does this code actually do? — IR-level semantic analysis
• What is the minimal correct implementation? — Eliminate accidental complexity
• How can we express this idiomatically in Rust? — Leverage ownership, not fight it

The 5-Phase Workflow

Batuta follows a strict 5-phase Kanban workflow with visual control:

┌──────────┐    ┌──────────────┐    ┌──────────────┐    ┌───────────┐    ┌────────────┐
│ Analysis │ -> │ Transpilation│ -> │ Optimization │ -> │ Validation│ -> │ Deployment │
└──────────┘    └──────────────┘    └──────────────┘    └───────────┘    └────────────┘
    20%              40%                  60%               80%               100%

 Languages       depyler/decy         SIMD/GPU           Renacer          WASM/Lambda
   Deps          bashrs/ruchy          MoE              Certeza             Edge
   TDG            Caching            Trueno              Tests             Binary

Each phase has:

• Clear entry criteria — Dependencies on previous phase (Jidoka)
• Specific deliverables — Outputs that feed next phase (One-piece flow)
• Quality gates — Validation before proceeding (Stop and fix)
• Automated tracking — State persistence and progress (Visual control)

Sovereign AI: Complete Stack

The Sovereign AI Stack is 100% Rust, no Python/C++ dependencies:

Why sovereign matters:

• No external API calls — Data never leaves your infrastructure
• AES-256-GCM encryption — .apr and .ald formats protect artifacts at rest
• X25519 + Ed25519 — Key exchange and signatures for secure sharing
• Pure Rust — Single audit surface, no C/C++ CVE tracking

Academic Foundation

Every component specification cites peer-reviewed research. This isn’t theory—it’s engineering rigor applied to every design decision:

Selected References

• [Lewis 2020] - “Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks” (NeurIPS)
• [Karpukhin 2020] - “Dense Passage Retrieval for Open-Domain Question Answering” (EMNLP)
• [Malkov 2020] - “Efficient and Robust Approximate Nearest Neighbor Search Using HNSW” (IEEE TPAMI)
• [Mitchell 2019] - “Model Cards for Model Reporting” (FAT*)
• [Gebru 2021] - “Datasheets for Datasets” (CACM)
• [Robertson 2009] - “The Probabilistic Relevance Framework: BM25 and Beyond” (FnTIR)
• [Liu 2024] - “Lost in the Middle: How Language Models Use Long Contexts” (TACL)
• [Nogueira 2019] - “Passage Re-ranking with BERT” (arXiv)

Who is This Book For?

This book is for:

• Legacy codebase maintainers drowning in Python/C/C++ technical debt
• Performance engineers seeking ML inference speedups (10-100x)
• Systems programmers modernizing shell-based infrastructure
• Engineering managers planning strategic rewrites
• AI/ML engineers building sovereign, private AI systems
• Security teams requiring single-language audit surfaces

What You’ll Learn

By the end of this book, you will:

1. Understand the philosophy — Toyota Way applied to code migration
2. Master the 5-phase workflow — Analysis through deployment
3. Use all stack components — Hands-on integration patterns
4. Apply waste elimination — Identify and remove Muda in your projects
5. Validate semantic equivalence — Syscall tracing with Renacer
6. Optimize performance — SIMD/GPU acceleration with Trueno
7. Build RAG pipelines — Hybrid retrieval with Trueno-RAG
8. Deploy LLM inference — GGUF models with Realizar
9. Track ML experiments — Model lineage with Pacha
10. Ensure data privacy — Encryption and DP-SGD

Prerequisites

Required:

• Basic understanding of Rust (ownership, lifetimes, traits)
• Familiarity with at least one source language (Python, C, C++, Shell)
• Command-line proficiency

Helpful but not required:

• Experience with build systems (Cargo, Make, CMake)
• Understanding of ML frameworks (NumPy, PyTorch, scikit-learn)
• Lean manufacturing concepts (helpful for philosophy sections)

How to Read This Book

If you’re brand new to Batuta: Read Part I (Core Philosophy) to understand the “why”, then work through Part II (5-Phase Workflow) hands-on with a small example project.

If you’re experienced with transpilers: Start with Part III (Tool Ecosystem) to understand Batuta’s orchestration capabilities, then dive into Part IV (Practical Examples) for real-world patterns.

If you’re migrating a specific project: Begin with Part II (5-Phase Workflow) for the systematic approach, consult Part V (Configuration) for customization, and keep Part VIII (Troubleshooting) handy.

If you’re building AI/ML systems: Focus on Part III (Tool Ecosystem) for Trueno/Aprender/Realizar integration, and Pacha for MLOps. Use Oracle Mode for intelligent stack queries.

Running Examples

Batuta includes 30+ runnable examples demonstrating stack capabilities:

# Core pipeline demo (no features required)
cargo run --example pipeline_demo

# Oracle-mode examples
cargo run --example oracle_local_demo --features oracle-mode

# Stack quality analysis
cargo run --example stack_quality_demo --features native

# PMAT query: function-level code search with quality grades
cargo run --example pmat_query_demo --features native

# Bug-hunter: proactive bug detection with GPU/CUDA patterns
cargo run --example bug_hunter_demo --features native

# ML framework conversion
cargo run --example numpy_conversion
cargo run --example sklearn_conversion
cargo run --example pytorch_conversion

See Part IV: Example Overview for the complete list with feature requirements.

Oracle Mode

Batuta includes Oracle Mode — an intelligent query interface backed by a knowledge graph of all 22 components:

# Natural language queries
batuta oracle "How do I train a model on GPU?"
batuta oracle "What's best for vector similarity search?"
batuta oracle "Which components support WASM?"

# Component discovery
batuta oracle --list-capabilities trueno
batuta oracle --integrations "aprender -> realizar"

# JSON output for automation
batuta oracle --json "RAG pipeline components"

Oracle Mode knows capabilities, integration patterns, and recommends optimal component combinations based on your requirements.

Conventions

Throughout this book:

• Bold text emphasizes key concepts
• Inline code represents commands, code snippets, or file names
• 💡 Tips provide helpful shortcuts
• ⚠️ Warnings highlight potential pitfalls
• 🎯 Best practices recommend proven approaches
• 🏭 Toyota Way callouts show lean manufacturing applications

Community and Support

• GitHub: paiml/Batuta
• Book: paiml.github.io/batuta
• Issues: Report bugs and request features
• Discussions: Ask questions and share experiences

Let’s Begin

The journey from legacy code to modern Rust is challenging but immensely rewarding. With Batuta orchestrating the 22-component Sovereign AI Stack, you’re equipped with:

Every component follows Toyota Way principles. Every specification cites peer-reviewed research. Every design decision eliminates waste.

Welcome to systematic code migration. Let’s conduct this orchestra. 🎵

Next: Part I: Core Philosophy

The Orchestration Paradigm

“A single instrument cannot play a symphony. Neither can a single transpiler migrate a complex codebase.”

The Problem with Simple Transpilation

Traditional transpilers make a fundamental mistake: they treat code migration as a one-step translation problem. This is like trying to move a house by picking it up and dropping it in a new location. It might work for a shed, but not for complex structures.

Why Simple Transpilation Fails

1. Loss of Semantic Meaning

# Python
x = [1, 2, 3]
y = x
y.append(4)
# x is now [1, 2, 3, 4] - shared reference

Simple transpilation to Rust:

#![allow(unused)]
fn main() {
// Naive transpilation
let mut x = vec![1, 2, 3];
let mut y = x;  // ❌ Moved! x is now invalid
y.push(4);
}

Correct Batuta approach (via Depyler):

#![allow(unused)]
fn main() {
// Semantic preservation
let mut x = vec![1, 2, 3];
let y = &mut x;  // ✓ Shared mutable reference
y.push(4);
// x is [1, 2, 3, 4] - semantics preserved
}

2. Missing Optimizations

Simple transpilers translate code literally. Batuta recognizes opportunities:

# Python - CPU only
import numpy as np
result = np.dot(large_matrix_a, large_matrix_b)

Batuta orchestration (Depyler + Trueno):

#![allow(unused)]
fn main() {
// Automatic SIMD/GPU dispatch
use trueno::linalg::dot;
let result = dot(&matrix_a, &matrix_b)?;
// ✓ Dispatches to GPU if matrices > threshold
// ✓ Falls back to SIMD for smaller operations
}

3. No Validation

How do you know the transpiled code is correct? Simple transpilers say “it compiles, ship it!” Batuta says “prove it with syscall tracing, test execution, and benchmarks.”

The Orchestra Metaphor

Consider a symphony orchestra:

• Conductor (Batuta): Coordinates all musicians, maintains tempo, ensures harmony
• String Section (Transpilers): Decy, Depyler, Bashrs convert code to Rust
• Brass Section (Foundation Libraries): Trueno, Aprender, Realizar provide runtime capabilities
• Percussion (Support Tools): Ruchy, PMAT, Renacer provide quality and validation

Each instrument is virtuoso in its domain. But without coordination, you get noise, not music.

The Conductor’s Role

Batuta coordinates:

1. Timing: When to invoke which tool (5-phase workflow)
2. Communication: How tools share outputs (IR, AST, config)
3. Quality: Validation at each phase boundary
4. Optimization: Automatic selection of best tool for task

Orchestration vs. Monolithic Tools

Core Principles

1. Specialization

Each tool excels at ONE thing:

• Decy: C/C++ ownership inference
• Trueno: Multi-backend compute dispatch
• Renacer: Syscall-level validation

Do NOT try to make Depyler handle C code. Use the right tool for the job.

2. Composition

Tools are composable building blocks:

Python + NumPy  →  Depyler + Trueno  →  Rust + SIMD/GPU
Python + sklearn → Depyler + Aprender → Rust + ML primitives

3. State Management

Orchestration requires tracking:

• Which phase are we in?
• What completed successfully?
• What failed and why?
• What’s next?

This is why Batuta has a workflow state machine (.batuta-state.json).

4. Incremental Progress

Unlike monolithic transpilers, orchestration supports:

• Partial completion (Phase 1-2 done, 3-5 pending)
• Resume after errors
• Selective re-execution
• Caching of completed work

Real-World Example

Consider migrating a Python ML web service:

project/
├── api.py            # Flask web server
├── model.py          # ML inference
├── preprocessing.py  # NumPy data transforms
├── utils.sh          # Deployment scripts
└── requirements.txt

Monolithic Approach

# Try to transpile everything with one tool
some-transpiler --input project/ --output rust-project/
# ❌ Fails because:
# - Shell scripts not supported
# - NumPy performance poor
# - No validation of ML accuracy
# - No optimization

Batuta Orchestration

# Phase 1: Analysis
batuta analyze --languages --dependencies --tdg
# ✓ Detects: Python (80%), Shell (20%)
# ✓ Identifies: Flask, NumPy, sklearn
# ✓ TDG Score: 73/100 (B)

# Phase 2: Transpilation
batuta transpile
# ✓ Depyler: api.py, model.py, preprocessing.py → Rust
# ✓ Bashrs: utils.sh → Rust CLI
# ✓ NumPy → Trueno: Automatic mapping
# ✓ sklearn → Aprender: Model conversion

# Phase 3: Optimization
batuta optimize --enable-gpu
# ✓ Trueno: SIMD for small matrices
# ✓ Trueno: GPU dispatch for large batch inference
# ✓ Memory layout optimization

# Phase 4: Validation
batuta validate --trace-syscalls --benchmark
# ✓ Renacer: Syscall equivalence check
# ✓ API tests: All passing
# ✓ Performance: 12x faster, 60% less memory

# Phase 5: Deployment
batuta build --release
# ✓ Optimized binary: 8MB (vs 200MB Python + deps)
# ✓ No interpreter, no GC pauses

When NOT to Use Orchestration

Orchestration has overhead. Don’t use Batuta if:

1. Single file, simple logic: Just hand-write Rust
2. Already have Rust version: You’re done!
3. Prototype/throwaway code: Not worth the effort
4. Actively changing code: Finish development first

Use Batuta when:

• Multiple languages/files
• Complex dependencies
• Performance critical
• Need validation
• Long-term maintenance
• Team knowledge transfer

Key Takeaways

Orchestration is:

• ✓ Systematic and repeatable
• ✓ Tool-agnostic (uses best tool for each task)
• ✓ Validatable at each step
• ✓ Optimizable automatically
• ✓ Recoverable from failures

Orchestration is NOT:

• ✗ Magic (it’s systematic process)
• ✗ Perfect (tools have limitations)
• ✗ Instant (phases take time)
• ✗ Suitable for all projects

Next Steps

Now that you understand the orchestration paradigm, let’s explore how it embodies Toyota Way principles - the manufacturing philosophy that makes systematic code migration possible.

Previous: Introduction Next: Toyota Way Principles

Toyota Way Principles

“The Toyota Production System is not just about cars. It’s about eliminating waste, building quality in, and continuous improvement - principles that apply equally to code migration.”

Why Toyota Way for Software?

In the 1950s, Toyota revolutionized manufacturing by focusing on:

• Eliminating waste (Muda)
• Building quality into the process (Jidoka)
• Continuous improvement (Kaizen)
• Level production scheduling (Heijunka)
• Visual workflow management (Kanban)
• Immediate problem signaling (Andon)

These principles transformed automobile manufacturing from craft work to systematic process. Batuta applies the same transformation to code migration.

The Six Principles

1. Muda (Waste Elimination)

In Manufacturing: Eliminate unnecessary movement, waiting, overproduction, defects.

In Code Migration:

Waste: Re-analyzing code multiple times

# ❌ Wasteful approach
analyze-tool project/
transpile-tool project/  # Re-analyzes!
optimize-tool project/   # Re-analyzes again!

Batuta Solution: Single analysis, cached results

# ✓ Efficient orchestration
batuta analyze    # Analyzes once, saves state
batuta transpile  # Uses cached analysis
batuta optimize   # Reuses type information

Waste: Manual tool coordination

# ❌ Manual orchestration
decy file1.c > out1.rs
depyler file2.py > out2.rs
# Wait, did I handle dependencies?
# Which order should these run?

Batuta Solution: Automatic orchestration

# ✓ Handles dependencies automatically
batuta transpile
# ✓ Detects languages, selects tools
# ✓ Orders operations correctly

Impact: Batuta’s caching reduces repeated work by ~40% compared to running tools independently.

2. Jidoka (Built-in Quality)

In Manufacturing: Machines stop automatically when defects detected. Workers can stop the production line.

In Code Migration:

Jidoka Mechanism: Phase dependencies enforce quality gates

# ❌ Without Jidoka
transpile --force  # Transpiles even if analysis failed
optimize           # Optimizes broken code
validate           # Validates incorrect transformation

Batuta with Jidoka:

$ batuta optimize
⚠️  Transpilation phase not completed!

Run batuta transpile first to transpile your project.

📊 Workflow Progress
──────────────────────────────────────────────
  ✓ Analysis [Completed]
  ✗ Transpilation [Failed]
  ○ Optimization [Not Started]
  ...

Quality Gates:

1. Analysis Gate: Must complete before transpilation

   • All languages detected?
   • Dependencies resolved?
   • TDG score calculated?

2. Transpilation Gate: Must succeed before optimization

   • Code compiles?
   • All errors addressed?
   • Tests pass?

3. Optimization Gate: Must validate before deployment

   • Performance improved?
   • Semantics preserved?
   • Tests still pass?

Principle: “Never pass defects downstream.”

3. Kaizen (Continuous Improvement)

In Manufacturing: Small, incremental improvements by everyone, continuously.

In Code Migration:

Bad: One-shot migration, then manual maintenance

#![allow(unused)]
fn main() {
// After transpilation: ugly but working code
fn ugly_function_that_works_but_could_be_better() { /* ... */ }
// Never gets improved because "it works"
}

Batuta Approach: Iterative improvement cycles

Iteration 1: Basic transpilation

#![allow(unused)]
fn main() {
// Depyler output - functional but not idiomatic
pub fn process_data(data: Vec<i32>) -> Vec<i32> {
    let mut result: Vec<i32> = Vec::new();
    for i in 0..data.len() {
        result.push(data[i] * 2);
    }
    return result;
}
}

Iteration 2: Post-transpilation optimization (manual or automatic)

#![allow(unused)]
fn main() {
// Idiomatic Rust
pub fn process_data(data: Vec<i32>) -> Vec<i32> {
    data.into_iter().map(|x| x * 2).collect()
}
}

Iteration 3: Performance optimization (Trueno integration)

#![allow(unused)]
fn main() {
// SIMD-accelerated
use trueno::simd::*;
pub fn process_data(data: Vec<i32>) -> Vec<i32> {
    simd_map(data, |x| x * 2)
}
}

Metrics Track Improvement:

4. Heijunka (Level Scheduling)

In Manufacturing: Level production load to avoid bottlenecks and idle time.

In Code Migration:

Problem: Unbalanced tool usage causes bottlenecks

Transpiler    [████████████████████                    ] 60% CPU
Optimizer     [████                                    ] 10% CPU (waiting)
Validator     [                                        ]  0% CPU (waiting)

Batuta Solution: Balanced orchestration

# Parallel transpilation of independent modules
batuta transpile --modules auth,api,db --parallel
# ✓ auth: Depyler running (30% CPU)
# ✓ api:  Depyler running (30% CPU)
# ✓ db:   Depyler running (30% CPU)
# Total: 90% CPU utilization

Heijunka in Action:

#![allow(unused)]
fn main() {
// Batuta's internal scheduler (simplified)
fn schedule_transpilation(modules: Vec<Module>) {
    let dependency_graph = build_dag(modules);
    let parallel_batches = toposort(dependency_graph);

    for batch in parallel_batches {
        // Run independent modules in parallel
        batch.par_iter().for_each(|module| {
            transpile(module);  // Balanced load
        });
    }
}
}

5. Kanban (Visual Workflow)

In Manufacturing: Visual cards show work status, prevent overproduction, signal when to start next task.

In Code Migration:

Batuta’s Kanban Board:

📊 Workflow Progress
──────────────────────────────────────────────
  ✓ Analysis [Completed]           ← Done
  ⏳ Transpilation [In Progress]   ← Current
  ○ Optimization [Not Started]     ← Waiting
  ○ Validation [Not Started]       ← Waiting
  ○ Deployment [Not Started]       ← Waiting

  Overall: 40% complete

Kanban Rules:

1. Visualize: Always know current state
2. Limit WIP: One phase in-progress at a time
3. Pull System: Phase pulls from previous (doesn’t push)
4. Explicit Policies: Clear phase entry/exit criteria

Example: Pull System

# Transpilation phase "pulls" from Analysis
$ batuta transpile
✓ Loaded configuration
✓ Detecting installed tools...
✓ Primary language: Python

# Pulls analysis results from state file
✓ Analysis completed: 2025-11-19 14:21:32 UTC
  Files: 127 | Lines: 8,432 | TDG: 73.2/100

# Now proceeds with transpilation...

6. Andon (Problem Visualization)

In Manufacturing: Cord workers pull to stop production line when issues detected. Lights signal problem type immediately.

In Code Migration:

Andon Mechanism: Immediate, visible error feedback

$ batuta transpile

❌ Transpilation failed!

Error: No transpiler available for Python.

💡 Troubleshooting:
  • Verify depyler is properly installed
  • Check that source path is correct: "./project"
  • Try running with --verbose for more details
  • See transpiler docs: https://github.com/paiml/depyler

📊 Workflow Progress
──────────────────────────────────────────────
  ✓ Analysis [Completed]
  ✗ Transpilation [Failed]  ← Problem here!
  ○ Optimization [Not Started]
  ...

Andon Lights:

Applying All Principles Together

Example: Complete migration with Toyota Way

# Muda: Single analysis, cached
$ batuta analyze --languages --tdg
✓ Analysis cached to .batuta-state.json

# Jidoka: Quality gate enforces prerequisites
$ batuta optimize
⚠️ Transpilation not completed!

# Kaizen: Iterative improvement
$ batuta transpile --incremental
✓ Transpiled 80% (20% with warnings for review)

# Review, fix, iterate
$ batuta transpile --modules problematic_module
✓ 100% transpiled

# Heijunka: Balanced optimization
$ batuta optimize --profile balanced
✓ SIMD: 234 loops, GPU: 12 operations

# Kanban: Visual progress
$ batuta status
📊 Workflow: 80% complete

# Andon: Clear error signaling
$ batuta validate
✗ Syscall mismatch in module auth.py
  Expected: write(fd=3, buf=...)
  Got:      write(fd=4, buf=...)

Metrics: Toyota Way Impact

Comparing Batuta (with Toyota Way) vs. ad-hoc tool usage:

Key Takeaways

Toyota Way principles are not metaphors - they are operational requirements:

✓ Muda: Batuta caches analysis, reuses results ✓ Jidoka: Phase dependencies enforce quality ✓ Kaizen: Iterative optimization cycles ✓ Heijunka: Parallel module transpilation ✓ Kanban: Visual workflow state tracking ✓ Andon: Immediate error visualization

These aren’t nice-to-haves. They’re how Batuta ensures reliable, systematic code migration.

Next Steps

Now let’s dive deep into each Toyota Way principle and see concrete implementation details.

Previous: The Orchestration Paradigm Next: Muda: Waste Elimination

Muda: Waste Elimination

Muda (無駄) means “waste” – any activity that consumes resources without producing value. The Toyota Production System identifies seven types of waste and systematically eliminates each one.

The Seven Wastes in Software

Waste Elimination in Batuta

Caching and Incremental Compilation

Batuta tracks pipeline state in .batuta-state.json. When a phase completes successfully, it is not re-run unless inputs change.

# First run: all 5 phases execute
$ batuta transpile --input ./project
Phase 1: Analysis       [2.1s]
Phase 2: Transpilation   [8.4s]
Phase 3: Optimization    [3.2s]
Phase 4: Validation      [5.1s]
Phase 5: Deployment      [1.0s]

# Second run: only changed phases re-execute
$ batuta transpile --input ./project
Phase 1: Analysis       [cached]
Phase 2: Transpilation   [1.2s]  # Only modified files
Phase 3: Optimization    [cached]
Phase 4: Validation      [5.1s]  # Re-validates changed output
Phase 5: Deployment      [1.0s]

Cost Circuit Breakers

GPU dispatch is expensive. Batuta prevents waste by applying the Gregg 5x rule: GPU is only selected when the compute benefit exceeds five times the data transfer cost.

#![allow(unused)]
fn main() {
// Muda: avoid wasteful GPU transfers for small operations
let backend = if data_size > threshold && compute_ratio > 5.0 {
    Backend::Gpu
} else {
    Backend::Simd  // SIMD avoids PCIe transfer entirely
};
}

Eliminating Redundant Analysis

PMAT quality analysis uses hash-based invalidation. If source files have not changed, the cached TDG score is reused. Cold cache takes approximately 7 seconds; warm cache responds in under 100 milliseconds. Invalidation triggers are explicit: Cargo.toml changes, git HEAD moves, or TTL expiration.

Eliminating Unnecessary Transpilation

Batuta only transpiles files that match a known source language with an available transpiler. Files already in Rust or belonging to unsupported languages are skipped:

$ batuta transpile --input ./mixed_project
Skipping: src/lib.rs (already Rust)
Transpiling: scripts/preprocess.py (via Depyler)
Transpiling: vendor/parser.c (via Decy)

The goal is not zero time per phase, but zero time spent on work that does not change the output.

Benefits

1. Faster iteration – cached phases complete in milliseconds
2. Lower cost – circuit breakers prevent unnecessary GPU spend
3. Focused effort – only changed files are reprocessed
4. Predictable builds – deterministic state tracking eliminates surprise rebuilds

Navigate: Table of Contents

Jidoka: Built-in Quality

Jidoka (自働化) means “automation with a human touch” - the practice of building quality into the process itself.

Core Principle

Stop the line when a defect is detected. Fix the root cause before continuing.

In Batuta, Jidoka manifests as automatic quality gates that halt the pipeline when issues are found.

Jidoka in Batuta

Pre-commit Hooks

# Automatic checks before every commit
cargo fmt --check     # Formatting
cargo clippy          # Linting
cargo test            # Tests
pmat demo-score       # Quality gate

If any check fails, the commit is blocked.

Quality Gates

Stop-the-Line Examples

#![allow(unused)]
fn main() {
// Jidoka: Fail fast on type errors
fn transpile(source: &str) -> Result<String, Error> {
    let ast = parse(source)?;  // Stop if parse fails
    let typed = typecheck(ast)?;  // Stop if types invalid
    generate(typed)
}
}

Benefits

1. Early detection - Issues caught immediately
2. Root cause focus - Fix problems, not symptoms
3. No defect propagation - Bad code never reaches production
4. Team awareness - Everyone knows quality status

Implementation

Andon Board

Batuta’s diagnostics module provides Andon-style status:

🟢 Green  - All systems healthy
🟡 Yellow - Attention needed
🔴 Red    - Stop the line

Automated Response

When issues are detected:

1. Pipeline stops
2. Team is notified
3. Root cause is investigated
4. Fix is verified
5. Pipeline resumes

Navigate: Table of Contents | Next: Kaizen

Kaizen: Continuous Improvement

Kaizen (改善) means “change for the better” - the philosophy of continuous, incremental improvement.

Core Principle

Small improvements, consistently applied, compound into transformational change.

In Batuta, Kaizen drives the iterative refinement of transpiled code and quality metrics.

Kaizen in Batuta

Iterative Optimization

Iteration 1: Basic transpilation     → 60% quality
Iteration 2: Type inference          → 75% quality
Iteration 3: Memory optimization     → 85% quality
Iteration 4: SIMD acceleration       → 95% quality

MoE Backend Selection

Mixture-of-Experts continuously improves backend selection:

#![allow(unused)]
fn main() {
// Kaizen: Learn from each execution
let backend = BackendSelector::new()
    .with_moe(true)          // Enable learning
    .with_feedback(metrics)   // Improve from results
    .select(&operation);
}

Quality Trending

Track improvement over time:

Week 1: Demo Score 78.5 (C+)
Week 2: Demo Score 81.2 (B)
Week 3: Demo Score 84.1 (B+)
Week 4: Demo Score 86.3 (A-)  ✅ Quality gate passed

Kaizen Practices

Daily Improvements

PDCA Cycle

1. Plan - Identify improvement opportunity
2. Do - Implement change
3. Check - Measure results
4. Act - Standardize or adjust

Metrics-Driven

# Track quality over time
pmat demo-score --history

# Identify improvement areas
pmat analyze complexity --project-path .

# Measure progress
pmat quality-gate --strict

Benefits

1. Sustainable pace - Small changes are manageable
2. Compound gains - Improvements build on each other
3. Team engagement - Everyone contributes
4. Reduced risk - Incremental vs. big-bang changes

Example: Improving Demo Score

# Week 1: Identify issues
pmat demo-score --verbose
# Result: 78.5 - Error gracefulness: 0.5/3.0

# Week 2: Fix error handling
# Add Result returns, replace unwrap()

# Week 3: Improve documentation
# Fill placeholder chapters

# Week 4: Quality gate passes
pmat demo-score
# Result: 86.3 (A-) ✅

Navigate: Table of Contents | Next: Heijunka

Heijunka: Level Scheduling

Heijunka (平準化) means “leveling” - the practice of smoothing workload to prevent resource spikes and idle periods.

Core Principle

Level the load. Bursty demand causes waste; steady flow maximizes throughput.

In Batuta, Heijunka governs how compute workloads are distributed across CPU, GPU, and SIMD backends to prevent any single resource from becoming a bottleneck.

Heijunka in Batuta

MoE Backend Selection

The Mixture-of-Experts backend selector levels load across compute targets:

#![allow(unused)]
fn main() {
// Heijunka: select backend based on current load, not just capability
let backend = BackendSelector::new()
    .with_cost_model(CostModel::Gregg5x)  // 5x PCIe transfer rule
    .with_load_balancing(true)              // Level across backends
    .select(&operation);

// Small matrix multiply → SIMD (avoid GPU transfer overhead)
// Large batch inference → GPU (amortize PCIe cost)
// Mixed workload → distribute across both
}

The 5x PCIe Rule

Backend selection follows Gregg & Hazelwood (2011): GPU dispatch is only worthwhile when compute savings exceed 5x the PCIe transfer cost.

Spillover Routing

The serve module implements Heijunka for inference requests:

#![allow(unused)]
fn main() {
// Heijunka: spillover prevents overloading primary backend
pub fn route_request(req: &InferenceRequest, state: &ServerState) -> Backend {
    let primary = state.primary_backend();

    if primary.queue_depth() < primary.capacity() {
        primary  // Primary has headroom
    } else {
        state.spillover_backend()  // Level to secondary
    }
}
}

Circuit Breakers

Cost circuit breakers prevent runaway GPU usage — a Heijunka safety valve:

# Circuit breaker configuration
# batuta.toml
[serve.circuit_breaker]
gpu_cost_limit = 100.0      # Max GPU-seconds per minute
queue_depth_limit = 64       # Max queued requests
fallback = "cpu"             # Degrade gracefully to CPU

When the GPU budget is exhausted, requests spill over to CPU/SIMD backends rather than queuing unboundedly. Load stays level.

Stack Release Leveling

Releases across the Sovereign AI Stack are leveled to avoid dependency cascades:

Week 1: trueno 0.16.1          (foundation)
Week 2: aprender 0.27.2        (depends on trueno)
Week 3: realizar 0.8.0         (depends on both)
Week 4: batuta 0.7.2           (orchestration)

Sequential, leveled releases prevent the “big bang” integration problem.

Benefits

1. No resource spikes - GPU and CPU utilization stays predictable
2. Cost control - Circuit breakers enforce budget limits
3. Graceful degradation - Spillover routing prevents failures under load
4. Predictable latency - Level scheduling avoids queuing delays

Navigate: Table of Contents | Next: Kanban

Kanban: Visual Workflow

Kanban (看板) means “signboard” - the practice of making work visible so teams can manage flow and limit work in progress.

Core Principle

Make the invisible visible. Limit work in progress to maximize throughput.

In Batuta, Kanban manifests as real-time dashboards that surface pipeline state, stack health, and quality metrics at a glance.

Kanban in Batuta

Pipeline State Visibility

# Show current pipeline state across all phases
batuta status

# Phase      | Status     | Duration
# -----------|------------|----------
# Analysis   | Complete   | 1.2s
# Transpile  | Running    | 3.4s (depyler)
# Optimize   | Pending    | -
# Validate   | Pending    | -
# Build      | Pending    | -

Each phase of the 5-phase pipeline is a Kanban column. Work items flow left to right, and Jidoka stops the line if any phase fails.

Stack Quality Matrix

# TUI dashboard showing all stack components
batuta stack status

# Component   | Version | Health | Coverage | TDG
# ------------|---------|--------|----------|-----
# trueno      | 0.16.x  | Green  | 95%      | A
# aprender    | 0.27.x  | Green  | 95%      | A-
# realizar    | 0.8.x   | Yellow | 91%      | B+
# repartir    | 2.0.x   | Green  | 93%      | A

WIP Limits

Batuta enforces WIP limits to prevent overloading any stage:

Pull-Based Execution

#![allow(unused)]
fn main() {
// Kanban: downstream phases pull work when ready
fn run_pipeline(config: &Config) -> Result<Report> {
    let analysis = analyze(config)?;        // Phase 1
    let transpiled = transpile(&analysis)?;  // Phase 2 pulls from 1
    let optimized = optimize(&transpiled)?;  // Phase 3 pulls from 2
    let validated = validate(&optimized)?;   // Phase 4 pulls from 3
    build(&validated)                        // Phase 5 pulls from 4
}
}

Benefits

1. Flow visibility - See bottlenecks before they stall the pipeline
2. WIP control - Prevent resource exhaustion from over-parallelism
3. Pull scheduling - Each phase processes work only when capacity allows
4. Stack awareness - One dashboard for the entire Sovereign AI Stack

Board Layout

| Backlog | Analysis | Transpile | Optimize | Validate | Done |
|---------|----------|-----------|----------|----------|------|
|         | app.py   |           |          |          |      |
|         |          | lib.c     |          |          |      |
|         |          |           |          | util.sh  |      |
| WIP: -  | WIP: 2/4 | WIP: 1/4 | WIP: 0/2 | WIP: 1/2 |      |

Navigate: Table of Contents | Next: Andon

Andon: Problem Visualization

Andon (行灯) means “lantern” - a signal board that makes quality problems immediately visible to the entire team.

Core Principle

Problems must be visible the moment they occur. Hidden failures compound into catastrophes.

In Batuta, Andon manifests as the diagnostics engine that provides colored, at-a-glance status for every stack component and pipeline phase.

Andon in Batuta

Stack Health Dashboard

# Real-time health across all components
batuta stack status

# Component      | Signal | Detail
# ---------------|--------|----------------------------
# trueno         | 🟢     | v0.16.1 — all tests pass
# aprender       | 🟢     | v0.27.2 — coverage 95%
# realizar       | 🟡     | v0.8.0 — 2 clippy warnings
# whisper-apr    | 🔴     | v0.1.0 — build failure

Signal Levels

Diagnostics Engine

The diagnostics module continuously monitors quality signals:

#![allow(unused)]
fn main() {
// Andon: aggregate signals from all quality sources
pub fn diagnose(workspace: &Workspace) -> HealthReport {
    let mut report = HealthReport::new();

    for component in workspace.components() {
        let signal = match (component.tests_pass(), component.clippy_clean()) {
            (true, true)  => Signal::Green,
            (true, false) => Signal::Yellow,
            (false, _)    => Signal::Red,
        };
        report.add(component.name(), signal);
    }

    report
}
}

Pipeline Andon

Each pipeline phase reports its own Andon signal:

# Pipeline status with timing and errors
batuta status --verbose

# Phase 1: Analysis    🟢  1.2s
# Phase 2: Transpile   🟢  4.1s (depyler)
# Phase 3: Optimize    🟡  2.3s (SIMD fallback: no AVX-512)
# Phase 4: Validate    🔴  FAILED — output mismatch at line 42
# Phase 5: Build       --  Skipped (Jidoka stop)

When Phase 4 signals red, Jidoka halts the pipeline. The Andon board shows exactly where and why.

Benefits

1. Instant awareness - Problems surface immediately, not at release time
2. Root cause focus - Signal includes context, not just pass/fail
3. Team alignment - Everyone sees the same board, same priorities
4. Escalation path - Yellow warns, Red blocks — graduated response

Andon Cord: Manual Signals

Any team member can pull the Andon cord to flag an issue:

# Flag a component for investigation
batuta stack flag realizar --reason "output mismatch on Q4K models"

# Clear after resolution
batuta stack clear realizar

Navigate: Table of Contents | Next: First Principles

First Principles Thinking

First Principles Thinking means building from fundamental truths rather than adopting existing frameworks with their inherited assumptions and technical debt.

Core Principle

Own every layer. External frameworks are borrowed complexity — first-principles implementations are permanent assets.

The Sovereign AI Stack builds each capability from scratch in pure Rust, producing a vertically integrated system with no opaque dependencies.

Why First Principles?

The Framework Tax

Traditional ML stacks depend on layers of borrowed complexity:

Each external dependency brings: build complexity, ABI instability, Python runtime overhead, and opaque failure modes.

What First Principles Gives You

No Python runtime    → Deploy as a single static binary
No C++ dependencies  → Cross-compile to any target
No CUDA SDK          → GPU via wgpu (Vulkan/Metal/DX12/WebGPU)
No framework lock-in → Swap any layer independently
WASM support         → Run ML in the browser

First Principles in Batuta

Compute: trueno

Instead of wrapping BLAS/LAPACK, trueno implements SIMD kernels directly:

#![allow(unused)]
fn main() {
// First principles: hand-written AVX2 dot product
// No opaque C library — every instruction is visible and auditable
#[cfg(target_arch = "x86_64")]
unsafe fn dot_avx2(a: &[f32], b: &[f32]) -> f32 {
    use std::arch::x86_64::*;
    let mut sum = _mm256_setzero_ps();
    for i in (0..a.len()).step_by(8) {
        let va = _mm256_loadu_ps(a.as_ptr().add(i));
        let vb = _mm256_loadu_ps(b.as_ptr().add(i));
        sum = _mm256_fmadd_ps(va, vb, sum);
    }
    hsum_avx2(sum)
}
}

ML: aprender

Algorithms implemented from the math, not wrapped from scikit-learn:

#![allow(unused)]
fn main() {
// First principles: Random Forest from decision theory
// Not a binding to a C library — pure Rust, fully auditable
let model = RandomForest::builder()
    .n_trees(100)
    .max_depth(10)
    .criterion(SplitCriterion::Gini)
    .build(&training_data)?;
}

The Stack Builds on Itself

Each layer depends only on the layers below it — no circular or external dependencies:

trueno          → SIMD/GPU primitives (no dependencies)
aprender        → ML algorithms (depends on trueno)
realizar        → Inference runtime (depends on trueno + aprender)
whisper-apr     → Speech recognition (depends on all three)
batuta          → Orchestrates everything

Benefits

1. Total auditability - Every computation is visible in Rust source
2. No supply chain risk - No opaque native binaries in the dependency tree
3. Cross-platform - WASM, embedded, server — all from the same codebase
4. Performance ownership - Optimize any layer directly, no FFI boundaries
5. Privacy by construction - No telemetry, no cloud calls, sovereign by default

Navigate: Table of Contents

Semantic Preservation

Semantic Preservation is Batuta’s core guarantee: transpiled Rust code produces results identical to the original source.

Core Principle

Correctness is non-negotiable. A transpilation that changes behavior is worse than no transpilation at all.

Every pipeline execution validates that the output program is semantically equivalent to the input, across numerical results, API behavior, and system interactions.

Three Pillars

1. Numerical Fidelity

Floating-point operations must produce bitwise-identical or epsilon-bounded results:

#![allow(unused)]
fn main() {
// Python: numpy.dot(a, b)
// Rust:   trueno::simd::dot(a, b)

// Validation: compare outputs within machine epsilon
fn verify_numerical_fidelity(python_out: &[f64], rust_out: &[f64]) -> bool {
    python_out.iter().zip(rust_out).all(|(p, r)| {
        (p - r).abs() < f64::EPSILON * 10.0
    })
}
}

2. API Equivalence

Public interfaces must accept the same inputs and produce the same outputs:

3. Behavioral Parity

Side effects — file I/O, network calls, exit codes — must match:

# Validate behavioral parity via syscall tracing
batuta validate --trace

# Renacer captures syscalls from both programs
# Python run:  open("out.csv", W) → write(1024 bytes) → close()
# Rust run:    open("out.csv", W) → write(1024 bytes) → close()
# Result: MATCH

Validation Pipeline

Batuta’s Phase 4 (Validation) enforces semantic preservation automatically:

Source Program ──► Run + Capture ──► Reference Output
                                          │
                                    ┌─────┴─────┐
                                    │  Compare   │
                                    └─────┬─────┘
                                          │
Transpiled Rust ──► Run + Capture ──► Actual Output

Example: NumPy to Trueno

# Original Python
import numpy as np
a = np.array([1.0, 2.0, 3.0])
b = np.array([4.0, 5.0, 6.0])
result = np.dot(a, b)  # 32.0

#![allow(unused)]
fn main() {
// Transpiled Rust — semantically identical
use trueno::Tensor;
let a = Tensor::from_slice(&[1.0, 2.0, 3.0]);
let b = Tensor::from_slice(&[4.0, 5.0, 6.0]);
let result = a.dot(&b);  // 32.0
}

Batuta validates that both produce 32.0 before marking the transpilation as successful.

Benefits

1. Confidence - Teams trust that transpiled code is correct
2. Automation - No manual verification needed
3. Regression prevention - Every change is validated against the reference
4. Auditability - Syscall traces provide a provable equivalence record

Navigate: Table of Contents

Workflow Overview

“A conductor doesn’t play all instruments at once. Each section performs in sequence, building upon the previous. So too with code migration.”

The 5-Phase Workflow

Batuta enforces a strict 5-phase Kanban workflow. You cannot skip phases. You cannot run phases out of order. This is not a limitation - it’s a quality guarantee.

┌──────────────────────────────────────────────────────────────────┐
│                    BATUTA 5-PHASE WORKFLOW                        │
└──────────────────────────────────────────────────────────────────┘

Phase 1: Analysis (20%)
├─ Language detection
├─ Dependency analysis
├─ Technical Debt Grade (TDG)
├─ ML framework identification
└─ Transpiler recommendation
      ↓
Phase 2: Transpilation (40%)
├─ Tool selection (Decy/Depyler/Bashrs)
├─ Code conversion
├─ Type inference
├─ Ownership analysis
└─ Initial Rust generation
      ↓
Phase 3: Optimization (60%)
├─ SIMD vectorization (Trueno)
├─ GPU dispatch (Trueno)
├─ Memory layout optimization
└─ MoE backend selection
      ↓
Phase 4: Validation (80%)
├─ Syscall tracing (Renacer)
├─ Output comparison
├─ Test suite execution
└─ Performance benchmarking
      ↓
Phase 5: Deployment (100%)
├─ Release build
├─ Cross-compilation
├─ WebAssembly target
└─ Distribution packaging

Phase Dependencies

Why enforce order?

Consider what happens if you skip Analysis:

# ❌ Without Analysis
$ batuta transpile
Error: Don't know what language this is!
Error: Don't know which transpiler to use!
Error: Don't know about dependencies!

Each phase builds on the previous:

State Persistence

Every phase updates .batuta-state.json:

{
  "current_phase": "Transpilation",
  "phases": {
    "Analysis": {
      "status": "Completed",
      "started_at": "2025-11-19T14:21:32Z",
      "completed_at": "2025-11-19T14:21:33Z",
      "duration": "0.13s"
    },
    "Transpilation": {
      "status": "InProgress",
      "started_at": "2025-11-19T14:22:15Z"
    },
    "Optimization": {
      "status": "NotStarted"
    },
    ...
  }
}

Benefits:

1. Resume after errors: Fix the problem, run same command
2. Track progress: Know exactly where you are
3. Performance analysis: See which phases take longest
4. Audit trail: Complete history of migration

Workflow Commands

Start Fresh

# Reset everything
$ batuta reset --yes
✅ Workflow state reset successfully!

# Begin migration
$ batuta status
No workflow started yet.

💡 Get started:
  1. Run batuta analyze to analyze your project

Run Full Pipeline

# Standard workflow (all phases in sequence)
$ batuta analyze --languages --dependencies --tdg
$ batuta init --source ./my-python-app
$ batuta transpile --incremental --cache
$ batuta optimize --enable-gpu --profile aggressive
$ batuta validate --trace-syscalls --benchmark
$ batuta build --release

Check Progress Anytime

$ batuta status

📊 Workflow Progress
──────────────────────────────────────────────
  ✓ Analysis [Completed]
  ✓ Transpilation [Completed]
  ⏳ Optimization [In Progress]
  ○ Validation [Not Started]
  ○ Deployment [Not Started]

  Overall: 60% complete

Phase Details:
──────────────────────────────────────────────

✓ Analysis
  Started: 2025-11-19 14:21:32 UTC
  Completed: 2025-11-19 14:21:33 UTC
  Duration: 0.13s

✓ Transpilation
  Started: 2025-11-19 14:22:15 UTC
  Completed: 2025-11-19 14:25:48 UTC
  Duration: 213.2s

⏳ Optimization
  Started: 2025-11-19 14:26:02 UTC

Phase Entry Criteria

Each phase has explicit entry criteria that must be satisfied:

Phase 1: Analysis

• Entry: Valid source directory
• Exit: Language map generated, dependencies resolved, TDG calculated

Phase 2: Transpilation

• Entry: Analysis completed successfully
• Exit: All source files transpiled, code compiles, basic tests pass

Phase 3: Optimization

• Entry: Transpilation completed, code compiles
• Exit: Optimizations applied, code still compiles, tests pass

Phase 4: Validation

• Entry: Optimization completed
• Exit: Equivalence verified, benchmarks complete, acceptance criteria met

Phase 5: Deployment

• Entry: Validation passed
• Exit: Binaries built, packaged, ready for distribution

Error Handling

Principle: Fail fast, fail clearly, provide actionable guidance.

Phase Failure Example

$ batuta transpile

🔄 Transpiling code...

✓ Loaded configuration
✓ Detected tools: Depyler (Python → Rust)
✓ Primary language: Python

❌ Transpilation failed!

Error: depyler exited with code 1
  File "complex_class.py", line 42
    Unsupported Python feature: metaclass with __prepare__

💡 Troubleshooting:
  • Simplify metaclass usage in complex_class.py
  • Use Ruchy for gradual migration of complex features
  • See: https://github.com/paiml/depyler/issues/23

📊 Workflow Progress
──────────────────────────────────────────────
  ✓ Analysis [Completed]
  ✗ Transpilation [Failed]  ← Fix this!
  ○ Optimization [Not Started]
  ○ Validation [Not Started]
  ○ Deployment [Not Started]

  Overall: 20% complete

Note: Phase status is “Failed”, not “In Progress”. This prevents downstream phases from using broken output.

Workflow Patterns

Pattern 1: Iterate on Single Phase

# Fix transpilation errors iteratively
$ batuta transpile
✗ Failed on module auth.py

# Fix auth.py manually or with Ruchy
$ batuta transpile --modules auth
✓ auth.py transpiled successfully

# Continue with full transpilation
$ batuta transpile
✓ All modules transpiled

Pattern 2: Skip Completed Phases

# Workflow state persists
$ batuta status
Current phase: Optimization

# Running earlier phases does nothing
$ batuta analyze
ℹ️ Analysis already completed

# But you can force re-analysis
$ batuta analyze --force
⚠️  This will reset downstream phases!
Proceed? [y/N] y

Pattern 3: Parallel Development

# Developer A works on transpilation
$ batuta transpile --modules frontend

# Developer B works on different modules
$ batuta transpile --modules backend

# Merge and complete
$ batuta transpile --modules shared
$ batuta status
✓ Transpilation: 100% complete

Performance Characteristics

Typical phase durations (varies by project size):

Note: Incremental compilation reduces re-transpilation time by 60-80%.

Workflow Visualization

The workflow is a state machine:

    [Not Started]
         ↓
    start_phase()
         ↓
    [In Progress] ─── fail_phase() ───→ [Failed]
         ↓                                   ↑
    complete_phase()                         │
         ↓                                   │
    [Completed] ──── retry ─────────────────┘

State transitions:

Key Takeaways

✓ 5 phases, strict order: No skipping, no reordering ✓ State persistence: Resume after errors, track progress ✓ Quality gates: Each phase validates previous output ✓ Visual progress: Always know where you are ✓ Fail fast: Errors stop pipeline, require fixes ✓ Actionable errors: Clear guidance on how to proceed

Next Steps

Now let’s dive deep into each phase, starting with Phase 1: Analysis.

Previous: Toyota Way Principles Next: Phase 1: Analysis

Phase 1: Analysis

Phase 1 is the entry point of the Batuta transpilation pipeline. It scans the source project to build a complete understanding of what needs to be converted before any code transformation begins.

What Analysis Produces

The AnalysisStage walks the source directory and generates a ProjectAnalysis containing:

• Language map – which files are Python, C, Shell, or mixed
• Dependency graph – pip, Conda, npm, Makefile dependencies detected
• TDG score – Technical Debt Grade from PMAT static analysis
• ML framework usage – PyTorch, sklearn, NumPy import detection
• Transpiler recommendation – which tool handles each language

Pipeline Integration

Analysis populates the PipelineContext that flows through all subsequent stages:

#![allow(unused)]
fn main() {
pub struct PipelineContext {
    pub input_path: PathBuf,
    pub output_path: PathBuf,
    pub primary_language: Option<Language>,
    pub file_mappings: Vec<(PathBuf, PathBuf)>,
    pub metadata: HashMap<String, serde_json::Value>,
    // ...
}
}

The primary_language field drives transpiler selection in Phase 2. The metadata map carries TDG scores, dependency counts, and ML framework details forward.

CLI Usage

# Full analysis with all sub-phases
batuta analyze --languages --dependencies --tdg /path/to/project

# Language detection only
batuta analyze --languages /path/to/project

# JSON output for tooling integration
batuta analyze --languages --format json /path/to/project

Analysis Sub-Phases

Jidoka Behavior

If the source directory does not exist or contains no recognizable files, the AnalysisStage returns an error. The pipeline’s ValidationStrategy::StopOnError setting halts execution immediately, preventing downstream stages from operating on invalid input.

Phase 1 fails --> Phase 2 never starts --> No broken output

Transpiler Recommendation

Based on the detected primary language, Analysis recommends a transpiler:

Sub-Phase Details

Each sub-phase is documented in its own section:

• Language Detection – file extension and content-based detection
• Dependency Analysis – package manager parsing
• TDG Scoring – quality grading via PMAT
• ML Framework Detection – PyTorch, sklearn, NumPy mapping

Navigate: Table of Contents

Language Detection

Language detection is the first sub-phase of Analysis. It identifies every programming language present in the source project and calculates line-count statistics.

Detection Method

Batuta uses a two-layer detection strategy:

1. File extension mapping – .py to Python, .c/.h to C, .sh to Shell, etc.
2. Content inspection – shebang lines (#!/usr/bin/env python3) disambiguate extensionless scripts

The Language enum in src/types.rs covers all supported languages:

#![allow(unused)]
fn main() {
pub enum Language {
    Python, C, Cpp, Rust, Shell,
    JavaScript, TypeScript, Go, Java,
    Other(String),
}
}

Parsing from strings is case-insensitive with common aliases:

#![allow(unused)]
fn main() {
// All of these resolve to Language::Shell
"shell".parse::<Language>()  // Ok(Shell)
"bash".parse::<Language>()   // Ok(Shell)
"sh".parse::<Language>()     // Ok(Shell)
}

Multi-Language Projects

Most real projects contain multiple languages. Batuta produces a LanguageStats vector sorted by line count:

#![allow(unused)]
fn main() {
pub struct LanguageStats {
    pub language: Language,
    pub file_count: usize,
    pub line_count: usize,
    pub percentage: f64,
}
}

The language with the highest percentage becomes the primary_language, which determines the default transpiler in Phase 2.

Example Output

$ batuta analyze --languages ./my-project

Language Analysis
-----------------
Python     |  142 files |  28,400 lines |  72.3%  (primary)
Shell      |   18 files |   4,200 lines |  10.7%
C          |   12 files |   3,800 lines |   9.7%
JavaScript |    8 files |   2,900 lines |   7.3%

Supported Extensions

Mixed-Language Handling

When a project contains multiple transpilable languages (e.g., Python and Shell), Batuta processes each language with its corresponding transpiler in Phase 2. The primary_language sets the default, but all detected languages are stored in the analysis results for per-file transpiler dispatch.

Navigate: Table of Contents

Dependency Analysis

Dependency analysis identifies package managers and their manifest files in the source project, building a graph of external libraries that must be mapped to Rust equivalents.

Supported Package Managers

Batuta’s DependencyManager enum recognizes manifests from all major ecosystems:

Detection Output

Each detected manifest produces a DependencyInfo record:

#![allow(unused)]
fn main() {
pub struct DependencyInfo {
    pub manager: DependencyManager,
    pub file_path: PathBuf,
    pub count: Option<usize>,
}
}

The count field holds the number of declared dependencies when parseable. This feeds into TDG scoring since high dependency counts correlate with migration complexity.

Python to Rust Mapping

For Python projects, the most critical output is mapping pip packages to Rust crate equivalents within the Sovereign AI Stack:

CLI Usage

# Dependency-only analysis
$ batuta analyze --dependencies ./my-project

Dependencies
------------
pip (requirements.txt)  |  24 packages
Conda (environment.yml) |  18 packages
Make (Makefile)         |  detected

Dependency Graph Construction

When multiple manifest files reference the same packages, Batuta deduplicates and builds a unified dependency graph. Version constraints are preserved for compatibility checking during transpilation.

For projects using requirements.txt, Batuta parses version specifiers:

numpy>=1.24,<2.0    -->  trueno = "0.14"
scikit-learn~=1.3    -->  aprender = "0.24"
torch>=2.0           -->  realizar = "0.5"

ML Dependency Detection

The has_ml_dependencies() method on ProjectAnalysis checks whether any Python package manager (Pip, Conda, Poetry) is present. When true, the ML detection sub-phase activates to perform deeper import-level analysis.

Navigate: Table of Contents

Technical Debt Grade (TDG)

The Technical Debt Grade is a composite quality score computed by PMAT static analysis. It provides a single letter grade (A through F) that summarizes the migration readiness of the source project.

Grading Scale

What TDG Measures

TDG is a weighted composite of four dimensions:

1. Cyclomatic Complexity – number of independent paths through functions
2. Cognitive Complexity – how difficult code is for humans to understand
3. Test Coverage – percentage of lines exercised by tests
4. Code Quality – linting violations, dead code, duplication

How TDG Is Computed

Batuta delegates TDG computation to the PMAT tool:

# PMAT runs complexity analysis and returns JSON
pmat analyze complexity /path/to/project --format json

The analyze_quality() function in src/tools.rs invokes PMAT and parses the result:

#![allow(unused)]
fn main() {
pub fn analyze_quality(path: &Path) -> Result<String> {
    let args = vec!["analyze", "complexity", &path_str, "--format", "json"];
    run_tool("pmat", &args, None)
}
}

The resulting score is stored as tdg_score: Option<f64> in ProjectAnalysis.

CLI Usage

$ batuta analyze --tdg ./my-python-app

Technical Debt Grade
--------------------
Overall: B (78.3)

  Complexity:  72/100  (12 functions above threshold)
  Coverage:    85/100  (85% line coverage)
  Quality:     81/100  (3 clippy-equivalent warnings)
  Duplication: 75/100  (2 code clones detected)

Migration Priority

TDG scores guide migration order. High-scoring modules are the best candidates for automated transpilation because they have well-defined behavior and test coverage to validate against.

Pre-commit Integration

Batuta’s pre-commit hook enforces complexity thresholds to prevent TDG regression:

# Pre-commit runs on staged .rs files
pmat analyze complexity --max-cyclomatic 30 --max-cognitive 25

Functions exceeding these thresholds block the commit until the complexity is reduced.

Navigate: Table of Contents

ML Framework Detection

ML framework detection scans Python source files for import statements from NumPy, scikit-learn, and PyTorch. Each detected operation is mapped to its equivalent in the Sovereign AI Stack.

Detection Pipeline

The LibraryAnalyzer in src/pipeline_analysis.rs walks all .py files and checks for library-specific import patterns:

#![allow(unused)]
fn main() {
pub struct LibraryAnalyzer {
    numpy_converter: NumPyConverter,
    sklearn_converter: SklearnConverter,
    pytorch_converter: PyTorchConverter,
}
}

Detection is import-gated: a file must contain import numpy or from numpy before individual operations are scanned. This avoids false positives from string matches in comments or documentation.

Framework Mapping

NumPy to Trueno

The NumPyConverter maps 12 NumPy operations to Trueno equivalents:

Each operation carries a complexity level that feeds into the MoE backend selector during Phase 3 optimization.

scikit-learn to Aprender

The SklearnConverter maps algorithms across six sklearn module groups:

PyTorch to Realizar

The PyTorchConverter handles inference-focused operations:

CLI Usage

$ batuta analyze --languages --dependencies --tdg ./ml-project

ML Framework Detection
----------------------
NumPy:    model.py (np.array, np.dot, np.sum) --> trueno::Vector
sklearn:  train.py (LinearRegression, KMeans) --> aprender
PyTorch:  infer.py (torch.load, .forward)     --> realizar

Navigate: Table of Contents

Phase 2: Transpilation

Phase 2 converts source code from the detected language into Rust using external transpiler tools. It dispatches each file to the appropriate transpiler based on the language map produced by Phase 1.

Transpiler Dispatch

The TranspilationStage reads the primary_language from PipelineContext and selects the matching tool from the ToolRegistry:

The ToolRegistry::get_transpiler_for_language() method performs the lookup:

#![allow(unused)]
fn main() {
pub fn get_transpiler_for_language(&self, lang: &Language) -> Option<&ToolInfo> {
    match lang {
        Language::C | Language::Cpp => self.decy.as_ref(),
        Language::Python => self.depyler.as_ref(),
        Language::Shell => self.bashrs.as_ref(),
        _ => None,
    }
}
}

Pipeline Context Flow

Phase 2 receives the context from Phase 1 and adds file mappings:

PipelineContext {
    primary_language: Some(Python),    // <-- from Phase 1
    file_mappings: [                   // <-- populated by Phase 2
        ("src/main.py", "src/main.rs"),
        ("src/utils.py", "src/utils.rs"),
    ],
}

These mappings are consumed by Phase 4 (Validation) for equivalence checking.

Parallel File Processing

For multi-file projects, transpilation processes files independently. Each file is dispatched to its language-specific transpiler in parallel, with results collected and merged into the pipeline context.

Jidoka Stop-on-Error

If any file fails to transpile, the ValidationStrategy::StopOnError setting halts the pipeline. The error includes the specific file and transpiler output:

Error: Stage 'Transpilation' failed
  Caused by: depyler exited with code 1
  File "complex_class.py", line 42
    Unsupported Python feature: metaclass with __prepare__

The workflow state records the failure, and Phase 3 refuses to start until the issue is resolved.

Sub-Topics

• Tool Selection – how transpilers are detected and validated
• Incremental Compilation – only retranspile changed files
• Caching Strategy – cross-run persistence of transpilation results
• Error Handling – Jidoka error patterns

CLI Usage

# Transpile the entire project
batuta transpile --incremental --cache

# Transpile specific modules
batuta transpile --modules auth,api

# Force retranspilation of all files
batuta transpile --force

Navigate: Table of Contents

Tool Selection

Batuta orchestrates external transpiler tools rather than implementing transpilation itself. The ToolRegistry detects which tools are available on the system and selects the appropriate one for each source language.

Tool Detection

On startup, ToolRegistry::detect() probes the system PATH for each known tool using the which crate:

#![allow(unused)]
fn main() {
fn detect_tool(name: &str) -> Option<ToolInfo> {
    let path = which::which(name).ok()?;
    let version = get_tool_version(name);
    Some(ToolInfo {
        name: name.to_string(),
        version,
        path: path.to_string_lossy().to_string(),
        available: true,
    })
}
}

Version detection runs <tool> --version and extracts the version string from the last whitespace-delimited token in the first line of output.

Registry Contents

The full registry checks for nine tools:

Fallback Strategies

When a required transpiler is missing, Batuta provides actionable installation instructions:

$ batuta transpile

Error: No transpiler available for Python
Install Depyler: cargo install depyler

The get_installation_instructions() method generates per-tool instructions. CLI tools use cargo install, while library crates reference Cargo.toml additions.

Version Compatibility

Each transpiler version is recorded in the ToolInfo struct. Batuta logs the detected version at the start of transpilation for reproducibility. Future versions will enforce minimum version requirements to prevent compatibility issues.

Checking Available Tools

$ batuta tools

Detected Tools
--------------
Depyler (Python -> Rust)     v2.1.0  /usr/local/bin/depyler
Bashrs (Shell -> Rust)       v1.3.0  /usr/local/bin/bashrs
PMAT (Quality analysis)      v1.8.0  /usr/local/bin/pmat
Renacer (Syscall tracing)    v0.9.0  /usr/local/bin/renacer

Missing:
  Decy (C/C++ -> Rust)       cargo install decy
  Ruchy (Rust scripting)     cargo install ruchy

Tool Invocation

All tool invocation goes through the run_tool() function in src/tools.rs, which captures stdout and stderr, checks exit codes, and wraps failures in structured anyhow errors with the tool name and exit code.

Navigate: Table of Contents

Incremental Compilation

Incremental compilation avoids retranspiling files that have not changed since the last run. This reduces Phase 2 execution time by 60-80% on subsequent runs.

How It Works

Batuta tracks file modification times and content hashes for every source file processed during transpilation. On the next run, only files whose hash has changed are sent to the transpiler.

Run 1: 50 files transpiled (all new)         -- 45s
Run 2: 3 files changed, 47 skipped           -- 2.8s
Run 3: 0 files changed, 50 skipped           -- 0.1s

Change Detection

For each source file, Batuta stores:

The check uses a two-tier strategy for speed:

1. Fast path: Compare mtime – if unchanged, skip hash computation
2. Slow path: If mtime differs, compute SHA-256 and compare to stored hash

This handles cases where a file is touched (mtime changes) but content remains identical.

Dependency-Aware Invalidation

When a file changes, Batuta also invalidates files that depend on it. For Python projects, this means if utils.py is modified, any file that imports utils is also retranspiled.

utils.py changed
  --> retranspile utils.py
  --> retranspile main.py     (imports utils)
  --> retranspile test_app.py (imports utils)
  --> skip config.py          (no dependency)

CLI Usage

# Enable incremental compilation (default)
batuta transpile --incremental

# Force full retranspilation
batuta transpile --force

# Show what would be retranspiled without doing it
batuta transpile --incremental --dry-run

State File

Incremental state is persisted to .batuta-state.json alongside the workflow state. This file survives across terminal sessions and CI runs when cached appropriately.

{
  "file_hashes": {
    "src/main.py": "a1b2c3d4...",
    "src/utils.py": "e5f6g7h8..."
  },
  "dependency_graph": {
    "src/main.py": ["src/utils.py"],
    "src/test_app.py": ["src/utils.py"]
  }
}

When to Force Full Rebuild

Use --force when:

• Upgrading the transpiler tool to a new version
• Changing transpilation options (e.g., --format project to --format module)
• Suspecting cache corruption
• After modifying shared configuration files

Navigate: Table of Contents

Caching Strategy

Batuta employs multiple caching layers to minimize redundant work across pipeline runs. Caching operates at the file level, the AST level, and the build artifact level.

Cache Layers

File-Level Cache

The file hash cache is the foundation. Every source file’s SHA-256 is stored in .batuta-state.json. Before any processing, the hash is checked:

Source file --> compute SHA-256 --> compare to cache
  |                                     |
  |  (match)                            |  (mismatch)
  v                                     v
  Skip                              Retranspile + update cache

AST Parse Cache

For Python files, the initial AST parse (used for import detection and ML framework scanning) is cached separately. This allows re-running analysis without re-parsing unchanged files.

Build Artifact Cache

After transpilation, cargo build uses its own incremental compilation cache in target/. Batuta does not manage this directly but ensures the output directory is stable across runs so that Cargo’s cache remains valid.

Cross-Run Persistence

All caches are stored in the project directory:

my-project/
  .batuta-state.json     # File hashes, dependency graph, workflow state
  .batuta-cache/         # AST parse cache, analysis results
  rust-output/
    target/              # Cargo's build cache (managed by Cargo)

Cache Invalidation

Caches are invalidated automatically when:

• A source file’s content hash changes
• The transpiler version changes (detected via --version)
• Configuration in batuta.toml changes
• The user passes --force to any command

CLI Usage

# Use cache (default behavior)
batuta transpile --cache

# Clear all caches
batuta cache clear

# Show cache statistics
batuta cache stats

Cache Statistics
----------------
File hashes:   142 entries (28 KB)
AST cache:      89 entries (1.2 MB)
Build cache:   managed by Cargo (340 MB)
Last full run: 2025-11-19 14:21:32 UTC

Cache Size Management

AST and analysis caches are bounded by a configurable maximum size. When the cache exceeds the limit, least-recently-used entries are evicted. Build artifacts are managed by Cargo and can be cleaned with cargo clean in the output directory.

Navigate: Table of Contents

Error Handling

Batuta applies the Toyota Production System principle of Jidoka (autonomation) to its pipeline: when an error is detected, the pipeline stops immediately rather than propagating broken state to downstream phases.

Validation Strategies

The TranspilationPipeline supports three error handling modes:

#![allow(unused)]
fn main() {
pub enum ValidationStrategy {
    StopOnError,      // Jidoka: halt on first failure
    ContinueOnError,  // Collect all errors, report at end
    None,             // Skip validation entirely
}
}

The default is StopOnError, which ensures no phase operates on invalid input.

Stop-on-Error Flow

Each pipeline stage is validated after execution. If validation fails under StopOnError, the pipeline bails immediately:

#![allow(unused)]
fn main() {
if !validation_result.passed
    && self.validation == ValidationStrategy::StopOnError
{
    anyhow::bail!(
        "Validation failed for stage '{}': {}",
        stage.name(),
        validation_result.message
    );
}
}

This prevents a cascade of errors where Phase 3 tries to optimize code that Phase 2 failed to transpile correctly.

Structured Error Types

Pipeline errors are wrapped with context using anyhow::Context:

#![allow(unused)]
fn main() {
ctx = stage
    .execute(ctx)
    .await
    .with_context(|| format!("Stage '{}' failed", stage.name()))?;
}

This produces error chains that trace back to the root cause:

Error: Stage 'Transpilation' failed
  Caused by: Tool 'depyler' failed with exit code 1
    stderr: Unsupported feature at line 42: async generators

Validation Results

Each stage produces a ValidationResult that is accumulated in the pipeline context:

#![allow(unused)]
fn main() {
pub struct ValidationResult {
    pub stage: String,
    pub passed: bool,
    pub message: String,
    pub details: Option<serde_json::Value>,
}
}

The final PipelineOutput checks all results: validation_passed is true only if every stage passed.

Workflow State on Failure

When a phase fails, WorkflowState::fail_phase() records the error and keeps current_phase pointed at the failed phase. The workflow does not advance. Downstream phases refuse to start until the prerequisite completes.

Recovery Pattern

# Phase fails
$ batuta transpile
Error: Transpilation failed for auth.py

# Fix the issue, then retry (incremental)
$ batuta transpile
Success: All files transpiled

# Now Phase 3 will accept
$ batuta optimize

Navigate: Table of Contents

Phase 3: Optimization

Phase 3 analyzes transpiled code for compute-intensive patterns and selects optimal execution backends using Mixture-of-Experts (MoE) routing.

Overview

After transpilation produces Rust code, the optimization phase identifies opportunities for hardware acceleration:

Transpiled .rs files
       │
       ▼
┌──────────────────┐
│ Pattern Scanner  │ ← Scan for matmul, reduce, iter patterns
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  MoE Router      │ ← BackendSelector::select_with_moe()
│  (5× PCIe Rule)  │
└────────┬─────────┘
         │
    ┌────┼────┐
    ▼    ▼    ▼
 Scalar SIMD  GPU     ← Per-pattern recommendation

The 5x PCIe Dispatch Rule

Based on Gregg & Hazelwood (2011), GPU dispatch is only beneficial when:

compute_time > 5 × transfer_time

This prevents wasteful GPU dispatch for small workloads where PCIe transfer overhead dominates. The --gpu-threshold flag controls the matrix size cutoff (default: 500).

Compute Pattern Classification

Cargo Profile Optimization

The optimizer writes [profile.release] settings to Cargo.toml:

Jidoka Integration

If optimization analysis fails (e.g., output directory missing), the phase is marked as failed in the workflow state machine. Subsequent phases (Validation, Build) will refuse to run until the issue is resolved.

CLI Reference

See batuta optimize for full command documentation.

Previous: Phase 2: Transpilation Next: Phase 4: Validation

SIMD Vectorization

SIMD (Single Instruction, Multiple Data) vectorization is the primary optimization target in Phase 3. The Trueno crate provides portable SIMD backends that accelerate element-wise and reduction operations across CPU architectures.

Supported SIMD Backends

Automatic Detection

Trueno detects the best available SIMD instruction set at runtime using cpuid (x86) or feature registers (ARM). When the BackendSelector returns Backend::SIMD, it maps to trueno::Backend::Auto, letting Trueno pick the optimal instruction set:

#![allow(unused)]
fn main() {
pub fn to_trueno_backend(backend: Backend) -> trueno::Backend {
    match backend {
        Backend::Scalar => trueno::Backend::Scalar,
        Backend::SIMD   => trueno::Backend::Auto,
        Backend::GPU    => trueno::Backend::GPU,
    }
}
}

When SIMD Is Selected

The MoE router selects SIMD for:

• Low complexity operations (element-wise add, multiply) at 1M+ elements
• Medium complexity operations (reductions, dot product) at 10K-100K elements
• High complexity operations (matrix multiply) at 1K-10K elements

Below these thresholds, scalar code is sufficient. Above them, GPU dispatch becomes beneficial.

Code Patterns That Benefit

Example: Vector Addition

#![allow(unused)]
fn main() {
use trueno::Vector;

let a = Vector::from_slice(&[1.0, 2.0, 3.0, 4.0]);
let b = Vector::from_slice(&[5.0, 6.0, 7.0, 8.0]);
let c = a.add(&b).unwrap();
// c = [6.0, 8.0, 10.0, 12.0]
// Automatically uses AVX2/AVX-512/NEON based on CPU
}

Verifying SIMD Usage

# Check which SIMD features are available
rustc --print cfg | grep target_feature

# Verify Trueno detected the correct backend
RUST_LOG=trueno=debug cargo run 2>&1 | grep "Selected backend"

Portability

Code using trueno::Backend::Auto compiles and runs on any platform. On systems without SIMD support, Trueno falls back to scalar loops with identical results. No conditional compilation or feature flags are needed in user code.

Navigate: Table of Contents

GPU Acceleration

GPU acceleration is the highest tier of the MoE backend selection in Phase 3. Batuta uses the wgpu crate (via Trueno) for portable GPU compute across Vulkan, Metal, DX12, and WebGPU.

The 5x PCIe Dispatch Rule

GPU dispatch incurs overhead from data transfer across the PCIe bus. Based on Gregg and Hazelwood (2011), GPU compute is only beneficial when:

compute_time > 5 * transfer_time

The BackendSelector implements this as a cost model:

#![allow(unused)]
fn main() {
pub fn select_backend(&self, data_bytes: usize, flops: u64) -> Backend {
    let transfer_s = data_bytes as f64 / self.pcie_bandwidth;
    let compute_s = flops as f64 / self.gpu_gflops;

    if compute_s > self.min_dispatch_ratio * transfer_s {
        Backend::GPU
    } else {
        Backend::SIMD
    }
}
}

Default parameters assume PCIe 4.0 x16 (32 GB/s) and A100-class throughput (20 TFLOPS).

When GPU Is Beneficial

Matrix Multiplication Example

#![allow(unused)]
fn main() {
let selector = BackendSelector::new();

// Small matrix: SIMD is faster
let backend = selector.select_for_matmul(64, 64, 64);
// --> Backend::SIMD

// Large matrix: GPU is faster
let backend = selector.select_for_matmul(1024, 1024, 1024);
// --> Backend::GPU
}

Customizing Thresholds

The selector can be configured for different hardware:

#![allow(unused)]
fn main() {
let selector = BackendSelector::new()
    .with_pcie_bandwidth(64e9)       // PCIe 5.0
    .with_gpu_gflops(40e12)          // RTX 4090
    .with_min_dispatch_ratio(3.0);   // More aggressive dispatch
}

GPU Backends via wgpu

Trueno abstracts GPU compute through wgpu, which maps to the native GPU API on each platform:

When to Avoid GPU

GPU dispatch should be avoided when:

• Data fits entirely in L1/L2 cache (SIMD will be faster)
• The operation is memory-bound (element-wise operations)
• The program will run in WASM without WebGPU support
• Latency matters more than throughput (kernel launch overhead is ~10us)

Navigate: Table of Contents

Memory Layout

The Sovereign AI Stack enforces a row-major tensor layout across all components. This is a critical architectural decision documented as LAYOUT-002 that affects aprender, realizar, and all model conversion pipelines.

LAYOUT-002: Row-Major Mandate

All tensors in the stack use row-major (C-style) memory layout. External formats that use column-major layout are transposed at import time.

External Formats                    Stack Internal (Row-Major)
----------------                    -------------------------
SafeTensors (row-major) ----------> APR v2 --> realizar --> output
                         (native)       ^
GGUF (column-major) ---------------/
                    (transposed by aprender)

Why Row-Major

Three factors drive this decision:

1. PyTorch/SafeTensors compatibility – HuggingFace models are natively row-major. No conversion needed for the most common import path.

2. Cache efficiency – Row-major matches C memory layout. When iterating over rows (the common case in matrix-vector products), data is contiguous in memory, maximizing L1/L2 cache utilization.

3. Kernel simplicity – Realizar’s fused quantization kernels (fused_q4k_parallel_matvec, fused_q6k_parallel_matvec) assume row-major layout. A single layout eliminates runtime branching.

Component Responsibilities

Diagnosing Layout Bugs

If model output produces garbage text like "olumbia+lsi nunca/localENTS" instead of coherent language, the root cause is almost always a layout mismatch: column-major data fed to a row-major kernel.

Fix: Ensure the model was converted through aprender’s GGUF converter, which transposes weight matrices to row-major.

Cache-Friendly Access Patterns

Row-major layout means elements in the same row are contiguous:

Row-major [3x4]:
  [a b c d | e f g h | i j k l]
   row 0     row 1     row 2

Column-major [3x4]:
  [a e i | b f j | c g k | d h l]
   col 0   col 1   col 2   col 3

For a matrix-vector product y = Wx, each output element computes dot(row_i, x). In row-major layout, row_i is a contiguous memory span, which the CPU prefetcher handles efficiently.

Quantized Tensor Layout

Quantized formats (Q4K, Q6K) store data in 256-element blocks. Each block contains scales, minimums, and quantized values packed together. The block layout is row-major at the block level:

APR v2 Format

The APR v2 binary format stores tensors with 64-byte alignment for zero-copy memory mapping. Metadata (including layout information) is padded to 64-byte boundaries:

[header] [metadata (64-byte aligned)] [tensor data (64-byte aligned)]

Navigate: Table of Contents

MoE Backend Selection

The Mixture-of-Experts (MoE) router is the core decision engine in Phase 3 optimization. It classifies each compute operation by complexity and data size, then selects the optimal backend: Scalar, SIMD, or GPU.

How MoE Routing Works

The BackendSelector::select_with_moe() method takes two inputs:

1. Operation complexity – Low, Medium, or High
2. Data size – number of elements in the operation

#![allow(unused)]
fn main() {
pub fn select_with_moe(&self, complexity: OpComplexity, data_size: usize) -> Backend {
    match complexity {
        OpComplexity::Low => {
            if data_size > 1_000_000 { Backend::SIMD }
            else { Backend::Scalar }
        }
        OpComplexity::Medium => {
            if data_size > 100_000 { Backend::GPU }
            else if data_size > 10_000 { Backend::SIMD }
            else { Backend::Scalar }
        }
        OpComplexity::High => {
            if data_size > 10_000 { Backend::GPU }
            else if data_size > 1_000 { Backend::SIMD }
            else { Backend::Scalar }
        }
    }
}
}

Complexity Classification

Threshold Table

These thresholds are derived from empirical benchmarks on Trueno SIMD kernels and the 5x PCIe dispatch rule from Gregg and Hazelwood (2011).

Per-Converter Integration

Each framework converter embeds complexity metadata in its operation mappings:

#![allow(unused)]
fn main() {
// NumPy
NumPyOp::Add.complexity()                         // Low
NumPyOp::Sum.complexity()                         // Medium
NumPyOp::Dot.complexity()                         // High

// sklearn
SklearnAlgorithm::StandardScaler.complexity()     // Low
SklearnAlgorithm::LinearRegression.complexity()   // Medium
SklearnAlgorithm::KMeans.complexity()             // High

// PyTorch
PyTorchOperation::TensorCreation.complexity()     // Low
PyTorchOperation::Linear.complexity()             // Medium
PyTorchOperation::Forward.complexity()            // High
}

End-to-End Example

#![allow(unused)]
fn main() {
let converter = NumPyConverter::new();

// Small array addition: Scalar
converter.recommend_backend(&NumPyOp::Add, 100);       // Scalar

// Large array addition: SIMD
converter.recommend_backend(&NumPyOp::Add, 2_000_000); // SIMD

// Large matrix multiply: GPU
converter.recommend_backend(&NumPyOp::Dot, 50_000);    // GPU
}

The cost model parameters are configurable for different hardware. See GPU Acceleration for tuning details.

Navigate: Table of Contents

Phase 4: Validation

Phase 4 verifies that transpiled code preserves the semantic behavior of the original source through multiple independent validation methods.

Overview

Validation is the critical quality gate before deployment. It answers: “Does the transpiled code do the same thing as the original?”

Original Binary ──┬── Syscall Trace ──┐
                  ├── Stdout Capture ──┤── Compare ── Pass/Fail
Transpiled Binary ┬── Syscall Trace ──┘             │
                  ├── Stdout Capture ──────────────┘
                  ├── cargo test ───── Test Results ──┘
                  └── Timing ──── Benchmark Report ───┘

Validation Methods

1. Syscall Tracing (Renacer)

The deepest validation: traces system calls made by both binaries using the Renacer tracer. If the syscall sequences match, the programs exhibit equivalent OS-level behavior.

batuta validate --trace-syscalls

Uses ValidationStage from the pipeline library, which creates a Tokio runtime to execute the async tracing comparison.

2. Output Comparison

Runs both binaries and compares stdout line-by-line. Differences are displayed in a unified diff format (truncated to 20 lines). This catches functional regressions where the program logic diverges.

batuta validate --diff-output

3. Test Suite Execution

Runs cargo test in the transpiled output directory. This validates that any tests generated during transpilation (or manually added) pass. The output directory is read from batuta.toml (transpilation.output_dir).

batuta validate --run-original-tests

4. Performance Benchmarking

Times both binaries over 3 iterations and reports the average execution time and speedup factor. This is informational — performance regression does not fail the validation phase.

batuta validate --benchmark

Jidoka Stop-on-Error

Each validation method independently contributes to the overall pass/fail result. If any enabled method detects a mismatch:

1. The Validation phase is marked as failed in the workflow state
2. The failure reason is recorded
3. Phase 5 (Build) will refuse to start until validation passes

Missing binaries (for syscall tracing, diff, or benchmark) are treated as warnings, not failures. This allows validation to proceed even in environments where the original binary is not available.

CLI Reference

See batuta validate for full command documentation.

Previous: Phase 3: Optimization Next: Phase 5: Deployment

Syscall Tracing

Syscall tracing is the deepest validation method in Phase 4. It uses the Renacer tool to capture system calls made by both the original and transpiled programs, then compares the sequences to verify behavioral equivalence at the OS level.

Why Syscall Tracing

Unit tests verify individual functions. Output comparison verifies stdout. Syscall tracing verifies everything else: file operations, network calls, memory mapping, process management, and signal handling. If two programs make the same system calls in the same order with the same arguments, they exhibit equivalent OS-level behavior.

How It Works

Original program -----> Renacer -----> Syscall trace A
                                              |
Transpiled program ---> Renacer -----> Syscall trace B
                                              |
                                        Compare A vs B
                                              |
                                        Pass / Fail

Renacer intercepts system calls using ptrace (Linux) and records each call with:

• Syscall number and name (e.g., open, read, write)
• Arguments (file paths, buffer sizes, flags)
• Return value
• Timestamp

Source-Aware Correlation

Renacer provides source-level correlation: each syscall is linked back to the source line that triggered it. This makes debugging mismatches straightforward:

Mismatch at syscall #47:
  Original:   write(1, "Hello, World!\n", 14) = 14    [main.py:12]
  Transpiled: write(1, "Hello World!\n", 13)  = 13    [main.rs:18]
                          ^ missing comma

CLI Usage

# Run syscall validation
batuta validate --trace-syscalls

# Run with verbose trace output
batuta validate --trace-syscalls --verbose

# Compare specific binaries
batuta validate --trace-syscalls \
    --original ./python_app \
    --transpiled ./rust-output/target/release/app

What Is Compared

Filtering Noise

Some syscalls are non-deterministic by nature (e.g., brk for heap allocation, mmap for library loading). Renacer applies filters to exclude these from comparison:

• Memory management syscalls (brk, mmap, munmap)
• Thread scheduling (futex, sched_yield)
• Signal handling (rt_sigaction, rt_sigprocmask)
• Clock queries (clock_gettime)

Limitations

Syscall tracing requires:

• Linux (uses ptrace; macOS and Windows are not supported)
• Both original and transpiled binaries must be executable
• Programs must be deterministic (same input produces same syscall sequence)

When the original binary is not available (e.g., the source was Python without a compiled binary), syscall tracing is skipped with a warning rather than a failure.

Navigate: Table of Contents

Output Comparison

Output comparison runs both the original and transpiled programs with identical input and verifies that their stdout output matches. This is the most intuitive validation method: if both programs print the same thing, they likely compute the same result.

Comparison Process

Input data ------> Original program ------> Capture stdout A
     |
     +-----------> Transpiled program ----> Capture stdout B
                                                   |
                                            Compare A vs B
                                                   |
                                            Pass / Fail

Byte-Level Comparison

The default comparison mode is byte-level exact match. Each line of stdout from the original program must be identical to the corresponding line from the transpiled program.

Differences are displayed in unified diff format, truncated to 20 lines:

--- original output
+++ transpiled output
@@ -3,4 +3,4 @@
 Processing batch 1...
 Processing batch 2...
-Total: 42.0
+Total: 42.00000000000001
 Done.

Numerical Tolerance

Floating-point computations may produce slightly different results due to instruction ordering differences between Python and Rust. Batuta supports configurable tolerance:

# Exact comparison (default)
batuta validate --diff-output

# With floating-point tolerance
batuta validate --diff-output --tolerance 1e-6

Structured Output Comparison

For programs that produce structured output (JSON, CSV, XML), Batuta can perform semantic comparison rather than byte-level diff:

# JSON comparison (ignores key ordering)
batuta validate --diff-output --format json

# CSV comparison (ignores column ordering)
batuta validate --diff-output --format csv

CLI Usage

# Basic output comparison
batuta validate --diff-output

# With specific input file
batuta validate --diff-output --input test-data.txt

# Compare specific binaries
batuta validate --diff-output \
    --original ./run_original.sh \
    --transpiled ./rust-output/target/release/app

Handling Non-Determinism

Some programs produce non-deterministic output (timestamps, random numbers, process IDs). Strategies for handling this:

1. Seed random generators – pass --seed 42 to both programs
2. Filter timestamps – --ignore-pattern '\d{4}-\d{2}-\d{2}'
3. Sort output – --sort-lines for set-like output

If the original program binary is not available, the comparison is skipped with a warning rather than a failure.

Navigate: Table of Contents

Test Suite Execution

Test suite execution validates the transpiled Rust code by running cargo test in the output directory. This catches regressions in both transpiler-generated tests and manually written tests.

How It Works

The ValidationStage reads the output directory from batuta.toml and runs the test suite:

# Batuta runs this internally
cd ./rust-output && cargo test

Test output is captured and parsed. A non-zero exit code marks the validation as failed.

Test Sources

Transpiled projects can contain tests from multiple origins:

Property-Based Testing

For numerical code (common in ML pipelines), property-based testing with proptest provides stronger guarantees than example-based tests:

#![allow(unused)]
fn main() {
use proptest::prelude::*;

proptest! {
    #[test]
    fn vector_add_commutative(
        a in prop::collection::vec(-1e6f32..1e6, 1..1000),
        b in prop::collection::vec(-1e6f32..1e6, 1..1000),
    ) {
        let len = a.len().min(b.len());
        let a = &a[..len];
        let b = &b[..len];
        // a + b == b + a
        let result1 = vector_add(a, b);
        let result2 = vector_add(b, a);
        assert_eq!(result1, result2);
    }
}
}

Coverage Tracking

Batuta integrates with cargo llvm-cov to track test coverage of the transpiled code:

# Run tests with coverage
batuta validate --run-original-tests --coverage

# Coverage report
batuta validate --coverage-report

Coverage: 87.3% (target: 95%)
  src/main.rs     92.1%
  src/utils.rs    84.5%
  src/parser.rs   79.2%  <-- below target

CLI Usage

# Run transpiled test suite
batuta validate --run-original-tests

# Run with verbose test output
batuta validate --run-original-tests --verbose

# Run specific test
batuta validate --run-original-tests --test test_name

# Run with nextest for parallel execution
batuta validate --run-original-tests --nextest

Test Failure Handling

Test failures are recorded in the ValidationResult with full output. The validation phase is marked as failed, blocking Phase 5 (Deployment) until all tests pass.

Navigate: Table of Contents

Benchmarking

Benchmarking measures the performance of the transpiled Rust binary against the original program. It is the final check in Phase 4, providing quantitative evidence that the migration preserved or improved performance.

Benchmark Method

Batuta runs both binaries multiple times and computes average execution time:

Original program   x3 iterations --> avg: 1.24s
Transpiled program x3 iterations --> avg: 0.31s
                                     Speedup: 4.0x

The number of iterations is configurable. Three iterations is the default to balance accuracy against validation time.

Benchmark Report

$ batuta validate --benchmark

Performance Benchmark
---------------------
Original:    1.243s (avg of 3 runs)
Transpiled:  0.312s (avg of 3 runs)
Speedup:     3.99x

Breakdown:
  Run 1: 1.251s vs 0.315s
  Run 2: 1.238s vs 0.310s
  Run 3: 1.241s vs 0.311s

Status: PASS (informational -- regression does not fail validation)

Criterion Integration

For micro-benchmarking individual functions, transpiled projects can include Criterion benchmarks. Criterion provides statistical analysis, regression detection, and HTML reports:

# Run Criterion benchmarks in the transpiled project
cd rust-output && cargo bench

Regression Detection

While the Phase 4 benchmark is informational (it does not fail the pipeline), Criterion benchmarks can detect regressions between runs:

matmul_1024x1024    time: [312.45 us 315.21 us 318.02 us]
                    change: [+2.1% +3.4% +4.8%] (p = 0.02 < 0.05)
                    Performance has regressed.

Before/After Comparison

CLI Usage

# Run performance benchmark
batuta validate --benchmark

# With custom iteration count
batuta validate --benchmark --iterations 10

# Save benchmark results to file
batuta validate --benchmark --output benchmark-results.json

Navigate: Table of Contents

Phase 5: Deployment

Phase 5 builds the transpiled Rust project into a final binary, with support for release optimization, cross-compilation, and WebAssembly targets.

Overview

Deployment is the final phase of the transpilation pipeline. It compiles the validated Rust code into a distributable binary:

Validated .rs project
       │
       ▼
┌──────────────────────────┐
│  cargo build             │
│  --release               │ ← Optional: release mode
│  --target <triple>       │ ← Optional: cross-compile
│  --target wasm32-unknown │ ← Optional: WebAssembly
│  [extra cargo_flags]     │ ← From batuta.toml
└────────────┬─────────────┘
             │
             ▼
    Final Binary / .wasm

Build Modes

Debug Build

Default mode for quick iteration:

batuta build

Release Build

Optimized binary with the profile settings from Phase 3:

batuta build --release

WebAssembly

Builds for wasm32-unknown-unknown target:

batuta build --wasm --release

Cross-Compilation

Target a specific platform:

batuta build --release --target aarch64-unknown-linux-gnu
batuta build --release --target x86_64-apple-darwin

Configuration

Build settings are read from batuta.toml:

[transpilation]
output_dir = "./rust-output"    # Compiled project location

[build]
cargo_flags = ["--locked"]      # Extra flags for cargo build

The build command:

1. Reads transpilation.output_dir to locate the project
2. Verifies Cargo.toml exists
3. Appends build.cargo_flags to the cargo command
4. Runs cargo build with inherited stdio

Jidoka Integration

Build failures (non-zero cargo exit code) mark the Deployment phase as failed in the workflow state. The exit code is captured and reported. Success marks the full 5-phase migration as complete.

Beyond batuta build

For production deployment of ML models (not transpiled code), Batuta also provides:

• batuta serve — Serve models via Realizar with OpenAI-compatible API
• batuta deploy — Generate Docker, Lambda, K8s, Fly.io, or Cloudflare deployments
• batuta pacha — Model registry with versioning and Ed25519 signatures

CLI Reference

See batuta build for full command documentation.

Previous: Phase 4: Validation Next: Part III: The Tool Ecosystem

Release Builds

Release builds produce optimized binaries for production deployment. Phase 5 applies Cargo profile settings tuned during Phase 3 optimization.

Optimization Profiles

Phase 3 writes [profile.release] settings to the output project’s Cargo.toml. Three profiles are available:

Cargo.toml Configuration

[profile.release]
opt-level = 3
lto = "fat"
codegen-units = 1
strip = "symbols"
panic = "abort"

What Each Setting Does

opt-level = 3 – Maximum optimization. Enables auto-vectorization, loop unrolling, and function inlining beyond the default level 2.

lto = "fat" – Link-Time Optimization across all crates. Allows the linker to optimize across crate boundaries, eliminating dead code and enabling cross-crate inlining. Increases build time significantly.

codegen-units = 1 – Forces single-threaded code generation. This allows LLVM to see the entire crate at once, enabling better optimization at the cost of slower compilation.

strip = "symbols" – Removes debug symbols from the final binary, reducing size by 50-80%.

panic = "abort" – Generates abort on panic instead of unwinding. Reduces binary size and improves performance by eliminating unwind tables.

Profile-Guided Optimization (PGO)

For maximum performance, PGO uses a profiling run to guide optimization:

# Step 1: Build with instrumentation
RUSTFLAGS="-Cprofile-generate=/tmp/pgo-data" \
    cargo build --release

# Step 2: Run representative workload
./target/release/app < benchmark-input.txt

# Step 3: Rebuild with profile data
RUSTFLAGS="-Cprofile-use=/tmp/pgo-data/merged.profdata" \
    cargo build --release

PGO typically provides an additional 5-15% speedup over standard release builds by optimizing branch prediction and code layout.

Size Optimization

For deployment-constrained environments (embedded, WASM):

[profile.release]
opt-level = "z"      # Optimize for size
lto = true
codegen-units = 1
strip = true
panic = "abort"

CLI Usage

# Standard release build
batuta build --release

# With aggressive optimization
batuta build --release --profile aggressive

# Check binary size
ls -lh rust-output/target/release/app

Navigate: Table of Contents

Cross-Compilation

Cross-compilation builds the transpiled Rust project for a target platform different from the host. Batuta supports cross-compilation through Cargo’s target triple system and the cross tool.

Target Triples

A target triple specifies the architecture, vendor, OS, and ABI:

<arch>-<vendor>-<os>-<abi>

Common Targets

Using Cargo Directly

# Install target toolchain
rustup target add aarch64-unknown-linux-gnu

# Cross-compile
batuta build --release --target aarch64-unknown-linux-gnu

Using the cross Tool

The cross tool uses Docker containers with pre-configured cross-compilation toolchains:

# Install cross
cargo install cross

# Cross-compile without manual toolchain setup
cross build --release --target aarch64-unknown-linux-gnu

This is the recommended approach because it handles linker configuration, system libraries, and C dependencies automatically.

musl Static Linking

The musl target produces fully static binaries with no dynamic library dependencies, ideal for Docker scratch containers, Lambda functions, and air-gapped environments:

rustup target add x86_64-unknown-linux-musl
batuta build --release --target x86_64-unknown-linux-musl

WebAssembly Target

WASM builds require special handling. See the Batuta wasm feature flag:

# WASM debug build
batuta build --wasm

# WASM release build
batuta build --wasm --release

The WASM build disables filesystem access and uses in-memory analysis, controlled by the wasm feature flag in Cargo.toml.

Configuration

Cross-compilation settings in batuta.toml:

[build]
target = "x86_64-unknown-linux-musl"
cargo_flags = ["--locked"]

Navigate: Table of Contents

WebAssembly (WASM) Build Target

“Batuta in the browser: Analyze, convert, and optimize code without leaving your documentation or web IDE.”

Overview

Batuta can be compiled to WebAssembly (WASM) to run directly in web browsers, enabling client-side code analysis, conversion demonstrations, and interactive documentation. This brings Batuta’s core capabilities to:

• Interactive documentation with live code conversion examples
• Web-based IDEs integrating Batuta’s analysis engine
• Educational platforms demonstrating transpilation techniques
• Browser extensions for code quality analysis
• Offline-first web applications without server-side dependencies

Why WASM?

Running Batuta in the browser provides several advantages:

1. Zero Server Costs

All analysis and conversion happens client-side. No need for backend infrastructure to demonstrate transpilation capabilities.

2. Instant Feedback

No network latency - code analysis and conversion results appear immediately as users type.

3. Privacy

User code never leaves their browser. Perfect for proprietary code analysis or security-sensitive environments.

4. Educational Value

Interactive examples in documentation allow users to experiment with Batuta’s features before installing.

5. Integration Flexibility

Embed Batuta into React, Vue, or vanilla JavaScript applications as a lightweight library.

Building for WASM

Prerequisites

Install the WASM toolchain:

# Add WASM target
rustup target add wasm32-unknown-unknown

# Install wasm-bindgen CLI (matches Cargo.toml version)
cargo install wasm-bindgen-cli --version 0.2.89

# Install wasm-opt for size optimization (optional)
cargo install wasm-opt

Quick Build

Use the provided build script:

# Debug build (faster compilation, larger size)
./scripts/build-wasm.sh debug

# Release build (optimized, ~500-800 KB)
./scripts/build-wasm.sh release

The script will:

1. Compile Rust to WASM (wasm32-unknown-unknown target)
2. Generate JavaScript bindings (wasm-bindgen)
3. Optimize WASM binary (wasm-opt -Oz)
4. Copy browser demo files to wasm-dist/

Manual Build

For custom builds:

# Build WASM module
cargo build --target wasm32-unknown-unknown \
    --no-default-features \
    --features wasm \
    --release

# Generate JavaScript bindings
wasm-bindgen target/wasm32-unknown-unknown/release/batuta.wasm \
    --out-dir wasm-dist \
    --target web \
    --no-typescript

# Optimize (optional, reduces size by 30-50%)
wasm-opt -Oz wasm-dist/batuta_bg.wasm \
    -o wasm-dist/batuta_bg_opt.wasm

Build Output

After building, wasm-dist/ contains:

wasm-dist/
├── batuta.js              # JavaScript glue code
├── batuta_bg.wasm         # WASM module (~1.5 MB debug)
├── batuta_bg_opt.wasm     # Optimized WASM (~500 KB release)
├── index.html             # Interactive demo
└── README.md              # Integration guide

JavaScript API

Batuta exposes a JavaScript-friendly API via wasm-bindgen. All functions are asynchronous and return Promises.

Initialization

import init, * as batuta from './batuta.js';

// Initialize WASM module (call once)
await init();

// Module is ready to use
console.log('Batuta version:', batuta.version());

Code Analysis

Detect language and ML library usage:

const code = `
import numpy as np
import sklearn.linear_model as lm

X = np.array([[1, 2], [3, 4]])
model = lm.LinearRegression()
`;

const analysis = batuta.analyze_code(code);

console.log(analysis);
// Output:
// {
//   language: "Python",
//   has_numpy: true,
//   has_sklearn: true,
//   has_pytorch: false,
//   lines_of_code: 5
// }

NumPy Conversion

Convert NumPy operations to Trueno:

const numpy_code = "np.add(a, b)";
const data_size = 10000;

const result = batuta.convert_numpy(numpy_code, data_size);

console.log(result);
// Output:
// {
//   rust_code: "trueno::add(&a, &b)",
//   imports: ["use trueno;"],
//   backend_recommendation: "SIMD",
//   explanation: "Array addition using SIMD vectorization"
// }

For GPU-scale operations:

const large_matmul = "np.dot(a, b)";
const gpu_size = 1000000;

const result = batuta.convert_numpy(large_matmul, gpu_size);

// backend_recommendation: "GPU"
// Uses trueno's CUDA/Metal backend for large matrices

sklearn Conversion

Convert scikit-learn to Aprender:

const sklearn_code = "LinearRegression()";

const result = batuta.convert_sklearn(sklearn_code, 5000);

console.log(result);
// Output:
// {
//   rust_code: "aprender::LinearRegression::new()",
//   imports: ["use aprender::LinearRegression;"],
//   backend_recommendation: "CPU",
//   explanation: "First-principles linear regression implementation"
// }

Supported algorithms:

• Linear Models: LinearRegression, LogisticRegression, Ridge, Lasso
• Clustering: KMeans, DBSCAN
• Ensemble: RandomForest (limited support)
• Preprocessing: StandardScaler, MinMaxScaler

PyTorch Conversion

Convert PyTorch inference to Realizar:

const pytorch_code = "model.generate(prompt, max_length=100)";

const result = batuta.convert_pytorch(pytorch_code, 2000);

console.log(result);
// Output:
// {
//   rust_code: "realizar::generate_text(&model, prompt, 100)",
//   imports: ["use realizar;"],
//   backend_recommendation: "GPU",
//   explanation: "Optimized LLM inference with KV cache"
// }

Backend Recommendation

Get MoE backend selection for specific operations:

// Small dataset → CPU
const backend1 = batuta.backend_recommend("matrix_multiply", 1000);
console.log(backend1); // "CPU"

// Medium dataset → SIMD
const backend2 = batuta.backend_recommend("matrix_multiply", 50000);
console.log(backend2); // "SIMD"

// Large dataset → GPU
const backend3 = batuta.backend_recommend("matrix_multiply", 1000000);
console.log(backend3); // "GPU"

Supported operation types:

• "matrix_multiply" - Dense matrix multiplication
• "element_wise" - Element-wise operations (add, sub, mul)
• "reduction" - Sum, mean, max, min
• "dot_product" - Vector dot products
• "convolution" - 2D convolutions (CNN)
• "linear_regression" - ML training
• "kmeans" - Clustering
• "text_generation" - LLM inference

Browser Integration

Vanilla JavaScript

<!DOCTYPE html>
<html>
<head>
    <title>Batuta WASM Demo</title>
</head>
<body>
    <textarea id="code" rows="10" cols="80">
import numpy as np
x = np.array([1, 2, 3])
    </textarea>
    <button onclick="analyzeCode()">Analyze</button>
    <pre id="output"></pre>

    <script type="module">
        import init, * as batuta from './batuta.js';

        await init();

        window.analyzeCode = async () => {
            const code = document.getElementById('code').value;
            const result = batuta.analyze_code(code);
            document.getElementById('output').textContent =
                JSON.stringify(result, null, 2);
        };
    </script>
</body>
</html>

React Integration

import { useEffect, useState } from 'react';
import init, * as batuta from './batuta.js';

function BatutaConverter() {
    const [initialized, setInitialized] = useState(false);
    const [code, setCode] = useState('');
    const [result, setResult] = useState(null);

    useEffect(() => {
        init().then(() => setInitialized(true));
    }, []);

    const handleConvert = () => {
        if (!initialized) return;

        const analysis = batuta.analyze_code(code);
        if (analysis.has_numpy) {
            const conversion = batuta.convert_numpy(code, 10000);
            setResult(conversion);
        }
    };

    return (
        <div>
            <textarea
                value={code}
                onChange={(e) => setCode(e.target.value)}
                placeholder="Paste NumPy code here..."
            />
            <button onClick={handleConvert} disabled={!initialized}>
                Convert to Rust
            </button>
            {result && (
                <pre>{result.rust_code}</pre>
            )}
        </div>
    );
}

Vue Integration

<template>
    <div>
        <textarea v-model="code"></textarea>
        <button @click="analyze" :disabled="!ready">
            Analyze
        </button>
        <pre v-if="analysis">{{ analysis }}</pre>
    </div>
</template>

<script>
import init, * as batuta from './batuta.js';

export default {
    data() {
        return {
            ready: false,
            code: '',
            analysis: null
        };
    },
    async mounted() {
        await init();
        this.ready = true;
    },
    methods: {
        analyze() {
            this.analysis = batuta.analyze_code(this.code);
        }
    }
};
</script>

Feature Flags

Batuta uses conditional compilation to support both native and WASM builds:

# Cargo.toml
[features]
default = ["native"]

native = [
    "clap",           # CLI parsing
    "walkdir",        # Filesystem traversal
    "tracing",        # Logging
    "serde_yaml",     # Config files
    # ... native-only dependencies
]

wasm = [
    "wasm-bindgen",       # JS bindings
    "wasm-bindgen-futures",
    "js-sys",             # JavaScript types
    "web-sys",            # Web APIs
]

This allows:

• Native builds: Full CLI with file I/O, logging, process spawning
• WASM builds: Browser-safe API with in-memory operations

Limitations

The WASM build has intentional limitations compared to the native CLI:

No Filesystem Access

• ❌ Cannot read/write files directly
• ✅ Works with in-memory code strings
• Workaround: Use File API in browser to read user-selected files

No Process Spawning

• ❌ Cannot call external transpilers (Decy, Depyler, Bashrs)
• ✅ Can analyze code and recommend conversions
• Workaround: Use WASM for analysis, native CLI for actual transpilation

No Logging Infrastructure

• ❌ No tracing or env_logger support
• ✅ Uses JavaScript console.log() via web-sys
• Workaround: Stub macros for logging (info!, debug!, etc.)

Synchronous-Only API

• ❌ No async file I/O or network requests
• ✅ All API calls are instant (no disk I/O)
• Workaround: Use Web Workers for long-running analysis

Size Constraints

• Release WASM binary: ~500-800 KB (after wasm-opt -Oz)
• Debug binary: ~1.5-2 MB
• Optimization: Use wasm-opt, enable LTO, strip debug symbols

Capabilities

Despite limitations, WASM builds support:

✅ Language Detection: Identify Python, C, C++, Shell, Rust, JavaScript ✅ ML Library Detection: Recognize NumPy, sklearn, PyTorch usage ✅ Code Conversion: Generate Rust equivalents for ML operations ✅ Backend Selection: MoE-based compute backend recommendations ✅ Quality Analysis: Complexity estimation (without full PMAT) ✅ Interactive Demos: Real-time code analysis in documentation

Size Optimization

Reduce WASM binary size:

1. Use wasm-opt

wasm-opt -Oz input.wasm -o output.wasm

Savings: 30-50% reduction in file size.

2. Enable LTO

# Cargo.toml
[profile.release]
lto = true
codegen-units = 1
opt-level = "z"  # Optimize for size

3. Strip Debug Symbols

[profile.release]
strip = true
debug = false

4. Remove Unused Features

Only include necessary WASM features:

[dependencies.web-sys]
features = [
    "console",  # Only if logging needed
    # Omit unused features like "Window", "Document", etc.
]

5. Use wee_alloc

Smaller allocator for WASM:

[dependencies]
wee_alloc = "0.4"

#![allow(unused)]
fn main() {
#[cfg(feature = "wasm")]
#[global_allocator]
static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT;
}

Savings: 10-20 KB reduction.

Deployment

Static Hosting

Serve WASM files from any static host:

# GitHub Pages
cp -r wasm-dist/* docs/demo/

# Netlify
netlify deploy --dir=wasm-dist

# Vercel
vercel wasm-dist/

CDN Distribution

Use a CDN for faster global access:

<script type="module">
    import init from 'https://cdn.example.com/batuta/batuta.js';
    await init('https://cdn.example.com/batuta/batuta_bg.wasm');
</script>

npm Package

Publish as an npm package:

{
  "name": "@paiml/batuta-wasm",
  "version": "0.1.0",
  "files": ["batuta.js", "batuta_bg.wasm"],
  "main": "batuta.js",
  "type": "module"
}

Users can install via:

npm install @paiml/batuta-wasm

Practical Use Cases

1. Interactive Documentation

Embed live code examples in Batuta’s docs:

Try converting NumPy code to Trueno:

<textarea id="numpy-input">np.dot(a, b)</textarea>
<button onclick="convertNumpy()">Convert</button>
<pre id="rust-output"></pre>

2. Web-Based Code Review

Build a browser extension that analyzes Python code for migration potential:

// Chrome extension content script
const code = getSelectedCodeFromGitHub();
const analysis = batuta.analyze_code(code);

if (analysis.has_numpy) {
    showMigrationSuggestion("This code can be 10x faster with Trueno!");
}

3. Educational Platforms

Interactive Rust learning platform:

• Students paste Python code
• Batuta generates Rust equivalent
• Side-by-side comparison with explanations
• Instant feedback without server costs

4. Code Quality Dashboards

Real-time complexity analysis:

const files = await loadProjectFiles();
const analyses = files.map(f => batuta.analyze_code(f.content));

const avgComplexity = analyses.reduce((sum, a) =>
    sum + a.lines_of_code, 0) / analyses.length;

renderDashboard({ avgComplexity, mlLibraries: ... });

5. Offline-First Migration Tool

Progressive Web App (PWA) for code migration:

• Works without internet connection
• Stores project state in IndexedDB
• Generates Rust code locally
• Syncs to cloud when online

Testing WASM Builds

Run WASM-specific tests:

# Run tests targeting WASM
cargo test --target wasm32-unknown-unknown \
    --no-default-features \
    --features wasm \
    --lib

# Run in headless browser (requires wasm-pack)
wasm-pack test --headless --firefox

Add WASM-specific tests:

#![allow(unused)]
fn main() {
#[cfg(all(test, target_arch = "wasm32"))]
mod wasm_tests {
    use super::*;
    use wasm_bindgen_test::*;

    #[wasm_bindgen_test]
    fn test_analyze_python() {
        let code = "import numpy as np";
        let result = analyze_code(code).unwrap();
        assert_eq!(result.language, "Python");
        assert!(result.has_numpy);
    }
}
}

Next Steps

• Tool Selection: How Batuta selects transpilers
• MoE Backend Selection: Mixture-of-Experts algorithm details
• Phase 3: Optimization: Backend-specific optimizations

Navigate: Table of Contents

Docker Containerization

“Package Batuta and all transpilation tools in reproducible containers for consistent development, CI/CD, and deployment.”

Overview

Batuta provides comprehensive Docker support for containerized development, testing, and deployment. Docker ensures:

• Reproducible environments across development, CI/CD, and production
• Isolated toolchains with all transpilers (Decy, Depyler, Bashrs) pre-installed
• Zero setup time for new team members
• Consistent CI/CD builds without “works on my machine” issues
• Multi-stage builds for minimal production image sizes

Quick Start

Running Batuta in Docker

# Pull the production image (when published)
docker pull paiml/batuta:latest

# Run Batuta CLI
docker run --rm -v $(pwd):/workspace paiml/batuta:latest \
    batuta analyze /workspace/my_project

Building Locally

# Build production image
make docker

# Build development image (with hot reload)
make docker-dev

# Run tests in container
make docker-test

Docker Images

Batuta provides three Docker images for different use cases:

1. Production Image (batuta:latest)

Minimal image for running Batuta CLI in production:

• Base: debian:bookworm-slim (minimal Debian)
• Size: ~150-200 MB (multi-stage build)
• Contents: Batuta binary only, minimal runtime dependencies
• User: Non-root user (batuta:1000)
• Use case: Production deployments, CI/CD pipelines

docker build -t batuta:latest .

2. Development Image (batuta:dev)

Full development environment with hot reload:

• Base: rust:1.75-slim
• Size: ~2-3 GB (includes Rust toolchain, build cache)
• Contents: Full Rust toolchain, source code, cargo watch
• Volumes: Cargo cache, target directory, source code
• Use case: Local development, interactive debugging

docker build -f Dockerfile.dev -t batuta:dev .

3. CI Image (batuta:ci)

Optimized for CI/CD pipelines:

• Base: Same as production
• Size: ~150-200 MB
• Contents: Batuta + test dependencies
• Use case: Automated testing, quality gates, PR checks

docker-compose up --abort-on-container-exit ci

Multi-Stage Build

The production Dockerfile uses multi-stage builds to minimize image size:

# ============================================
# Stage 1: Builder
# ============================================
FROM rust:1.75-slim as builder

# Install build dependencies
RUN apt-get update && apt-get install -y \
    pkg-config \
    libssl-dev \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /build

# Copy dependency files first (layer caching)
COPY Cargo.toml Cargo.lock ./

# Build dependencies only (cached layer)
RUN mkdir src && \
    echo "fn main() {}" > src/main.rs && \
    cargo build --release --features native --locked && \
    rm -rf src

# Copy source code
COPY src ./src
COPY examples ./examples

# Build Batuta (only rebuilds if source changed)
RUN cargo build --release --features native --locked

# ============================================
# Stage 2: Runtime
# ============================================
FROM debian:bookworm-slim

# Install runtime dependencies only
RUN apt-get update && apt-get install -y \
    ca-certificates \
    libssl3 \
    && rm -rf /var/lib/apt/lists/*

# Create non-root user
RUN useradd -m -u 1000 -s /bin/bash batuta

# Copy binary from builder
COPY --from=builder /build/target/release/batuta /usr/local/bin/batuta

# Set working directory
WORKDIR /workspace

# Switch to non-root user
USER batuta

# Default command
CMD ["batuta", "--help"]

Key optimizations:

1. Dependency caching: Build dependencies in separate layer (rarely changes)
2. Minimal runtime: Only copy final binary to runtime stage
3. Clean APT cache: Remove package lists after installation
4. Non-root user: Security best practice
5. Locked dependencies: Use Cargo.lock for reproducibility

Size reduction:

• Before multi-stage: ~1.5 GB (includes Rust toolchain)
• After multi-stage: ~150 MB (only runtime dependencies)
• Savings: ~1.35 GB (90% reduction)

Docker Compose

Batuta includes docker-compose.yml for orchestrating 5 services:

version: '3.8'

services:
  # ==========================================
  # Production CLI
  # ==========================================
  batuta:
    build:
      context: .
      dockerfile: Dockerfile
    image: batuta:latest
    volumes:
      - .:/workspace:rw
      - cargo-cache:/usr/local/cargo/registry
    working_dir: /workspace
    command: batuta --help

  # ==========================================
  # Development (hot reload)
  # ==========================================
  dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    image: batuta:dev
    volumes:
      - .:/workspace:rw
      - cargo-cache:/usr/local/cargo/registry
      - cargo-git:/usr/local/cargo/git
      - target-cache:/workspace/target
    working_dir: /workspace
    command: cargo watch -x check -x test -x run
    environment:
      - RUST_LOG=batuta=debug

  # ==========================================
  # CI/CD Testing
  # ==========================================
  ci:
    image: batuta:latest
    volumes:
      - .:/workspace:ro  # Read-only for CI
    working_dir: /workspace
    command: >
      bash -c "cargo test --all --features native &&
               cargo clippy --all-targets --all-features -- -D warnings"

  # ==========================================
  # WASM Build
  # ==========================================
  wasm:
    image: batuta:dev
    volumes:
      - .:/workspace:rw
      - cargo-cache:/usr/local/cargo/registry
      - target-cache:/workspace/target
    working_dir: /workspace
    command: cargo build --target wasm32-unknown-unknown --no-default-features --features wasm

  # ==========================================
  # Documentation Server
  # ==========================================
  docs:
    image: nginx:alpine
    volumes:
      - ./target/doc:/usr/share/nginx/html:ro
    ports:
      - "8000:80"
    depends_on:
      - batuta

# ==========================================
# Named Volumes (persistent cache)
# ==========================================
volumes:
  cargo-cache:
    driver: local
  cargo-git:
    driver: local
  target-cache:
    driver: local

Service Descriptions

Volume Mounts

Named volumes for caching (persist across container restarts):

• cargo-cache: Cargo registry cache (~500 MB, rarely changes)
• cargo-git: Git dependencies cache
• target-cache: Build artifacts cache (~1-2 GB, speeds up rebuilds)

Bind mounts for live editing:

• .:/workspace:rw: Source code (read-write)
• .:/workspace:ro: Source code (read-only for CI)

Usage Patterns

1. Local Development

Start development container with hot reload:

# Start dev container
docker-compose up dev

# In another terminal, edit source code
vim src/main.rs

# Container automatically recompiles and runs tests
# Output shows in first terminal

Features:

• Automatic recompilation on file save
• Runs tests on every change
• Persistent cargo cache across restarts
• Full Rust toolchain available

2. Running CLI Commands

Execute Batuta commands in isolated container:

# Analyze a Python project
docker-compose run --rm batuta \
    batuta analyze /workspace/my_python_project

# Transpile with Depyler
docker-compose run --rm batuta \
    batuta transpile --input /workspace/src --output /workspace/target/rust

# Generate migration report
docker-compose run --rm batuta \
    batuta report --format html --output /workspace/report.html

Note: Use /workspace/ prefix for paths (container working directory).

3. CI/CD Integration

Run tests in clean container (CI/CD pipeline):

# Run full test suite + linting
docker-compose up --abort-on-container-exit ci

# Exit code indicates pass/fail
echo $?  # 0 = success, non-zero = failure

GitHub Actions example:

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Run tests in Docker
        run: docker-compose up --abort-on-container-exit ci

      - name: Check exit code
        run: |
          if [ $? -ne 0 ]; then
            echo "Tests failed!"
            exit 1
          fi

GitLab CI example:

# .gitlab-ci.yml
test:
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker-compose up --abort-on-container-exit ci

4. Building WASM

Build WASM in container:

# Build WASM target
docker-compose run --rm wasm

# Generated files in target/wasm32-unknown-unknown/
ls -lh target/wasm32-unknown-unknown/release/batuta.wasm

5. Serving Documentation

Build and serve rustdoc:

# Build documentation
docker-compose run --rm batuta cargo doc --no-deps

# Start documentation server
docker-compose up docs

# Open browser
open http://localhost:8000/batuta/

6. One-Off Commands

Run arbitrary commands in container:

# Run specific example
docker-compose run --rm batuta \
    cargo run --example full_transpilation

# Check clippy lints
docker-compose run --rm batuta \
    cargo clippy -- -D warnings

# Format code
docker-compose run --rm batuta \
    cargo fmt --all

# Run benchmarks
docker-compose run --rm batuta \
    cargo bench

Build Script

The scripts/docker-build.sh script automates Docker builds:

#!/usr/bin/env bash
set -euo pipefail

MODE="${1:-prod}"

case "$MODE" in
    prod)
        echo "🐳 Building production Docker image..."
        docker build -t batuta:latest \
            --target runtime \
            --build-arg FEATURES=native \
            .
        echo "✅ Built: batuta:latest"
        ;;

    dev)
        echo "🐳 Building development Docker image..."
        docker build -f Dockerfile.dev -t batuta:dev .
        echo "✅ Built: batuta:dev"
        ;;

    ci)
        echo "🐳 Building CI Docker image..."
        docker build -t batuta:ci \
            --target runtime \
            --build-arg FEATURES=native \
            .
        echo "✅ Built: batuta:ci"
        ;;

    wasm)
        echo "🐳 Building WASM Docker image..."
        docker build -t batuta:wasm \
            --target builder \
            --build-arg FEATURES=wasm \
            --build-arg TARGET=wasm32-unknown-unknown \
            .
        echo "✅ Built: batuta:wasm"
        ;;

    *)
        echo "Usage: $0 {prod|dev|ci|wasm}"
        exit 1
        ;;
esac

Usage:

# Build production image
./scripts/docker-build.sh prod

# Build development image
./scripts/docker-build.sh dev

# Build CI image
./scripts/docker-build.sh ci

# Build WASM-capable image
./scripts/docker-build.sh wasm

Dockerfile.dev

The development Dockerfile includes additional tools:

FROM rust:1.75-slim

# Install development dependencies
RUN apt-get update && apt-get install -y \
    pkg-config \
    libssl-dev \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Install cargo-watch for hot reload
RUN cargo install cargo-watch

# Install wasm toolchain
RUN rustup target add wasm32-unknown-unknown

# Install external transpilation tools
RUN cargo install depyler bashrs pmat

WORKDIR /workspace

# Default: watch mode
CMD ["cargo", "watch", "-x", "check", "-x", "test"]

Additional tools:

• cargo-watch: Automatic recompilation on file changes
• wasm32-unknown-unknown: WASM build target
• depyler, bashrs, pmat: External transpilers

.dockerignore

Exclude unnecessary files from Docker build context:

# Build artifacts
target/
wasm-dist/
dist/

# Dependency cache
Cargo.lock  # Keep if you want reproducible builds

# Git
.git/
.gitignore

# IDE
.vscode/
.idea/
*.swp
*.swo

# Documentation build
book/book/

# CI/CD
.github/
.gitlab-ci.yml

# Local config
.env
.batuta-state.json

# macOS
.DS_Store

# Logs
*.log

Benefits:

• Faster Docker builds (smaller context)
• No accidental secrets in images
• Cleaner build logs

Environment Variables

Configure Batuta via environment variables:

# Enable debug logging
docker-compose run -e RUST_LOG=batuta=debug batuta \
    batuta analyze /workspace/project

# Set custom config path
docker-compose run -e BATUTA_CONFIG=/workspace/custom.toml batuta \
    batuta transpile --input /workspace/src

# Disable GPU backend
docker-compose run -e BATUTA_DISABLE_GPU=1 batuta \
    batuta optimize --input /workspace/project

Supported variables:

Security Best Practices

1. Non-Root User

All images run as non-root user batuta:1000:

# Create user
RUN useradd -m -u 1000 -s /bin/bash batuta

# Switch user
USER batuta

Benefits:

• Limits container breakout impact
• Matches host user permissions (if UID=1000)
• Industry security standard

2. Read-Only Volumes

CI containers use read-only mounts:

volumes:
  - .:/workspace:ro  # Read-only

Prevents CI from modifying source code.

3. Minimal Attack Surface

Production image:

• No Rust toolchain (can’t compile malicious code)
• No package managers (can’t install backdoors)
• Only essential runtime dependencies

4. Trusted Base Images

Use official images:

• rust:1.75-slim (official Rust image)
• debian:bookworm-slim (official Debian)
• nginx:alpine (official nginx)

Avoid unknown/untrusted bases.

5. Dependency Scanning

Scan for vulnerabilities:

# Using Trivy
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
    aquasec/trivy image batuta:latest

# Using Snyk
snyk container test batuta:latest

Cleanup

Remove Docker artifacts:

# Clean all Batuta containers and images
make docker-clean

# Manually remove containers
docker-compose down

# Remove volumes (deletes cache!)
docker-compose down -v

# Remove all images
docker rmi batuta:latest batuta:dev batuta:ci

# Prune unused Docker resources
docker system prune -a --volumes

Performance Tips

1. Use BuildKit

Enable Docker BuildKit for faster builds:

# Enable BuildKit
export DOCKER_BUILDKIT=1

# Build with BuildKit
docker build -t batuta:latest .

Benefits:

• Parallel layer building
• Better caching
• Smaller images

2. Layer Caching

Order Dockerfile commands by change frequency:

# 1. Base image (rarely changes)
FROM rust:1.75-slim

# 2. System dependencies (rarely changes)
RUN apt-get update && apt-get install -y ...

# 3. Cargo dependencies (changes occasionally)
COPY Cargo.toml Cargo.lock ./
RUN cargo build --release

# 4. Source code (changes frequently)
COPY src ./src
RUN cargo build --release

3. Cargo Cache Volumes

Use named volumes for cargo cache:

volumes:
  - cargo-cache:/usr/local/cargo/registry  # Persistent cache

Speedup: 5-10x faster dependency builds after first run.

4. Parallel Builds

Build multiple images in parallel:

# Build prod and dev simultaneously
docker-compose build batuta dev &
wait

Integration with Makefile

The Makefile includes Docker targets:

# Build production Docker image
docker:
\t@echo "🐳 Building production Docker image..."
\t./scripts/docker-build.sh prod

# Build development Docker image
docker-dev:
\t@echo "🐳 Building development Docker image..."
\t./scripts/docker-build.sh dev

# Run tests in Docker
docker-test:
\t@echo "🧪 Running tests in Docker..."
\tdocker-compose up --abort-on-container-exit ci

# Clean Docker artifacts
docker-clean:
\t@echo "🧹 Cleaning Docker images and volumes..."
\tdocker-compose down -v
\tdocker rmi batuta:latest batuta:dev batuta:ci 2>/dev/null || true
\t@echo "✅ Docker cleanup complete"

Usage:

make docker       # Build production image
make docker-dev   # Build development image
make docker-test  # Run tests in container
make docker-clean # Remove all artifacts

Troubleshooting

Issue: Slow builds

Cause: Docker not using layer cache.

Solution:

# Use BuildKit
export DOCKER_BUILDKIT=1
docker build --cache-from batuta:latest -t batuta:latest .

Issue: Permission denied

Cause: Container user UID doesn’t match host user.

Solution:

# Build with custom UID
docker build --build-arg UID=$(id -u) -t batuta:latest .

Or:

# Run as current user
docker-compose run --user $(id -u):$(id -g) batuta batuta --help

Issue: Out of disk space

Cause: Docker images and volumes consuming disk.

Solution:

# Check disk usage
docker system df

# Clean unused resources
docker system prune -a --volumes

# Remove specific volumes
docker volume rm batuta_cargo-cache batuta_target-cache

Issue: Cannot connect to Docker daemon

Cause: Docker service not running or permissions issue.

Solution:

# Start Docker service
sudo systemctl start docker

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
newgrp docker

Next Steps

• Distribution: Publishing Batuta packages
• Release Builds: Production optimization
• Phase 4: Validation: Testing transpiled code

Navigate: Table of Contents

Distribution

Distribution is the final step in Phase 5, packaging the compiled binary for delivery to end users. Batuta supports multiple distribution channels depending on the target audience.

Distribution Channels

crates.io Publishing

For libraries that other Rust projects will depend on:

# Verify package contents
cargo package --list

# Dry run (no upload)
cargo publish --dry-run

# Publish to crates.io
cargo publish

Key checks before publishing:

• Cargo.toml has version, description, license, repository
• No path dependencies (use crates.io versions)
• All tests pass with --locked
• MSRV (Minimum Supported Rust Version) is declared

Binary Distribution

For end-user tools, distribute pre-built binaries:

# Build release binaries for multiple targets
batuta build --release --target x86_64-unknown-linux-musl
batuta build --release --target aarch64-unknown-linux-gnu
batuta build --release --target x86_64-apple-darwin

# Package with checksums
tar czf app-linux-x86_64.tar.gz -C target/x86_64-unknown-linux-musl/release app
sha256sum app-linux-x86_64.tar.gz > app-linux-x86_64.tar.gz.sha256

cargo-binstall Support

Add metadata to Cargo.toml for automatic binary installation:

[package.metadata.binstall]
pkg-url = "{ repo }/releases/download/v{ version }/{ name }-{ target }.tar.gz"
bin-dir = "{ bin }{ binary-ext }"
pkg-fmt = "tgz"

Users can then install with:

cargo binstall my-app

Docker Distribution

For cloud deployment, Batuta’s batuta deploy command generates Dockerfiles using scratch base images (works because musl-linked binaries have no dynamic dependencies).

Stack Publish Status

For Sovereign AI Stack crates, batuta stack publish-status checks which crates need publishing. Results are cached (warm: <100ms, cold: ~7s) with invalidation on Cargo.toml changes, git HEAD moves, or crates.io TTL expiry (15 minutes).

Navigate: Table of Contents

Tool Overview

Batuta does not transpile code itself. It orchestrates a curated ecosystem of external tools, each purpose-built for a specific language or task. Tools are organized into three categories: transpilers that convert source languages to Rust, foundation libraries that provide compute and ML primitives, and support tools that handle analysis, testing, and tracing.

Tool Categories

Transpilers

Transpilers convert source code from one language to idiomatic Rust. Batuta selects the appropriate transpiler based on the detected source language.

Foundation Libraries

Foundation libraries are Rust crates used as dependencies in generated code. They replace source-language libraries with SIMD/GPU-accelerated Rust equivalents.

Support Tools

Support tools assist with quality analysis, runtime validation, and scripting.

Tool Detection

Batuta discovers tools automatically at startup using PATH-based detection. The ToolRegistry struct in src/tools.rs drives this process:

#![allow(unused)]
fn main() {
// Batuta scans PATH for each known tool
let registry = ToolRegistry::detect();

// Check what is available
for tool in registry.available_tools() {
    println!("Found: {}", tool);
}
}

Detection follows three steps:

1. PATH lookup – which::which(name) locates the binary
2. Version probe – runs tool --version and parses the output
3. Registry population – stores name, path, version, and availability flag

If a tool is missing, Batuta provides installation instructions:

$ batuta analyze --input project/
Warning: Depyler not found. Install with: cargo install depyler

Language-to-Tool Mapping

When Batuta encounters source files, it maps the detected language to the appropriate transpiler:

Languages without a matching transpiler are reported but not processed. Batuta never guesses – if the right tool is not installed, the pipeline stops with a clear error (Jidoka principle).

Checking Tool Status

# List all detected tools
batuta analyze --tools

# Install all stack tools at once
cargo install depyler decy bashrs pmat renacer ruchy

Navigate: Table of Contents

Transpilers

Batuta orchestrates three transpilers, each targeting a specific source language. All three are standalone Rust binaries installed via cargo install and discovered through PATH at runtime.

The Three Transpilers

Note that Bashrs operates in the reverse direction: it takes Rust as input and produces shell scripts. This solves the bootstrap problem where installers need to run on systems that do not yet have Rust installed.

Automatic Detection

Batuta detects transpilers via PATH lookup at pipeline startup:

$ batuta transpile --input ./my_project
Detecting tools...
  Depyler 3.20.0    /home/user/.cargo/bin/depyler
  Decy 2.1.0        /home/user/.cargo/bin/decy
  Bashrs 6.41.0     /home/user/.cargo/bin/bashrs

If the required transpiler is missing, Batuta halts with installation instructions rather than silently skipping files.

Common Transpilation Patterns

Single File

# Python file
batuta transpile --input script.py --output script.rs

# C file
batuta transpile --input parser.c --output parser.rs

Full Project

# Transpile entire Python project to a Cargo workspace
batuta transpile --input ./python_app --output ./rust_app --format project

Batuta delegates to the appropriate transpiler based on the file extension and detected language.

Mixed-Language Projects

For projects with multiple source languages, Batuta runs each transpiler on its respective files:

# Project contains .py, .c, and .sh files
batuta transpile --input ./mixed_project --output ./rust_project

# Internal dispatch:
#   *.py  -> depyler transpile
#   *.c   -> decy transpile
#   *.sh  -> (flagged for bashrs review)

Transpiler Invocation

Batuta calls each transpiler through run_tool(), which captures stdout/stderr and propagates errors. Failures are surfaced immediately (Jidoka), with the full tool stderr included in the error report.

Installation

# Install all three transpilers
cargo install depyler decy bashrs

# Verify
depyler --version
decy --version
bashrs --version

Next Steps

• Depyler: Python to Rust – type inference, ML library conversion
• Decy: C/C++ to Rust – ownership inference, memory management
• Bashrs: Rust to Shell – bootstrap scripts, cross-platform deployment

Navigate: Table of Contents

Decy: C/C++ to Rust

Decy transpiles C and C++ source code into safe, idiomatic Rust. Its core challenge is inferring Rust ownership semantics from C pointer patterns and replacing manual memory management with RAII.

Overview

Ownership Inference from Pointer Analysis

C uses raw pointers for everything: ownership, borrowing, output parameters, and arrays. Decy analyzes pointer usage patterns to infer the correct Rust ownership model.

Memory Management Translation

Decy replaces malloc/free pairs with Rust RAII, eliminating use-after-free and double-free at compile time.

Buffer* buf = (Buffer*)malloc(sizeof(Buffer));
buf->data = (char*)malloc(size);
free(buf->data);
free(buf);

#![allow(unused)]
fn main() {
// RAII: dropped automatically when buf goes out of scope
let buf = Buffer { data: vec![0u8; size], len: size };
}

Common translations: char* + strlen() becomes String, strdup(s) becomes s.to_string(), strcmp(a,b)==0 becomes a == b, and snprintf becomes format!(...).

FFI Boundary Generation

For gradual migration, Decy generates extern "C" wrappers so existing C code can call the new Rust functions. This allows teams to migrate one file at a time, linking Rust objects into the existing C build system.

#![allow(unused)]
fn main() {
#[no_mangle]
pub extern "C" fn process_buffer(data: *const u8, len: usize) -> i32 {
    let slice = unsafe { std::slice::from_raw_parts(data, len) };
    process_buffer_safe(slice).unwrap_or(-1)
}
}

Pass --ffi to decy transpile to generate these wrappers alongside the safe Rust implementation.

Common C Patterns and Rust Equivalents

CLI Usage

# Transpile a single C file
decy transpile --input parser.c --output parser.rs

# Transpile with FFI wrappers for gradual migration
decy transpile --input lib.c --output lib.rs --ffi

# Transpile a C project directory
decy transpile --input ./c_project --output ./rust_project

# Via Batuta orchestration
batuta transpile --input ./c_project --output ./rust_project

Limitations

• Inline assembly: Not transpiled; must be replaced manually or wrapped in unsafe
• Complex macros: Preprocessor macros with side effects require manual review
• Void pointers: void* used as generic storage needs manual type annotation
• Bit fields: Struct bit fields are converted to explicit mask operations

Navigate: Table of Contents

Depyler: Python → Rust

“Depyler transpiles Python to Rust with automatic type inference, NumPy→Trueno conversion, and sklearn→Aprender migration.”

Overview

Depyler is Batuta’s Python-to-Rust transpiler that converts Python projects into idiomatic Rust code with:

• Automatic type inference: Infers Rust types from Python code
• NumPy → Trueno: Converts NumPy operations to SIMD/GPU-accelerated Trueno
• sklearn → Aprender: Migrates scikit-learn to first-principles Aprender
• PyTorch → Realizar: Transpiles PyTorch inference to optimized Realizar
• Project structure generation: Creates full Cargo projects with dependencies

Installation

# Install from crates.io
cargo install depyler

# Verify installation
depyler --version
# Output: depyler 3.20.0

Basic Usage

Single File Transpilation

# Transpile Python file to Rust
depyler transpile --input script.py --output script.rs

# View generated Rust code
cat script.rs

Example:

# script.py
import numpy as np

def add_arrays(a, b):
    return np.add(a, b)

x = np.array([1, 2, 3])
y = np.array([4, 5, 6])
result = add_arrays(x, y)
print(result)

Generated Rust:

// script.rs
use trueno::Array;

fn add_arrays(a: &Array<f64>, b: &Array<f64>) -> Array<f64> {
    trueno::add(a, b)
}

fn main() {
    let x = Array::from_vec(vec![1.0, 2.0, 3.0]);
    let y = Array::from_vec(vec![4.0, 5.0, 6.0]);
    let result = add_arrays(&x, &y);
    println!("{:?}", result);
}

Project Transpilation

# Transpile entire Python project
depyler transpile \
    --input /path/to/python_project \
    --output /path/to/rust_project \
    --format project

# Generated structure:
# rust_project/
# ├── Cargo.toml
# ├── src/
# │   ├── main.rs
# │   ├── lib.rs
# │   └── modules/
# ├── tests/
# └── benches/

Batuta Integration

Batuta automatically uses Depyler for Python transpilation:

# Batuta detects Depyler and uses it
batuta transpile --input my_python_app --output my_rust_app

Internal call:

depyler transpile \
    --input my_python_app \
    --output my_rust_app \
    --format project

ML Library Conversion

NumPy → Trueno

Depyler converts NumPy operations to Trueno for SIMD/GPU acceleration:

sklearn → Aprender

Converts scikit-learn to first-principles Aprender:

PyTorch → Realizar

Transpiles PyTorch inference to Realizar:

Features

Type Inference

Depyler infers Rust types from Python:

# Python (dynamic typing)
def multiply(x, y):
    return x * y

result = multiply(5, 10)  # int

#![allow(unused)]
fn main() {
// Rust (inferred types)
fn multiply(x: i32, y: i32) -> i32 {
    x * y
}

let result: i32 = multiply(5, 10);
}

Ownership Inference

Converts Python references to Rust ownership:

# Python
def process_list(items):
    items.append(42)
    return items

#![allow(unused)]
fn main() {
// Rust (mutable reference)
fn process_list(items: &mut Vec<i32>) -> &Vec<i32> {
    items.push(42);
    items
}
}

Error Handling

Converts Python exceptions to Rust Result:

# Python
def divide(a, b):
    if b == 0:
        raise ValueError("Division by zero")
    return a / b

#![allow(unused)]
fn main() {
// Rust
fn divide(a: f64, b: f64) -> Result<f64, String> {
    if b == 0.0 {
        Err("Division by zero".to_string())
    } else {
        Ok(a / b)
    }
}
}

Command-Line Options

depyler transpile [OPTIONS]

OPTIONS:
    --input <PATH>      Input Python file or directory
    --output <PATH>     Output Rust file or directory
    --format <FORMAT>   Output format: file, project [default: file]
    --optimize <LEVEL>  Optimization level: 0, 1, 2, 3 [default: 2]
    --backend <BACKEND> Trueno backend: cpu, simd, gpu, auto [default: auto]
    --strict            Strict mode (fail on warnings)
    --no-ml             Disable ML library conversion
    -h, --help          Print help
    -V, --version       Print version

Examples:

# Strict mode (fail on type inference warnings)
depyler transpile --input script.py --output script.rs --strict

# Disable ML conversions (keep NumPy as-is)
depyler transpile --input ml_app.py --output ml_app.rs --no-ml

# Force GPU backend
depyler transpile --input gpu_code.py --output gpu_code.rs --backend gpu

Limitations

Depyler has some known limitations:

• Dynamic typing: Complex dynamic types may require manual annotations
• Metaprogramming: Decorators and metaclasses not fully supported
• C extensions: Python C extensions cannot be transpiled
• Runtime reflection: eval(), exec(), getattr() limited support

Workarounds:

• Use type hints in Python code for better inference
• Refactor metaprogramming to explicit code
• Replace C extensions with pure Rust equivalents
• Avoid runtime reflection in critical paths

Version

Current version: 3.20.0

Check installed version:

depyler --version

Update to latest:

cargo install depyler --force

Next Steps

• Bashrs: Shell → Rust: Shell script transpilation
• Trueno: Multi-target Compute: SIMD/GPU acceleration
• Aprender: First-Principles ML: ML algorithms in Rust

Navigate: Table of Contents

Bashrs: Rust to Shell Transpiler

“Write Rust, deploy shell. Deterministic bootstrap scripts for any environment.”

Bashrs transpiles Rust code to portable POSIX shell scripts. It enables writing complex installation and bootstrap logic in Rust while deploying as zero-dependency shell scripts.

Overview

Why Bashrs?

The Bootstrap Problem

When deploying software, you face a chicken-and-egg problem:

1. Your installer needs dependencies (Rust, Python, Node…)
2. But you’re trying to install those dependencies
3. The only universal runtime is /bin/sh

Traditional Solutions

Bashrs Solution

Write your installer in Rust with full type safety and testing, then transpile to a portable shell script:

Rust (tested, typed) → bashrs → Shell (universal, portable)

Capabilities

rust_to_shell

Transpile Rust functions to shell:

// install.rs
use bashrs::prelude::*;

#[bashrs::main]
fn main() {
    // Check if Rust is installed
    if !command_exists("rustc") {
        println("Installing Rust...");
        curl("https://sh.rustup.rs", "-sSf") | sh();
    }

    // Install the application
    cargo(&["install", "batuta"]);

    println("Installation complete!");
}

Generates:

#!/bin/sh
set -e

main() {
    # Check if Rust is installed
    if ! command -v rustc >/dev/null 2>&1; then
        echo "Installing Rust..."
        curl -sSf https://sh.rustup.rs | sh
    fi

    # Install the application
    cargo install batuta

    echo "Installation complete!"
}

main "$@"

bootstrap_scripts

Generate deterministic bootstrap scripts for reproducible environments:

#![allow(unused)]
fn main() {
use bashrs::prelude::*;

#[bashrs::bootstrap]
fn setup_dev_environment() {
    // Deterministic package installation
    apt_install(&["build-essential", "pkg-config", "libssl-dev"]);

    // Rust toolchain
    rustup_install("stable");
    rustup_component_add(&["clippy", "rustfmt", "llvm-tools-preview"]);

    // Cargo tools
    cargo_install(&["cargo-nextest", "cargo-llvm-cov", "cargo-mutants"]);

    // Verify installation
    assert_command("cargo --version");
    assert_command("cargo nextest --version");
}
}

cross_platform_shell

Generate POSIX-compliant shell code that works everywhere:

#![allow(unused)]
fn main() {
use bashrs::prelude::*;

#[bashrs::portable]
fn detect_os() -> String {
    // Bashrs generates portable OS detection
    match os() {
        Os::Linux => "linux",
        Os::MacOS => "darwin",
        Os::Windows => "windows",  // WSL/Git Bash
        Os::FreeBSD => "freebsd",
    }
}

#[bashrs::portable]
fn install_package(name: &str) {
    // Generates package manager detection
    match package_manager() {
        Apt => apt_install(&[name]),
        Brew => brew_install(&[name]),
        Dnf => dnf_install(&[name]),
        Pacman => pacman_install(&[name]),
    }
}
}

Generates:

detect_os() {
    case "$(uname -s)" in
        Linux*)  echo "linux";;
        Darwin*) echo "darwin";;
        MINGW*|MSYS*|CYGWIN*) echo "windows";;
        FreeBSD*) echo "freebsd";;
        *) echo "unknown";;
    esac
}

install_package() {
    if command -v apt-get >/dev/null 2>&1; then
        sudo apt-get install -y "$1"
    elif command -v brew >/dev/null 2>&1; then
        brew install "$1"
    elif command -v dnf >/dev/null 2>&1; then
        sudo dnf install -y "$1"
    elif command -v pacman >/dev/null 2>&1; then
        sudo pacman -S --noconfirm "$1"
    else
        echo "No supported package manager found" >&2
        exit 1
    fi
}

Integration with Batuta

Generate installation scripts for batuta deployments:

#![allow(unused)]
fn main() {
use bashrs::prelude::*;

#[bashrs::main]
fn install_batuta() {
    println("=== Batuta Installation ===");

    // Step 1: System dependencies
    println("Installing system dependencies...");
    install_build_essentials();

    // Step 2: Rust toolchain
    println("Setting up Rust...");
    ensure_rust_installed();
    rustup_update();

    // Step 3: Install batuta
    println("Installing batuta...");
    cargo_install(&["batuta"]);

    // Step 4: Verify
    println("Verifying installation...");
    let version = capture("batuta --version");
    println(format!("Installed: {}", version));

    println("=== Installation Complete ===");
}
}

Integration with Repartir

Generate cluster node bootstrap scripts:

#![allow(unused)]
fn main() {
use bashrs::prelude::*;

#[bashrs::main]
fn bootstrap_worker_node() {
    let coordinator = env_required("COORDINATOR_HOST");
    let node_id = env_or("NODE_ID", &generate_node_id());

    println(format!("Bootstrapping worker node: {}", node_id));

    // Install repartir
    cargo_install(&["repartir"]);

    // Configure node
    write_file("/etc/repartir/config.toml", &format!(r#"
[node]
id = "{}"
coordinator = "{}"

[resources]
cpus = {}
memory_gb = {}
"#, node_id, coordinator, num_cpus(), memory_gb()));

    // Start worker service
    systemctl_enable("repartir-worker");
    systemctl_start("repartir-worker");

    println("Worker node ready!");
}
}

CLI Usage

# Transpile Rust to shell
bashrs transpile install.rs -o install.sh

# Build and run directly
bashrs run install.rs

# Generate with specific shell target
bashrs transpile --target bash install.rs    # Bash-specific features
bashrs transpile --target posix install.rs   # POSIX-only (most portable)
bashrs transpile --target zsh install.rs     # Zsh-specific features

# Verify generated script
bashrs verify install.sh  # Check for common issues

# Test on multiple shells
bashrs test install.rs --shells bash,dash,zsh

Example: Multi-Stage Installer

use bashrs::prelude::*;

#[bashrs::main]
fn main() {
    let args = parse_args();

    match args.command.as_str() {
        "install" => install(),
        "uninstall" => uninstall(),
        "upgrade" => upgrade(),
        "doctor" => doctor(),
        _ => print_help(),
    }
}

fn install() {
    println("Installing Sovereign AI Stack...");

    // Phase 1: Base dependencies
    section("Phase 1: System Dependencies");
    install_system_deps();

    // Phase 2: Rust ecosystem
    section("Phase 2: Rust Toolchain");
    install_rust_ecosystem();

    // Phase 3: Stack components
    section("Phase 3: Stack Components");
    cargo_install(&[
        "trueno",
        "aprender",
        "batuta",
        "repartir",
        "renacer",
    ]);

    // Phase 4: Verification
    section("Phase 4: Verification");
    verify_installation();

    success("Installation complete!");
}

fn doctor() {
    println("Checking installation health...");

    check("Rust compiler", "rustc --version");
    check("Cargo", "cargo --version");
    check("Trueno", "cargo install --list | grep trueno");
    check("Batuta", "batuta --version");

    println("All checks passed!");
}

Comparison with Alternatives

Key Takeaways

• Write Rust, deploy shell: Full Rust safety, universal deployment
• Zero dependencies: Generated scripts need only /bin/sh
• Deterministic: Same input always generates same output
• Testable: Test your Rust code, deploy the shell
• Cross-platform: POSIX-compliant output works everywhere

Previous: Decy: C/C++ to Rust Next: Ruchy: Systems Scripting

Foundation Libraries

The Sovereign AI Stack is built on a core set of foundation libraries that provide compute, ML, inference, and data management capabilities. All libraries are pure Rust with no Python/CUDA dependencies.

Current Versions (November 2025)

Stack Architecture

┌─────────────────────────────────────────────────────────────────┐
│  Applications (Presentar, CLI tools)                            │
├─────────────────────────────────────────────────────────────────┤
│  Realizar (Inference) │ Aprender (Training) │ Alimentar (Data)  │
├─────────────────────────────────────────────────────────────────┤
│  Trueno (Compute Foundation)                                    │
│  ├── Backend: CPU (SIMD) │ WASM (SIMD) │ GPU (WebGPU)          │
│  ├── Tensor operations                                          │
│  └── Memory management                                          │
└─────────────────────────────────────────────────────────────────┘

Trueno: The Compute Foundation

Trueno is the bedrock of the stack, providing:

• Multi-backend dispatch: CPU SIMD, WASM SIMD, WebGPU
• Array programming model: Following Iverson (1962)
• Columnar memory layout: For SIMD efficiency (Stonebraker et al., 2005)
• Zero-copy operations: Via lifetime-based borrowing

#![allow(unused)]
fn main() {
use trueno::{Tensor, Backend};

// Automatic backend selection
let a = Tensor::from_vec(vec![1.0, 2.0, 3.0], Backend::Auto);
let b = Tensor::from_vec(vec![4.0, 5.0, 6.0], Backend::Auto);
let c = &a + &b;  // SIMD-accelerated
}

Recent (v0.7.3): WebGPU support for WASM targets (gpu-wasm feature).

Aprender: First-Principles ML

Aprender implements ML algorithms from mathematical foundations:

• No PyTorch/TensorFlow dependency
• Transparent implementations: Every algorithm is readable
• Academic rigor: Peer-reviewed algorithm implementations
• Integration: Outputs .apr model format

Realizar: ML Inference Runtime

Realizar executes trained models with:

• Multi-format support: .apr, ONNX (limited)
• Optimized inference: Quantization, pruning
• Batch processing: Efficient throughput
• WASM deployment: Browser-native inference

Alimentar: Data Pipeline

Alimentar manages data loading and validation:

• Format: .ald (Alimentar Data format)
• Schema validation: At load time, not runtime
• Quality scoring: 100-point weighted system (v0.2.0)
• Streaming: Large dataset support

#![allow(unused)]
fn main() {
use alimentar::{Dataset, Schema};

let schema = Schema::load("transactions.schema.yaml")?;
let dataset = Dataset::load("transactions.ald", &schema)?;
}

Pacha: Content Registry

Pacha manages model and dataset versions:

• URI scheme: pacha://models/name:version, pacha://datasets/name:version
• Lineage tracking: W3C PROV-DM compliant
• Oracle Mode: Intelligent query interface for codebase understanding

# Reference in Presentar app.yaml
models:
  classifier:
    source: "pacha://models/fraud-detector:1.2.0"

Dependency Graph

presentar ─────► trueno-viz ─────► trueno
                     │
aprender ────────────┘
    │
realizar ────────────► trueno
    │
alimentar ───────────► trueno
    │
pacha (registry, no compute deps)

Toyota Way Integration

Following the Toyota Production System:

Further Reading

• Trueno: Multi-target Compute
• Aprender: First-Principles ML
• Realizar: ML Inference Runtime

Navigate: Table of Contents | Tool Overview

Trueno: Multi-target Compute

Trueno (Spanish: “thunder”) is a Rust library providing unified, high-performance compute primitives across multiple execution targets. It serves as the foundation for numerical computation in the sovereign stack.

Overview

Trueno delivers:

• CPU SIMD - x86 (SSE2/AVX/AVX2/AVX-512), ARM (NEON), WASM (SIMD128)
• GPU - Vulkan/Metal/DX12/WebGPU via wgpu
• WebAssembly - Portable SIMD128 for browser/edge deployment

┌─────────────────────────────────────────────────┐
│           Trueno Public API (Safe)              │
│  compute(), map(), reduce(), transform()        │
└─────────────────────────────────────────────────┘
                      │
        ┌─────────────┼─────────────┐
        ▼             ▼             ▼
   ┌────────┐   ┌─────────┐   ┌──────────┐
   │  SIMD  │   │   GPU   │   │   WASM   │
   │ Backend│   │ Backend │   │  Backend │
   └────────┘   └─────────┘   └──────────┘
        │             │             │
   ┌────┴────┐   ┌────┴────┐   ┌───┴─────┐
   │ Runtime │   │  wgpu   │   │ SIMD128 │
   │ Detect  │   │ Compute │   │ Portable│
   └─────────┘   └─────────┘   └─────────┘

Installation

[dependencies]
trueno = "0.14"

# With GPU support
trueno = { version = "0.14", features = ["gpu"] }

# With CUDA monitoring (NVIDIA GPUs)
trueno = { version = "0.14", features = ["cuda-monitor"] }

What’s New in 0.14

• Streaming Tensors: Memory-mapped streaming for large datasets
• Q5K/Q6K Quantization: Extended quantization formats
• Improved WASM: Better WebAssembly SIMD128 support
• LZ4/ZSTD Compression: Built-in tensor compression for memory efficiency
• GPU PTX Fixes: Resolved NVIDIA PTX codegen issues
• AVX-512 Improvements: Better auto-vectorization
• Simulation Framework: Toyota-style Jidoka guards and stress testing

Core Features

Vector Operations

#![allow(unused)]
fn main() {
use trueno::{Vector, VectorOps};

// Create vectors
let a = Vector::from_slice(&[1.0, 2.0, 3.0, 4.0]);
let b = Vector::from_slice(&[5.0, 6.0, 7.0, 8.0]);

// Element-wise operations (auto-selects best SIMD backend)
let sum = a.add(&b)?;       // [6.0, 8.0, 10.0, 12.0]
let product = a.mul(&b)?;   // [5.0, 12.0, 21.0, 32.0]
let dot = a.dot(&b)?;       // 70.0

// Reductions
let total = a.sum()?;       // 10.0
let average = a.mean()?;    // 2.5
}

Matrix Operations

#![allow(unused)]
fn main() {
use trueno::Matrix;

let a = Matrix::from_slice(2, 3, &[
    1.0, 2.0, 3.0,
    4.0, 5.0, 6.0,
]);

let b = Matrix::from_slice(3, 2, &[
    7.0, 8.0,
    9.0, 10.0,
    11.0, 12.0,
]);

// Matrix multiplication (SIMD-accelerated)
let c = a.matmul(&b)?;  // 2x2 result

// Transpose
let at = a.transpose();

// Eigendecomposition (symmetric matrices)
let eigen = matrix.symmetric_eigen()?;
}

Activation Functions

#![allow(unused)]
fn main() {
use trueno::activations::*;

let x = Vector::from_slice(&[-1.0, 0.0, 1.0, 2.0]);

// Neural network activations (SIMD-optimized)
let relu_out = relu(&x)?;      // [0.0, 0.0, 1.0, 2.0]
let sigmoid_out = sigmoid(&x)?;
let gelu_out = gelu(&x)?;
let swish_out = swish(&x)?;
let tanh_out = tanh_activation(&x)?;
}

Backend Selection

Trueno automatically selects the optimal backend based on:

1. Data size - GPU only for large workloads (>100K elements)
2. CPU features - AVX-512 > AVX2 > AVX > SSE2 > NEON
3. Operation complexity - Complex ops benefit more from GPU

#![allow(unused)]
fn main() {
use trueno::Backend;

// Auto-select (recommended)
let result = vector.add(&other)?;

// Force specific backend
let result = vector.add_with_backend(&other, Backend::Avx2)?;
let result = vector.add_with_backend(&other, Backend::GPU)?;
}

Backend Priority

Simulation Testing Framework (v0.8.5+)

Trueno 0.8.5 introduces a comprehensive simulation testing framework based on Toyota Production System principles.

SimRng: Deterministic Random Number Generator

#![allow(unused)]
fn main() {
use trueno::simulation::SimRng;

// Deterministic PCG-based RNG
let mut rng = SimRng::new(42);  // Seed for reproducibility

// Generate deterministic random values
let value = rng.next_f32();           // [0.0, 1.0)
let int = rng.next_u32();             // Full u32 range
let range = rng.range(1.0, 10.0);     // Custom range
let normal = rng.normal(0.0, 1.0);    // Gaussian distribution

// Fork for parallel testing (maintains determinism)
let child_rng = rng.fork();
}

BackendSelector: Intelligent Backend Selection

#![allow(unused)]
fn main() {
use trueno::simulation::{BackendSelector, BackendThresholds};

let thresholds = BackendThresholds {
    gpu_min_elements: 100_000,
    simd_min_elements: 32,
};

let selector = BackendSelector::new(thresholds);
let backend = selector.select(data_size, op_complexity);
}

JidokaGuard: Stop-on-Defect Quality Checks

#![allow(unused)]
fn main() {
use trueno::simulation::JidokaGuard;

// Toyota-style quality gate - stops on first defect
let guard = JidokaGuard::new();

// Check for NaN/Inf values
guard.check_finite(&result)?;

// Custom invariant checking
guard.assert_invariant(|| value >= 0.0, "Value must be non-negative")?;
}

BufferRenderer: Visual Regression Testing

#![allow(unused)]
fn main() {
use trueno::simulation::{BufferRenderer, ColorPalette};

let renderer = BufferRenderer::new(800, 600);
let palette = ColorPalette::viridis();

// Render data to RGBA buffer for visual comparison
let buffer = renderer.render_heatmap(&data, &palette)?;

// Compare with golden baseline
let diff = renderer.compare_buffers(&buffer, &golden)?;
assert!(diff.max_error < 1e-5);
}

StressTestConfig: Stress Testing Infrastructure

#![allow(unused)]
fn main() {
use trueno::simulation::{StressTestConfig, StressTestResult};

let config = StressTestConfig {
    iterations: 10_000,
    data_size_range: 100..1_000_000,
    anomaly_threshold: 3.0,  // Standard deviations
};

let result = stress_test(&operation, &config)?;
assert!(result.anomaly_count == 0);
}

BackendTolerance: Cross-Backend Comparison

#![allow(unused)]
fn main() {
use trueno::simulation::BackendTolerance;

let tolerance = BackendTolerance::relaxed();

// Get tolerance for comparing results across backends
let tol = tolerance.for_backends(Backend::GPU, Backend::Scalar);
assert!((gpu_result - scalar_result).abs() < tol);
}

GPU Compute

Synchronous API

#![allow(unused)]
fn main() {
use trueno::gpu::GpuDevice;

let device = GpuDevice::new()?;

// Large matrix multiplication on GPU
let result = device.matmul(&a, &b)?;

// Batch operations
let results = device.batch_add(&vectors_a, &vectors_b)?;
}

Async API

#![allow(unused)]
fn main() {
use trueno::gpu::GpuDevice;

let device = GpuDevice::new()?;

// Non-blocking GPU operations
let future = device.matmul_async(&a, &b);
let result = future.await?;
}

NumPy Compatibility (via Batuta)

Trueno is the target for NumPy → Rust transpilation:

Performance

Expected speedups vs scalar baseline:

Related Crates

• trueno-gpu - CUDA monitoring via NVML
• trueno-db - High-performance vector database
• trueno-graph - Graph analytics engine
• trueno-viz - GPU-accelerated visualization
• trueno-rag - RAG pipeline components

References

• trueno on crates.io
• trueno GitHub
• SIMD Programming Guide
• GPU Acceleration Guide

Navigate: Table of Contents | Previous: Foundation Libraries | Next: Aprender

trueno-zram: SIMD Memory Compression

trueno-zram provides SIMD-accelerated compression for Linux zram and general-purpose memory compression. It achieves 3+ GB/s with LZ4 and up to 13 GB/s with ZSTD on AVX-512.

Overview

trueno-zram delivers:

• SIMD Acceleration: AVX2/AVX-512/NEON optimized
• Multiple Algorithms: LZ4 (speed) and ZSTD (ratio)
• Adaptive Selection: Entropy-based algorithm choice
• Page Compression: 4KB aligned for zram integration
• Optional CUDA: GPU acceleration for batch compression

┌─────────────────────────────────────────────────────────────┐
│                    trueno-zram                              │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  LZ4 SIMD   │  │ ZSTD SIMD   │  │  Adaptive Selector  │  │
│  │  (3+ GB/s)  │  │ (13 GB/s)   │  │  (entropy-based)    │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│  AVX-512     │     AVX2      │     NEON      │   Scalar    │
└─────────────────────────────────────────────────────────────┘

Installation

[dependencies]
trueno-zram-core = "0.1"

# With adaptive compression
trueno-zram-adaptive = "0.1"

# With CUDA support
trueno-zram-cuda = { version = "0.1", optional = true }

Quick Start

#![allow(unused)]
fn main() {
use trueno_zram_core::{Compressor, Algorithm};

// Create compressor with LZ4 (fastest)
let compressor = Compressor::new(Algorithm::Lz4);

// Compress data
let compressed = compressor.compress(&data)?;
println!("Ratio: {:.2}x", data.len() as f64 / compressed.len() as f64);

// Decompress
let decompressed = compressor.decompress(&compressed)?;
assert_eq!(data, decompressed);
}

Algorithm Comparison

SIMD Backend Selection

#![allow(unused)]
fn main() {
use trueno_zram_core::{SimdBackend, detect_backend};

// Auto-detect best available backend
let backend = detect_backend();
println!("Using: {:?}", backend);

// Force specific backend
let compressor = Compressor::builder()
    .algorithm(Algorithm::Lz4)
    .backend(SimdBackend::Avx512)
    .build()?;
}

Backend Priority

Page Compression

Optimized for 4KB page-aligned compression:

#![allow(unused)]
fn main() {
use trueno_zram_core::{PageCompressor, PAGE_SIZE};

let compressor = PageCompressor::new();

// Compress a 4KB page
let page: [u8; PAGE_SIZE] = get_page();
let compressed = compressor.compress_page(&page)?;

// Check if page is compressible
if compressed.len() < PAGE_SIZE / 2 {
    store_compressed(compressed);
} else {
    store_uncompressed(page);  // Not worth compressing
}
}

Adaptive Compression

Entropy-based algorithm selection:

#![allow(unused)]
fn main() {
use trueno_zram_adaptive::AdaptiveCompressor;

let compressor = AdaptiveCompressor::new();

// Automatically selects best algorithm per-page
let result = compressor.compress_adaptive(&data)?;

match result.algorithm_used {
    Algorithm::SameFill => println!("Zero/repeated page"),
    Algorithm::Lz4 => println!("High entropy, used LZ4"),
    Algorithm::Zstd { .. } => println!("Compressible, used ZSTD"),
}
}

Decision Tree

Is page all zeros/same byte?
  YES → Same-Fill (2048:1 ratio)
  NO  → Check entropy
        High entropy → LZ4 (fast, low ratio)
        Low entropy  → ZSTD (slower, high ratio)

Performance Benchmarks

Measured on AMD EPYC 7763 (AVX-512):

Running the Example

cargo run --example trueno_zram_demo

Related Crates

• trueno-ublk: GPU-accelerated block device using trueno-zram
• trueno: SIMD/GPU compute primitives

References

• trueno-zram on crates.io
• LZ4 Specification
• Zstandard

Navigate: Table of Contents | Previous: whisper.apr | Next: trueno-ublk

trueno-ublk: GPU Block Device

trueno-ublk provides a GPU-accelerated ZRAM replacement using Linux’s userspace block device (ublk) interface. It achieves 10-50 GB/s throughput by offloading compression to GPU.

Overview

trueno-ublk delivers:

• ublk Driver: Userspace block device via libublk
• GPU Compression: CUDA/wgpu accelerated
• ZRAM Replacement: Drop-in swap device
• Adaptive Backend: Automatic GPU/SIMD/CPU selection
• High Throughput: 10-50 GB/s with GPU

┌─────────────────────────────────────────────────────────────┐
│                      Linux Kernel                           │
│                    /dev/ublkb0                              │
└───────────────────────┬─────────────────────────────────────┘
                        │ io_uring
┌───────────────────────▼─────────────────────────────────────┐
│                    trueno-ublk                              │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ GPU Backend │  │ SIMD Backend│  │   CPU Backend       │  │
│  │ (CUDA/wgpu) │  │ (AVX/NEON)  │  │   (fallback)        │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Installation

[dependencies]
trueno-ublk = "0.1"

# With CUDA support (NVIDIA GPUs)
trueno-ublk = { version = "0.1", features = ["cuda"] }

System requirements:

• Linux kernel 6.0+ (ublk support)
• libublk userspace library
• Root privileges for device creation

Quick Start

#![allow(unused)]
fn main() {
use trueno_ublk::{UblkDevice, DeviceConfig, Backend};

// Create device with 8GB capacity
let config = DeviceConfig {
    capacity_bytes: 8 * 1024 * 1024 * 1024,  // 8 GB
    queue_depth: 128,
    num_queues: 4,
    backend: Backend::Auto,  // Auto-select GPU/SIMD/CPU
};

let device = UblkDevice::create(config).await?;
println!("Created: /dev/{}", device.name());

// Run the device (blocks until shutdown)
device.run().await?;
}

Backend Selection

#![allow(unused)]
fn main() {
use trueno_ublk::Backend;

// Force specific backend
let config = DeviceConfig {
    backend: Backend::Cuda,  // NVIDIA GPU only
    ..Default::default()
};

// Or use adaptive (switches based on load)
let config = DeviceConfig {
    backend: Backend::Adaptive {
        gpu_batch_threshold: 64,  // Use GPU for 64+ pages
    },
    ..Default::default()
};
}

CLI Usage

# Create 8GB GPU-accelerated swap
sudo trueno-ublk --capacity 8G --backend auto

# Force CUDA backend with stats
sudo trueno-ublk --capacity 16G --backend cuda --stats

# Use as block device (not swap)
sudo trueno-ublk --capacity 4G --no-swap
sudo mkfs.ext4 /dev/ublkb0
sudo mount /dev/ublkb0 /mnt/fast-storage

systemd Integration

/etc/systemd/system/trueno-ublk.service:

[Unit]
Description=trueno-ublk GPU-accelerated swap
Before=swap.target

[Service]
Type=simple
ExecStart=/usr/local/bin/trueno-ublk \
    --capacity 16G \
    --backend auto
ExecStartPost=/sbin/mkswap /dev/ublkb0
ExecStartPost=/sbin/swapon -p 100 /dev/ublkb0

[Install]
WantedBy=swap.target

Enable:

sudo systemctl enable trueno-ublk
sudo systemctl start trueno-ublk

Performance Monitoring

#![allow(unused)]
fn main() {
use trueno_ublk::Stats;

let stats = device.stats();

println!("Compression ratio: {:.2}x", stats.compression_ratio);
println!("Read throughput:   {:.1} GB/s", stats.read_gbps);
println!("Write throughput:  {:.1} GB/s", stats.write_gbps);
println!("Backend:           {:?}", stats.active_backend);
println!("GPU utilization:   {:.0}%", stats.gpu_utilization * 100.0);
}

Example output:

┌─────────────────────────────────────────────────────┐
│ trueno-ublk stats                                   │
├─────────────────────────────────────────────────────┤
│ Device:          /dev/ublkb0                        │
│ Capacity:        16 GB                              │
│ Used:            8.2 GB (51%)                       │
│ Compressed:      2.1 GB (3.9x ratio)                │
│ Backend:         CUDA (RTX 4090)                    │
│ Read:            42.3 GB/s                          │
│ Write:           38.7 GB/s                          │
│ GPU util:        23%                                │
└─────────────────────────────────────────────────────┘

Comparison with zram

Running the Example

cargo run --example trueno_ublk_demo

Note: Running the actual ublk driver requires root privileges and Linux 6.0+.

Related Crates

• trueno-zram-core: SIMD compression algorithms used by trueno-ublk
• trueno-zram-adaptive: Entropy-based algorithm selection
• trueno: SIMD/GPU compute primitives

References

• trueno-ublk on crates.io
• ublk kernel documentation
• libublk

Navigate: Table of Contents | Previous: trueno-zram | Next: Aprender

Repartir: Distributed Computing

repartir is the Sovereign AI Stack’s distributed computing library, providing CPU, GPU, and remote task execution with work-stealing scheduling.

Overview

Key Features

• 100% Rust, Zero C/C++: Complete auditability for sovereign AI
• Work-Stealing Scheduler: Based on Blumofe & Leiserson (1999)
• Multi-Backend Execution: CPU, GPU, and Remote executors
• Iron Lotus Quality: 95% coverage, 80% mutation score

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    repartir Pool                            │
├─────────────────────────────────────────────────────────────┤
│                      Scheduler                              │
│              (Work-Stealing, Task Queue)                    │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ CpuExecutor │  │ GpuExecutor │  │   RemoteExecutor    │  │
│  │             │  │             │  │                     │  │
│  │  Rayon-like │  │    wgpu     │  │   TCP/TLS           │  │
│  │  AVX2/512   │  │ Vulkan/Metal│  │  Multi-Node         │  │
│  │    NEON     │  │ DX12/WebGPU │  │  Distributed        │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Feature Flags

Quick Start

Installation

[dependencies]
repartir = { version = "1.1", features = ["cpu"] }

# With GPU support
repartir = { version = "1.1", features = ["cpu", "gpu"] }

# Full distributed with all features
repartir = { version = "1.1", features = ["full"] }

Basic CPU Pool

use repartir::{Pool, task::{Task, Backend}};

#[tokio::main]
async fn main() -> repartir::error::Result<()> {
    // Create pool with 8 CPU workers
    let pool = Pool::builder()
        .cpu_workers(8)
        .build()?;

    // Submit a task
    let task = Task::builder()
        .binary("./worker")
        .arg("--input").arg("data.csv")
        .backend(Backend::Cpu)
        .build()?;

    let result = pool.submit(task).await?;

    if result.is_success() {
        println!("Output: {}", result.stdout_str()?);
    }

    pool.shutdown().await;
    Ok(())
}

GPU Execution

use repartir::executor::gpu::GpuExecutor;
use repartir::executor::Executor;

#[tokio::main]
async fn main() -> repartir::error::Result<()> {
    // Initialize GPU executor (auto-selects best GPU)
    let gpu = GpuExecutor::new().await?;

    println!("GPU: {}", gpu.device_name());
    println!("Compute units: {}", gpu.capacity());

    // GPU selection priority:
    // 1. Discrete GPU (dedicated graphics)
    // 2. Integrated GPU (CPU-integrated)
    // 3. Software rasterizer (fallback)

    Ok(())
}

Multi-Machine Distribution

Step 1: Start workers on each node

# On node1 (192.168.1.10)
repartir-worker --bind 0.0.0.0:9000

# On node2 (192.168.1.11)
repartir-worker --bind 0.0.0.0:9000

# On node3 (192.168.1.12)
repartir-worker --bind 0.0.0.0:9000

Step 2: Connect from coordinator

use repartir::executor::remote::RemoteExecutor;
use repartir::task::{Task, Backend};

#[tokio::main]
async fn main() -> repartir::error::Result<()> {
    // Connect to remote workers
    let executor = RemoteExecutor::builder()
        .add_worker("192.168.1.10:9000")
        .add_worker("192.168.1.11:9000")
        .add_worker("192.168.1.12:9000")
        .build()
        .await?;

    // Task distributed to available worker
    let task = Task::builder()
        .binary("./gpu-workload")
        .arg("--shard=0")
        .backend(Backend::Gpu)
        .build()?;

    let result = executor.execute(task).await?;
    println!("Result: {:?}", result.stdout_str()?);

    Ok(())
}

TLS-Secured Remote Execution

#![allow(unused)]
fn main() {
use repartir::executor::tls::TlsRemoteExecutor;

let executor = TlsRemoteExecutor::builder()
    .add_worker("node1.internal:9443")
    .cert_path("./certs/client.pem")
    .key_path("./certs/client.key")
    .ca_path("./certs/ca.pem")
    .build()
    .await?;
}

SIMD Tensor Operations

With the tensor feature, repartir integrates with trueno for SIMD-accelerated operations:

use repartir::tensor::{TensorExecutor, Tensor};
use repartir::task::Backend;

#[tokio::main]
async fn main() -> repartir::error::Result<()> {
    let executor = TensorExecutor::builder()
        .backend(Backend::Cpu)  // Uses AVX2/AVX-512/NEON
        .build()?;

    let a = Tensor::from_slice(&[1.0, 2.0, 3.0, 4.0]);
    let b = Tensor::from_slice(&[5.0, 6.0, 7.0, 8.0]);

    // SIMD-accelerated operations
    let sum = executor.add(&a, &b).await?;
    let product = executor.mul(&a, &b).await?;
    let dot = executor.dot(&a, &b).await?;

    println!("Sum: {:?}", sum.as_slice());
    println!("Product: {:?}", product.as_slice());
    println!("Dot product: {}", dot);

    Ok(())
}

Checkpointing

With the checkpoint feature, repartir can persist state using trueno-db and Parquet:

#![allow(unused)]
fn main() {
use repartir::checkpoint::CheckpointManager;

let checkpoint = CheckpointManager::new("./checkpoints")?;

// Save state
checkpoint.save("training_epoch_10", &model_state).await?;

// Restore on failure
let state = checkpoint.load("training_epoch_10").await?;
}

Job Flow TUI

Monitor distributed jobs with the TUI dashboard:

cargo run --bin job-flow --features tui,remote

┌─ Job Flow Monitor ─────────────────────────────────────────┐
│ Workers: 3 active   │  Tasks: 45 pending / 120 completed   │
├─────────────────────┴──────────────────────────────────────┤
│ Node                 │ Status  │ Load │ Tasks │ Uptime     │
├──────────────────────┼─────────┼──────┼───────┼────────────┤
│ 192.168.1.10:9000    │ Active  │ 78%  │ 15    │ 2h 34m     │
│ 192.168.1.11:9000    │ Active  │ 65%  │ 18    │ 2h 34m     │
│ 192.168.1.12:9000    │ Active  │ 82%  │ 12    │ 2h 30m     │
└──────────────────────┴─────────┴──────┴───────┴────────────┘

Integration with Batuta

Batuta uses repartir for distributed orchestration:

#![allow(unused)]
fn main() {
use batuta::backend::{select_backend, to_repartir_backend};
use batuta::oracle::types::HardwareSpec;

// MoE router selects optimal backend
let backend = select_backend(
    OpComplexity::High,
    Some(DataSize::samples(1_000_000)),
    &HardwareSpec {
        has_gpu: true,
        is_distributed: true,
        node_count: Some(4),
        ..Default::default()
    },
);

// Map to repartir backend
let repartir_backend = to_repartir_backend(backend);
}

Backend Selection Criteria

Batuta’s MoE router uses the 5x PCIe rule (Gregg & Hazelwood, 2011):

GPU is beneficial when: compute_time > 5 × transfer_time

Performance Considerations

Work-Stealing Efficiency

The Blumofe & Leiserson work-stealing algorithm provides:

• O(T₁/P + T∞) expected time with P processors
• Near-linear speedup for embarrassingly parallel workloads
• Low contention through randomized stealing

GPU vs CPU Decision

#![allow(unused)]
fn main() {
// Automatic backend selection
let backend = if data_size > 100_000 && complexity == High {
    Backend::Gpu
} else if data_size > 1_000 {
    Backend::Cpu  // SIMD-accelerated
} else {
    Backend::Cpu  // Scalar
};
}

Remote Execution Overhead

• Serialization: bincode (fast, compact)
• Network: Length-prefixed TCP messages
• Latency: ~1ms per task submission (local network)

Comparison with Alternatives

Example: Distributed ML Training

#![allow(unused)]
fn main() {
use repartir::executor::remote::RemoteExecutor;
use repartir::task::{Task, Backend};

async fn distributed_training(
    nodes: &[&str],
    epochs: usize,
) -> repartir::error::Result<()> {
    let executor = RemoteExecutor::builder()
        .add_workers(nodes)
        .build()
        .await?;

    for epoch in 0..epochs {
        // Distribute training shards
        let tasks: Vec<_> = (0..nodes.len())
            .map(|shard| {
                Task::builder()
                    .binary("./train")
                    .arg("--epoch").arg(epoch.to_string())
                    .arg("--shard").arg(shard.to_string())
                    .arg("--total-shards").arg(nodes.len().to_string())
                    .backend(Backend::Gpu)
                    .build()
            })
            .collect::<Result<Vec<_>, _>>()?;

        // Execute in parallel
        for task in tasks {
            let result = executor.execute(task).await?;
            println!("Shard completed: {:?}", result.exit_code());
        }

        println!("Epoch {} complete", epoch);
    }

    Ok(())
}
}

Navigate: Table of Contents | Trueno | Aprender

Pepita: Sovereign AI Kernel Interfaces

pepita is the Sovereign AI Stack’s kernel interface library, providing minimal Linux kernel interfaces (io_uring, ublk, blk-mq) and distributed computing primitives for sovereign AI workloads.

Overview

Key Features

• First-Principles Rust: Zero external dependencies in kernel mode
• 100% Rust, Zero C/C++: Complete auditability for sovereign AI
• no_std Compatible: Core kernel interfaces work without standard library
• Work-Stealing Scheduler: Blumofe-Leiserson algorithm implementation
• Iron Lotus Quality: 417 tests, 95% coverage

Design Principles

Pepita follows the Iron Lotus Framework:

1. First-Principles Rust: Zero external dependencies in kernel mode
2. Pure Rust Sovereignty: 100% auditable, zero C/C++ dependencies
3. Toyota Way Quality: Jidoka, Poka-yoke, Genchi Genbutsu
4. EXTREME TDD: Comprehensive test coverage

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                           User Code                              │
└──────────────────────────────┬──────────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────────┐
│                          pool.rs                                 │
│                    (High-level Pool API)                         │
└──────────────────────────────┬──────────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────────┐
│                       scheduler.rs                               │
│              (Work-Stealing, Blumofe-Leiserson)                  │
└──────────────────────────────┬──────────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────────┐
│                       executor.rs                                │
│                    (Backend Dispatch)                            │
├─────────────┬─────────────┬─────────────┬───────────────────────┤
│   CPU       │    GPU      │   MicroVM   │        SIMD           │
│ (threads)   │  (wgpu)     │   (KVM)     │    (AVX/NEON)         │
└─────────────┴──────┬──────┴──────┬──────┴───────────┬───────────┘
                     │             │                  │
              ┌──────▼──────┐ ┌────▼─────┐    ┌───────▼───────┐
              │   gpu.rs    │ │  vmm.rs  │    │   simd.rs     │
              │   (wgpu)    │ │  (KVM)   │    │ (AVX-512/NEON)│
              └─────────────┘ └────┬─────┘    └───────────────┘
                                   │
                            ┌──────▼──────┐
                            │  virtio.rs  │
                            │(vsock,block)│
                            └─────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                    Kernel Interfaces (no_std)                    │
├─────────────┬─────────────┬─────────────┬───────────────────────┤
│  io_uring   │    ublk     │   blk_mq    │       memory          │
│ (async I/O) │(block dev)  │ (multiqueue)│   (DMA/pages)         │
└─────────────┴─────────────┴─────────────┴───────────────────────┘

Module Overview

Core Kernel Interfaces (no_std compatible)

Distributed Computing (std required)

Sovereign Infrastructure (std required)

Feature Flags

Quick Start

Installation

[dependencies]
pepita = "0.1"

# Kernel mode (no_std)
pepita = { version = "0.1", default-features = false, features = ["kernel"] }

io_uring - Async I/O

#![allow(unused)]
fn main() {
use pepita::io_uring::{IoUringSqe, IoUringCqe, IORING_OP_URING_CMD};

// Submission queue entry - describes an I/O operation
let sqe = IoUringSqe::new(IORING_OP_URING_CMD, fd, addr, len);

// Completion queue entry - result of the operation
let cqe: IoUringCqe = /* from kernel */;
assert_eq!(cqe.res, 0); // Success
}

Why it matters: io_uring eliminates syscall overhead by batching I/O operations. One syscall can submit hundreds of operations.

ublk - Userspace Block Devices

#![allow(unused)]
fn main() {
use pepita::ublk::{UblkCtrlCmd, UblkIoDesc, UBLK_U_CMD_ADD_DEV};

// Control command - add a new block device
let cmd = UblkCtrlCmd::new(UBLK_U_CMD_ADD_DEV, dev_id);

// I/O descriptor - describes a read/write request
let io_desc: UblkIoDesc = /* from kernel */;
let sector = io_desc.start_sector();
}

Why it matters: ublk allows implementing block devices entirely in userspace with near-native performance.

zram - Compressed Memory

#![allow(unused)]
fn main() {
use pepita::zram::{ZramDevice, ZramConfig, ZramCompressor};

// Create a 1GB compressed RAM device
let config = ZramConfig::with_size(1024 * 1024 * 1024)
    .compressor(ZramCompressor::Lz4);
let device = ZramDevice::new(config)?;

// Write a page (4KB)
let data = [0u8; 4096];
device.write_page(0, &data)?;

// Check compression stats
let stats = device.stats();
println!("Compression ratio: {:.2}x", stats.compression_ratio());
}

Why it matters: zram provides swap/storage that lives in compressed RAM. A 4GB system can effectively have 12-16GB of memory.

MicroVM Runtime

#![allow(unused)]
fn main() {
use pepita::vmm::{MicroVm, VmConfig, VmState};

let config = VmConfig::builder()
    .vcpus(2)
    .memory_mb(256)
    .kernel_path("/boot/vmlinuz")
    .build()?;

let vm = MicroVm::create(config)?;
vm.start()?;
let exit_reason = vm.run()?;
}

Why it matters: MicroVMs provide hardware-level isolation with sub-100ms cold start. Each function runs in its own VM.

Work-Stealing Scheduler

#![allow(unused)]
fn main() {
use pepita::scheduler::Scheduler;
use pepita::task::{Task, Priority};

let scheduler = Scheduler::with_workers(4);

let task = Task::builder()
    .binary("./compute")
    .priority(Priority::High)
    .build()?;

scheduler.submit(task).await?;
}

Why it matters: Work stealing provides automatic load balancing. Idle workers steal from busy workers’ queues.

Integration with Repartir

Pepita provides the low-level primitives that repartir uses for its high-level distributed computing API:

#![allow(unused)]
fn main() {
// repartir uses pepita's SIMD executor
use repartir::executor::simd::{SimdExecutor, SimdTask};

let executor = SimdExecutor::new(); // Uses pepita::simd internally
let task = SimdTask::vadd_f32(a, b);
let result = executor.execute_simd(task).await?;

// repartir uses pepita's MicroVM for serverless
use repartir::executor::microvm::MicroVmExecutor;

let executor = MicroVmExecutor::new(config)?; // Uses pepita::vmm internally
}

Use Cases

Sovereign Infrastructure

Pepita provides building blocks for a complete Docker/Lambda/Kubernetes replacement in pure Rust:

High-Performance Computing

• SIMD acceleration: Auto-detects AVX-512/AVX2/SSE4.1/NEON
• GPU compute: Cross-platform via wgpu (Vulkan/Metal/DX12)
• Work stealing: Near-linear speedup for parallel workloads

Comparison with Alternatives

Performance

running 417 tests
test result: ok. 417 passed; 0 failed; 0 ignored

Benchmarks

Navigate: Table of Contents | Repartir | Trueno

Aprender

Aprender is the ML library for the Sovereign AI Stack, providing training algorithms, model formats, and format conversion utilities.

Key Features

• Algorithms: Linear regression, logistic regression, k-means, decision trees, random forests, gradient boosting, SVM, KNN, Naive Bayes, PCA
• Formats: APR v2 native format, SafeTensors import, GGUF import
• Quantization: Q4_K, Q5_K, Q6_K encoding with row-padded super-blocks

LAYOUT-002: Row-Major Mandate

Critical: Aprender handles all layout conversion for the Sovereign AI Stack.

Format Conversion Architecture

┌─────────────────────────────────────────────────────────┐
│         APRENDER FORMAT CONVERTER                        │
│         src/format/converter/write.rs                   │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  SafeTensors (row-major) ───(pass-through)───► APR v2   │
│                                                          │
│  GGUF (column-major) ───(TRANSPOSE)───► APR v2          │
│                         dequant→transpose→requant        │
│                                                          │
└─────────────────────────────────────────────────────────┘

Key Functions

Transpose Process

1. Dequantize: Q4K bytes → F32 floats
2. Transpose: [rows, cols] → [cols, rows]
3. Re-quantize: F32 → Q4K with row-padded super-blocks

Usage

# Import GGUF with automatic transpose
apr import model.gguf -o model.apr

# Import SafeTensors (no transpose needed)
apr import model.safetensors -o model.apr

Navigate: Table of Contents

Realizar

Realizar is the pure-Rust ML inference engine for the Sovereign AI Stack. It provides high-performance model serving with fused quantized kernels.

Key Features

• Format Support: APR v2, GGUF, SafeTensors
• Quantization: Q4_K, Q5_K, Q6_K, Q8_0 with fused dequant+matmul
• Performance: Ollama-parity throughput targets (100+ tok/s CPU, 500+ GPU)
• Architecture: Qwen2, LLaMA, Mistral, Phi model families

LAYOUT-002: Row-Major Mandate

Critical: Realizar exclusively uses row-major tensor layout.

All GGUF models must be converted to APR format using aprender’s converter, which transposes data from GGUF’s column-major layout to row-major.

# Correct workflow
apr import model.gguf -o model.apr
realizar run model.apr --prompt "Hello"

# WRONG - bypasses layout conversion
realizar run model.gguf  # May produce garbage output

Fused Kernels (Row-Major Only)

Never use trueno’s *_colmajor variants for APR/GGUF data.

Garbage Output Diagnosis

If output looks like "olumbia+lsi nunca/localENTS":

1. Check that model was converted via apr import
2. Verify APR file (not raw GGUF) is being loaded
3. See CLAUDE.md LAYOUT-002 section for details

Navigate: Table of Contents

Whisper.apr: Pure Rust Speech Recognition

whisper.apr is a pure Rust implementation of OpenAI’s Whisper automatic speech recognition model, designed for the Sovereign AI Stack with WASM-first deployment and APR v2 model format.

Overview

whisper.apr delivers:

• Pure Rust: No Python, no C++ dependencies
• WASM-First: Browser deployment with full functionality
• APR v2 Format: LZ4/ZSTD compressed models
• Quantization: Int4/Int8 for reduced memory footprint
• Streaming: Real-time transcription support
• Multilingual: 99+ languages

┌─────────────────────────────────────────────────────────────┐
│                    whisper.apr                              │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ APR v2 Model│  │  Streaming  │  │   Quantization      │  │
│  │ LZ4/ZSTD    │  │ Transcriber │  │   Int4/Int8         │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│  trueno (SIMD)  │  aprender (ML)  │  realizar (inference)  │
└─────────────────────────────────────────────────────────────┘

Installation

[dependencies]
whisper-apr = "0.1"

# With GPU acceleration
whisper-apr = { version = "0.1", features = ["gpu"] }

# WASM-only (smaller bundle)
whisper-apr = { version = "0.1", default-features = false, features = ["wasm"] }

Quick Start

#![allow(unused)]
fn main() {
use whisper_apr::{WhisperModel, Transcriber, TranscribeOptions};

// Load model (APR v2 format with compression)
let model = WhisperModel::load_apr("whisper-small-int8.apr")?;
let transcriber = Transcriber::new(model);

// Transcribe audio file
let result = transcriber.transcribe_file(
    "audio.wav",
    TranscribeOptions::default(),
)?;

println!("Text: {}", result.text);
println!("Language: {}", result.language);

// With timestamps
for segment in result.segments {
    println!("[{:.2}s - {:.2}s] {}",
        segment.start, segment.end, segment.text);
}
}

Model Sizes

Streaming Transcription

Real-time transcription from audio stream:

#![allow(unused)]
fn main() {
use whisper_apr::{StreamingTranscriber, AudioChunk};

let mut streamer = StreamingTranscriber::new(model);

// Process audio chunks as they arrive
while let Some(chunk) = audio_source.next_chunk().await {
    if let Some(partial) = streamer.process_chunk(&chunk)? {
        print!("\r{}", partial.text);  // Live update
    }
}

// Finalize and get complete transcription
let final_result = streamer.finalize()?;
}

WASM Deployment

Browser-compatible transcription:

#![allow(unused)]
fn main() {
use whisper_apr::wasm::{WasmWhisper, init_wasm};

#[wasm_bindgen]
pub async fn transcribe_audio(audio_data: &[u8]) -> String {
    init_wasm().await;

    let whisper = WasmWhisper::load_from_bytes(MODEL_BYTES).await?;
    let result = whisper.transcribe(audio_data)?;
    result.text
}
}

Bundle sizes (gzipped):

Language Detection

#![allow(unused)]
fn main() {
use whisper_apr::LanguageDetector;

let detector = LanguageDetector::new(&model);
let detection = detector.detect(&audio)?;

println!("Detected: {} ({:.1}% confidence)",
    detection.language, detection.confidence * 100.0);

// Top 5 candidates
for (lang, prob) in detection.top_languages(5) {
    println!("  {}: {:.1}%", lang, prob * 100.0);
}
}

Stack Integration

whisper.apr integrates with the Sovereign AI Stack:

Running the Example

cargo run --example whisper_apr_demo

References

• whisper-apr on crates.io
• OpenAI Whisper Paper
• APR v2 Format Specification

Navigate: Table of Contents | Previous: Realizar | Next: trueno-zram

trueno-cuda-edge: GPU Edge-Case Testing

trueno-cuda-edge is a GPU edge-case test framework implementing Popperian falsificationism for CUDA/GPU code. It provides 5 falsification frameworks with a 50-point verification checklist.

Overview

GPU code is notoriously difficult to test due to:

• Non-deterministic behavior
• Hardware-dependent edge cases
• Complex lifecycle management
• Numerical precision variations

trueno-cuda-edge addresses these challenges with systematic falsification testing that integrates with batuta’s orchestration pipelines.

Integration with Batuta

Batuta orchestrates GPU workloads across the Sovereign AI Stack. trueno-cuda-edge validates that these orchestrations handle GPU edge cases correctly.

Pipeline Validation

Use trueno-cuda-edge to validate batuta’s GPU backend selection:

#![allow(unused)]
fn main() {
use trueno_cuda_edge::shmem_prober::{ComputeCapability, shared_memory_limit, check_allocation};

// Validate backend selection considers GPU capabilities
let ampere = ComputeCapability::new(8, 0);
assert_eq!(shared_memory_limit(ampere), 164 * 1024); // 164 KB

// Check allocation fits before dispatching
check_allocation(ampere, 128 * 1024)?;
}

Null Pointer Safety

Prevent null pointer bugs in GPU memory operations:

#![allow(unused)]
fn main() {
use trueno_cuda_edge::null_fuzzer::{NonNullDevicePtr, InjectionStrategy, NullFuzzerConfig};

// Type-safe device pointer that rejects null at construction
let ptr = NonNullDevicePtr::<f32>::new(0x7f00_0000_0000)?;
assert!(NonNullDevicePtr::<f32>::new(0).is_err());

// Fault injection for testing error handling
let config = NullFuzzerConfig {
    strategy: InjectionStrategy::Periodic { interval: 10 },
    total_calls: 1000,
    fail_fast: false,
};
}

ML Converter Quantization Parity

Validate CPU/GPU numerical parity in batuta’s ML converters:

#![allow(unused)]
fn main() {
use trueno_cuda_edge::quant_oracle::{QuantFormat, check_values_parity, ParityConfig};

// Format-specific tolerances
assert_eq!(QuantFormat::Q4K.tolerance(), 0.05);  // 5% for 4-bit
assert_eq!(QuantFormat::Q6K.tolerance(), 0.01);  // 1% for 6-bit

// Compare CPU and GPU results
let config = ParityConfig::new(QuantFormat::Q4K);
let report = check_values_parity(&cpu_values, &gpu_values, &config);
assert!(report.passed());
}

PTX Kernel Validation

Validate PTX kernels generated by trueno:

#![allow(unused)]
fn main() {
use trueno_cuda_edge::ptx_poison::{PtxVerifier, PtxMutator, default_mutators};

let verifier = PtxVerifier::new();

// Structural verification (6 checks)
let verified = verifier.verify(ptx_source)?;

// Mutation testing with 8 operators
let mutators = default_mutators();
let mutated = PtxMutator::FlipAddSub.apply(ptx_source);
}

Falsification Frameworks

F1: Null Pointer Sentinel Fuzzer

• NonNullDevicePtr<T>: Type-safe device pointer
• InjectionStrategy: Periodic, SizeThreshold, Probabilistic, Targeted
• NullSentinelFuzzer: State machine for null injection

F2: Shared Memory Boundary Prober

• ComputeCapability: GPU capability detection
• shared_memory_limit(): SM-specific limits
• check_allocation(): Validate before dispatch

F3: Context Lifecycle Chaos

• ChaosScenario: 8 lifecycle edge cases
• ContextLeakDetector: Memory leak detection
• 1 MB tolerance for driver allocations

F4: Quantization Parity Oracle

• QuantFormat: Q4K, Q5K, Q6K, Q8_0, F16, F32
• BoundaryValueGenerator: Edge case inputs
• check_values_parity(): CPU/GPU comparison

F5: PTX Compilation Poison Trap

• PtxVerifier: 6 structural checks
• PtxMutator: 8 mutation operators
• Mutation score calculation

50-Point Falsification Protocol

Track verification coverage:

#![allow(unused)]
fn main() {
use trueno_cuda_edge::falsification::{FalsificationReport, all_claims};

let mut report = FalsificationReport::new();

// Mark claims as verified during testing
report.mark_verified("NF-001");  // Null fuzzer claim
report.mark_verified("QO-001");  // Quantization oracle claim

// Track coverage
println!("Coverage: {:.1}%", report.coverage() * 100.0);
assert!(report.coverage() >= 0.80);  // 80% minimum for release
}

Supervision Integration

Erlang OTP-style supervision for GPU workers:

#![allow(unused)]
fn main() {
use trueno_cuda_edge::supervisor::{
    SupervisionStrategy, SupervisionTree, GpuHealthMonitor, HeartbeatStatus
};

// OneForOne: isolated restarts
let mut tree = SupervisionTree::new(SupervisionStrategy::OneForOne, 4);

// Health monitoring
let monitor = GpuHealthMonitor::builder()
    .max_missed(3)
    .throttle_temp(85)
    .shutdown_temp(95)
    .build();

// Check worker health
let action = monitor.check_status(HeartbeatStatus::MissedBeats(2));
}

See Also

• Trueno: Multi-target Compute
• Realizar: ML Inference Runtime
• GPU Acceleration

Model Serving Ecosystem

The Model Serving Ecosystem provides a unified interface for local and remote model serving across the ML ecosystem. Built on Toyota Way principles, it ensures reliable, cost-effective, and privacy-aware model inference.

Toyota Way Principles

Components

ChatTemplateEngine

Unified prompt templating supporting multiple formats:

#![allow(unused)]
fn main() {
use batuta::serve::{ChatTemplateEngine, ChatMessage, TemplateFormat};

// Auto-detect from model name
let engine = ChatTemplateEngine::from_model("llama-2-7b-chat");

let messages = vec![
    ChatMessage::system("You are a helpful assistant."),
    ChatMessage::user("What is Rust?"),
];

let prompt = engine.apply(&messages);
}

Supported Formats:

• Llama2 - Meta’s Llama 2 format with [INST] tags
• Mistral - Mistral’s format (similar to Llama2)
• ChatML - OpenAI-style <|im_start|> format
• Alpaca - Stanford Alpaca instruction format
• Vicuna - Vicuna conversation format
• Raw - Passthrough without formatting

BackendSelector

Intelligent backend selection with privacy tiers:

#![allow(unused)]
fn main() {
use batuta::serve::{BackendSelector, PrivacyTier, ServingBackend};

let selector = BackendSelector::new()
    .with_privacy(PrivacyTier::Sovereign)  // Local only
    .with_latency(LatencyTier::Interactive);

let backends = selector.recommend();
// Returns: [Realizar, Ollama, LlamaCpp]
}

Privacy Tiers:

Supported Backends:

Local (8):

• Realizar, Ollama, LlamaCpp, Llamafile, Candle, Vllm, Tgi, LocalAI