ss-tools/specs/033-gradio-agent-chat/contracts/modules.md

#region AgentChat.Contracts [C:4] [TYPE ADR] [SEMANTICS contracts,modules,agent-chat,langgraph,final] @BRIEF Final module contracts — LangGraph create_react_agent(), native LangChain @tool, static interrupt_before HITL, PostgresSaver, structured JSON metadata, dual-identity RBAC, compact per-turn tool subsets.

Backend

Contract	C	File	Notes
AgentChat.GradioApp	C4	backend/src/agent/app.py	gr.ChatInterface(type="messages", multimodal=True, additional_inputs=[gr.Textbox("conversation_id"), gr.Textbox("action")], examples=[["Покажи дашборды",null,null],["Статус системы",null,null]]). Handler: def handler(message, history, request: gr.Request, conversation_id=None, action=None). Per-user lock via in-memory dict (no global concurrency_limit — Gradio handles concurrent users by default).
AgentChat.GradioApp.Handler	C4	↑	Creates create_react_agent() with PostgresSaver and a compact tool subset. astream_events(config={"configurable":{"thread_id":conversation_id}}). Resume: detects action="confirm"/"deny" in additional_inputs, loads checkpoint, recreates graph with interrupt_before=[] to avoid repeated pause, and continues the checkpoint stream. Injects hidden runtime context into LLM-facing message while saving clean visible user text.
AgentChat.LangGraph.Setup	C4	backend/src/agent/langgraph_setup.py	create_react_agent(model, tools=<subset>, checkpointer=PostgresSaver(conn_string), interrupt_before=<dangerous tools or []>). No RunnableWithMessageHistory; history/checkpoint continuity is keyed by thread_id=conversation_id. System prompt includes maintenance relative-time rules using runtime context.
AgentChat.Tools	C4	backend/src/agent/tools.py	24 native @tool functions. Each: Pydantic BaseModel args_schema, calls FastAPI REST with dual-identity headers. Includes hybrid get_tools_for_query() — keyword primary + embedding fallback for context-budgeted subset selection.
AgentChat.EmbeddingRouter	C3	backend/src/agent/_embedding_router.py	Lazy-loaded paraphrase-multilingual-MiniLM-L12-v2. Tool description corpus (RU+EN). embedding_top_k(query) → top-K tool names above cosine threshold. Graceful degradation to empty list if model unavailable.
AgentChat.Middleware	C3	backend/src/agent/middleware.py	LoggingMiddleware only (audit trail).
AgentChat.Document.Parser	C3	backend/src/agent/document_parser.py	pdfplumber (PDF) + openpyxl (XLSX).
AgentChat.Api.Conversations	C3	backend/src/api/routes/agent_conversations.py	CRUD (list, history, create, archive) + multi-tab gate GET .../conversations/{id}/active.
AgentChat.Api.ServiceToken	C3	backend/src/api/routes/auth.py	POST /api/auth/service-token — returns service JWT (role agent).
Models.Agent	C2	backend/src/models/agent.py	AgentConversation, AgentMessage.
Schemas.Agent	C1	backend/src/schemas/agent.py	Pydantic: ConversationItem, ConversationListResponse, MessageItem, HistoryResponse, DeleteResponse.

Frontend

Contract	C	File	Notes
AgentChat.Model	C4	frontend/src/lib/models/AgentChatModel.svelte.ts	submit("/chat", {text,files}, [conversationId, action]) lifecycle. Structured ChatMessage.metadata parsing. HITL resume via second submit with additional_inputs[1]="confirm"/"deny" and immediate streaming state. Owns first-activity timeout, recovery actions, visible-text cleaning, process-step derivation. No tabRole, no follower.
AgentChat.Panel	C4	frontend/src/lib/components/agent/AgentChat.svelte	Client.connect("${window.location.origin}/api/agent/gradio"), submit(), metadata-based rendering of tool cards + confirmation cards, operator process strip, diagnostics menu, recovery card.
AgentChat.Page	C3	frontend/src/routes/agent/+page.svelte	Full-page route hosting current AgentChat.svelte; syncs auth and selected environment before sends.
AgentChat.ConversationList	C3	frontend/src/lib/components/assistant/ConversationList.svelte	Search, infinite scroll, date grouping, archive action.
AgentChat.ToolCallCard	C2	frontend/src/lib/components/assistant/ToolCallCard.svelte	Props from metadata.type="tool_start"/"tool_end"/"tool_error".
AgentChat.ConfirmationCard	C3	frontend/src/lib/components/assistant/ConfirmationCard.svelte	Renders on metadata.type="confirm_required". Calls second submit() with additional_inputs=[conversation_id, "confirm"/"deny"].

Contracts Removed (vs prior versions)

• AgentChat.LangChain.Setup → renamed to AgentChat.LangGraph.Setup
• HumanInTheLoopMiddleware → replaced by interrupt_before=DANGEROUS_TOOLS (LangGraph native)
• __resume__ field → replaced by additional_inputs[1]="confirm"/"deny"
• Pure substring get_tools_for_query() → replaced by hybrid keyword+embedding router with word-boundary guards
• RunnableWithMessageHistory requirement → replaced by explicit persisted conversation records plus LangGraph checkpoints keyed by thread_id

#endregion AgentChat.Contracts