61 lines
4.1 KiB
Markdown
61 lines
4.1 KiB
Markdown
# Implementation Plan: Gradio Agent Chat (LangGraph)
|
||
|
||
**Branch**: `033-gradio-agent-chat` | **Date**: 2026-06-08 | **Updated**: 2026-06-30 | **Spec**: `spec.md`
|
||
|
||
## Summary
|
||
|
||
Gradio agent backend + Svelte frontend via `@gradio/client submit()`. LangGraph `create_react_agent()` + static `interrupt_before` + `PostgresSaver`. Hybrid keyword+embedding tool router (keyword primary <1ms, embedding fallback 5-20ms). Negation guard for fast-track HITL. Smart dashboard prefetch trigger. Structured JSON metadata streaming. No REST confirmations, no custom WebSocket, no deprecated assistant tool registry for agent runtime.
|
||
|
||
## Current Implementation Snapshot (2026-06-30)
|
||
|
||
- `/agent` works through SvelteKit `AgentChat.svelte` and `AgentChatModel.svelte.ts`, connecting with `@gradio/client` to `${window.location.origin}/api/agent/gradio`.
|
||
- `DEV_MODE=true ./run.sh` wires `BACKEND_URL`, `GRADIO_URL`, and `GRADIO_SERVER_PORT`; `backend/src/agent/run.py` allows port fallback only with `GRADIO_ALLOW_PORT_FALLBACK=true`.
|
||
- `backend/src/agent/tools.py` contains **24** native LangChain `@tool` functions and `get_tools_for_query()` for hybrid intent-based subset selection.
|
||
- `backend/src/agent/_embedding_router.py` provides embedding-based tool similarity fallback (cosine similarity via `paraphrase-multilingual-MiniLM-L12-v2`).
|
||
- `fast_confirmation_tool()` includes negation guard (`\bне\b`, `\bno\b`) to bypass fast-track for negated requests.
|
||
- Dashboard prefetch uses intent-aware trigger (excludes creation/diagnostic patterns).
|
||
- `run_llm_validation` uses `/api/validation-tasks`; Git, maintenance, migration, backup, and documentation tools call their existing FastAPI REST endpoints with dual identity headers.
|
||
- HITL resume path recreates the agent with `interrupt_before=[]`, preventing repeated guardrail cards after confirm.
|
||
- `/agent` exposes debug info: `conv_id`, pending `thread_id`, connection/streaming state, env/user, message count, last message id, active tool calls, and error.
|
||
- Verified: backend agent tests `375 passed`; frontend `AgentChatModel.test.ts` `73 passed`; frontend build passed.
|
||
|
||
## Technical Context
|
||
|
||
**Language**: Python 3.9+/TypeScript Svelte 5 runes
|
||
**Key Dependencies**: gradio>=5.0, langgraph>=0.2, langchain-core>=0.3, langchain-openai>=0.3, langgraph-checkpoint-postgres, pdfplumber, openpyxl (back); @gradio/client (front)
|
||
**Storage**: PostgreSQL 16 (persistence + checkpoints via langgraph-checkpoint-postgres)
|
||
**Testing**: pytest (back), vitest L1 model + L2 UX (front)
|
||
**Frontend**: SvelteKit SPA, model-first (AgentChatModel.svelte.ts C4), runes-only
|
||
**Performance**: First token <1.5s, streaming 60fps, file upload ≤10MB
|
||
|
||
## Constitution Check — Passed
|
||
|
||
All 8 principles satisfied: semantic contracts, decision memory, external orchestrator, module discipline, RBAC, Svelte 5 runes, test-driven C3+, attention-optimized.
|
||
|
||
## Project Structure
|
||
|
||
### New/Changed Files
|
||
```
|
||
backend/src/agent/ — app.py, langgraph_setup.py, tools.py, _embedding_router.py, middleware.py, document_parser.py
|
||
backend/src/api/routes/ — agent_conversations.py, auth.py
|
||
backend/src/models/ — agent.py
|
||
backend/src/schemas/ — agent.py
|
||
frontend/src/lib/models/ — AgentChatModel.svelte.ts (rewritten)
|
||
frontend/src/lib/components/agent/ — AgentChat.svelte
|
||
frontend/src/lib/components/assistant/ — ConversationList, ToolCallCard, ConfirmationCard, ConnectionIndicator
|
||
frontend/src/routes/agent/ — +page.svelte
|
||
frontend/src/types/ — agent.ts
|
||
docker/ — Dockerfile.agent, docker-compose.yml updated, nginx.conf updated
|
||
```
|
||
|
||
## Deprecated
|
||
`backend/src/api/routes/assistant/_tool_registry.py` → `@DEPRECATED` Tombstone (FR-022).
|
||
|
||
## Runtime Context-Budget Rule
|
||
|
||
The runtime MUST use the hybrid router: keyword primary + embedding fallback.
|
||
Tool subset is 5-10 tools (50-75% token reduction vs full 24-tool catalog).
|
||
Embedding model (`paraphrase-multilingual-MiniLM-L12-v2`) lazy-loaded on first fallback call; graceful degradation to keyword-only if `sentence-transformers` unavailable.
|
||
Dashboard-prefetched requests MUST avoid adding `search_dashboards` to the tool schema (prefetch data already in context).
|
||
#endregion (plan summary)
|