Implement AI orchestration wedding demo

docs/api.md

@@ -0,0 +1,37 @@
+# API
+
+Primary orchestrator/demo endpoints:
+
+- `POST /tasks`
+- `PATCH /tasks/{task_id}`
+- `POST /notes`
+- `POST /reservations`
+- `PATCH /reservations/{reservation_id}`
+- `GET /dashboard`
+- `GET /tools`
+- `POST /transcriptions`
+- `GET /transcriptions/{job_id}`
+- `GET /pending-actions`
+- `PATCH /pending-actions/{action_id}`
+- `POST /pending-actions/{action_id}/approve` generates the API call; it does not send it
+- `POST /pending-actions/{action_id}/reject`
+- `WS /ws/transcript`
+
+Generated Wed backend tools:
+
+- `create_task` -> `POST /tasks/`
+- `update_task` -> `PATCH /tasks/{task_id}`
+- `create_note` -> `POST /notes/`
+- `update_note` -> `PATCH /notes/{note_id}`
+- `create_guest_reservation` -> `POST /reservations/guest`
+- `update_reservation` -> `PATCH /reservations/{reservation_id}`
+
+Transcript chunks:
+
+```json
+{
+  "speaker": "Bride",
+  "timestamp": "2026-06-26T12:00:00Z",
+  "text": "Create a task for Maria to confirm the photographer."
+}
+```

docs/architecture.md

@@ -0,0 +1,54 @@
+# Architecture
+
+```mermaid
+flowchart LR
+  Client[React Dashboard] -->|WebSocket transcript chunks| Gateway[Streaming Gateway]
+  Gateway --> Orchestrator[AI Orchestrator]
+  Orchestrator --> Context[Context Builder]
+  Orchestrator --> Memory[Memory Manager]
+  Orchestrator --> Planner[Hybrid LLM Planner]
+  Orchestrator --> Registry[Generated Tool Registry]
+  Orchestrator --> Policy[Policy Engine]
+  Orchestrator --> Validation[Validation Layer]
+  Orchestrator --> Publisher[Event Publisher]
+  Client -->|approve/reject/edit| Review[Pending Review API]
+  Review --> Generator[API Call Generator]
+  Generator -->|method + URL + headers + JSON + cURL| GeneratedCall[Generated Wed API Call]
+  GeneratedCall -. not sent .-> WedAPI[Wed Backend API]
+  Executor -. dashboard demo state .-> REST[REST Demo Backend]
+  REST --> Postgres[(PostgreSQL)]
+  WedAPI --> WedPostgres[(Wed PostgreSQL)]
+  Context --> Redis[(Redis)]
+  Publisher --> Streams[(Redis Streams)]
+  Memory --> Qdrant[(Qdrant)]
+```
+
+## Sequence
+
+```mermaid
+sequenceDiagram
+  participant UI as React Dashboard
+  participant WS as Streaming Gateway
+  participant O as Orchestrator
+  participant P as Planner
+  participant V as Validation
+  participant PE as Policy Engine
+  participant DB as PostgreSQL
+  participant EX as Executor
+
+  UI->>WS: transcript chunk
+  WS->>O: ConversationEvent
+  O->>P: transcript + context + memories + tools
+  P-->>O: structured plan
+  O->>V: validate schema and parameters
+  O->>PE: evaluate confidence, duplicates, rules
+  O->>DB: create PendingAction
+  UI->>DB: approve/edit/reject pending action
+  UI->>EX: approve / generate call
+  EX-->>DB: store generated API call
+  EX-->>UI: generated call state
+```
+
+## Design Notes
+
+The planner never executes tools. It produces structured decisions against the Wed backend tool contract, the policy and validation layers gate those decisions, and approval only generates the exact Wed REST call. The app does not send that call to the Wed backend. The deterministic planner keeps demos and tests reliable when no Claude key is configured.

docs/setup.md

@@ -0,0 +1,67 @@
+# Setup
+
+## Docker
+
+```bash
+docker compose up --build
+```
+
+Open:
+
+- Frontend: http://localhost:5173
+- Backend docs: http://localhost:9000/docs
+
+The backend runs Alembic migrations and sample data seeding before startup.
+
+## Local Backend
+
+```bash
+cd backend
+pip install -e ".[dev]"
+uvicorn app.main:app --reload
+```
+
+## Local Frontend
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Set `ANTHROPIC_API_KEY` to use the Claude planner. Leave it empty to use the deterministic planner.
+
+```bash
+export ANTHROPIC_API_KEY="your_claude_key_here"
+export ANTHROPIC_MODEL="claude-3-5-sonnet-latest"
+docker compose up --build
+```
+
+## Real Wed Backend API
+
+The orchestrator generates tools from the Wed backend contract found in:
+
+```text
+/Volumes/Corsair/Wed/wed-backend
+```
+
+Approved actions generate a Wed API call description, including method, URL, headers, JSON body, and cURL. The orchestrator does not send the request.
+
+```bash
+export WED_API_BASE_URL="http://host.docker.internal:8000"
+export WED_DEFAULT_PARTNER_ID="partner_uuid_for_reservation_requests"
+export SONIOX_API_KEY="your_soniox_api_key"
+docker compose up -d --build
+```
+
+`WED_DEFAULT_PARTNER_ID` is only required for transcript phrases that create guest reservation requests.
+
+## Microphone Transcription
+
+The dashboard records microphone audio locally with the browser `MediaRecorder` API. Stopping the recording uploads the audio to:
+
+```text
+POST /transcriptions
+```
+
+The backend sends the audio to Soniox using `SONIOX_API_KEY`, polls until transcription completes, groups speaker-labeled segments, and ingests each segment through the orchestrator. The resulting pending actions still only generate API calls; they do not execute them.