39 lines
4.8 KiB
Markdown
39 lines
4.8 KiB
Markdown
#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. |
|
|
| 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`. |
|
|
| 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. 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, debug/reference block. |
|
|
| AgentChat.Page | C3 | `frontend/src/routes/agent/+page.svelte` | Full-page route hosting current `AgentChat.svelte`. |
|
|
| 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
|