docs: reconcile README and docs with actual codebase

README: - Remove duplicated agent config, safety, security sections (covered by docs) - Add ux_design_system.md and safety.py to project structure and doc links - Convert doc links to descriptive table agent-config-guide.md: - Replace fictional agents/tools with real ones from agents.yaml - Remove nonexistent 'admin' permission level (only read/write) - Fix template names (e-commerce, saas, fintech) - List all available built-in tools openapi-import-guide.md: - Fix /result -> /classifications endpoint - Fix POST /approve to show no request body - Remove nonexistent 'admin' access type - Update response examples to match actual API demo-script.md: - Fix agent names (order_agent -> order_lookup) - Replace fictional refund scenario with real lookup+cancel flow ARCHITECTURE.md: - Fix langgraph-supervisor version (v1.1 -> 0.0.12+) docker-compose.yml: - Expose postgres on port 5433 for local dev
2026-04-06 13:55:45 +02:00
parent 19fc9f3289
commit be5c84bcff
6 changed files with 142 additions and 131 deletions
--- a/README.md
+++ b/README.md
@@ -45,10 +45,11 @@ User message -> Chat UI -> FastAPI WebSocket -> LangGraph Supervisor -> Speciali
 | Component | Technology |
 |-----------|-----------|
 | Backend | Python 3.11+, FastAPI |
-| Agent orchestration | LangGraph v1.1 |
-| Session state | PostgreSQL + langgraph-checkpoint-postgres |
-| LLM | Claude Sonnet 4.6 (configurable: OpenAI, Google) |
+| Agent orchestration | LangGraph 0.4+, langgraph-supervisor |
+| Session state | PostgreSQL 16 + langgraph-checkpoint-postgres |
+| LLM | Claude Sonnet 4.6 (configurable: OpenAI, Azure OpenAI, Google) |
 | Frontend | React 19, TypeScript, Vite |
+| Testing | pytest (backend), vitest + happy-dom (frontend) |
 | Deployment | Docker Compose |

 ## Quick Start
@@ -59,7 +60,11 @@ cd smart-support

 # Configure your LLM API key
 cp .env.example .env
-# Edit .env: set ANTHROPIC_API_KEY (or OPENAI_API_KEY)
+# Edit .env: set LLM_PROVIDER and the corresponding API key
+#   anthropic    -> ANTHROPIC_API_KEY
+#   openai       -> OPENAI_API_KEY
+#   azure_openai -> AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT + AZURE_OPENAI_DEPLOYMENT
+#   google       -> GOOGLE_API_KEY

 # Start all services
 docker compose up -d
@@ -68,6 +73,25 @@ docker compose up -d
 open http://localhost
 ```

+### Local Development
+
+```bash
+# Start only PostgreSQL via Docker (exposed on port 5433)
+docker compose up postgres -d
+
+# Backend (in one terminal)
+cd backend
+pip install -e ".[dev]"
+uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload
+
+# Frontend (in another terminal)
+cd frontend
+npm install
+npm run dev    # http://localhost:5173 (proxies /api and /ws to :8001)
+```
+
+See [Deployment Guide](docs/deployment.md) for production setup, HTTPS, and scaling.
+
 ## Project Structure

 ```
@@ -77,15 +101,14 @@ smart-support/
 │   │   ├── main.py              # FastAPI + WebSocket entry point
 │   │   ├── graph.py             # LangGraph Supervisor
 │   │   ├── ws_handler.py        # WebSocket message dispatch + rate limiting
-│   │   ├── conversation_tracker.py  # Conversation lifecycle tracking
+│   │   ├── safety.py            # Confirmation rules + MCP error taxonomy
 │   │   ├── agents/              # Agent definitions and tools
 │   │   ├── registry.py          # YAML agent registry loader
-│   │   ├── openapi/             # OpenAPI parser and review API
+│   │   ├── openapi/             # OpenAPI parser, classifier, and review API
 │   │   ├── replay/              # Conversation replay API
-│   │   ├── analytics/           # Analytics queries and API
-│   │   └── tools/               # Error handling and retry utilities
+│   │   └── analytics/           # Analytics queries and API
 │   ├── agents.yaml              # Agent registry configuration
-│   ├── fixtures/                # Demo data and sample OpenAPI spec
+│   ├── templates/               # Vertical industry templates
 │   └── tests/                   # Unit, integration, and E2E tests
 ├── frontend/
 │   ├── src/
@@ -99,29 +122,6 @@ smart-support/
 └── .env.example                 # Environment variable template
 ```

-## Agent Configuration
-
-```yaml
-# agents.yaml
-agents:
-  - name: order_agent
-    description: "Handles order status, tracking, and cancellations."
-    permission: write
-    tools:
-      - get_order_status
-      - cancel_order
-    personality:
-      tone: friendly
-      greeting: "I can help with your order. What is the order number?"
-      escalation_message: "I'm escalating this to a human agent."
-
-  - name: general_agent
-    description: "Answers general questions and FAQs."
-    permission: read
-    tools:
-      - search_faq
-```
-
 ## API Endpoints

 | Method | Path | Description |
@@ -137,42 +137,31 @@ agents:
 | PUT | `/api/openapi/jobs/{id}/classifications/{idx}` | Update a classification |
 | POST | `/api/openapi/jobs/{id}/approve` | Approve and generate tools |

-## Safety and Confirmation Rules
-
-Destructive-action confirmation is explicit and auditable (see `backend/app/safety.py`):
-
- **Read actions** execute immediately -- no confirmation required.
- **Write actions** require human-in-the-loop approval via an interrupt gate.
- **OpenAPI-imported endpoints** use the `needs_interrupt` classification flag.
- **Multi-intent handling** is sequential: if a write action is blocked by an interrupt, subsequent actions are paused until the interrupt is resolved or rejected.
- **MCP errors** are classified into `transient` (retryable, up to 3 attempts), `validation` (not retryable), `auth` (not retryable, escalate), and `unknown` (not retryable, log and escalate).
-
-## Security
-
- **SSRF protection** -- OpenAPI import blocks private IPs and metadata service URLs
- **Input validation** -- messages validated for size (32 KB), content length (10 KB), thread ID format
- **Rate limiting** -- 10 messages per 10 seconds per session
- **Audit trail** -- every tool call logged with agent, params, result, timestamp
- **Permission isolation** -- each agent only accesses its configured tools
- **Interrupt TTL** -- unanswered approval prompts expire after 30 minutes
-
 ## Running Tests

 ```bash
+# Backend (516 tests, 94% coverage)
 cd backend
 pytest --cov=app --cov-report=term-missing
+
+# Frontend (23 tests, vitest + happy-dom)
+cd frontend
+npm test
 ```

-Coverage is enforced at 80%+.
+Backend coverage is enforced at 80%+.

 ## Documentation

- [Architecture](docs/ARCHITECTURE.md) -- System design and component diagram
- [Development Plan](docs/DEVELOPMENT-PLAN.md) -- Phase breakdown and status
- [Agent Config Guide](docs/agent-config-guide.md) -- How to configure agents
- [OpenAPI Import Guide](docs/openapi-import-guide.md) -- Auto-discovery workflow
- [Deployment Guide](docs/deployment.md) -- Docker and production deployment
- [Demo Script](docs/demo-script.md) -- Step-by-step live demo walkthrough
+| Document | Description |
+|----------|-------------|
+| [Architecture](docs/ARCHITECTURE.md) | System design, component diagram, data flow, ADRs |
+| [Development Plan](docs/DEVELOPMENT-PLAN.md) | Phase breakdown, task checklists, and status |
+| [Agent Config Guide](docs/agent-config-guide.md) | agents.yaml format, fields, templates, routing logic |
+| [OpenAPI Import Guide](docs/openapi-import-guide.md) | Auto-discovery workflow, REST API, SSRF protection |
+| [Deployment Guide](docs/deployment.md) | Docker, local dev, production, HTTPS, backups, scaling |
+| [Demo Script](docs/demo-script.md) | Step-by-step live demo walkthrough (5 scenes) |
+| [UX Design System](docs/ux_design_system.md) | Color palette, typography, component patterns, CSS tokens |

 ## License