Implementation Plan: Gradio Agent Chat (LangChain v1 Native Stack)

Branch: 033-gradio-agent-chat | Date: 2026-06-08 | Spec: spec.md

Summary

Integrate Gradio as agent backend, Svelte frontend via @gradio/client submit(). LangGraph agent: create_react_agent() + @tool + interrupt()/Command(resume=...) + RunnableWithMessageHistory + PostgresSaver. Structured JSON metadata streaming. No REST confirmations, no custom WebSocket.

Technical Context

Language: Python 3.9+/TypeScript Svelte 5 runes
Key Dependencies: Gradio≥5.0, LangChain≥1.0, langchain-openai≥1.0, langgraph-checkpoint, 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
Target: Linux/Docker, modern browsers
Performance: First token <1.5s, streaming 60fps, file upload ≤10MB

Constitution Check — All 8 Principles Passed

Principle	Compliance
I. Semantic Contract First	All 18 contracts use #region/#endregion, hierarchical IDs, C1-C4 tiers
II. Decision Memory	@RATIONALE/@REJECTED on all 8 research decisions; T030 deprecates @assistant_tool
III. External Orchestrator	Gradio agent calls FastAPI services; no Superset plugin coupling
IV. Module Discipline	All modules <400 lines; model ~220 lines
V. RBAC	User JWT forwarded to each tool call (closure factory); permission checks in FastAPI
VI. Svelte 5 Runes	$state/$derived only; no legacy syntax
VII. Test-Driven C3+	@TEST_EDGE on all C3+ contracts; 10 test tasks
VIII. Attention-Optimized	ATTN_1-4 validated; one-line anchors, hierarchical IDs, shared @SEMANTICS, ≤150 lines

Project Structure

New/Changed Files

backend/src/agent/
├── app.py              # gr.ChatInterface + handler + resume protocol
├── langchain_setup.py  # create_agent() + middleware + checkpointer
├── tools.py            # @tool functions → FastAPI REST
├── middleware.py        # LoggingMiddleware, risk config
├── document_parser.py  # PDF + XLSX parsing
└── run.py              # entrypoint

backend/src/api/routes/
├── agent_conversations.py  # CRUD + multi-tab gate
└── auth.py                 # POST /api/auth/service-token

backend/src/models/agent.py     # AgentConversation, AgentMessage
backend/src/schemas/agent.py    # Pydantic schemas

frontend/src/lib/models/AgentChatModel.svelte.ts  # submit() lifecycle
frontend/src/lib/components/assistant/
├── AssistantChatPanel.svelte  # adapted for @gradio/client submit()
├── ConversationList.svelte    # new
├── ToolCallCard.svelte        # new
├── ConfirmationCard.svelte    # new
└── ConnectionIndicator.svelte # new
frontend/src/routes/agent/+page.svelte  # new
frontend/src/types/agent.ts             # TypeScript DTOs

docker/Dockerfile.agent     # new
docker/docker-compose.yml   # updated
docker/nginx.conf           # updated: proxy /api/agent/gradio

Deprecated

backend/src/api/routes/assistant/_tool_registry.py + _tool_*.py → @DEPRECATED Tombstone. Old @assistant_tool registry preserved for FR-020.

#endregion (plan.md)

3.3 KiB Raw Blame History