admin/Context-Lifecycle-Management-f-r-Agents
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: embed kontext-system diagram in README and architecture

Browse Source 
Add assets/kontext-system.jpg and reference it in the README intro and
architecture overview so the layered system model is visible in-repo.
This commit is contained in:
grok-bot committed 2026-08-04 22:16:18 +02:00
1 parent 7c788bdbf1
commit 6e56d847f7
4 files changed
+74 -38
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

HANDOFF.md
+64 -38
View File
@@ -2,14 +2,15 @@
| Feld | Wert |
|------|------|
| **Stand** | 2026-08-04 (P4 complete) |
| **Stand** | 2026-08-04 (docs: Kontext-System-Diagramm in README + architecture) |
| **Version** | `0.4.0a1` (Phase 4 complete) |
| **Branch** | `main` (lokal ahead of origin nur durch **uncommitted** Work) |
| **HEAD (committed)** | `faf00df` — entspricht `origin/main`; P2+P3+P4 liegen **nur working tree** |
| **Branch** | `main` |
| **HEAD** | siehe `git log -1` nach docs-Commit (Kontext-System-Bild) |
| **Remote** | `http://10.27.27.139:3000/admin/Context-Lifecycle-Management-f-r-Agents.git` |
| **Tracking** | `main` → `origin/main` |
| **P1 quality gate** | `c48b837` — `chore: phase1 mvp quality gate` |
| **Status** | `ready_for_commit` — P4 lokal fertig + quality-gated; **Commit/Push User-Entscheidung** |
| **P2–P4 release** | `7c788bd` — phases 2–4 squash commit on `main` |
| **Status** | `complete` — P0–P4 on origin; Doku-Asset `assets/kontext-system.jpg` eingebunden |
---
@@ -17,32 +18,32 @@
Automatisiertes Context-Lifecycle-Management für LLM-Agents: Outer Control Loop entscheidet **CONTINUE / COMPACT / HANDOFF**, hält Context kontrolliert (inkl. **Verified Compaction**), schreibt datei-basiertes (oder Mem0/Hybrid) Memory und erzeugt auditierbare Handoff-Manifeste — framework-agnostisch, SimulatedAgent + OpenAI-compatible PoC.
**Phasenstand:** P0–P4 implementiert. Roadmap-Meilensteine des Plans sind abgedeckt; weitere Iteration = Production polish / Research-Policies nach Bedarf.
**Phasenstand:** P0–P4 implementiert und auf `origin/main`. Roadmap-Meilensteine des Plans sind abgedeckt; weitere Iteration = Production polish / Research-Policies / Live-Smokes nach Bedarf.
---
## Next safe action
### 1. Optional: P2+P3+P4 committen + pushen (User muss freigeben)
Working tree enthält **alle** P2-, P3- und P4-Änderungen uncommitted (modified + untracked). Vor Commit Quality Gate erneut laufen lassen:
### 1. Session starten / Qualität kurz bestätigen
```bash
cd /Volumes/SSD2TB/books/clm-agents
source .venv/bin/activate
git pull origin main
source .venv/bin/activate # oder: uv venv && uv pip install -e ".[dev]"
pytest -q && ruff check src tests && mypy src/clm
# dann nach User-OK: git add … && git commit && git push origin main
```
**Hinweis:** Nicht force-pushen. `uv.lock` ist untracked — optional mitcommitten.
Empfehlung Commit-Split: (1) P2, (2) P3, (3) P4 — oder ein Squash „phase 2–4“.
Erwartung: **126 passed**, ruff/mypy clean, working tree clean.
### 2. Danach / alternativ: Ops-Nutzung / Erweiterungen
### 2. Ops-Nutzung / Erweiterungen (empfohlen)
- Live Mem0 / Live OpenAI gegen echte Keys smoke-testen
- Eigene `DecisionPolicy`-Plugins (ARC/ACM-Heuristiken) hinter `DecisionEngine`
- Cost `price_table` pro Provider in Deploy-Config pflegen
- Optional: `clm experiment ab-memory` in CI als Regression
- Optional: Auto-Apply von Calibrate in `clm run` (aktuell manuell)
**Nicht:** P0–P4 erneut implementieren.
---
@@ -52,36 +53,39 @@ Empfehlung Commit-Split: (1) P2, (2) P3, (3) P4 — oder ein Squash „phase 2
|----------|------|
| Design-Spec | `docs/superpowers/specs/2026-08-04-clm-design.md` |
| Umsetzungsplan | `docs/superpowers/plans/2026-08-04-clm-mvp.md` |
| Architektur | `docs/architecture.md` |
| Architektur | `docs/architecture.md` (inkl. Kontext-System-Diagramm) |
| System-Diagramm | `assets/kontext-system.jpg` (README + architecture) |
| Metriken | `docs/metrics.md` |
| Manifest | `docs/manifest-schema.md`, `schemas/handoff_manifest.schema.json` |
| README / Demos | `README.md` |
| Package | `src/clm/` |
| Tests | `tests/unit/`, `tests/integration/` |
| Lockfile | `uv.lock` (committed) |
---
## Done (Phase 0–4)
### P0–P1 (committed / quality gate)
### P0–P1 (committed)
- Package-Scaffold, Docs, Manifest-Schema, Config, Metrics, File Memory, Decision Engine, Compaction (structured), Handoff, SimulatedAgent, Outer Loop, CLI (`init/status/decide/compact/handoff/run`)
- Quality gate: `c48b837`
### P2 (implementiert, **uncommitted**)
### P2 (committed in `7c788bd`)
- Verified Compaction (`compaction/verify.py` + Pipeline)
- Memory backends: factory, Mem0 store, Hybrid store
- OpenAI-compatible Agent PoC
- Resume-Run, Loop-Polish, Integrationstests (verify-fail → handoff, resume)
### P3 (implementiert, **uncommitted**)
### P3 (committed in `7c788bd`)
- Adaptive Thresholds (`clm calibrate`)
- Observability Export (`clm export metrics`)
- Phase-Orchestration Hooks (`clm signal --phase-done`)
- HITL Policy (`require_confirm_on` / `--yes`)
### P4 Deliverables (implementiert, **uncommitted**, quality-gated)
### P4 Deliverables (committed in `7c788bd`)
- [x] **M4.1 Production**
- Structured JSON logging (`clm.logging.structured`)
@@ -99,21 +103,43 @@ Empfehlung Commit-Split: (1) P2, (2) P3, (3) P4 — oder ein Squash „phase 2
- [x] **M4.4 Policy-Plugins**
- `DecisionPolicy` Protocol + `DecisionEngine(policies=…)`
- Beispiel: `BlockersForceHandoffPolicy`, `PreferHandoffOverCompactPolicy`
- [x] Docs/README/architecture/metrics/manifest; Version `0.4.0a1`
- [x] Docs/README/architecture/metrics/manifest; Version `0.4.0a1`; `uv.lock`
### Wichtige neue Pfade (P4)
### Wichtige Pfade (P2–P4)
| Pfad | Rolle |
|------|--------|
| `src/clm/compaction/verify.py` | Verified compaction / recall |
| `src/clm/memory/factory.py`, `mem0_store.py`, `hybrid_store.py` | Memory backends |
| `src/clm/session/openai_compatible.py` | OpenAI-compatible agent PoC |
| `src/clm/calibration/` | Adaptive thresholds |
| `src/clm/export/` | Metrics export |
| `src/clm/logging/structured.py` | JSON structured logging |
| `src/clm/metrics/cost.py` | Cost model helpers |
| `src/clm/memory/backup.py` | tar.gz backup/restore |
| `src/clm/memory/namespaced.py` | Multi-agent key prefix |
| `src/clm/experiments/ab_memory.py` | A/B experiment runner |
| `src/clm/decision/policy.py` | DecisionPolicy plugins |
| `src/clm/cli/backup_cmd.py`, `experiment.py` | CLI |
| `src/clm/cli/{calibrate,export_cmd,signal,backup_cmd,experiment}.py` | CLI |
| `tests/unit/test_production_p4.py`, `test_ab_memory.py`, `test_multi_agent.py`, `test_decision_policy.py`, `test_cli_p4.py` | P4 tests |
### Commits (Auszug, `main`)
```text
(docs) docs: embed kontext-system diagram in README and architecture
7c788bd feat: complete phases 2–4 (verified compaction through production)
faf00df docs: stabilize HANDOFF branch tip reference
c48b837 chore: phase1 mvp quality gate
…
91e03d0 chore: initial empty repository
```
### Done (nach P4 — Docs)
- [x] `assets/kontext-system.jpg` committed
- [x] Diagramm in `README.md` (Intro) und `docs/architecture.md` (Überblick) eingebunden
- [x] ASCII-Datenfluss in architecture.md beibehalten (Runtime-Implementierung)
### Commands & results (Quality Gate, 2026-08-04 P4)
| Command | Result |
@@ -121,7 +147,7 @@ Empfehlung Commit-Split: (1) P2, (2) P3, (3) P4 — oder ein Squash „phase 2
| `pytest -q` | **126 passed** |
| `ruff check src tests` | clean |
| `mypy src/clm` | clean |
| `git push` | **pending** — nichts committed seit `faf00df` |
| `git push origin main` | **OK** (P2–P4 + docs-diagram) |
---
@@ -135,7 +161,7 @@ Empfehlung Commit-Split: (1) P2, (2) P3, (3) P4 — oder ein Squash „phase 2
- Namespaced memory prefixes keys; factory honors `memory_namespace`
- Policy plugins override base DecisionEngine decisions
- CLI: `backup memory`, `experiment ab-memory`, help lists new commands
- P1–P3 suite still green (126 total)
- Full suite green (126 total) at P4 gate; P2–P4 on origin as `7c788bd`
---
@@ -154,7 +180,7 @@ Empfehlung Commit-Split: (1) P2, (2) P3, (3) P4 — oder ein Squash „phase 2
| Thema | Hinweis |
|-------|---------|
| Uncommitted bulk | P2+P3+P4 gemeinsam im Working Tree — Commit-Split oder Squash; User entscheidet |
| Squash commit | P2+P3+P4 als ein Commit `7c788bd` — History nicht pro Phase aufgesplittet |
| A/B mem0 arms | Nutzen `InMemoryMem0Client` ohne API-Key — misst Integration, nicht Live-Vector-Qualität |
| Namespace | Präfix gilt für alle Keys des Stores; Agents teilen Namespace bewusst |
| Policy order | Policies laufen sequentiell; spätere können frühere Overrides weiter ersetzen |
@@ -164,7 +190,7 @@ Empfehlung Commit-Split: (1) P2, (2) P3, (3) P4 — oder ein Squash „phase 2
## Blockers
Keine technischen Blocker für P4. **Commit/Push wartet auf explizite User-Freigabe.**
Keine. P0–P4 sind auf `origin/main`. Nächste Arbeit = Ops / Research-Plugins / Live-Smokes.
---
@@ -176,28 +202,28 @@ Keine technischen Blocker für P4. **Commit/Push wartet auf explizite User-Freig
| `.clm/calibrations/` | P3 `calibrate --write` |
| `.clm/exports/` | P3 export metrics; P4 A/B reports |
| `.clm/backups/` | P4 memory tar.gz |
| `uv.lock` | untracked; optional committen |
| `uv.lock` | committed (Dependencies gelockt) |
---
## Decision rationale (dieser Handoff)
- P4 M4.1–M4.4 aus Plan-Meilensteinen umgesetzt und quality-gated (126 / ruff / mypy).
- Offline-Default intakt; Backup/A/B/Policies additiv; Multi-Agent nur Konventionen.
- Version `0.4.0a1`; Handoff-Status **`ready_for_commit`**.
- Nächste Session: committen/pushen oder Ops/Research-Plugins — **nicht** P4 neu bauen.
- P4 M4.1–M4.4 quality-gated und auf origin (`7c788bd`).
- Docs: System-Diagramm `assets/kontext-system.jpg` in README + architecture eingebunden (User: commit+push).
- Offline-Default intakt; Version `0.4.0a1`; Status **`complete`** (Roadmap P0–P4).
- Nächste Session: Ops smoke / custom policies / cost tables — **nicht** P0–P4 neu bauen.
---
## Quick resume checklist
- [ ] `git status` — erwarten: viele M + ?? unter `src/clm/`, `tests/`, docs, `pyproject.toml`
- [ ] Optional: commit + `git push origin main` (nur mit User-OK)
- [ ] `git pull origin main` · `git status` → clean
- [ ] `git log -1` → docs-Commit mit Kontext-System-Diagramm (nach `7c788bd`)
- [ ] `source .venv/bin/activate` / bei Bedarf `uv pip install -e ".[dev]"`
- [ ] `pytest -q && ruff check src tests && mypy src/clm` → 126 / clean / clean
- [ ] Dieses `HANDOFF.md` + `docs/architecture.md` (P4)
- [ ] **Nicht** P4 erneut implementieren
- [ ] Nächster Task: **Commit** oder Ops/Policy-Erweiterungen
- [ ] Dieses `HANDOFF.md` + `README.md` / `docs/architecture.md` (Diagramm)
- [ ] **Nicht** P0–P4 erneut implementieren
- [ ] Nächster Task: Ops / Live-Smoke / DecisionPolicy / price_table
---
@@ -205,7 +231,7 @@ Keine technischen Blocker für P4. **Commit/Push wartet auf explizite User-Freig
```text
Repo: /Volumes/SSD2TB/books/clm-agents
Branch: main @ faf00df (origin) + uncommitted P2+P3+P4 working tree
HANDOFF.md lesen · P4 complete (0.4.0a1, 126 tests) · nicht neu bauen
User-Wahl: (A) commit+push P2/P3/P4 | (B) Ops smoke / custom DecisionPolicy
Branch: main @ origin (P0–P4 complete, 0.4.0a1; docs: kontext-system.jpg)
HANDOFF.md lesen · 126 tests · nicht neu bauen
Nächster Fokus: Live Mem0/OpenAI smoke, custom DecisionPolicy, price_table
```
README.md
+4
View File
@@ -4,6 +4,10 @@ Automated Context Lifecycle Management for LLM Agents.
**Phase 4** (`0.4.0a1`): Production hardening (structured JSON logging, manifest `schema_version`, memory backup/restore, cost model per provider), A/B memory experiments (`clm experiment ab-memory`), multi-agent handoffs (`agent_id`, shared `memory_namespace`), and DecisionPolicy plugins. Builds on P3 calibrate/export/signal/HITL and P2 verified compaction — defaults still work offline.
![CLM Kontext-System — Outer Control Loop, Orchestration Layer und Context Management Core](assets/kontext-system.jpg)
*Systemübersicht: Outer Loop (Decision Engine), Orchestrierung (Phasen/Handoffs) und Context Management Core (Memory + Verified Compaction). Details: [`docs/architecture.md`](docs/architecture.md).*
## Requirements
- Python ≥ 3.12
assets/kontext-system.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 582 KiB

docs/architecture.md
+6
View File
@@ -9,6 +9,12 @@ Design-Grundlage: [`docs/superpowers/specs/2026-08-04-clm-design.md`](superpower
CLM ist ein **framework-agnostischer Outer Control Loop** über einem ausführenden Agenten. Es misst Context/Tokens, entscheidet zwischen **CONTINUE**, **COMPACT** und **HANDOFF**, schreibt Memory und erzeugt bei Handoff ein strukturiertes Manifest.
![CLM Kontext-System — Outer Control Loop, Orchestration Layer und Context Management Core](../assets/kontext-system.jpg)
*Drei Schichten: **Outer Loop** (Token/Entropy-Monitor, Compact-vs-Handoff-Entscheidung, Manifest-Generator), **Orchestration Layer** (Phasen/Artefakte, z. B. Traycer oder custom), **Context Management Core** (Long-Term Memory + Native/Verified Compaction) um die Working Agent Session.*
### Runtime-Datenfluss (Implementierung)
```text
┌─────────────────────────────────────────────────────────────────┐
│ OuterControlLoop │