WAIT — Mixed signals — read the receipts

• Last commit today
• 4 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 78% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Tract is a lightweight neural network inference engine written in Rust that loads, optimizes, and executes ONNX and NNEF models without external dependencies. It powers Sonos' on-device inference for tasks like ASR and LLM execution, passing 85% of ONNX backend tests and successfully running production models like MobileNet, ResNet, BERT, and Stable Diffusion. Monorepo with 24 workspace crates: core/ contains the inference engine, hir/ is the intermediate representation, onnx/ and tensorflow/ are format loaders, pulse/ handles optimization passes, linalg/ provides math kernels, and gpu/cuda/metal/ are optional accelerators. Examples/ folder contains runnable end-to-end demos (mobilenet, BERT, Stable Diffusion). CI orchestration via .travis/ shell scripts and .github/workflows/.

Embedded systems engineers, ML ops teams, and Sonos product developers who need to deploy neural networks on resource-constrained devices (ARM, x86, mobile) without TensorFlow/PyTorch runtime overhead; also companies needing inference engines with minimal binary size and zero external C++ dependencies.

Production-ready with active development: backed by Sonos, uses comprehensive CI (19 GitHub workflows including ASAN, cross-platform, large_models, cost_model), extensive test harnesses (test-rt/suite-*), and 6.3M lines of Rust code. The workspace structure with 24+ crates, stable API surface (tract-core on docs.rs), and real-world model examples indicate mature infrastructure, though some ONNX operator gaps remain intentional (Tensor Sequences, Optional types).

Moderate risk: single organization (Sonos) as primary maintainer with no visible public issue tracker in file list; dependency chain is minimal by design but monorepo size (6.3M LoC) creates integration risk; CUDA/Metal/GPU support is optional but requires platform-specific toolchains; breaking changes possible given pre-1.0 versioning implied by workspace structure. Metal and CUDA crates excluded from default-members suggest platform-specific stability concerns.

Active development of LLM inference (examples/causal_llm, examples/stable-diffusion-3), ASR models (nemo-parakeet, nemo-nemotron examples), cost modeling infrastructure (cost_model.yml workflow), and platform-specific optimization (Metal, CUDA, ASAN testing). Recent focus on wheel distribution (wheels.yml) and large model support (large_models.yml workflow).

Clone and build with Rust 1.91.0+: git clone https://github.com/sonos/tract.git && cd tract && cargo build --release. Run an example: cargo run --example onnx-mobilenet-v2 --release -- <path-to-onnx-model> <input-data>. For Python: pip install tract and see pypi.org/project/tract/.

Daily commands: Debug: cargo build && cargo test. Release binary: cargo build --release. Run full CI suite: ./.travis/run_all.sh or invoke specific workflows via GitHub Actions. Python package: cd api/rs && cargo build --release then pip install -e ..

• Cargo.toml — Workspace root defining all crates (core, onnx, tensorflow, tflite, api) and their interdependencies—essential for understanding project structure and build configuration.
• core/Cargo.toml — Core inference engine crate; all other inference backends depend on abstractions defined here, making it the load-bearing abstraction layer.
• onnx/Cargo.toml — ONNX operator library and model loading; primary entry point for ONNX model inference, heavily used in examples and tests.
• api/ffi/src/lib.rs — C FFI bindings that expose tract's inference engine to non-Rust consumers; critical integration point for production deployments.
• api/proxy/src/lib.rs — High-level proxy API unifying C, Python, and Rust interfaces; this is how external code actually calls tract.
• .github/workflows/full.yml — Primary CI/CD pipeline that validates build, tests, and release artifacts across platforms; understanding this shows testing and release strategy.
• README.md — Project vision and quick-start reference for inference toolkit capabilities; defines scope and primary use cases.

Add a new ONNX operator implementation

1. Define operator signature in tract-core operator registry (check existing operators for patterns) (core/src/ops/mod.rs or onnx/src/ops/)
2. Implement Op trait for your operator with validate() and eval() methods (onnx/src/ops/[your_operator].rs)
3. Register operator mapping from ONNX model format to implementation in the ONNX loader (onnx/src/lib.rs (operator registration in opset parsing))
4. Add test case converting ONNX model with your operator and validating output (.travis/onnx-tests.sh or create new test in onnx/tests/)

Add support for a new hardware accelerator (e.g., new GPU backend)

1. Create new crate directory following pattern of 'metal' or 'cuda', with Cargo.toml declaring dependency on core and gpu (gpu/ (new directory with src/lib.rs))
2. Implement the DeviceBase trait defining memory allocation, kernel execution, and data transfer (gpu/src/lib.rs - device abstraction interface)
3. Implement GEMM and core tensor ops for your hardware target ([accelerator]/src/kernels.rs or similar)
4. Register accelerator in core's Device enum and enable conditional compilation (core/src/runtime.rs or gpu/src/lib.rs (device factory))
5. Add CI workflow to test on hardware or via emulation (.github/workflows/ (new or update cross-platform.yml))

Add a new language binding (e.g., Go, Ruby, C#)

1. Create new API module in api/ directory following api/ffi/ or api/proxy/ structure (api/[language]/ with Cargo.toml and build script)
2. Use cbindgen or manual C header definitions to map tract types to language-native types (api/[language]/src/lib.rs or api/[language]/cbindgen.toml)
3. Implement InferenceModel wrapper and tensor marshaling following proxy pattern (api/proxy/src/lib.rs as reference implementation)
4. Write integration test loading a model and running inference in target language (api/[language]/tests/ (e.g., api/[language]/tests/mobilenet.rs))

Optimize a model or add a graph transformation pass

1. Implement GraphRewrite trait in core's simplification/optimization module (core/src/optim/ or hir/src/ (HIR for high-level rewrite))
2. Add before/after test case showing transformation impact (use ONNX/NNEF model as fixture) (core/tests/ or hir/tests/)
3. Register pass in optimization pipeline (typically in InferenceModel setup) (core/src/lib.rs or api/proxy/src/lib.rs (run_passes or optimize))
4. Benchmark using examples (e.g., mobilenet) and update cost model if needed (examples/onnx-mobilenet-v2/ or use cost_model tests)

• Rust — Memory safety without GC, zero-cost abstractions for performance-critical tensor ops, excellent FFI ecosystem for polyglot bindings
• ONNX & NNEF formats — Industry-standard model interchange formats enabling training framework agnosticity (PyTorch, TensorFlow, JAX)
• WGPU / Metal / CUDA — Portable GPU acceleration: WGPU runs on any platform with Vulkan/Metal/DX12; Metal for macOS; CUDA for NVIDIA-specific optimization
• Graph optimization (HIR, Pulse) — Layer-wise operator fusion, constant folding, and sequence optimization reduce memory bandwidth and latency before execution
• Workspace Cargo crate structure — Modular dependency graph allows optional features (e.g., GPU, TensorFlow) without bloating minimal builds; each crate independently versioned

• No built-in automatic differentiation (AD/backpropagation)

  • Why: tract is inference-only; training is handled by upstream frameworks (PyTorch, TF), keeping codebase focused and small
  • Consequence: Cannot use tract to refine/train models; users must export trained models from frameworks

• Separate C FFI layer (api/ffi) from Rust API (api/proxy)

  • Why: Rust API uses idiomatic ergonomics (Result, ownership); FFI must expose stable C-compatible types for long-term binary compatibility
  • Consequence: Two maintenance surfaces; changes to core require updates in both bindings

• Optional GPU backends behind feature flags

  • Why: Avoid heavyweight dependencies (CUDA SDK, Metal frameworks) for CPU-only or embedded deployments
  • Consequence: Users targeting GPU must explicitly enable features; binary size grows significantly with GPU support enabled

• Graph optimization passes are eager, not JIT

  • Why: Simplifies deployment: optimize once at load-time, no runtime overhead; deterministic performance
  • Consequence: undefined

Rust 1.91.0+ required (not 1.90 or earlier); CUDA/Metal builds need external SDK setup (.travis/ci-system-setup.sh shows platform-specific complexity); Python wheels build via .github/workflows/wheels.yml with platform-specific dockers; some tests marked as platform-specific and excluded from default-members (metal, cuda, tflite); cost_model.yml workflow requires specific hardware profiling setup; TensorFlow/ONNX test suites expect exact operator semantics (intentional Tensor Sequence gaps will cause failures on some ONNX conformance tests).

• Intermediate Representation (HIR) — Tract uses hir/ to decouple model loading (ONNX/TensorFlow) from inference runtime, enabling format-agnostic optimization passes and executor targeting
• Operator Fusion & Dead Code Elimination — Pulse optimization passes fold adjacent ops (conv+relu) and eliminate unused tensors to reduce latency and memory—critical for embedded inference where every µs matters
• Quantization-Aware Inference — Tract supports int8 quantized ONNX models (ConvInteger, DequantizeLinear ops) to run low-precision models on ARM devices without separate quantization framework
• Multi-backend Dispatch (CUDA/Metal/CPU) — gpu/, cuda/, metal/ crates use runtime dispatch to select accelerators without recompiling; enables single binary supporting heterogeneous hardware
• Recurrent Neural Network (RNN/GRU) Optimization — Pulse/ contains specialized passes for unrolling and fusing RNN cells; tract/transformers crate optimizes LLM inference (causal_llm example) by handling attention efficiently
• Memory-Mapped I/O for Model Loading — Tract can load models via mmap without full deserialization, reducing startup latency and peak memory on embedded systems
• Cost Modeling & Profiling Infrastructure — cost_model.yml workflow captures per-operation latency profiles; tract uses these to make optimization decisions (e.g., when to fuse ops) in a platform-aware way

• onnx/onnx — Official ONNX specification and test suite that tract aims to pass; defines operator semantics and conformance tests
• pytorch/pytorch — Common source of ONNX models via torch.onnx.export; ONNX interop is a primary use case
• tensorflow/tensorflow — Second major model source supported by tract (via tensorflow/ crate); some users export TF frozen graphs to tract format
• tvm-project/tvm — Competing neural network inference framework with similar goals (lightweight, multi-backend) but heavier footprint; benchmark reference for tract performance
• openxla/xla — Google's compiler for neural networks; shares optimization philosophy with tract's pulse/ but designed for GPU-centric workloads where tract targets embedded

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive CI workflow for Python wheel distribution validation

The repo has .github/workflows/wheels.yml but lacks integration tests validating that published wheel distributions work across platforms (Linux, macOS, Windows) with different Python versions (3.9+). The PyPI badge in README.md suggests active Python package distribution, but there's no visible workflow testing actual wheel installation and basic inference on multiple Python versions.

• [ ] Create .github/workflows/wheels-validation.yml to test wheel installation on ubuntu-latest, macos-latest, windows-latest
• [ ] Add matrix strategy for Python 3.9, 3.10, 3.11, 3.12
• [ ] Include basic inference tests from examples/ (e.g., mobilenet) after wheel installation
• [ ] Validate that import tract works and core API functions execute correctly

Add missing integration tests for ONNX and TensorFlow model format conversions

The repo supports multiple model formats (ONNX, NNEF, TensorFlow, TFLite) with separate test harnesses in .travis/ (onnx-tests.sh, tf.sh), but test-rt/ directory shows fragmented test suites without unified cross-format conversion validation. There's no visible test ensuring that a model loaded from ONNX produces identical inference results when converted through NNEF.

• [ ] Create test-rt/test-format-conversion/ with Cargo.toml for cross-format tests
• [ ] Add test cases comparing inference outputs: ONNX → NNEF → inference vs direct ONNX inference
• [ ] Add test cases for TensorFlow → NNEF → inference equivalence validation
• [ ] Include fixture models (simple conv nets) in test-rt/test-format-conversion/models/

Consolidate and modernize legacy Travis CI scripts into GitHub Actions workflows

The repo maintains both .travis.yml and .github/workflows/ in parallel. The .travis/ directory contains 20+ shell scripts (native.sh, tf.sh, tflite.sh, etc.) that duplicate logic already attempted in GitHub Actions. This technical debt makes maintenance harder and creates inconsistent CI behavior. Migrating these to GitHub Actions and removing .travis/ reduces confusion.

• [ ] Audit which .travis/*.sh scripts are still in active use by checking .github/workflows/*.yml references
• [ ] Consolidate .travis/regular-tests.sh, native.sh, debug-tests.sh logic into .github/workflows/full.yml
• [ ] Migrate .travis/tflite.sh and tflite Dockerfiles to a dedicated .github/workflows/tflite-validation.yml
• [ ] Update documentation (README.md, CONTRIBUTING guide) to reference GitHub Actions, then safely remove .travis/ directory

• Add missing ONNX Resize operator variants: the README notes 'Resize' as a dark corner; implement the missing resampling modes (cubic, linear) in onnx/src/ops/resize.rs with corresponding tests in test-rt/suite-onnx/.
• Expand linalg/src/ with ARM NEON SIMD fastpaths: build ARM-specific gemm/conv kernels leveraging NEON intrinsics for mobile inference (Sonos uses ARM heavily); reference linalg/src/frame for the pattern.
• Document pulse/ optimization passes: add rustdoc comments to pulse/src/lib.rs explaining each optimization pass (dead-code elimination, constant folding, etc.) with before/after graph examples, unblocking contributors wanting to extend optimizations.

The tract repository demonstrates a mature Rust/ML inference project with generally good security practices (GitHub Actions, workspace organization, FFI isolation). Primary concerns are: (1) Legacy Travis CI infrastructure creating configuration debt, (2) Complex multi-crate workspace increasing dependency management complexity, (3) FFI boundaries requiring careful unsafe code auditing, and (4) Test data management practices. No critical vulnerabilities detected in visible structure, but comprehensive dependency auditing via 'cargo audit' and regular security reviews of unsafe FFI code are essential. Recommendation: Fully migrate from Travis CI, implement mandatory dependency scanning in GitHub Actions, and conduct security-focused code review of FFI and unsafe blocks.

• Medium · Outdated Travis CI Configuration — .travis.yml, .travis/ directory. The repository contains legacy .travis.yml and .travis/ directory structure alongside modern GitHub Actions workflows. Travis CI has known security concerns and is no longer recommended. Maintenance of dual CI systems increases attack surface and configuration drift risks. Fix: Migrate all CI/CD logic to GitHub Actions workflows and remove legacy Travis CI configuration files. Ensure all secrets are rotated and managed only through GitHub Secrets.
• Medium · Potential Hardcoded Test Data — api/c/grace_hopper_3_224_224.f32.raw. The presence of raw binary files (e.g., grace_hopper_3_224_224.f32.raw) in the repository could indicate committed test data. If these files are large or frequently updated, they may bloat the repository and create supply chain risks. Fix: Use Git LFS (Large File Storage) for binary test data or host test models externally. Add binary files to .gitignore and document how to obtain them separately.
• Low · Multiple Crate Dependencies Without Lock File Visibility — Cargo.toml (workspace definition). The Cargo.toml shows a large workspace with 50+ crates including examples and harness tests. Without visible Cargo.lock content analysis, transitive dependency vulnerabilities cannot be fully assessed. The workspace complexity increases supply chain risk. Fix: Regularly run 'cargo audit' in CI/CD pipelines. Use 'cargo-deny' (already referenced in .travis scripts) to audit dependencies. Maintain and commit Cargo.lock to ensure reproducible builds.
• Low · Exposed Debug/Test Harness Crates — Cargo.toml (harness/* and test-rt/* members), harness/ and test-rt/ directories. Multiple test harness and example crates are included in the workspace (harness/, test-rt/, examples/). These should not be published to crates.io as they may contain development-only code with reduced security standards. Fix: Explicitly exclude harness and test-rt members from being published. Add 'publish = false' to their Cargo.toml files. Review example crates for embedded credentials or secrets.
• Low · FFI Boundary Exposure — api/ffi/Cargo.toml, api/ffi/cbindgen.toml, api/ffi/src/lib.rs. The api/ffi crate provides C language bindings via cbindgen. FFI boundaries are historically prone to security issues (buffer overflows, type confusion). The cbindgen configuration should be carefully reviewed for safety. Fix: Audit all FFI code for unsafe blocks. Use #[deny(unsafe_code)] or minimize unsafe usage. Conduct security review of cbindgen output. Add bounds checking and input validation at FFI boundaries.
• Low · Proxy Crate Licensing Concerns — api/proxy/LICENSE, api/proxy/LICENSE-APACHE, api/proxy/LICENSE-MIT. The api/proxy crate contains separate LICENSE files, suggesting it may have different license terms. Multiple license files in a monorepo can cause compliance confusion. Fix: Clarify licensing strategy. Use a single top-level LICENSE or clearly document why different licenses are needed. Run license compliance checks in CI/CD.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/sonos/tract shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live sonos/tract repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/sonos/tract.

What it runs against: a local clone of sonos/tract — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in sonos/tract | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of sonos/tract. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/sonos/tract.git
#   cd tract
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of sonos/tract and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "sonos/tract(\\.git)?\\b" \\
  && ok "origin remote is sonos/tract" \\
  || miss "origin remote is not sonos/tract (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "core/Cargo.toml" \\
  && ok "core/Cargo.toml" \\
  || miss "missing critical file: core/Cargo.toml"
test -f "onnx/Cargo.toml" \\
  && ok "onnx/Cargo.toml" \\
  || miss "missing critical file: onnx/Cargo.toml"
test -f "api/ffi/src/lib.rs" \\
  && ok "api/ffi/src/lib.rs" \\
  || miss "missing critical file: api/ffi/src/lib.rs"
test -f "api/proxy/src/lib.rs" \\
  && ok "api/proxy/src/lib.rs" \\
  || miss "missing critical file: api/proxy/src/lib.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/sonos/tract"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.