GuitarAlchemist/ix

> **Read this first:** docs/MANUAL.md — the canonical user manual. Install, tool inventory, pipeline format, governance integration, extension guide, troubleshooting. Start there.
A Rust workspace of composable ML/math algorithms and AI governance, designed to be exposed as **Claude Code skills** via an MCP server and CLI. Part of the GuitarAlchemist ecosystem (ix + tars + ga + Demerzel).
For industrial engineering and robotics, IX is an **offline/advisory co-processor**. It can analyze telemetry, run reproducible optimization experiments, rank planner parameters, and orchestrate external engineering tools. It is not a CAD kernel, FEA/CFD solver, collision engine, complete digital twin, hard-real-time controller, safety PLC, consensus service, or authoritative distributed lock. See ADR-0005.
81 crates. 96 MCP tools. 80+ Claude Code skills. Pure Rust. No external ML frameworks.
Quick Start
ix-embed accepts an ix-local-embedding-request/1 JSON document on stdin (or
from --input ) and emits ix-local-embedding-response/1. The caller must
provide --model-cache containing a complete cached
Xenova/bge-base-en-v1.5 revision. The adapter verifies every required cache
object before inference and forces any cache-miss fallback to loopback, so it
never downloads a model or calls a paid provider implicitly.
Crate Maturity & Stability
Maturity Tiers
| Tier | Meaning | Downstream-Safe? |
|------|---------|:---:|
| **Stable** | API commitments, well-tested, used in production MCP tools | Yes |
| **Beta** | Feature-complete, actively used, API may change between minor versions | With caution |
| **Experimental** | Research-grade, novel math, no stability guarantees | No |
| **Internal** | Tooling/infra, not intended for direct external use | No |
Stable Subset (safe for ga, tars, Demerzel consumption via MCP)
| Crate | Tier | Notes |
|-------|------|-------|
| ix-math | Beta | Core linear algebra, statistics, activations — everything depends on this. Demoted from Stable 2026-06-21 while the new inference surface (two-sample tests, divergences, moments) settles |
| ix-optimize | Stable | SGD, Adam, PSO, simulated annealing |
| ix-supervised | Stable | Regression, trees, KNN, SVM, metrics |
| ix-ensemble | Stable | Random forest, gradient boosted trees |
| ix-unsupervised | Stable | KMeans, DBSCAN, PCA, t-SNE, GMM |
| ix-search | Stable | A*, MCTS, minimax, BFS/DFS |
| ix-graph | Beta | Markov chains, HMM/Viterbi, agent routing, components + centrality. Demoted from Stable 2026-06-21 while the new components/centrality surface settles |
| ix-signal | Beta | FFT, wavelets, Kalman, state-space + observability/controllability, spectral analysis |
| ix-cache | Stable | Embedded in-process cache (TTL, LRU, pub/sub) — promoted 2026-05-02 |
| ix-probabilistic | Stable | Bloom, HLL, Count-Min, Cuckoo — promoted 2026-05-02 |
| ix-game | Stable | Nash, Shapley, auctions, mechanism design — promoted 2026-05-02 |
| ix-rl | Stable | Bandits (EpsilonGreedy, UCB1, Thompson), Q-learning — promoted 2026-05-02 |
Stability contract
"Stable" is not just documentation — **CI prevents silent breakage**. The
stable-surface.yml workflow runs on
every PR: it hashes the public-API surface of each Stable-tier crate on
main, then again on the PR branch, and **fails** the check if any hash
changed. Non-stable crates produce a warning only.
Source of truth: crate-maturity.toml at the workspace
root. The CLI subcommand ix stable-surface is the reference implementation
used by CI and is runnable locally:
The hash is a BLAKE3 over the sorted, deduplicated set of pub declarations
discovered in each crate's src/**.rs. It catches **added / removed /
renamed exported symbols** — enough to stop accidental breaks. It does NOT
catch finer-grained changes (function signature edits, trait-bound
additions, variance shifts). Those are out of scope for v1; revisit with
cargo public-api integration when a real break slips through.
**To intentionally break a Stable API**, do one of the following in the
SAME PR that introduces the change:
1. **Demote the crate** to beta in crate-maturity.toml. The guard then
downgrades the diff to a warning. Document the demotion in the PR body.
2. **Bump the crate's major version** in its Cargo.toml. (v1 of this
guard still flags the hash change — bumping the major version is the
semver-correct signal to downstream consumers, but the guard does not
yet auto-detect it. Use the demotion path for the CI to go green, then