Quickstart · How it works · The constellation · House rules · Docs
📬 What is this?
Picture a law firm's mailroom. Letters arrive. Someone sorts them,
someone reads them and pulls out the facts, a supervisor checks the
work, and every envelope ends up filed with a receipt. Nothing gets
lost and nobody gets to guess.
The Digital Mailroom does the same job with AI agents. It is the
integration hub for the LLM-Mailroom constellation: one checkout that
wires together a multi-agent legal-document pipeline, a deterministic scoring
dojo, a pixel-art visualizer, an offline and GPU testing sandbox, and the
corpus EDA that feeds them. It runs on one uv workspace, one lockfile and
one virtualenv, and no member imports code from outside the workspace.
🤔 When to reach for it
| ✅ Reach for it when… | ↪️ Look elsewhere when… |
|---|
| You want the whole constellation in one checkout: one uv workspace, one lockfile, one virtualenv | You want to change package code. Author it in the standalone Exios66/* source, then import it here |
| You are running cross-package suites, regenerating vendor snapshots or cutting a hub release | You want a single package on its own. Install it from its standalone repository |
| You coordinate work through the board and the live dispatch board | You want the pruned alumni (llm-entity-extraction, llm-mailroom-graph). They live on only as standalone repos |
🏭 A day in the life of a document
| Stage | What happens |
|---|
| 📥 | Ingest | One fused triage, clean and prepare pass claims the raw file, normalizes it and writes its manifest |
| 🏷️ | Classify | The SorterAgent assigns one of five live classes (contract · merger_agreement · corporate_record · correspondence · insurance_claim) with a confidence score. High confidence goes straight to extraction, medium confidence retries, and low or unknown confidence goes to review |
| 🔍 | Extract | A class specialist produces structured Pydantic output, gated on schema, confidence, factuality and completeness |
| ⚖️ | Judge → Arbiter → Boss | The Judge checks ambiguous completeness and the Arbiter decides whether to stand, re-extract or send the document to a human. Matter conflicts go to the Boss, which never resolves them silently by recency |
| 🧑⚖️ | Human review | The governance boundary: approve, correct, reconcile or reject. A correction resumes the run from the corrected state |
| 🗂️ | Compile → Catalog → Archive | Deterministic matter-record assembly (no LLM call), persistence, and a hash-chained audit archive |
These six phases cover the 13 nodes of the llm-mailroom graph. The full map is docs/assets/mailroom-pipeline.svg and the terminology is in the v7 taxonomy spec; both are the root-level sources of truth.
🌌 The constellation
Five core packages live in packages/ as git subtrees imported from their
authoritative standalone Exios66/* repositories. Four are built members;
the fifth, the corpus EDA, is a virtual member.
The hub itself is LLM-Mailroom-Services/Digital-Mailroom. It hosts the live 📋 Dispatch Board.
[!NOTE]
mailroom-corpus-eda is the only virtual member (package = false). It has no build system and is not installed; its EDA code and deliverables live alongside the four built members.
Enron-Evaluation-Environment ─┐ (external corpus feeds)
claims-data-eda ──────────────┴─> mailroom-corpus-eda
EDA + centralized HF upload helpers
│ publishes
▼
HF Hub: mailroom-dataset (pinned tag)
┌───────────────────┴───────────────────┐
│ pinned pull │ pinned pull
▼ ▼
┌─────────────────────────────┐ executes ┌─────────────────────────────┐
│ local-mailroom-sandbox │ ───────> │ llm-mailroom │
│ offline/local + Modal/vLLM │ │ 13-node LangGraph pipeline │
│ GPU testing harness │ │ (FastAPI producer) │
└──────────────┬──────────────┘ └──────────────┬──────────────┘
│ scores with │ scores with
└───────────────────┐ ┌─────────────────┘
▼ ▼
┌───────────────────────────────┐
│ llm-dojo-scoring │
│ ALL scoring engine + metrics │
└───────────────────────────────┘
llm-mailroom ───────────┐
local-mailroom-sandbox ─┴─ traces / API ─> Langfuse ─> The-Mailroom
shared visualizer, both
Standalone sources ─── sync_packages.py pull ──> Digital-Mailroom packages/
Imported packages ──── sync_vendor.py ─────────> sandbox vendor snapshots
Digital-Mailroom owns hub wiring, governance, board, integration tooling.
Pruned in DMR-079. llm-entity-extraction and llm-mailroom-graph left
the monorepo. They live on only as standalone Exios66/* repos and are no
longer synced. agent-mailroom is preserved on the branch
feature/agent-mailroom. Hub v0.8.0 is the last release containing them
and serves as the rollback point.
External corpus feeds. Enron and claims remain usable standalone feeds,
and their datasets, taxonomy and published sites keep their identities.
DMR-093 (PR #167, merged 2026-10-23) removed their local copies from the
active workspace. Both preservation branches point to
59c879d9fb4480084e53137e2e9fb25650933944, the last commit that carried the
complete package trees.
You can browse Enron's preserved package or
claims' preserved package on GitHub.
For the original complete workspace, including the old hub chart generator,
use a separate checkout of the preservation branch. To selectively restore a
package, reconcile membership, sync entries, dependencies and tests
explicitly, and keep the current root metadata. The earlier
feature/agent-mailroom preservation branch remains unchanged.
🚀 Quickstart
git clone https://github.com/LLM-Mailroom-Services/Digital-Mailroom.git
cd Digital-Mailroom
uv sync # install workspace + dev group into .venv (editable)
Run the suites one package per pytest invocation. Several packages ship a
top-level tests package, and they collide when batched.
uv run pytest packages/llm-dojo-scoring/tests
uv run pytest packages/llm-mailroom/src/tests
uv run pytest packages/The-Mailroom/tests
uv run pytest packages/local-mailroom-sandbox/tests
uv run pytest packages/mailroom-corpus-eda/tests
python3 -m unittest discover scripts/tests # hub governance tooling (hermetic)
(cd board-site && node tests/api.test.js) # served-board API proxy
[!IMPORTANT]
CI does not run the package suites, so your local run is the gate.
docs/TESTING.md has the tiers, timings and the
change-type → required-suite matrix.
During development, cross-package dependencies resolve to workspace
sources through [tool.uv.sources] in each member's pyproject. The
published git pins stay in the dependency lines for release builds.
📜 House rules
The mailroom runs on a few non-negotiables:
- Standalone repos own the code. Author, test and commit package changes in their
Exios66/* repo, then import them here. Never implement a package change in the hub, and never push hub copies back to a standalone repo.
- Vendor snapshots are generated, never hand-edited.
packages/local-mailroom-sandbox/vendor/ comes from sync_vendor.py and nothing else.
- The board is the source of truth. Read
governance/TASKS.md first, claim a card before you edit, and don't call a card done without evidence.
- Every commit tells a story. Lead with the
DMR-0NN: prefix and write a body that names each changed file and why it changed. See the template and examples.
- Tests must be able to fail. Ship each bug fix with its regression test, hand-compute expected values, and use honest doubles. Details are in
AGENTS.md.
🔄 Sync & release
python scripts/sync_packages.py status # live drift report
python scripts/sync_packages.py pull --package <name> --squash # import committed standalone source
python scripts/sync_vendor.py # regenerate vendor snapshots from imported sources
python scripts/sync_vendor.py --check # verify the snapshots match the workspace
python scripts/sync_packages.py snapshot # cursor verification
Packages are released from their standalone repositories, and consuming
pins are bumped there at release time. The hub then imports the committed
sources, regenerates the vendor snapshots and runs the integration suites.
Hub releases version the integration workspace on their own track: cut with
release_chain.py cut X.Y.Z --apply, run uv lock, commit the changelog,
version and lockfile together, merge the PR, then tag the merged main tip.
The runbooks are
Sub-Package Sync and
Releases.
The board and the GitHub surface are kept machine-readable and consistent with each other. The live dispatch board is https://digital-mailroom-theta.vercel.app. It is issue-backed; see board-site/ and docs/wiki/Served-Board.md.
python scripts/board_state.py status # live board snapshot (--json for machines)
python scripts/board_state.py check # board invariants; exit 1 on structural errors
python scripts/github_labels.py audit # label taxonomy drift (CI gate)
python scripts/taxonomy_parity.py # doc-class taxonomy drift (CI gate, HUB-019 §65A)
python scripts/release_chain.py status # hub release chain: tags, changelog sections, hub version
python scripts/release_chain.py check # chain invariants; exit 1 on structural errors
python scripts/release_chain.py cut X.Y.Z # cut a hub release (dry run; --apply writes; tag after merge)
./docs/wiki/sync-wiki.sh # push docs/wiki/ source to the GitHub wiki (--check for drift)
The full governance contract lives in .github/ISSUE_TEMPLATE/, .github/PULL_REQUEST_TEMPLATE/, .github/labels.json, scripts/board_state.py and governance/TASKS.md.
Digital-Mailroom/
├── AGENTS.md # workspace rules & cross-package conventions
├── README.md # this file — the canonical entry point
├── CHANGELOG.md # hub release chain ([Unreleased] → vX.Y.Z)
├── pyproject.toml # uv workspace definition (hub version)
├── uv.lock # single lockfile for all packages
├── governance/ # task board (TASKS.md) & governance README
├── board-site/ # served Vercel dispatch board (api/, lib/, tests/)
├── docs/
│ ├── TESTING.md # test tiers, per-package commands, required suites
│ ├── COMMIT_MESSAGES.md # shared commit-message template
│ ├── DOCCLASS_CONTRACT.md · docclass-merged-plan.md · v7-taxonomy.md
│ ├── assets/ # pipeline diagram, banners, readme/ animations
│ ├── reports/audits/ # baseline, branch, import and release audits
│ └── wiki/ # GitHub-wiki source (sync-wiki.sh)
├── scripts/ # governance, sync and release tooling + scripts/tests
│ ├── board_state.py · github_labels.py · taxonomy_parity.py
│ ├── sync_packages.py · sync_vendor.py · packages_sync.json
│ ├── release_chain.py · release_notes.py · audit_references.py
│ └── deploy_gh_pages.py # corpus-EDA Pages deploy (no Actions)
├── data/ · reports/ # hub-level runtime data and report pointers
├── tools/feeder-resync/ # historical feeder-resync bundle (2026-09-27)
├── .github/ # workflows, labels, issue/PR/release templates
├── .opencode/ · .devin/ # specialist subagent personas and skills
└── packages/ # five core packages (four built + one virtual)
📚 Where to go next
❓ FAQ
Because the standalone repositories own package code. A hub-only fix would be overwritten by the next import. Author and test the fix in the Exios66/* source, merge it, then import it with sync_packages.py pull --package <name> --squash.
Several packages ship a top-level tests package, and they collide when pytest batches them.
Not necessarily. CI does not run the package suites, so your local run is the gate. Quote the exact pass/skip/fail counts in the card and the PR. Every PR also reads BLOCKED on a phantom required ci status until DMR-080 is resolved; that is not a test failure.
Not inside unrelated work. An unintended lock diff means the committed lock is stale: fix it as its own carded commit (uv lock, then uv lock --check), and use uv run --frozen for read-only runs.
Nowhere. packages/local-mailroom-sandbox/vendor/ is generated by python scripts/sync_vendor.py and verified with --check.
🙏 Built on
The hub stands on these tools:
| Project | What it does here |
|---|
| uv | The workspace, the single lockfile and workspace-source redirects |
| git subtree | Squash imports of the standalone sources |
| GitHub Issues · Vercel | The issue-backed live dispatch board |
| 🤗 Hub | The pinned mailroom-dataset corpus |
🤝 Contributing, security and license
llm-mailroom ·
llm-dojo-scoring ·
The-Mailroom ·
local-mailroom-sandbox ·
Mailroom-Corpus-EDA
The Digital Mailroom · maintained by LLM-Mailroom-Services (Exios66 · grantmooslin) · 2026
📮 No envelope left behind.
