220 lines
20 KiB
Markdown
220 lines
20 KiB
Markdown
#region AgentChat.Spec [C:3] [TYPE ADR] [SEMANTICS spec,requirements,agent-chat,gradio,langgraph]
|
||
@BRIEF Feature specification — Gradio `submit()` + LangGraph agent with native LangChain tools, static `interrupt_before` HITL, PostgresSaver checkpoints, hybrid keyword+embedding tool router. No custom WebSocket, no REST confirmations, no @assistant_tool for new agent code.
|
||
@RATIONALE LangGraph chosen over LangChain AgentExecutor: static `interrupt_before` + checkpointed resume are native HITL features, `PostgresSaver` is LangGraph-native checkpointer, `create_react_agent` from `langgraph.prebuilt` provides standard tool-calling. Gradio `submit()` for streaming, nginx/Vite reverse proxy for browser access.
|
||
@REJECTED Replacing Svelte frontend with Gradio UI — violates ADR-0006.
|
||
@REJECTED Custom SSE/WebSocket — @gradio/client `submit()` is the native transport.
|
||
@REJECTED Custom bidirectional WebSocket — @gradio/client is request/job-oriented, not raw WS.
|
||
@REJECTED REST confirmation endpoints — LangGraph `interrupt()` eliminates them.
|
||
@REJECTED @assistant_tool for new tools — native LangChain `@tool` is SSOT. Old registry → @DEPRECATED for FR-020.
|
||
|
||
**Feature Branch**: `033-gradio-agent-chat`
|
||
**Created**: 2026-06-08 | **Status**: Implemented fact snapshot | **Last revised**: 2026-06-30 (hybrid router, negation guard, embedding fallback)
|
||
|
||
## Current Implementation Facts (2026-06-30)
|
||
|
||
- `/agent` is served by SvelteKit `AgentChat.svelte` + `AgentChatModel.svelte.ts`; the browser connects through `@gradio/client` to absolute `${window.location.origin}/api/agent/gradio`.
|
||
- `DEV_MODE=true ./run.sh` starts FastAPI, frontend, and Gradio with explicit `BACKEND_URL`, `GRADIO_URL`, `GRADIO_SERVER_PORT`; Gradio no longer silently falls back to a random port unless `GRADIO_ALLOW_PORT_FALLBACK=true`.
|
||
- `backend/src/agent/tools.py` is the agent tool SSOT. It exposes 24 native LangChain `@tool` functions: `show_capabilities`, `search_dashboards`, `get_health_summary`, `list_environments`, `get_task_status`, `list_llm_providers`, `get_llm_status`, `create_branch`, `commit_changes`, `deploy_dashboard`, `execute_migration`, `run_backup`, `run_llm_validation`, `run_llm_documentation`, `list_maintenance_events`, `start_maintenance`, `end_maintenance`, `superset_execute_sql`, `superset_explore_database`, `superset_audit_permissions`, `superset_create_dashboard`, `superset_copy_dashboard`, `superset_create_dataset`, `superset_format_sql`.
|
||
- Deprecated `backend/src/api/routes/assistant/_tool_registry.py` is legacy only and MUST NOT be used by the agent runtime.
|
||
- **Hybrid tool router** (`get_tools_for_query()`): keyword primary (word-boundary-aware, <1ms) with embedding fallback (cosine similarity via `paraphrase-multilingual-MiniLM-L12-v2`, 5-20ms) when keyword matching yields <3 tools. Eliminates substring collision bugs (tool⊂tools, env⊂environment, доступ⊂доступные). Tool subset is 5-10 tools (50-75% token reduction vs full 24-tool catalog).
|
||
- **Negation guard** in `fast_confirmation_tool()`: regex pre-check for negation patterns (`\bне\b`, `\bno\b`, `\bdon't\b`) bypasses fast-track and routes to LLM. Prevents false-positive confirmations for negated requests like "не показывай схему".
|
||
- **Smart prefetch trigger**: dashboard prefetch fires only for search/list intent, excludes creation/diagnostic patterns (`как создать`, `почему`, `speed`, `performance`). Capped by `AGENT_PREFETCH_DASHBOARD_LIMIT` (default `25`).
|
||
- HITL guardrails use LangGraph `interrupt_before` for dangerous tools. Resume creates the agent with `interrupt_before=[]` so the confirmed checkpoint does not pause again before the same tool.
|
||
- The `/agent` header includes a collapsible debug/reference block with `conv_id`, pending `thread_id`, connection state, streaming state, env/user, message count, last message id, active tool-call count, and current error.
|
||
- Current verification: backend agent tests `375 passed`; frontend `AgentChatModel.test.ts` `73 passed`; frontend build passed with existing unrelated Svelte warnings.
|
||
|
||
## Architecture Overview
|
||
|
||
```
|
||
Browser (SvelteKit) Docker
|
||
┌──────────────────────┐ nginx ┌──────────────────────┐
|
||
│ @gradio/client │──→ /api/agent/gradio─→│ Gradio Agent :7860 │
|
||
│ submit("/chat", │ proxy+JWT │ gr.ChatInterface │
|
||
│ {message}, │ │ │
|
||
│ conversation_id) │ │ ┌─────────────────┐ │
|
||
│ for await(event) {} │ │ │ Hybrid Router │ │
|
||
│ submission.cancel() │ │ │ keyword primary │ │
|
||
│ │ │ │ ↓ <3 tools? │ │
|
||
│ REST /api/assistant/*│ │ │ embedding fallbk│ │
|
||
└──────────────────────┘ │ └─────────────────┘ │
|
||
│ create_agent(model, │
|
||
│ tools=subset, │
|
||
│ interrupt_before, │
|
||
│ checkpointer=PG) │
|
||
└──────────┬──────────┘
|
||
│ HTTP
|
||
┌──────────▼──────────┐
|
||
│ FastAPI :8000 │
|
||
│ PostgreSQL │
|
||
│ /api/assistant (leg.)│
|
||
│ /api/auth/svc-token │
|
||
└─────────────────────┘
|
||
```
|
||
|
||
## User Stories
|
||
|
||
### Story 1 — Gradio Agent Engine with Streaming Chat (P1) 🎯
|
||
|
||
**Independent Test**: `Client.connect("/api/agent/gradio")`, `submit("/chat", {message}, conversation_id)`, verify tokens stream via `for await (event)`.
|
||
|
||
**Acceptance**:
|
||
1. **Given** Gradio running, **When** Svelte calls `submit()`, **Then** tokens stream in real time via `event.data` chunks.
|
||
2. **Given** streaming in progress, **When** user calls `submission.cancel()`, **Then** generation stops, partial text preserved.
|
||
|
||
### Story 2 — Autonomous Tool Selection (P1) 🎯
|
||
|
||
**Independent Test**: "покажи дашборды с проблемами валидации" → agent calls search + health tools.
|
||
|
||
**Acceptance**:
|
||
1. **Given** user query, **When** agent processes it, **Then** agent selects and invokes `@tool` functions from `backend/src/agent/tools.py`.
|
||
2. **Given** tool requires confirmation, **When** agent calls it, **Then** LangGraph `interrupt_before` pauses execution, UI shows confirmation card.
|
||
3. **Given** tool fails, **When** error returned, **Then** agent explains failure and suggests recovery.
|
||
|
||
### Story 3 — Tool-Call Visibility (P2)
|
||
|
||
**Independent Test**: Send multi-tool query, verify each tool appears as inline card with spinner → checkmark/cross transition.
|
||
|
||
**Acceptance**:
|
||
1. **Given** agent triggers a tool, **When** `metadata.type="tool_start"` received, **Then** UI shows card with tool name (mono font) and spinner.
|
||
2. **Given** tool completes, **When** `metadata.type="tool_end"` received, **Then** spinner becomes green checkmark, result expandable on click.
|
||
3. **Given** tool fails, **When** `metadata.type="tool_error"` received, **Then** spinner becomes red cross with error detail expandable on click.
|
||
|
||
### Story 4 — Multi-Turn Context (P2)
|
||
|
||
**Independent Test**: Ask "покажи дашборд 42", then "создай для него ветку". Agent resolves "него" → dashboard 42.
|
||
|
||
**Acceptance**:
|
||
1. **Given** prior messages in conversation, **When** user uses pronouns/implicit references, **Then** agent resolves them via PostgreSQL conversation persistence and LangGraph checkpoint context.
|
||
2. **Given** conversation exceeds 4000 tokens, **When** new message sent, **Then** older messages are summarized/truncated before being passed to LLM.
|
||
3. **Given** user starts new conversation, **When** referencing entities from prior conversation, **Then** agent does NOT have access to prior context (clean isolation).
|
||
|
||
### Story 5 — Conversation Persistence (P3)
|
||
|
||
**Independent Test**: Create 3 conversations, close browser tab, reopen — all 3 visible, resume any.
|
||
|
||
**Acceptance**:
|
||
1. **Given** past conversations exist, **When** user opens chat panel, **Then** conversations listed with auto-titles (truncated first message 60 chars), dates, message counts.
|
||
2. **Given** past conversation selected, **When** user sends new message, **Then** handler uses `conversation_id` / `thread_id` and persisted messages/checkpoints instead of Gradio-provided history.
|
||
3. **Given** conversation archived, **When** user deletes, **Then** `is_archived=true`, removed from active list, visible in archive filter.
|
||
4. **Given** conversation archived, **When** associated checkpoints cleared, **Then** no zombie threads remain in `langgraph-checkpoint-postgres` tables.
|
||
|
||
### Story 6 — File Upload & Document Analysis (P2)
|
||
|
||
**Independent Test**: Upload PDF report, type "выдели риски". Agent extracts text and responds with structured analysis.
|
||
|
||
**Acceptance**:
|
||
1. **Given** user attaches PDF, **When** message sent, **Then** backend extracts text via pdfplumber, injects as system message context.
|
||
2. **Given** user attaches XLSX, **When** message sent, **Then** backend parses sheets via openpyxl, presents structured data to agent.
|
||
3. **Given** user attaches unsupported format (`.exe`, `.zip`), **When** upload attempted, **Then** UI shows validation error with supported format list.
|
||
4. **Given** file exceeds 10MB, **When** upload attempted, **Then** UI rejects with size limit message.
|
||
|
||
### Edge Cases
|
||
- Gradio unreachable → reconnect 5×5s
|
||
- LLM malformed → retry once, then error
|
||
- Message too long → truncate + warn
|
||
- Tool >30s → async, result when ready
|
||
- Multi-tab → REST gate: `GET /api/agent/conversations/{id}/active` rejects second tab
|
||
- Network lost → detect disconnect, offer retry
|
||
|
||
## Functional Requirements
|
||
|
||
### Transport & Core
|
||
- **FR-001**: Gradio `gr.ChatInterface(type="messages", multimodal=True)`. Consumable via `@gradio/client` `submit("/chat", payload)` with `additional_inputs=conversation_id`.
|
||
- **FR-002**: Svelte frontend uses `@gradio/client submit()` exclusively. No `predict()`, no custom WebSocket.
|
||
- **FR-003**: Streaming via LangGraph `agent.astream_events()` → yield → `event.data` chunks. Frontend iterates `for await (event of submission)`.
|
||
|
||
### Agent & Tools
|
||
- **FR-004**: LangGraph `create_react_agent(model, tools, checkpointer=PostgresSaver)` from `langgraph.prebuilt`. `tools` MUST be the intent-scoped subset returned by the hybrid `get_tools_for_query()` — keyword primary (word-boundary-aware, <1ms) with embedding fallback (cosine similarity, 5-20ms) when keyword matching yields <3 tools. Full 24-tool catalog injection is forbidden for models with ≤8k context.
|
||
- **FR-005**: Native `@tool` functions in `backend/src/agent/tools.py`. Each calls FastAPI REST. Old `@assistant_tool` registry → `@DEPRECATED` Tombstone and is not used by the agent runtime.
|
||
- **FR-006**: `@tool` functions use Pydantic `BaseModel` for `args_schema`. Docstring = description. Single source of metadata.
|
||
- **FR-007**: Tools call FastAPI with **dual identity**: service JWT authenticates the agent, user JWT (forwarded from browser via closure) authorizes the operation. RBAC enforced by FastAPI under user identity.
|
||
|
||
### Confirmation (HumanInTheLoop)
|
||
- **FR-008**: LangGraph static `interrupt_before` for dangerous tool nodes (`deploy_dashboard`, `execute_migration`, `commit_changes`, and other configured risky operations). Handled entirely by LangGraph — **zero REST confirmation endpoints**.
|
||
- **FR-009**: Resume mechanism: graph pauses at `interrupt_before` node → primary `submit()` stream yields `metadata.type="confirm_required"` with `thread_id` and terminates. User confirms → second `submit("/chat", msg, additional_inputs=[conversation_id, "confirm"])` → handler loads checkpoint by thread_id and recreates the graph with `interrupt_before=[]` for the resumed run so the same tool is not interrupted again. If checkpoint not found: yield `metadata.type="error" code="CHECKPOINT_EXPIRED"`.
|
||
|
||
### Persistence
|
||
- **FR-010**: Conversation history in PostgreSQL (`agent_conversations`, `agent_messages`). REST: `POST /api/assistant/conversations`, `GET .../conversations`, `GET .../history`, `DELETE .../{id}`.
|
||
- **FR-011**: Soft-delete: `is_archived=true`. Renamed to "Archive" in UX.
|
||
- **FR-012**: LangGraph checkpointer uses **PostgreSQL** (same instance as FastAPI) via `langgraph-checkpoint-postgres`. Survives container restarts. Thread ID = conversation_id.
|
||
- **FR-013**: Svelte passes `conversation_id` via `additional_inputs`. The Gradio handler receives `history` from Gradio's built-in `ChatInterface` (mandatory parameter) but MUST ignore it; persisted history is maintained through `agent_conversations` / `agent_messages`, and LangGraph continuity uses `thread_id=conversation_id`.
|
||
|
||
### UX & Cancel
|
||
- **FR-014**: `submission.cancel()` — native cancel. Partial text preserved.
|
||
- **FR-015**: Per-user lock via in-memory dict in handler prevents concurrent sends within same user session. `GET /api/agent/conversations/{id}/active` as additional gate for multi-tab. Gradio handles concurrent users by default — no global `concurrency_limit` needed.
|
||
- **FR-016**: Tool-call visibility via **structured JSON metadata in `ChatMessage.metadata`**, not emoji string parsing. `{type: "tool_start", tool: "...", input: {...}}`.
|
||
- **FR-017**: Confirmation card renders from `ChatMessage.metadata.confirm_required`.
|
||
|
||
### Auth
|
||
- **FR-018**: Browser → nginx → Gradio. nginx forwards `Authorization` header. Gradio handler extracts via `request: gr.Request.headers`.
|
||
- **FR-019**: Gradio → FastAPI: service JWT from `POST /api/auth/service-token`. Dual identity: service JWT authenticates agent, user JWT authorizes tool calls.
|
||
- **FR-020**: Stateless JWT validation in Gradio using shared `JWT_SECRET`. No DB required for auth.
|
||
|
||
### File Upload
|
||
- **FR-021**: PDF (pdfplumber), XLSX (openpyxl), JSON, CSV, PNG, JPEG. `multimodal=True` handles upload. Parser in `backend/src/agent/document_parser.py`.
|
||
|
||
### Backward Compat
|
||
- **FR-022**: Existing `/api/assistant` REST preserved. Old `@assistant_tool` → `@DEPRECATED` Tombstone.
|
||
- **FR-023**: Existing Svelte UX patterns preserved: drawer/embedded variants, focus-target sync.
|
||
|
||
### Additional
|
||
- **FR-024**: Audit logging via `LoggingMiddleware` — all interactions to `assistant_audit`.
|
||
- **FR-025**: RU/EN i18n keys for all new UI strings.
|
||
|
||
- **FR-026**: Resume `submit()` MUST wait for primary stream cleanup via per-conversation mutex before loading checkpoint. Primary acquires lock on start, releases on stream end. Resume waits for lock release (max 2s timeout).
|
||
|
||
- **FR-027**: Deployment MUST run `PostgresSaver.setup()` on agent container startup to create checkpoint tables (`checkpoints`, `checkpoint_writes`, `checkpoint_migrations`). Managed via startup hook.
|
||
|
||
- **FR-028**: User messages exceeding 100,000 characters (~25k tokens) are truncated to 100,000 characters with `[...truncated]` suffix appended. Truncation occurs at sentence boundary when possible.
|
||
|
||
- **FR-029**: When conversation is archived (soft-deleted), agent MUST clear associated checkpoints from `langgraph-checkpoint-postgres` tables for that `thread_id`.
|
||
|
||
- **FR-030**: Context budget protection: before every agent run, hybrid `get_tools_for_query()` MUST return an intent-scoped subset (5-10 tools, 50-75% token reduction vs full 24-tool catalog). Keyword primary with embedding fallback ensures synonym/typo coverage. Full 24-tool schema injection is forbidden for ≤8k context models.
|
||
|
||
- **FR-031**: Dashboard prefetch MUST be bounded and compact (default cap `AGENT_PREFETCH_DASHBOARD_LIMIT=25`). Prefetch trigger MUST use intent-aware matching — fire for search/list intent, exclude creation/diagnostic patterns (`как создать`, `почему`, `speed`, `performance`). `prefetch_available` flag suppresses `search_dashboards` in the tool schema.
|
||
|
||
- **FR-032**: `/agent` MUST expose operator debug/reference info: `conv_id`, pending `thread_id`, connection/streaming state, env/user, message count, last message id, active tool-call count, and current error. The block must be toggleable and copyable as JSON.
|
||
|
||
- **FR-033**: DEV mode transport MUST be deterministic: frontend connects to the same origin proxy path, `run.sh` exports backend/Gradio URLs, and Gradio port fallback is opt-in only.
|
||
|
||
- **FR-034 — Hybrid Intent Router**: The agent MUST use a two-tier tool selection strategy. Primary: word-boundary-aware keyword matching (regex `\b` guards for `tool`, `env`, `доступ`). `show_capabilities` is always included; no early return blocks other intents. Fallback (triggered when primary <3 tools): embedding-based cosine similarity between user query and tool description vectors via `_embedding_router.py`. Top-K above `EMBEDDING_SIMILARITY_THRESHOLD` (default 0.65) merged with keyword results. Graceful degradation to keyword-only if embedding model unavailable.
|
||
|
||
- **FR-035 — Negation Guard**: `fast_confirmation_tool()` MUST pre-check for negation patterns before inferring tool intent. Regex `\b(?:не|нет|no|don't|do not|stop|отмена|отмени)\b`. If matched, return `None` — bypass fast-track and let LLM handle the negated request.
|
||
|
||
- **FR-036 — Embedding Router Infrastructure**: `backend/src/agent/_embedding_router.py` MUST provide: (a) tool description corpus (RU+EN, 1-3 sentences per tool) for embedding; (b) lazy-loaded `paraphrase-multilingual-MiniLM-L12-v2` model (configurable via `EMBEDDING_MODEL` env var); (c) pre-embedded tool descriptions at load time; (d) `embedding_top_k(query)` returning tool names above cosine threshold. Fails gracefully (returns `[]`) when `sentence-transformers` unavailable.
|
||
|
||
## Success Criteria
|
||
|
||
- **SC-001**: Tool selection ≥92% accuracy (keyword 85% + embedding fallback covers synonym/typo remainder)
|
||
- **SC-002**: First token <1.5s
|
||
- **SC-003**: Dangerous ops 100% confirmation
|
||
- **SC-004**: RBAC bypass 0%
|
||
- **SC-005**: History survives restart
|
||
- **SC-006**: Multi-step ≥30% faster than manual UI
|
||
- **SC-007**: File upload ≤10MB, no degradation
|
||
- **SC-008**: Hybrid router ensures 50-75% token reduction (5-10 tools vs 24 full catalog). Embedding model lazy-loaded on first fallback call (cold-start ~2s), subsequent calls 5-20ms.
|
||
|
||
## Dependencies
|
||
|
||
- `langgraph>=0.2`, `langchain-core>=0.3`, `langchain-openai>=0.3`, `langgraph-checkpoint-postgres` (NEW — replaces sqlite)
|
||
- `gradio>=5.0`, `pdfplumber`, `openpyxl`
|
||
- `sentence-transformers>=3.0` (NEW — embedding fallback for hybrid router; graceful degradation if unavailable)
|
||
- `@gradio/client` npm
|
||
- Docker: new `superset-tools-agent` container, nginx proxy `/api/agent/gradio`
|
||
- Deprecated: `backend/src/api/routes/assistant/_tool_registry.py` → Tombstone
|
||
|
||
## @{ AgentChat.ADR.HybridRouter [C:4] [TYPE ADR]
|
||
@BRIEF Hybrid keyword+embedding tool router replaces pure substring matching.
|
||
@RATIONALE Pure substring matching caused P0 (tool⊂tools blocks all tools) and
|
||
cannot handle synonyms ("панели"≠"дашборды") or typos ("дашборд").
|
||
Full 24-tool catalog causes "Tool Paralysis" in models <27B params.
|
||
Embedding-only breaks on negations ("не делай бэкап" ≈ "сделай бэкап").
|
||
Hybrid: keyword for speed+determinism+negation, embedding for synonyms+typos.
|
||
@REJECTED Full catalog (all 24 tools) — causes Tool Paralysis in Gemma.
|
||
@REJECTED Embedding-only — blind to negations, adds 5-20ms to every request.
|
||
@REJECTED Pure substring (with fixes) — cannot handle synonyms or typos.
|
||
@LAYER Agent Service
|
||
## @} AgentChat.ADR.HybridRouter
|
||
|
||
#endregion AgentChat.Spec
|