Merlin — Specialized Agentic Coding Model
A 3B language model built from scratch exclusively for agentic coding — not a general assistant, not a fine-tuned GPT. Every training token, every design decision, every protocol token is optimized for one job: executing code tasks fast, locally, and at scale.
Runs on any MacBook. No API key. Your code never leaves your machine.
The Idea
LLM agents spend most of their tokens on execution, not reasoning — grep a file, run a test, rename a function. Today that all hits a frontier model at $1–10/M tokens.
Merlin is the brute-force execution layer beneath a smarter orchestrator. A frontier model (Claude, GPT-4) plans; Merlin executes — locally, in parallel, at zero marginal cost.
| Mode | Workers | Cost |
|---|---|---|
| Local | 1, on your MacBook | $0 — always |
| Hosted | 100–1000 via GPU batching | pay-per-task |
Design
| Choice | What | Why |
|---|---|---|
| Pre-trained from scratch | 100B tokens — code, bash, agentic traces, commits | No proprietary distillation; weights are commercially clean |
| Custom tokenizer | 32K BPE + 18 agent protocol special tokens | Tool-call protocol is first-class, not bolted on |
| 6K context window | Sized for one large Python file + agent overhead | Not a general-purpose model |
| RL post-training | GRPO on verifiable bash/filesystem rewards | Ground truth without a judge model |
| MLX int4 inference | ~1.5 GB weights, >500 tok/s on M3 | Fits any M-series Mac |
Agent Protocol
18 special tokens define the tool-call format — the model learns to emit and parse tool calls natively:
<|task|> Read src/main.py and return the function names.
<|think|> I need to read the file first.<|/think|>
<|tool_call|><|tool_name|>read_file<|tool_args|>{"path": "src/main.py"}<|/tool_call|>
<|tool_result|>def train(): ...\ndef evaluate(): ...<|/tool_result|>
<|answer|> train, evaluate
Architecture
GPT-style decoder-only. RMSNorm, SwiGLU, GQA (n_kv_head=8), no bias, weight tying, pre-norm.
| Config | Params | n_embd | n_head | n_layer | block_size |
|---|---|---|---|---|---|
| tiny | ~1.6M | 32 | 2 | 2 | 64 |
| medium | ~21M | 256 | 8 | 8 | 512 |
| base (330M) | ~330M | 1024 | 16 | 16 | 2048 |
| 3b | ~3.17B | 3072 | 24 | 20 | 4096 |
Corpus
~100B tokens across 7 sources. Two-phase curriculum: 80B general mix → 20B upweighted traces + instruction data.
| Source | Share |
|---|---|
| Stack v2 — Python | ~38% |
| Stack v2 — Bash / Markdown | ~8% |
| Agentic traces (synthetic) | ~15% |
| GitHub commits + issues | ~11% |
| Stack Overflow | ~10% |
| Math + instruction mix | ~12% |
| tldr pages | <1% |
v0 corpus (1.19B tokens): tsuberim/merlin-corpus-v0 Tokenizer: tsuberim/merlin-tokenizer-v0
Status
| Milestone | Status |
|---|---|
| Agentic protocol + eval harness (49 tasks, 47% on 3B baseline) | ✅ Done |
| Custom BPE tokenizer (32K vocab, 20 special tokens) | ✅ Done |
| Data pipeline (download → tokenize → pack) | ✅ Done |
| v0 corpus on HuggingFace (1.19B tokens) | ✅ Done |
| E2E training loop, 330M model on H100 | ✅ Done |
| SFT infrastructure | ✅ Done |
| Repo scanning pipeline (clone + pytest → passing repos) | 🔄 In progress |
| Agentic trace generation (target: 200K traces) | ⏸ Planned |
| Full 100B token corpus | ⏸ Planned |
| 3B pre-training run | ⏸ Planned |
| RL post-training (GRPO on verifiable rewards) | ⏸ Planned |
| MLX int4 3B model release | ⏸ Planned |
Stack
| Role | Tool |
|---|---|
| Training | PyTorch + CUDA (NVIDIA H100) |
| Inference | MLX (Apple Silicon / Metal) |
| Cloud compute | Modal |
| Tokenizer | HuggingFace tokenizers (BPE, Rust) |
| Trace generation | vLLM + Qwen2.5-Coder-32B |
| Observability | W&B |
| Datasets + models | HuggingFace Hub |
Setup
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for merlin-llm 0.1.12
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| merlin_llm-0.1.12.tar.gz | 14.4 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| merlin_llm-0.1.12-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 28.1 kB
Release files / merlin_llm-0.1.12.tar.gz
| Download URL | merlin_llm-0.1.12.tar.gz |
|---|---|
| Size | 14.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
978860e62e7330c3720409ae2a725ba8990993ff8ffde13da48224df550e7e2f
|
|
BLAKE2b-256 checksum How to use checksums |
0ec541cbebe7d1c1393a3e588ea432d00979240df7b6bec1737d48e448eba89c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Release files / merlin_llm-0.1.12-py3-none-any.whl
| Download URL | merlin_llm-0.1.12-py3-none-any.whl |
|---|---|
| Size | 13.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2514dabb6a24acd10399609327617c53a9ad441dd78dbc44b0eab10f22358e1d
|
|
BLAKE2b-256 checksum How to use checksums |
9cc01e8520b894ef67b15fbfe1a653ffeacfde90e3f1a606c752cc177f640577
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Security for merlin-llm 0.1.12
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
