ss-tools/specs/033-gradio-agent-chat/plan.md

Implementation Plan: Gradio Agent Chat (LangGraph)

Branch: 033-gradio-agent-chat | Date: 2026-06-08 | Updated: 2026-07-03 | 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. Hidden runtime context for operational prompts. Structured JSON metadata streaming. Operator recovery for silent streams. No REST confirmations, no custom WebSocket, no deprecated assistant tool registry for agent runtime.

Current Implementation Snapshot (2026-07-03)

• /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).
• Agent handler injects hidden runtime context (current datetime, selected environment, relative-time rules, bounded dashboard prefetch) into the LLM-facing message while saving clean visible user text.
• 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 synchronizes selected environment before each send and exposes operator process strip, diagnostics menu, debug JSON copy, first-activity timeout, visible-text cleaning, and recovery card.
• Verified: backend hidden-context regression passed; frontend AgentChatModel.test.ts 88 passed; frontend build passed with existing unrelated Svelte warnings.

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).

Operator UX Recovery Rule

The UI MUST not display endless "thinking" when the upstream stream has no first observable event. AgentChatModel races stream processing with a 60s first-activity timeout. If no token, tool call, confirmation/checkpoint, or pending thread id arrives, it transitions to an actionable recovery state. The recovery card provides retry of the last clean user request, LLM status check, debug JSON copy, and new-dialog escape. #endregion (plan summary)