Skip to content

AGENTS.md

Latest commit

 

History

History
33 lines (29 loc) · 2.36 KB

AGENTS.md

File metadata and controls

33 lines (29 loc) · 2.36 KB
Raw

u-moec-tiny: Agent Guide

Quick start

uv sync                          # install deps (uv, not pip)
ruff check .                     # lint only (no formatter)
python -m pytest                 # all tests
pytest tests/test_roundtrip.py -v::test_name  # single test
python -m bin.train --config configs/tier1_micro.yaml --data-root data --checkpoint-dir checkpoints/tier1_micro --device cuda
python -m bin.compress in.bin out.umc --config configs/tier1_micro.yaml --checkpoint ckpt.pt --profile turbo
python -m bin.decompress out.umc out.bin --config configs/tier1_micro.yaml --checkpoint ckpt.pt

Key facts

  • Single package, not a monorepo. umoec/ is the library; bin/ has CLI entrypoints. All entrypoints registered in [project.scripts] of pyproject.toml.
  • Build system: hatchling backend, uv for dependency management. uv.lock is canonical.
  • No CI, no pre-commit, no Makefile in the repo.
  • Tests: all live in tests/test_roundtrip.py. They are fast unit/smoke tests (rANS roundtrip, stats shapes, backbone forward, MoE bias). No external fixtures needed.
  • Config-driven tiers: model architecture is defined in YAML under configs/ (tier1_micro.yaml, tier2_small.yaml, etc.). Code is reused across tiers; only configs change.
  • Model construction is shared: bin.train.build_model() is imported by bin.compress and bin.decompress. Always build models through this factory.
  • No aux loss for MoE balancing: bias update is called manually after each training step (model.backbone.shared_moe.update_bias()).
  • Training metrics go to SQLite (training.db by default). The GUI (gui/app.py) reads from this DB.
  • Data pipeline: scripts/download_corpus.sh fetches enwik8 + HuggingFace datasets (FineWeb, The Stack). Sequence packing concatenates without padding.
  • torch.compile is OFF for POC (config: training.hardware.compile: false).

Ruff config (from pyproject.toml)

  • line-length = 100, target-version = "py310"
  • select = ["E", "F", "W", "I", "B", "UP"], ignore = ["E501"]
  • No mypy config (listed in dev deps but unconfigured)

Testing quirks

  • test_byte_level_roundtrip_with_dummy_model uses a fake UniformModel — it tests I/O plumbing, not real compression. Real roundtrip is verified via bin.compress + bin.decompress CLI.
  • The critical invariant: compress(x) → decompress = x for any x.