Codeseys/composer-replication-framework

1# composer_replication2 3The Composer 2.5 Replication Framework, packaged for `pip install`.4 5This package re-exports the verified APIs that live in the6[`spikes/`](../spikes/) directory of the parent repository, so that downstream7code can `import composer_replication` instead of poking at `sys.path`.8 9## Package map10 11| module | source spike | purpose |12|---|---|---|13| `composer_replication.loss` | spike 006 | Free `compose_loss(model, batch, ...)` 3-channel loss composer + `LossComponents` dataclass |14| `composer_replication.batch` | spike 006 | `build_batch(tokenizer)` — real chat-template batch from any HF tokenizer |15| `composer_replication.opsd` | spike 005 | `generalized_jsd_loss` (verified port of `siyan-zhao/OPSD`) |16| `composer_replication.teacher_replay` | spike 001/005 | `replay_trace`, `extract_dpo_pairs`, `TraceState`, `TeacherSpec` (multi-teacher OpenRouter replay) |17| `composer_replication.hint_generator` | spike 005 | Hint-text construction at error sites for SDPO channel |18| `composer_replication.trainer` | spike 005 | `ComposerReplicationTrainer` (TRL `GRPOTrainer` subclass with the 3 channels) |19| `composer_replication.ingestion` | spike 007 | `ClaudeCodeIngester` (Claude Code session JSONL → `TraceState`) |20| `composer_replication.diloco` | spike 008 | `make_diloco_outer_loop` (wraps `torchft.local_sgd.DiLoCo`) |21 22## Why a package on top of spikes?23 24The spikes are research artifacts: each one has its own `README.md`, tests,25verdict, and a `sys.path` hack to find sibling modules. They live forever as26verification harnesses.27 28Most users want to `pip install -e . && python my_training_script.py`. This29package is the pip-installable face of the framework. The two surfaces stay30in sync because the package modules are 1:1 copies of the spike modules with31only the import paths changed (sibling-relative → package-absolute).32 33## Quickstart34 35See [`examples/qwen_05b_quickstart/`](../examples/qwen_05b_quickstart/) at36the repo root.37