ML Odyssey

A Mojo-based platform for reproducing classic AI/ML research papers with production-quality implementations. ML Odyssey provides a shared library of SIMD-optimized tensor operations, an autograd engine, and a full training infrastructure — all implemented in Mojo for maximum performance and type safety.

What This Is

ML Odyssey is a standalone Mojo-based ML framework for reproducing classic AI/ML research papers with production-quality implementations. It has two goals:

1. Reproduce landmark neural network papers with verified, high-performance Mojo implementations
2. Provide a reusable shared library of ML components that paper implementations build on

The project currently has ~198K lines of Mojo code, 7 fully-implemented neural network architectures, and 371+ tests across layerwise unit tests and end-to-end integration tests.

Note on project identity: The GitHub repo description says "Training framework written in Mojo." This repo is sometimes described elsewhere as an "experimental agent research sandbox" -- that description is incorrect. ML Odyssey is an ML training framework, not an agent platform. It has no integration with ai-maestro, NATS, or any distributed agent mesh. The "agent system" referenced in this repo refers to Claude Code automation for development workflow (code generation, PR creation, CI management), not a runtime agent mesh.

Part of HomericIntelligence

Odyssey is one of several repositories in the HomericIntelligence organization. Here is how the repos relate:

What Odyssey is NOT

To avoid confusion with other ecosystem repos:

• Not a distributed agent mesh. AchaeanFleet and Myrmidons handle agent orchestration. Odyssey has zero integration with ai-maestro, NATS, or any agent registration/task queue system.
• Not an agent research sandbox. It is a straightforward ML training framework. The only "agents" here are Claude Code development automation (see .claude/agents/), which manage code generation and CI -- they do not run as distributed services.
• No REST API. There is no REST client, no agent registration endpoint, and no promotion path to AchaeanFleet. Implementations live entirely in this repo as Mojo libraries and executables.

Implemented Architectures

Each architecture has layerwise unit tests (runs on every PR) and end-to-end integration tests (runs weekly with real datasets).

Shared Library

The src/odyssey/ directory contains the ML components used by all paper implementations:

src/odyssey/core/ - Tensor Operations and Layers

• SIMD-optimized tensor type (AnyTensor) with compile-time dtype dispatch
• Convolution, linear, pooling, activation, normalization layers
• Matrix operations including Strassen multiplication
• Broadcasting, reduction, elementwise ops
• Dropout, batch normalization, attention

src/odyssey/autograd/ - Automatic Differentiation

• Tape-based reverse-mode autograd engine
• Variable type with gradient tracking
• Backward ops for all core operations
• Gradient utilities and type definitions

src/odyssey/training/ - Training Infrastructure

• Trainer with configurable training loops
• Optimizers: SGD, Adam, AdamW, RMSprop, LARS
• Learning rate schedulers
• Gradient clipping
• Mixed precision training
• Model checkpointing and callbacks
• Evaluation and metrics

Getting Started

Prerequisites

• uv for environment management
• Git

Installation

# Clone the repository
git clone https://github.com/HomericIntelligence/Odyssey.git
cd odyssey

# Install all dependencies (Mojo, Python tools, etc.)
uv sync --locked

Run Tests

# Run all Mojo tests
just test-mojo

# Run layerwise tests for a specific model
uv run mojo test tests/models/test_lenet5_layers.mojo

# Run all tests for a model
uv run mojo test tests/models/test_lenet5_layers.mojo tests/models/test_lenet5_e2e.mojo

Build the Shared Library

# Build project in debug mode
just build

# Build as distributable package
just package

Quick Reference

# Show all available commands
just --list

# Format all code
just format

# Run pre-commit hooks on all files
just pre-commit-all

# Full validation (build + test)
just validate

Documentation

• Installation Guide
• External Consumer Install Guide
• Roadmap
• Quickstart
• Your First Model
• Repository Structure
• Shared Library README
• Contributing Guide
• Architecture Decision Records
• Privacy & Data-Handling Policy

Project Structure

Odyssey/
├── src/odyssey/                  # Reusable ML library
│   ├── core/                # Tensor ops, layers, SIMD kernels
│   ├── autograd/            # Tape-based reverse-mode autograd
│   ├── training/            # Trainers, optimizers, schedulers
│   ├── data/                # Dataset loaders
│   └── testing/             # Shared test utilities
├── tests/
│   ├── models/              # Per-architecture test suites
│   └── src/odyssey/              # Shared library tests
├── docs/
│   ├── adr/                 # Architecture Decision Records
│   ├── getting-started/     # Setup and quickstart guides
│   └── dev/                 # Developer documentation
├── benchmarks/              # Performance benchmarks
├── scripts/                 # Python automation scripts
└── justfile                 # Build system recipes

Testing Strategy

Tests are organized in two tiers:

• Tier 1 (Layerwise Unit Tests): Run on every PR. Fast, deterministic tests using FP-representable values. Each layer's forward and backward pass is validated independently, including gradient checking against numerical finite differences.

• Tier 2 (End-to-End Tests): Run weekly. Full model training on EMNIST and CIFAR-10, validating convergence over 5 epochs.

See ADR-004 for the complete testing strategy rationale.

Running an individual optimizer or layer test

Each optimizer and recurrent/normalization layer ships a self-contained unit test (shape validation + numerical parity against an independent reference + the primitive's defining property). Run any one of them with a single command:

bash scripts/run_primitive_test.sh <name>     # run one primitive's test
bash scripts/run_primitive_test.sh all        # run every primitive test
bash scripts/run_primitive_test.sh --list     # list known primitives + paths

A primitive whose test file is not on the current branch is reported as SKIP (not a failure), so the runner works incrementally as each primitive lands. The invocation mirrors CI's include paths (mojo -I src -I . <test>; run --list for the authoritative primitive set, which the table documents).

Coverage Status

Full code coverage metrics are blocked by Mojo coverage tooling availability.

Current Workarounds

• All test_*.mojo files verified in CI via test discovery validation (scripts/validate_test_coverage.py)
• Source-to-test mapping: every src/odyssey/**/*.mojo is checked for a corresponding test_*.mojo file (scripts/check_source_coverage.py, warn-only as of initial rollout). Run locally: python scripts/check_source_coverage.py
• Test and source file counts (regenerate via the commands shown): find tests -name 'test_*.mojo' | wc -l and find src/odyssey -name '*.mojo' ! -name '__init__.mojo' | wc -l
• Manual code review via PR checklist for test coverage verification
• 70%+ threshold enforced for Python automation scripts via pytest-cov
• ADR-008 review cadence enforced quarterly via scripts/check_adr_review_dates.py in scheduled CI (see .github/workflows/mojo-version-check.yml)

Note on Mojo coverage: Mojo 1.0 still has no coverage instrumentation (mojo test --coverage does not exist). The targets in coverage.toml are aspirational, not gated in CI. This is a known gap; enforcement will be added once Mojo coverage tooling matures.

Note on gradient coverage: The gradient-coverage metric reported in CI is a proxy — it counts test files against backward-pass functions. It is not line-of-code coverage and cannot detect which branches within a backward pass are actually exercised.

When Mojo Coverage Available

mojo test --coverage tests/
mojo coverage report --format=lcov > coverage.lcov

See ADR-008 for complete explanation.

Benchmarks

Performance benchmarks live in benchmarks/. They are run as informational snapshots and are not a CI pass/fail gate — a slower result does not block a PR from merging. Use benchmark output to guide optimization work, not as a correctness signal.

License

BSD 3-Clause License. See LICENSE for details.