fai/reclaim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
reclaim/RUN.md
flemming-it 244ae4c219 docs(run): Live über den Store — install + end-to-end verification 
Document installing the 8 published modules from chain-modules/reclaim
(Forgejo-raw) and the 2026-06-22 fresh-hub verification: test-cohort green
(cohort 180000) and durchstich-full running all 5 modules on real GewO XML
(plausible deontic tuples + readability), pausing at the approval gate.
Note durchstich-gewo-14 is blocked by http.request (chain bundled module,
wasm_url 404).

Signed-off-by: flemming-it <sf@flemming.it>
2026-06-22 23:34:51 +02:00

7.4 KiB
Raw Blame History

Recl∆Im (F∆I) — Run-Guide (Phase 0)

Stand v0.1.0 — Demo-Modus, ohne externe Daten, ohne Hub-Verbindung.

Layout

fai_reclaim/
├── MACHBARKEITSSTUDIE.md     # die Studie (v0.3, AG-intern)
├── RUN.md                    # diese Datei
├── app/                      # Flutter-Client, Brand-Skin fai_web
│   ├── lib/                  # Dart-Code (Pages, Widgets, Data, Theme)
│   ├── assets/
│   │   ├── fonts/            # SIL-OFL TTFs (setup.sh holt sie)
│   │   └── fixtures/         # Phase-0 Demo-Daten
│   ├── macos/                # Plattform-Scaffolds (auto-generiert)
│   ├── setup.sh              # Fonts + Pakete
│   └── pubspec.yaml
└── flows/
    └── durchstich-gewo-14.yaml   # vertikaler Phase-0-Flow

Die acht zugehörigen Module liegen unter fai_chain_modules/ als eigene Crate-Verzeichnisse, ABI chain:platform, alle Apache 2.0:

  • text-akoma-normalize/ (Pflicht-Eingang, gesetze-im-internet-XML-Adapter)
  • text-deontic-extract/ (Pflicht-Tupel via Regex + LLM-Vorschlag im Flow)
  • graph-citation-extract/ (cites, verweist_iVm)
  • text-readability-score/ (Flesch-DE + Verweistiefe)
  • stats-cohort-size/ (DESTATIS-/IHK-Kohorten, Phase 0 mit Stub-Tabelle)
  • graph-shapley-attribution/ (Pfad-anteilige Splittung)
  • econ-skm-score/ (Standardkostenmodell P×F×T×h)
  • law-benefit-score/ (7-dim. Nutzen-Aggregation — das einzige genuin domänen-spezifische Modul, gehört in chain-modules-law/)

Sofort starten (Demo-UI, kein Hub nötig)

cd app
./setup.sh                # Fonts + flutter pub get
./build-macos.sh          # Robust-Build (strippt macOS-xattrs vor CodeSign)
open build/macos/Build/Products/Debug/reclaim_app.app

Direkter flutter run -d macos funktioniert auch, kann aber bei einem frischen Checkout an com.apple.provenance-xattrs scheitern (macOS-Eigenheit bei via curl/iCloud erstellten Dateien) — dann einmal ./build-macos.sh und danach flutter run -d macos.

Erwartet: Brand-Landing → Klick auf „App öffnen" → NavigationRail (Heatmap / Normen / Freigaben / Hub / Methodik / Recht) mit fünf Pilot-Norm-Punkten. Default ist der Live-Hub-Modus (läuft ein chain serve auf 127.0.0.1:50051, werden die fünf Normen live ausgewertet — submit pro Norm, echte skm/benefit-Achsen). Ohne Hub bzw. mit Demo-Toggle im Hub-Reiter: die fünf Fixtures mit T4-Demo-Banner.

Test-Suite (smoke):

flutter test

Web-Variante (gleiche Codebase, ein Befehl)

cd app
./serve-web.sh           # baut + serviert auf http://127.0.0.1:8080

Funktioniert im Demo- und im Live-Hub-Modus: die SDK wählt per conditional import den GrpcWebClientChannel, sodass der Browser denselben Hub auf 127.0.0.1:50051 erreicht (verifiziert: „App öffnen" feuert 5× Submit über gRPC-Web). Der Hub muss gRPC-Web anbieten — chain serve tut das auf einer Loopback-Bindung von Haus aus.

Produktion: build/web/ auf einen statischen Host kippen (F∆I-Pattern: Hetzner-CX + Caddy mit Auto-HTTPS, analog fai_chain Release-Host). DNS: reclaim.flemming.ai.

Hub-Smoke-Test (chain serve läuft separat)

Wenn ein chain serve lokal auf 127.0.0.1:50051 läuft (vom fai_chain-Setup):

  1. App starten, „Hub"-Reiter öffnen
  2. Host/Port stehen schon, „Hub beim Start nutzen" anschalten
  3. „Verbindung testen" → erwartet healthy=true
  4. Falls capabilities installiert sind: „Installierte Capabilities" listet sie auf
  5. Der Heatmap-Tab füllt sich automatisch live: HubRepository.list() führt pro Pilot-Norm den reclaim-evaluate-Flow via submit() aus (json-Inputs für skm/benefit) und mappt SubmitResponse.outputs (norm/skm/benefit/frust/cohort/duties) in Evaluation-Objekte. Kein manuelles chain run nötig — die App treibt die Flows selbst. (Der Audit-Log speichert keine Outputs, nur Hashes; daher der submit-Pfad statt eventLog.) Offene system.approval-Aufgaben erscheinen separat im „Freigaben"-Reiter zur juristischen Bestätigung.

Modul-Tests (lokal grün ohne Hub)

for m in text-akoma-normalize text-deontic-extract \
         graph-citation-extract text-readability-score \
         stats-cohort-size graph-shapley-attribution \
         econ-skm-score law-benefit-score; do
  (cd ../fai_chain_modules/$m && cargo test) || break
done

WASM-Build (für chain install)

cd ../fai_chain_modules/text-akoma-normalize
cargo build --release --target wasm32-wasip2
# Artefakt: target/wasm32-wasip2/release/text_akoma_normalize.wasm

Selber Aufruf für die anderen sieben Verzeichnisse.

Live-Flow (Default, sobald chain serve läuft)

chain serve &
chain install text.akoma-normalize text.deontic-extract \
              graph.citation-extract text.readability-score \
              stats.cohort-size graph.shapley-attribution \
              econ.skm-score law.benefit-score \
              http.request system.approval
chain run flows/durchstich-gewo-14.yaml \
  --input norm_url=https://www.gesetze-im-internet.de/gewo/__14.xml \
  --input cohort_id=berlin-kmu
chain admin events --limit 10
chain admin approvals list   # Juristen-Gate

Im Flutter-Client den MockRepository durch eine HubRepository (gRPC gegen localhost:50051) ersetzen — Interface bleibt gleich, keine UI-Änderung nötig.

Live über den Store

Die 8 Recl∆Im-Module sind publiziert unter chain-modules/reclaim (Forgejo-raw, .chain-Bundles, unsigniert) und lassen sich ohne lokalen WASM-Build direkt aus dem Store installieren:

chain store add "Recl∆Im" \
  https://git.flemming.ai/chain-modules/reclaim/raw/branch/main/store.yaml
chain store refresh        # fetcht den Store (8 Module)
chain store search         # die 8 Capabilities erscheinen als `pub`
chain install stats.cohort-size text.akoma-normalize \
              text.deontic-extract graph.citation-extract \
              text.readability-score   # Download von den Forgejo-raw-URLs

Capability-IDs sind Dash-Form (econ.skm-score, law.benefit-score, …); der Store-name: entspricht exakt der gebündelten provides.capability.

End-to-End verifiziert (2026-06-22, frischer isolierter Hub via Temp-HOME):

  • chain run flows/test-cohort.yaml --input cohort_id=berlin-kmu → grün, cohort.count = 180000 (DESTATIS, Tier T1).
  • chain run flows/durchstich-full.yaml --input content=@gewo.xml --input cohort_id=berlin-kmu → alle 5 Module laufen (normalize → deontic → citations → cohort → frust), Flow pausiert am system.approval-Gate (Soll). Auf echter GewO-XML liefert die Pipeline plausible deontische Tupel (OBLIGATION/PERMISSION, Confidence 0.7–0.85) und Lesbarkeit (flesch_de ≈ 35, composite_frust ≈ 3.8).

GewO-Volltext-XML: https://www.gesetze-im-internet.de/gewo/xml.zip (die per-§-URL …/gewo/__14.xml liefert inzwischen 404). durchstich-gewo-14.yaml braucht zusätzlich http.request — dieses bundled-Modul ist derzeit nicht installierbar (chain-seitige wasm_url liefert 404; Handoff an chain offen). Nutze solange durchstich-full mit --input content=@<norm>.xml.

Was Phase 0 NICHT enthält (bewusst)

  • gRPC-Anbindung Flutter ↔ Hub (Woche 1)
  • Echte NKR-Datenbank-Anbindung (Woche 2-3)
  • DESTATIS GENESIS-API-Adapter (Woche 4)
  • Juristen-Approval-Backend-Anbindung (Woche 5)
  • Volle Akoma-Ntoso-Konvertierung (v0.2)
  • HTML- und FORMEX-Adapter für text.akoma-normalize (v0.2/0.3)