<!-- Author: Simon-Pierre Boucher — simon-pierre.boucher@uqo.ca -->
# 🧠 Beyond Text: Cache Compression and Knowledge Transfer in Multi-Agent Systems

**UQO Working Paper No. 30** — *A Reproducible Study of Fidelity, Communication Cost, and Repeated Handoffs*

> **TL;DR** — Under which task, model, cache, network and reuse conditions does each communication representation (raw text,
> summaries, structured evidence, lossless codecs, learned prompt compression, native/quantized/evicted KV caches, learned cache
> mappings) preserve useful information at the lowest *measured* end-to-end cost? Real experiments on Apple Silicon (MLX) with
> Qwen2.5-3B / Llama-3.2-3B, genuine two-node cache transfer over a 1 GbE LAN, repeated-handoff chains with an evaluator-only
> fact ledger, fan-in with conflicting evidence, a same-family learned KV mapper, hosted-API receivers, and a development-fitted router.

## 📌 Status
See `STATUS.md` (phase gates), `DECISIONS.md` (dated decisions), `FINAL_REPORT.md` (completion status and limitations).

## 🗂 Repository layout
```
protocol/        hypotheses.md (registered), analysis_plan.md, frozen.json (protocol hash), run matrices
literature/      sources.csv (34 verified sources), audit_group{1,2,3}.md, method_notes.md
configs/         models, data, resources (budgets/timeouts), pilot/core experiment configs
src/wp30/        backends (MLX), cache adapters (sparse/quantized/serialize/selection), methods (A0–A8), runner, chains, fanin,
                 transport (two-node worker), hosted (API track), mapper (Track C), router (E8), analysis, CLI
tests/           cache correctness (12), leakage (3), scoring/data (5)
data/            manifests (splits, licences), generated/docs (agent-visible), generated/keys (evaluator-only), raw/longbench
runs/raw         per-attempt JSONL records (schema wp30-attempt-1), chains/ hop messages ; runs/logs ; runs/checkpoints (mapper, router)
results/         tables/ figures/ provenance.json claim_ledger.csv
paper/           LaTeX source + compiled PDF
reproduction/    requirements-lock.txt, minimal.yaml, report.json
```

## 🚀 Quick start (analysis-only reproduction, no inference)
```bash
uv venv --python 3.12 .venv && source .venv/bin/activate && uv pip install -r reproduction/requirements-lock.txt && uv pip install -e .
make reproduce-analysis        # rebuilds results/tables and results/figures from runs/raw
make paper                     # compiles paper/main.pdf
```

## 🔁 Inference reproduction (Apple Silicon, ~15 GB of checkpoints from Hugging Face `mlx-community`)
```bash
python -m wp30 doctor --output evidence/environment.json
python -m wp30 data prepare --config configs/data.yaml && python -m wp30 data validate --manifest data/manifests/splits.json
python -m wp30 models probe --config configs/models.yaml
python -m pytest -q                                   # cache correctness suite runs a real 1.5B model
python -m wp30 run --config configs/core.yaml --resume
python -m wp30 reproduce --profile reproduction/minimal.yaml
```
Two-node experiments need a second Mac with the same checkpoint revision: `python -m wp30 worker --port 9430 --model <repo>` on the
receiver node, then `python scripts/e6_network.py --host <ip> ...` on the sender node. Hosted-API experiments need `ANTHROPIC_API_KEY`
/ `OPENAI_API_KEY` and are capped by `configs/resources.yaml`.

## 📄 Citation
Boucher, S.-P. (2026). *Beyond Text: Cache Compression and Knowledge Transfer in Multi-Agent Systems*. UQO Working Paper No. 30.