Architecture - GuitarAlchemist/ix GitHub Wiki

Architecture

Workspace Structure

ix is a Cargo workspace with 33 crates organized by domain:

ix/
├── Cargo.toml                 # Workspace root
├── CLAUDE.md                  # Project conventions for Claude Code
├── .mcp.json                  # MCP server configuration
├── .claude/
│   ├── skills/                # 10 Claude Code skills
│   ├── hooks/                 # Pipeline validation, cache lifecycle
│   └── agents/                # Compound engineering agents
├── governance/
│   └── demerzel/              # Git submodule: constitutions, personas, policies
├── state/                     # Belief state persistence
│   ├── beliefs/               # Tetravalent belief states (*.belief.json)
│   ├── pdca/                  # PDCA cycle tracking
│   ├── knowledge/             # Knowledge transfer records
│   └── snapshots/             # Belief snapshots for reconnaissance
├── examples/                  # 16 runnable examples
├── docs/                      # 60+ tutorials (EN + FR)
└── crates/
    ├── ix-math/               # Core math primitives
    ├── ix-optimize/           # Optimization algorithms
    ├── ix-supervised/         # Regression, classification, metrics
    ├── ix-unsupervised/       # Clustering, dimensionality reduction
    ├── ix-ensemble/           # Random forest, gradient boosting
    ├── ix-nn/                 # Neural networks, transformers
    ├── ix-rl/                 # Reinforcement learning
    ├── ix-evolution/          # Evolutionary algorithms
    ├── ix-graph/              # Graphs, Markov, HMM/Viterbi
    ├── ix-search/             # Search algorithms (A*, Q*, MCTS)
    ├── ix-game/               # Game theory
    ├── ix-chaos/              # Chaos theory
    ├── ix-signal/             # Signal processing, time series
    ├── ix-adversarial/        # Adversarial ML, differential privacy
    ├── ix-dynamics/           # IK, Lie groups, neural ODEs
    ├── ix-topo/               # Persistent homology, TDA
    ├── ix-ktheory/            # Graph K-theory
    ├── ix-category/           # Category theory primitives
    ├── ix-grammar/            # Formal grammars, parsers
    ├── ix-rotation/           # Quaternions, SLERP, rotation math
    ├── ix-sedenion/           # Hypercomplex algebra
    ├── ix-fractal/            # Fractals, L-systems, space-filling curves
    ├── ix-number-theory/      # Primes, modular arithmetic, elliptic curves
    ├── ix-probabilistic/      # Bloom filter, HyperLogLog, etc.
    ├── ix-gpu/                # WGPU compute shaders
    ├── ix-cache/              # Embedded Redis-like cache
    ├── ix-pipeline/           # DAG executor
    ├── ix-io/                 # Data I/O (CSV, JSON, TCP, HTTP, WebSocket)
    ├── ix-governance/         # Demerzel governance runtime
    ├── ix-agent/              # MCP server (37 tools)
    ├── ix-skill/              # CLI binary
    └── ix-demo/               # egui desktop app

Technology Stack

Component Technology
Language Rust (MSRV 1.80+)
Matrix ops ndarray 0.17 (f64 on CPU)
GPU compute wgpu 28 (Vulkan/DX12/Metal, f32 via WGSL shaders)
Async runtime tokio 1 (I/O, cache server)
RNG rand 0.9 + rand_distr 0.5
Error handling thiserror 2
CLI clap 4
Governance parsing serde_yaml 0.9
Property testing proptest 1
Benchmarking criterion 0.5

Design Conventions

  • Pure Rust -- no external ML frameworks (except WGPU for GPU compute)
  • CPU uses f64 via ndarray::Array{1,2}<f64>; GPU uses f32 via WGSL shaders
  • Builder pattern for algorithm configuration
  • Seeded RNG for reproducibility
  • Domain traits -- each crate defines traits like Regressor, Classifier, Clusterer, Optimizer
  • No runtime code in governance -- governance artifacts are YAML/Markdown specifications

MCP Server Architecture

The ix-agent crate exposes 37 MCP tools via JSON-RPC over stdio. Tool categories:

  • Algorithm tools (26) -- optimization, clustering, search, chaos, HMM, adversarial, game theory, pipeline, signal, neural nets, bandits, evolution, etc.
  • Governance tools (3) -- ix_governance_check, ix_governance_persona, ix_governance_belief
  • Federation tools (4) -- federation_discover, federation_grammar, federation_music, federation_traces

MCP Federation

ix participates in a three-server federation defined in .mcp.json:

ix (Rust)  <-->  tars (F#)  <-->  ga (C#)
    \               |               /
     \              |              /
      +--- Demerzel governance ---+
  • ix provides math/ML algorithms
  • tars provides grammar weighting, pattern promotion, metacognition
  • ga provides music theory, chord analysis, trace export

Claude Code Skills

80+ skills organized by domain:

  • Algorithm skills (26): ix-optimize, ix-cluster, ix-search, ix-chaos, ix-hmm, ix-adversarial, ix-game, ix-pipeline, ix-signal, ix-benchmark, ix-nn, ix-bandit, ix-evolution, ix-random-forest, ix-supervised, ix-topo, ix-category, ix-dynamics, ix-ktheory, ix-gpu, ix-cache, ix-grammar, ix-rotation, ix-sedenion, ix-fractal, ix-number-theory
  • Governance skills (3): ix-governance-check, ix-governance-persona, ix-governance-belief
  • Federation skills (4): federation-discover, federation-grammar, federation-music, federation-traces
  • Ecosystem skills (4): governed-execute, ecosystem-audit, roadblock-resolver, delegate-cli

Crate Dependency Layers

Layer 4 (Integration):  ix-agent, ix-skill, ix-demo
Layer 3 (Governance):   ix-governance
Layer 2 (Algorithms):   ix-supervised, ix-unsupervised, ix-nn, ix-search, ...
Layer 1 (Foundation):   ix-math, ix-io, ix-gpu, ix-cache, ix-pipeline

Higher layers depend on lower layers. The governance crate integrates with the agent but does not affect algorithm implementations.

Auto-generated by Demerzel Wiki Sync on 2026-10-15 13:00 UTC.

⚠️ **GitHub.com Fallback** ⚠️