Skip to content

Commit c9b9086

Browse files
authored
docs: polish README presentation
Polish the German README presentation with status badges, refined Mermaid diagrams, an Evidence workflow knowledge graph, and a Non-Claims diagram. Scope: - README.md only Safety: - Synthetic-only and human-review boundaries preserved. - No production, legal, forensic, EU AI Act, official SPARK, or BMDS compliance claims. - No code, workflow, artifact, report, or governance-file changes.
1 parent b9191af commit c9b9086

1 file changed

Lines changed: 96 additions & 24 deletions

File tree

README.md

Lines changed: 96 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,97 @@
11
# Sparkctl
22

3-
**Lokaler Prototyp im Kontext des BMDS/SPARK-Hackathons: Evidence-, Replay- und Validierungsschicht für SPARK-artige Verwaltungs-KI-Workflows.**
3+
![Rust-Validierung](https://github.com/ProfRandom92/comptext-sparkctl/actions/workflows/rust-validation.yml/badge.svg)
4+
![Rust](https://img.shields.io/badge/Rust-CLI-orange)
5+
![Status](https://img.shields.io/badge/Status-Prototyp-blue)
6+
![Daten](https://img.shields.io/badge/Daten-synthetisch--only-purple)
7+
![Prüfung](https://img.shields.io/badge/Prüfung-Human--in--the--Loop-green)
8+
![Claims](https://img.shields.io/badge/Claims-keine%20Produktiv%2FRechts%2FCompliance--Claims-lightgrey)
49

5-
---
10+
**Lokale Rust-CLI für synthetische Evidence-Pakete, deterministisches Replay, Kontext-Rendering und überprüfbare KI-Workflow-Artefakte.**
11+
12+
**Prototyp im Kontext des BMDS/SPARK-Hackathons: Evidence-, Replay- und Validierungsschicht für SPARK-artige Verwaltungs-KI-Workflows.**
613

7-
## Status und Eigenschaften
14+
> Modelle sind Provider. Kontext ist das Produkt.
15+
16+
---
817

9-
- **Typ:** Prototyp / Konzept-Demo
10-
- **Datenbasis:** Rein synthetisch (*Synthetic-only*)
11-
- **Freigabe:** Erfordert menschliche Prüfung (*Human Review Required / Human-in-the-Loop*)
12-
- **Technologie:** Rust CLI (`agy-ct` und `sparkctl`)
13-
- **Architektur:** Lokal-first (*Local-first / Offline*)
14-
- **Einschränkung:** Keine Aussage zur Produktivreife, Rechtskonformität oder behördlichen Zertifizierung (*No production/legal/compliance claims*)
18+
## Snapshot
1519

16-
*Kernsatz: Modelle sind Provider, Kontext ist das Produkt.*
20+
| Dimension | Sparkctl-Scope |
21+
|---|---|
22+
| **Typ** | Prototyp / Konzept-Demo |
23+
| **Datenbasis** | Rein synthetisch (*Synthetic-only*) |
24+
| **Freigabe** | Erfordert menschliche Prüfung (*Human Review Required / Human-in-the-Loop*) |
25+
| **Technologie** | Rust CLI (`agy-ct` und `sparkctl`) |
26+
| **Architektur** | Lokal-first (*Local-first / Offline*) |
27+
| **Einschränkung** | Keine Aussage zur Produktivreife, Rechtskonformität oder behördlichen Zertifizierung (*No production/legal/compliance claims*) |
1728

1829
---
1930

2031
## Architektur-Übersicht
2132

2233
```mermaid
2334
flowchart LR
24-
A["Raw JSON Trace"] --> B["schema check"]
25-
B --> C["package compress"]
26-
C --> D["package verify"]
27-
C --> E["package inspect"]
28-
C --> F["package adversarial"]
29-
C --> I["context build"]
30-
I --> J["context render"]
31-
I --> K["notebook bundle"]
32-
J --> K
33-
K --> L[".ipynb Notebook"]
34-
A --> G["report export"]
35-
G --> H["Markdown Report"]
35+
roh["Synthetischer JSON-Trace"] --> schema["schema check"]
36+
schema --> compress["package compress"]
37+
compress --> spkg[".spkg Evidence-Paket"]
38+
39+
spkg --> inspect["package inspect"]
40+
spkg --> verify["package verify"]
41+
spkg --> replay["package replay"]
42+
spkg --> adversarial["package adversarial"]
43+
44+
schema --> report["report export"]
45+
report --> md["Markdown-Review-Report"]
46+
47+
spkg --> build["context build"]
48+
build --> render["context render"]
49+
build --> notebook["notebook bundle"]
50+
render --> notebook
51+
notebook --> ipynb[".ipynb Review-Notebook"]
52+
53+
classDef guard fill:#111827,stroke:#60a5fa,color:#e5e7eb;
54+
classDef artifact fill:#1f2937,stroke:#34d399,color:#e5e7eb;
55+
class schema,verify,adversarial guard;
56+
class spkg,md,ipynb artifact;
57+
```
58+
59+
---
60+
61+
## Evidence-Workflow als Wissensgraph
62+
63+
Sparkctl lässt sich als kleiner Evidence-Graph lesen:
64+
65+
```mermaid
66+
flowchart TB
67+
sparkctl["Sparkctl"] --> cli["agy-ct CLI"]
68+
cli --> package["Package-Lifecycle"]
69+
cli --> context["Context-Lifecycle"]
70+
cli --> review["Review-Artefakte"]
71+
72+
package --> spkg2[".spkg Evidence-Paket"]
73+
spkg2 --> integrity["Hash- und Ledger-Prüfungen"]
74+
spkg2 --> replay2["Deterministisches Replay"]
75+
spkg2 --> adversarial2["Adversarial-Simulation"]
76+
77+
context --> build2["Strukturierter Kontext"]
78+
build2 --> render2["Token-sparendes Rendering"]
79+
build2 --> notebook2["Notebook-Bundle"]
80+
81+
review --> report2["Markdown-Report"]
82+
review --> notebook2
83+
84+
governance["Governance-Grenzen"] --> synthetic["Synthetic-only"]
85+
governance --> human["Human Review"]
86+
governance --> nonclaims["Keine Produktiv-/Rechts-/Compliance-Claims"]
87+
88+
synthetic --> sparkctl
89+
human --> sparkctl
90+
nonclaims --> sparkctl
3691
```
3792

93+
Dieser Graph ist bewusst README-nativ gehalten. Eine interaktive Ace-Knowledge-Graph-Variante kann später aus derselben Struktur generiert werden; die README bleibt jedoch ohne externe Runtime vollständig lesbar.
94+
3895
---
3996

4097
## Warum relevant für den SPARK-Hackathon?
@@ -93,7 +150,7 @@ Führen Sie die folgenden sicheren lokalen Befehle im Rust-Unterverzeichnis aus:
93150
# In das Rust-Verzeichnis wechseln
94151
cd agy7rust
95152

96-
# Testsuite ausführen (73 PASS Tests)
153+
# Testsuite ausführen
97154
cargo test
98155

99156
# Berichtsexport mit einer synthetischen Beispieldokumentation ausführen
@@ -119,6 +176,20 @@ Sparkctl nutzt eine Reihe technischer Mechanismen, um die Integrität synthetisc
119176

120177
Um Missverständnisse im Rahmen des SPARK-Hackathons auszuschließen, gelten folgende Grenzen:
121178

179+
```mermaid
180+
flowchart TB
181+
prototype["Prototyp / Konzept-Demo"]
182+
synthetic2["Rein synthetische Daten"]
183+
human2["Menschliche Prüfung erforderlich"]
184+
local["Lokal-first / Offline"]
185+
noClaims["Keine Produktiv-, Rechts-, Forensik- oder Compliance-Claims"]
186+
187+
prototype --> noClaims
188+
synthetic2 --> noClaims
189+
human2 --> noClaims
190+
local --> noClaims
191+
```
192+
122193
### Matrix der Non-Claims
123194

124195
| Eigenschaft | Scope-Abgrenzung / Non-Claim |
@@ -152,10 +223,11 @@ Dieses Repository nutzt klare Richtlinien für die lokale Ausführung von KI-Ent
152223
- Erweiterung der synthetischen Planungs-Fixtures.
153224
- Evaluierung von Community-Feedback zu Evidence-Strukturen.
154225
- Optionale native Plugin- und Hook-Integrationen für verbesserte Absicherung.
226+
- Optionaler Repo-Hygiene-Fix für alte Submodule-/Workflow-Warnungen.
155227

156228
---
157229

158230
## Community
159231

160232
- **Feedback & Issues:** Fragen, Anregungen oder Fehlerberichte zu den Prototypen sind via GitHub Issues willkommen.
161-
- **Fokus auf Synthetik:** Bitte posten Sie in den Issues oder Diskussionen niemals echte Verwaltungs- oder Bürgerdaten. Verwenden Sie stets anonymisierte oder synthetische Beispieldaten.
233+
- **Fokus auf Synthetik:** Bitte posten Sie in den Issues oder Diskussionen niemals echte Verwaltungs- oder Bürgerdaten. Verwenden Sie stets anonymisierte oder synthetische Beispieldaten.

0 commit comments

Comments
 (0)