toc — Tool Output Compressor

Semantische Kompression für LLM-Agent-Terminalausgaben.
Rust CLI, 60–95% Reduktion ohne Informationsverlust für Entscheidungen.

---

Why toc?

Ansatz	Token-Kosten	Qualität
Rohausgabe	∞	✅ 100%
Hard Truncation	Niedrig	❌ Verlust von Fehlern in der Mitte
toc	~5%	✅ Alle Diagnose-Infos erhalten

toc ist speziell für LLM-Agenten entwickelt:

• Fehler, Warnungen, Panics bleiben immer erhalten
• Wiederholungen werden gefaltet, nicht abgeschnitten
• Binäre Eingaben passieren unverändert
• no-gain-Erkennung: wenn Kompression nichts bringt, wird das Original durchgereicht

---

Pipeline

Input → [Command Detection] → [Edge Check] → [Domain Detection] → [Normalizer]
         git/docker/ls/cargo/       binary?        test/log/json/      path/ts/UUID/IP
         ps/npm/pip/du/df/                         diff/compiler/      → alias
         find/tokei/shell                          stack/table/unknown
           │
           ├─ Command match → Command Miniaturizer (10–200x)
           ├─ Domain match  → Domain Summarizer (100–500x)
           └─ Fallback      → Block-RLE → Generic Compressor (30x)

---

Quick Install

# CLI-Binary bauen
cargo build --release -p toc-cli

# Symlink (empfohlen)
ln -sf $(pwd)/target/release/toc /usr/local/bin/toc

# Python-Binding (optional)
pip install ./toc-py

---

Usage

# Pipe beliebige Ausgaben
cargo test 2>&1 | toc
git status | toc                  # auto-detektiert git → Miniaturizer
docker ps | toc                   # auto-detektiert docker → Miniaturizer
ls -la | toc                      # auto-detektiert ls → Miniaturizer

# Modi
toc --mode diagnostic             # sicherer Default: alle Fehler erhalten
toc --mode aggressive             # maximale Kompression
toc --mode ultra                  # für gut verstandene Ausgaben
toc --mode agentic                # maximale Entscheidungs-Erhaltung
toc --mode lossless               # Passthrough (nur Stats)

# Optionen
toc --stats                       # Kompressions-Statistiken auf stderr
toc --input build.log             # aus Datei lesen
toc --output compressed.txt       # in Datei schreiben
toc --full original.txt           # unkomprimiertes Original sichern
toc --max-lines 200               # max Ausgabezeilen (head/tail bei Überschreitung)

# Generic-Modus (ohne Domain-Erkennung)
toc --generic                     # erzwingt generischen Kompressor

---

Workflow-Integration

Im Decider-Plugin (tool-router-wrap) wird toc automatisch für jeden Terminal-Call verwendet:

Agent ruft: terminal("cargo test --lib")
  ↓
tool-router-wrap -C 5000 cargo nextest --lib
  ├─ [Tool Router]     cargo test → cargo nextest
  ├─ [Process Manager] background + notify_on_complete
  └─ [toc]             3000 Zeilen → ~80 Zeilen (60–95% Reduktion)

---

Modes

Mode	Beschreibung	Typische Reduktion
diagnostic	Alle Fehler/Warnungen/Exceptions erhalten; Boilerplate falten	60–80%
aggressive	Höhere Kompression; mehr Zeilen falten	70–90%
ultra	Maximale Reduktion für gut verstandene Ausgaben	85–95%
agentic	Entscheidungs-Erhaltung garantiert: alle error/fail/panic-Zeilen bleiben verbatim; Nicht-Fehler werden mit Counts gefaltet; Qualitäts-Score + Stats-Logging	70–90%
generic	Domain-Erkennung deaktiviert; head/tail + Frequenz + Anomalien	30–60%
lossless	Nur Statistiken; Originalausgabe unverändert	0%

---

Command Miniaturizers (auto-detektiert)

Spezifische Kompressoren für bekannte CLI-Outputs erkennen die Struktur und extrahieren nur die relevanten Informationen:

Command	Roh → Komprimiert	Ratio
git status	344B → 144B	2.4×
docker ps	597B → 162B	3.7×
npm install	237B → 22B	10.8×
ps aux	792B → 143B	5.5×
Stack Trace	359B → 89B	4.0×
Log (50K Zeilen)	6.2 MB → 1.1 KB	5.489×

Unterstützt (38 Kommandos):

Kategorie	Kommandos
Git	status, diff, log, branch, stash, tag, remote
Docker	ps, images, containers, logs, system df
Pakete	npm install, pip install, cargo install
Prozesse	ps aux, top
Festplatte	du, df
Suche	find, loc (tokei/cloc)
System	systemctl status, free, lscpu, uname, uptime, hostnamectl
Netzwerk	ip addr, dig, ss, ping, curl
Kubernetes	kubectl get
Tools	journalctl, lsof
Tests	pytest / cargo test output
Fehler	command not found, permission denied, etc.

---

Domain Summarizers

Wenn kein Command-Spezialist matched, wird der Domain-Summarizer aktiviert:

Domain	Beispiel	Output
Test	cargo test	142 passed, 3 failed, 1 error
Log	App-Logs	Level-Counts + Top-10-Patterns
JSON	NDJSON	Schema-Extraktion + Samples
YAML	Config-Dumps	Strukturierte Zusammenfassung
Diff	git diff	3 files, 12 hunks, +147 -89
Compiler	rustc	5 errors, 12 warnings by code
Stack	Crash-Dump	47 frames (12 unique, 35 collapsed)
Table	kubectl get pods	Spalten + Zeilenzusammenfassung
Generic	Fallback	Head/Tail + Frequenz + Anomalien

---

Normalizer

Stabile Aliase für volatile Patterns — verbessert die Deduplizierung massiv:

Pattern	Beispiel	→ Alias
Pfade	/opt/decider/tool_router.py	$DECIDER/tool_router.py
Timestamps	2026-06-23T09:25:06Z	t0, t0+64s
UUIDs	550e8400-…	$UUID1
IP:Port	10.0.0.1:8080	$IP1:$PORT1
Hashes	a1b2c3d4…	$HASH1

Implementierung: Manuelle Byte-Scanner (kein Regex) — Aho-Corasick + SIMD-Heuristiken für UUID/Port/Hash-Erkennung → 0 Regex im Hot Path.

---

Block-RLE

Erkennt sich wiederholende Multi-Line-Blöcke (2–5 Zeilen) und kollabiert sie:

[ERROR] connection refused        [×20]
[WARN] retrying (attempt 1)       [ERROR] connection refused
[ERROR] connection refused   →    [WARN] retrying (attempt 1)
[WARN] retrying (attempt 2)       ...
[ERROR] connection refused        [WARN] retrying (attempt 20)

Pattern	Vorher	Nachher
[ERROR, WARN] ×20	40 Zeilen	3 Zeilen (13×)
[ERR, WARN, INFO] ×15	45 Zeilen	4 Zeilen (11×)

---

Template Mining (Drain-lite)

Bucket-basierter Algorithmus zum Mining von Templates aus normalisierten Zeilen.
Erkennt wiederkehrende Muster mit variablen Anteilen (IDs, Zahlen, Timestamps):

Template: "error[$CODE] $FILE:$LINE: $MSG"
  count: 47
  samples: [E0432, src/main.rs:12], [E0308, src/lib.rs:45], ...

---

Agentic Mode — Qualitätssicherung

Der --mode agentic garantiert Entscheidungs-Erhaltung:

1. Alle Decision Lines (error, fail, panic, fatal, exception, timeout, denied, assertion, ...) bleiben verbatim erhalten
2. Nicht-Entscheidungszeilen werden mit Wiederholungs-Counts gefaltet
3. Quality Score (0.0–1.0) misst, ob alle Entscheidungszeilen überlebt haben
4. Globales Stats-Logging nach ~/.toc/stats.jsonl

Qualitätsscore misst pro Keyword-Gruppe: (preserved / total) – Ziel: 1.0

---

Edge Cases

Situation	Verhalten
Leere Eingabe	Keine Kompression, kein Output
Binäre Eingabe (non-UTF-8)	Passthrough mit [BINARY INPUT]-Marker
no-gain	Original + [COMPRESSED no-gain]-Header
Idempotenz	Zweite Kompression ist stabil (keine Verschlechterung)
Max-Lines	Head/Tail bei Überschreitung (Konfiguration über --max-lines)

---

Performance

Benchmark (diagnostic mode, large_log_50K = 6.1 MB)

Commit	Optimierung	Zeit	Speedup	MB/s
bfe69ee	Original (OnceLock Regex)	319 ms	1×	18.7
c6145a6	+ Aho-Corasick + SIMD Scanner	187 ms	1.7×	31.9
9f70013	+ Manual Timestamp Scanner	164 ms	1.9×	36.5
HEAD	+ SWAR + Rayon + Domain-skip Norm.	85 ms	3.8×	72

Vergleich vs. RTK

Fixture	toc	rtk	toc (ms)	rtk (ms)
large_log_50k.txt (6.2 MB)	1.1 KB (5.489×)	106 B† (59.085×)	119	166
git_status.txt (344 B)	144 B (2.4×)	343 B (Passthrough)	2	87
docker_ps.txt (597 B)	162 B (3.7×)	589 B (Passthrough)	2	41
ps_aux.txt (792 B)	143 B (5.5×)	792 B (Passthrough)	2	31
npm_install.txt (237 B)	22 B (10.8×)	237 B (Passthrough)	2	17
stack_trace.txt (359 B)	89 B (4.0×)	359 B (Passthrough)	3	9

† RTK log mode = nur Statistiken, alle Inhalte verworfen.

toc ist 3–5× schneller als RTK und erhält tatsächliche Inhalte (RTK verwirft in log mode alle Zeilen).
RTK gewinnt bei Binary-Größe (Zero-Deps) und Distribution (brew/curl).
toc gewinnt bei Geschwindigkeit, Informationsdichte und Domain-Abdeckung.

---

Architektur

toc-cli/                  # CLI-Binary (clap + main)
└── src/main.rs           # Argument-Parsing, I/O, max-lines

toc-core/                 # Kern-Bibliothek
├── src/
│   ├── lib.rs            # compress()-Pipeline + agentic mode
│   ├── cli.rs            # CompressMode (6 Modi)
│   ├── domain.rs         # Domain-Erkennung (9 Typen, heuristisches Scoring)
│   ├── normalizer.rs     # Pfad/TS/UUID/IP → Alias (Aho-Corasick, SIMD)
│   ├── rle.rs            # Block-Level Run-Length Encoding
│   ├── generic.rs        # Generischer Fallback: Head/Tail + Frequenz + Anomalien
│   ├── miner.rs          # Template Mining (Drain-lite, 1024 Buckets)
│   ├── quality.rs        # Quality Scoring für agentic mode
│   ├── stats.rs          # Globales Stats-Logging (~/.toc/stats.jsonl)
│   ├── edge.rs           # Binary-Erkennung, Edge Cases
│   ├── commands/         # 18 Command-Miniaturizer (git, docker, ls, …)
│   └── summarizers/      # 6 Domain-Summarizer (test, log, json, diff, compiler, stack)
├── benches/              # Criterion-Benchmarks (compress + wrapper_ratio)
└── tests/                # Integrationstests + Property-Based Tests (proptest)

toc-py/                   # Python-Bindings (PyO3)
├── pytoc/__init__.py     # Python-API (compress, compress_agentic_safe)
└── src/lib.rs            # Rust → Python FFI (PyO3)

fuzz/                     # OSS-Fuzz Integration
├── fuzz_targets/
│   ├── cli.rs            # Fuzzing der CLI
│   └── compress.rs       # Fuzzing der compress()-Pipeline
└── corpus/               # Seed-Corpus (komprimierte + unkomprimierte Fixtures)

---

Test Suite

# Alle Tests
cargo test                    # ~200 Tests (Unit + Integration + Property)

# Spezifisch
cargo test -p toc-core        # Nur Kern-Bibliothek
cargo test -p toc-cli         # Nur CLI-Integration

# Property-Based (proptest)
cargo test -p toc-cli --test property
cargo test -p toc-core --test property

# Benchmarks
cargo bench -p toc-core       # Criterion-Benchmarks

# Fuzzing (via cargo-fuzz)
cargo fuzz run compress       # Pipeline-Fuzzing
cargo fuzz run cli            # CLI-Fuzzing

---

Python-API

from pytoc import compress, compress_agentic_safe, get_stats

# Einfache Kompression
result = compress("""error[E0308]: mismatched types
  --> src/main.rs:12:5
   |""", mode="diagnostic")

# Agentic Mode — maximale Entscheidungs-Erhaltung
safe = compress_agentic_safe(raw_output)

# Statistiken
stats = get_stats(raw_output, mode="diagnostic")

---

Safety-Garantien

1. No-Gain Detection — wenn Kompression nicht reduziert, geht Original durch
2. Errors immer erhalten — Domain- und Generic-Summarizer zeigen alle Fehlerzeilen
3. Idempotent — erneute Kompression ist stabil
4. Binary Passthrough — non-UTF-8 bleibt unverändert
5. Block-RLE nur für 2+ unique Lines — interferiert nicht mit Line-Level-Dedup
6. Keine Datenverluste — Volloutput wird optional (--full) gesichert

---

Hyperscale Roadmap

Phasenweise Optimierung auf Billionen-Request-Niveau (Details in PERFORMANCE.md):

Phase	Optimierung	Speedup	Durchsatz (1 Core)	Durchsatz (128 Cores)
0	Aktuell (SIMD + SWAR + Rayon)	1×	~66K Req/s	~8M Req/s
1	Zero-Copy + Library API	3–5×	~330K Req/s	~40M Req/s
2	Aho-Corasick + SIMD Scans	5–10×	~3M Req/s	~400M Req/s
3	Sharded LRU Cache (95% Hit)	20×	~60M Req/s	~8B Req/s
4	SIMD Domain Detection	2×	~120M Req/s	~16B Req/s
5	Schema-only JSON Scanner	2×	~240M Req/s	~32B Req/s
6	Parallel Pipeline (8–16 Cores)	8–16×	~240M Req/s	~32B Req/s
7	Cache-First (>99% Hit)	100–1000×	~6B Req/s	~1T Req/s

---

Skripte

python3 scripts/bench-compare.py              # Benchmark aller Fixtures
python3 scripts/bench-compare.py --save baseline.json
python3 scripts/bench-compare.py --compare baseline.json
python3 scripts/generate_fixtures.py          # Test-Fixtures generieren

---

Integration

toc ist Teil des Hermes Agent Decider Ecosystems:

• Hermes Agent → ruft Terminal-Kommandos
• Decider Plugin → Tool Router + Process Manager
• tool-router-wrap → wrappt jeden Call: toc --mode diagnostic komprimiert Ausgabe
• tool-router-wrap → wendet --max-lines als Safety Net an
• toc → semantische Kompression (dieses Projekt)

---

License

MIT — Teil des Hermes Agent Ecosystems by Nous Research.