Squashed 'ai-context/trustgraph-templates/' content from commit 42a5fd1b

git-subtree-dir: ai-context/trustgraph-templates git-subtree-split: 42a5fd1b678f32be378062e30451e2052ccb95dd
2026-07-02 22:41:01 +02:00 · 2026-04-05 21:09:49 -05:00 · 2026-04-05 21:09:49 -05:00 · 74cc8a4685
commit 74cc8a4685
1216 changed files with 116347 additions and 0 deletions
--- a/DIALOG-FLOW.md
+++ b/DIALOG-FLOW.md
@ -0,0 +1,168 @@
+# TrustGraph Configuration Dialog Flow
+
+## Overview
+
+A configuration wizard system that guides users through TrustGraph deployment setup. Outputs deployment configuration and contextual documentation.
+
+Supports two interfaces:
+- **Web UI**: Step-by-step wizard with visual cards
+- **CLI**: Interactive terminal prompts
+
+## Architecture
+
+```
+┌─────────────────────┐
+│  trustgraph-flow    │   State machine defining wizard steps
+│      .yaml          │   and transitions
+└──────────┬──────────┘
+           │
+           ▼
+┌─────────────────────┐
+│    Flow Engine      │   Executes state machine, collects user input,
+│   (Web UI / CLI)    │   manages state and backtracking
+└──────────┬──────────┘
+           │
+           ▼
+    ┌──────────────┐
+    │ Wizard State │   Simple key/value object
+    │    (JSON)    │   e.g., { platform: "gke", model_deployment: "ollama", ... }
+    └──────┬───────┘
+           │
+     ┌─────┴─────┐
+     ▼           ▼
+┌─────────┐ ┌─────────────┐
+│ Output  │ │Documentation│
+│Transform│ │  Assembler  │
+└────┬────┘ └──────┬──────┘
+     │             │
+     ▼             ▼
+┌─────────┐ ┌─────────────┐
+│Component│ │  README.md  │
+│  Array  │ │ / Checklist │
+│ (JSON)  │ │   (JSON)    │
+└─────────┘ └─────────────┘
+```
+
+## Key Design Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Flow structure | State machine | Explicit transitions, supports conditional branching |
+| Expression language | JSONata | Single language for conditions and transforms |
+| Documentation storage | Manifest + markdown fragments | Clean separation, easy to maintain |
+| Platform variants | `in ['docker-compose', 'podman-compose']` | Explicit grouping, no hidden logic |
+| Template variables | `{{var}}` syntax | Simple, familiar |
+
+## File Structure
+
+```
+config-dialog-flow/
+├── dialog-flow-schema.json       # Schema: flow definitions
+├── docs-manifest-schema.json     # Schema: documentation manifests
+├── trustgraph-flow.yaml          # Flow: wizard state machine
+├── trustgraph-output.jsonata     # Transform: state → components
+├── trustgraph-docs.yaml          # Manifest: state → documentation
+└── docs/                         # Fragments: markdown content
+    ├── platform/
+    ├── model/
+    ├── storage/
+    ├── gateway/
+    ├── deploy/
+    └── features/
+```
+
+## Data Flow
+
+1. **Flow engine** loads `trustgraph-flow.yaml`
+2. User progresses through steps, engine collects state
+3. On completion:
+   - **Output transform** evaluates `trustgraph-output.jsonata` against state → component array
+   - **Doc assembler** evaluates `trustgraph-docs.yaml` conditions against state → filtered instructions → loads markdown fragments → outputs README or checklist JSON
+
+## Implementation Phases
+
+### Phase 1: Core Flow Engine
+
+- [ ] Parse YAML flow definition
+- [ ] Implement state machine executor
+- [ ] Handle step rendering (title, description, input)
+- [ ] Evaluate JSONata transition conditions
+- [ ] Manage wizard state (set values, navigate)
+- [ ] Implement backtracking (previous step, state rollback)
+
+### Phase 2: Input Types
+
+- [ ] Select (single choice from options)
+- [ ] Toggle (boolean)
+- [ ] Number (with min/max/step)
+- [ ] Text (free input)
+- [ ] Skip single-option steps (UX decision)
+
+### Phase 3: Output Generation
+
+- [ ] Load JSONata transform
+- [ ] Evaluate against wizard state
+- [ ] Produce component array JSON
+- [ ] Package as downloadable ZIP (existing functionality)
+
+### Phase 4: Documentation Assembly
+
+- [ ] Parse documentation manifest
+- [ ] Evaluate `when` conditions (JSONata)
+- [ ] Filter to matching instructions
+- [ ] Load markdown fragments
+- [ ] Substitute `{{var}}` placeholders
+- [ ] Output as README.md (CLI) or checklist JSON (Web)
+
+### Phase 5: CLI Interface
+
+- [ ] Terminal prompt for each step
+- [ ] Numbered option selection
+- [ ] Progress indicator (`[3/12]`)
+- [ ] Back command
+- [ ] Review summary before generate
+
+### Phase 6: Web Interface
+
+- [ ] Step-by-step card UI
+- [ ] Progress bar
+- [ ] Option cards with icons/descriptions
+- [ ] Back navigation
+- [ ] Review screen with edit capability
+- [ ] Generate button
+
+## Expression Language
+
+All conditions use JSONata:
+
+```
+platform = 'docker-compose'
+platform in ['gke', 'eks', 'aks', 'minikube']
+model_deployment = 'ollama' and platform in ['docker-compose', 'podman-compose']
+version < '1.6.0'
+ocr.enabled = true
+```
+
+## State Shape
+
+```
+{
+  "version": "1.8.18",
+  "platform": "gke",
+  "k8s": { "namespace": "trustgraph" },
+  "graph_store": "cassandra",
+  "vector_db": "qdrant",
+  "object_store": "cassandra",
+  "model_deployment": "ollama",
+  "max_output_tokens": 2048,
+  "ocr": { "enabled": true, "engine": "tesseract" },
+  "embeddings": { "enabled": false }
+}
+```
+
+## Out of Scope (Future)
+
+- Dual model mode (separate main/RAG models)
+- Advanced settings (concurrency, chunking, memory profiles)
+- Configuration import/export
+- Validation beyond type checking