Getting Started

Prerequisites

• Rust 1.80+ (due to wgpu 28 dependency) -- install via rustup
• Git (with submodule support for governance artifacts)
• GPU drivers (optional, for ix-gpu crate -- Vulkan, DX12, or Metal)

Clone

git clone --recurse-submodules https://github.com/GuitarAlchemist/ix.git
cd ix

If you already cloned without submodules:

git submodule update --init --recursive

This pulls the Demerzel governance framework into governance/demerzel/.

Build

# Build all 33 crates
cargo build --workspace

# Build in release mode
cargo build --workspace --release

# Build a specific crate
cargo build -p ix-math

Test

# Run all unit and integration tests
cargo test --workspace

# Run with clippy (zero warnings policy)
cargo clippy --workspace -- -D warnings

# Property-based tests (proptest)
cargo test --workspace -- --include-ignored

# Benchmarks
cargo bench -p ix-math

# Generate API docs
cargo doc --workspace --no-deps --open

Run

CLI

Use ix-skill for direct command-line access to algorithms:

cargo run -p ix-skill -- optimize --algo pso --function sphere --dim 10

MCP Server

Start the MCP server for Claude Code integration:

cargo run -p ix-agent

To register ix as a Claude Code MCP server, add to .mcp.json:

{
  "mcpServers": {
    "ix": {
      "command": "cargo",
      "args": ["run", "-p", "ix-agent"]
    }
  }
}

Claude can then call tools like ix_kmeans, ix_viterbi, ix_optimize, etc. directly during conversations.

Desktop Demo

Launch the interactive egui demo with 22+ tabs:

cargo run -p ix-demo

Examples

16 runnable examples covering optimization, clustering, HMM, game theory, chaos, adversarial ML, and more:

cargo run --example pso_rosenbrock
cargo run --example decision_tree
cargo run --example kmeans_clustering
cargo run --example dbscan_anomaly
cargo run --example viterbi_hmm
cargo run --example nash_equilibrium
cargo run --example astar_qstar
cargo run --example logistic_map
cargo run --example dag_pipeline
cargo run --example robustness_test
cargo run --example fft_analysis
cargo run --example auctions
cargo run --example bandits
cargo run --example bloom_filter
cargo run --example similarity_search   # requires GPU
cargo run --example embedded_cache

Documentation

• Tutorials: 60+ tutorials at docs/INDEX.md
• French tutorials: docs/fr/INDEX.md
• API docs: cargo doc --workspace --no-deps --open

MCP Federation Setup

To connect ix with the full ecosystem (tars + ga), configure all three servers in .mcp.json:

{
  "mcpServers": {
    "ix": {
      "command": "cargo",
      "args": ["run", "--release", "-p", "ix-agent"]
    },
    "tars": {
      "command": "dotnet",
      "args": ["run", "--project", "path/to/Tars.Interface.Cli", "--", "mcp", "server"]
    },
    "ga": {
      "command": "dotnet",
      "args": ["run", "--project", "path/to/GaMcpServer"]
    }
  }
}

Contributing

Conventions

• Pure Rust (no external ML frameworks, except WGPU for GPU)
• CPU algorithms use f64; GPU uses f32 via WGSL shaders
• Builder pattern for algorithm configuration
• Seeded RNG for reproducibility
• Each crate defines domain traits (Regressor, Classifier, Clusterer, Optimizer, etc.)
• All /// doc examples must compile and run

Governance Compliance

All contributions operate under the Demerzel constitution. See Governance for details. Key points:

• Agents must comply with the 11-article operational constitution
• Confidence thresholds determine when to act autonomously vs. escalate
• The state/ directory tracks belief states and PDCA cycles
• Constitutional articles are append-only (removals need explicit justification)

CI

GitHub Actions runs on stable + nightly Rust, Linux + Windows:

• cargo build --workspace
• cargo test --workspace
• cargo clippy --workspace -- -D warnings