Sync from GitHub via hub-sync

README.md

@@ -30,39 +30,89 @@ This project explores that engineering boundary by building a small workflow run
 
 The workflow engine—not the language model—decides what may run next.
 
-## Demo Scenario
+## Demo Scenario — Fictional Wealth Management Household Onboarding
 
-The public demo uses a synthetic fictional **Service Request Workflow**.
+The public demo follows a fully synthetic household through a hypothetical wealth-management onboarding process. It is designed to illustrate workflow engineering, not to represent any firm's real compliance program or to open an actual account.
 
-A request moves through a controlled process:
+```text
+Synthetic household intake
+          ↓
+Validate intake
+          ↓
+🤖 AI Intake Organizer
+          ↓
+Check documents
+          ↓
+Apply deterministic onboarding rules
+          ↓
+Prepare onboarding package
+          ↓
+Verify package
+          ↓
+Review gate
+     ↙              ↘
+Standard         Exception
+   ↓                ↓
+Ready for      Human operations /
+advisor review compliance review
+                    ↓
+              Approve / Reject
+                    ↓
+             Ready after review
+```
+
+The demo contains no real clients, accounts, trades, KYC/AML service calls, money movement, or proprietary data.
+
+### Four one-click stories
+
+- **Straightforward household** — the fictional package becomes ready on the standard path.
+- **Temporary service problem** — package preparation fails once, retries within policy, and recovers.
+- **Trust / complex household** — deterministic exception rules pause the workflow for a person.
+- **Permanent dependency failure** — the workflow stops safely before uncertain downstream work runs.
+
+## Where AI Is Implemented
+
+The `AI Intake Organizer` is the intentionally narrow model boundary.
+
+A model may receive only:
+
+- fictional household type,
+- synthetic onboarding notes.
+
+It may return only strict JSON containing:
+
+- an approved household-profile category,
+- a short intake summary.
+
+Pydantic rejects malformed output, invented categories, and extra control fields.
 
 ```text
-Submit Request
-      ↓
-Validate Request
-      ↓
-Classify Request
-      ↓
-Policy Check
-      ↓
-Perform Task
-      ↓
-Verify Result
-      ↓
-Risk Gate
-   ↙       ↘
-Low         High
- ↓           ↓
-Finalize   Human Review
-              ↓
-         Approve / Reject
+synthetic intake notes
+        ↓
+🤖 model proposes profile + summary
+        ↓
+strict schema validation
+        ↓
+normalized bounded output
+        ↓
+deterministic workflow continues
 ```
 
-The scenario is intentionally synthetic and contains no private, client, financial, or proprietary data.
+The AI does **not** receive or control:
 
-## Architecture
+- document-completeness flags,
+- identity-review status,
+- relationship-complexity routing rules,
+- DAG structure,
+- route targets,
+- handler identifiers,
+- retry limits,
+- workflow state,
+- or human approval decisions.
 
-The system contains the following layers.
+The current public demo uses a deterministic fallback at this AI-capable node unless a live provider callable is connected. The provider boundary is deliberately separate from workflow control so a model can be added or changed without changing the engine's state-transition rules.
+
+## Architecture
 
 ### 1. Structured Workflow Definition
 
@@ -72,15 +122,7 @@ A workflow definition describes what **may** happen. A workflow run records what
 
 ### 2. DAG Validation
 
-Before execution, deterministic validation rejects invalid workflow definitions such as:
-
-- duplicate node identifiers,
-- unknown dependencies,
-- cyclic dependencies,
-- invalid decision routes,
-- unsupported branch reconvergence,
-- invalid retry policies,
-- and malformed workflow definitions.
+Before execution, deterministic validation rejects invalid workflow definitions such as duplicate node identifiers, unknown dependencies, cycles, invalid decision routes, unsupported branch reconvergence, invalid retry policies, and malformed definitions.
 
 Invalid workflows fail before any task executes.
 
@@ -92,7 +134,7 @@ Workflow task handlers are explicitly registered and allowlisted. A workflow can
 
 The executor determines which nodes are ready, completed, skipped, failed, retryable, awaiting human review, or terminal.
 
-The MVP uses sequential synchronous execution so the workflow semantics remain easy to inspect and test.
+The MVP uses sequential synchronous execution so workflow semantics remain easy to inspect and test.
 
 ### 5. Workflow State Store
 
@@ -100,13 +142,11 @@ An in-memory state store supports deterministic tests, while SQLite persistence
 
 ### 6. Retry Controller
 
-Retries are explicit, bounded, and policy-controlled.
-
-The runtime distinguishes explicitly retryable failures from permanent failures and never permits unlimited retry loops.
+Retries are explicit, bounded, and policy-controlled. The runtime distinguishes explicitly retryable failures from permanent failures and never permits unlimited retry loops.
 
 ### 7. Human Escalation
 
-The workflow may enter a `WAITING_FOR_HUMAN` state. Execution cannot continue until a valid structured decision is recorded.
+The workflow may enter `WAITING_FOR_HUMAN`. Execution cannot continue until a valid structured decision is recorded.
 
 Human decisions:
 
@@ -116,27 +156,10 @@ Human decisions:
 
 ### 8. Event and Audit Log
 
-Meaningful state transitions emit structured events so execution can be inspected and reconstructed.
-
-Examples include:
-
-- workflow started,
-- node started,
-- node completed,
-- node skipped,
-- node failed,
-- decision routed,
-- retry scheduled,
-- human review requested,
-- human approved or rejected,
-- workflow resumed,
-- workflow completed,
-- workflow failed.
+Meaningful state transitions emit structured events so execution can be inspected and reconstructed. Audit events carry control metadata rather than copying onboarding notes into the event stream.
 
 ## Workflow States
 
-Application-controlled workflow states:
-
 ```text
 PENDING
 RUNNING
@@ -151,8 +174,6 @@ The model cannot invent or directly set arbitrary workflow states.
 
 ## Node Types
 
-The MVP uses a deliberately small node vocabulary:
-
 ```text
 TASK
 DECISION
@@ -166,57 +187,26 @@ Additional node types should be introduced only when a demonstrated requirement
 
 The MVP demonstrates that:
 
-1. A normal workflow executes in dependency order and completes.
-2. A transient failure retries within a bounded policy and can recover.
+1. A straightforward onboarding workflow executes in dependency order and completes.
+2. A transient package-preparation failure retries within a bounded policy and can recover.
 3. A permanent or exhausted failure stops safely.
-4. A high-risk request pauses for human review and resumes only after a valid decision.
+4. An exception household pauses for human review and resumes only after a valid decision.
 5. A partially completed workflow can reload from persisted state without repeating completed work.
-6. Duplicate completion or resume events do not cause duplicate downstream execution.
-
-The sixth requirement introduces **idempotency**, a core reliability property for workflow systems.
+6. Duplicate completion or resume attempts do not cause duplicate downstream execution.
 
-## Model Boundary
-
-The service-request classifier supports an optional **bounded model-assisted mode**.
-
-The model receives only the request type and description needed for classification. It returns strict JSON containing a classification from an application-defined allowlist plus a short rationale. Pydantic validates that proposal before the workflow accepts it.
-
-```text
-model proposes classification
-          ↓
-strict JSON schema validates
-          ↓
-application accepts normalized data
-          ↓
-deterministic workflow continues
-```
-
-The deterministic classifier remains the default, and model integration is provider-agnostic through an injected callable. A live inference-provider adapter will be added separately so provider networking does not become part of workflow control logic.
-
-The model is not permitted to:
-
-- change the DAG,
-- choose arbitrary route targets,
-- register arbitrary handlers,
-- bypass approval gates,
-- change retry limits,
-- execute arbitrary code,
-- set workflow state,
-- or publish unvalidated structured output.
-
-Malformed model output, invented classifications, extra control fields, and provider failures are contained at the classification node. Rejected model text is not copied into audit-event details.
+The sixth requirement demonstrates **idempotency**, a core reliability property for workflow systems.
 
 ## Evaluation Suite
 
-The project includes a reusable deterministic evaluation harness in `src/evaluation.py`. It runs the workflow through ten named scenarios and returns a structured `EvaluationReport` that can be displayed directly in the Gradio UI or enforced in CI.
+`src/evaluation.py` runs ten named deterministic scenarios and returns a structured `EvaluationReport` that the Gradio UI and CI can consume.
 
 Current scenarios cover:
 
-- normal low-risk automatic completion,
+- straightforward onboarding completion,
 - transient failure with bounded retry and recovery,
-- high-risk escalation followed by approval,
-- high-risk escalation followed by rejection,
-- invalid input containment,
+- exception review followed by approval,
+- exception review followed by rejection,
+- invalid intake containment,
 - permanent failure without unsafe retry,
 - checkpoint reload and resume without replay,
 - adversarial model attempts to inject workflow-control fields,
@@ -253,25 +243,23 @@ duplicate execution count      0
 invalid transition count       0
 ```
 
-A focused local execution check of the ten evaluation scenarios passed 10/10. GitHub Actions runs the complete repository test suite on pushes and pull requests to `main`; the first full CI run passed **109 tests** on Python 3.11 with Gradio 6.26.0 installed.
-
 ## Gradio Demo
 
 `app.py` provides a thin Gradio interface over the same runtime used by the tests. Workflow control is not duplicated inside the UI.
 
-The demo exposes:
+The landing page is intentionally understandable to non-technical visitors first:
 
-- **Run Workflow** — submit a fictional service request and deliberately exercise normal, retry, high-risk, or permanent-failure paths,
-- **Status & Node Results** — inspect node state, attempts, errors, and structured outputs,
-- **Event Timeline** — inspect append-only control-plane audit events without copying workflow context into event details,
-- **Human Approval** — apply `APPROVE`, `REJECT`, or `RETRY` to an open durable review,
-- **Evaluation Results** — run the reusable ten-case evaluation harness and display system-level metrics.
+- a fictional wealth-management onboarding story,
+- a clearly highlighted AI Intake Organizer,
+- one-click standard, retry, exception, and permanent-failure scenarios,
+- a plain-English business outcome,
+- and a step-by-step explanation of what happened.
 
-Each new workflow execution receives a random run ID. The app stores checkpoints in SQLite and can reload a run by ID so a waiting human gate can survive ordinary UI interaction and process-level workflow pauses. The local database filename is gitignored, and `WORKFLOW_DB_PATH` can override its location at deployment time.
+Technical evidence remains available in separate views for node state, structured outputs, audit events, human decisions, persistence, and evaluation metrics.
 
-The deterministic workflow remains the public-demo default, so the Gradio app does not require a model token. Live provider networking is intentionally kept as a separate later integration step.
+Each new workflow execution receives a random run ID. The app stores checkpoints in SQLite and can reload a run by ID so a waiting human gate can survive ordinary UI interaction and process-level workflow pauses. The local database filename is gitignored, and `WORKFLOW_DB_PATH` can override its location at deployment time.
 
-Local SQLite persistence is appropriate for this portfolio demo, but it is not presented as multi-tenant production storage. Persistence across hosting-environment restarts depends on the storage configuration of the eventual deployment environment.
+Local SQLite persistence is appropriate for this portfolio demo, but it is not presented as multi-tenant production storage. Persistence across hosting-environment restarts depends on the deployment environment's storage configuration.
 
 ## CI and Deployment
 
@@ -279,8 +267,6 @@ Local SQLite persistence is appropriate for this portfolio demo, but it is not p
 
 The Hugging Face sync job uses `huggingface/hub-sync@v0.1.0`, targets `FlyingNunchucks/09-agentic-workflow-sys`, and authenticates only through the GitHub repository secret `HF_DEPLOY_TOKEN`. GitHub remains the code source of truth.
 
-The first production sync completed successfully after the test gate, and subsequent pushes to `main` now follow the same test-then-deploy path automatically.
-
 ## Project Structure
 
 ```text
@@ -294,26 +280,24 @@ src/
 tests/
 ```
 
-Implementation is being added incrementally in small, testable changes.
-
-## Planned Build Sequence
-
-1. Define structured schemas.
-2. Implement DAG validation.
-3. Implement an allowlisted handler registry.
-4. Implement the basic deterministic executor.
-5. Add structured event logging.
-6. Add bounded retries.
-7. Add workflow persistence and resume.
-8. Add human escalation.
-9. Add deterministic conditional routing.
-10. Assemble the synthetic service-request workflow.
-11. Add a model-assisted node only after deterministic behavior is tested.
-12. Build the evaluation suite.
-13. Add a Gradio demo.
-14. Add CI-gated GitHub → Hugging Face deployment.
-15. Complete live production and public-repository hygiene checks.
+## Build Sequence
+
+1. Structured schemas
+2. DAG validation
+3. Allowlisted handler registry
+4. Deterministic executor
+5. Structured event logging
+6. Bounded retries
+7. Workflow persistence and resume
+8. Human escalation
+9. Deterministic conditional routing
+10. Synthetic business workflow
+11. Bounded model-assisted node
+12. System evaluation suite
+13. Gradio demo
+14. CI-gated GitHub → Hugging Face deployment
+15. Live production and public-repository hygiene checks
 
 ## Status
 
-**Current phase:** Deterministic workflow engine, synthetic service-request workflow, bounded provider-agnostic model-assisted classification, structured evaluation harness, Gradio demo, GitHub Actions CI, and automated GitHub → Hugging Face deployment are implemented. Live Space validation and final public-repository hygiene remain.
+**Current phase:** Deterministic workflow engine, fictional wealth-management household-onboarding demo, bounded AI intake-organizer interface, structured evaluation harness, business-friendly Gradio experience, GitHub Actions CI, and automated GitHub → Hugging Face deployment are implemented. Final live validation of the redesigned onboarding UI and portfolio closeout remain.