72 lines
7.1 KiB
Markdown
72 lines
7.1 KiB
Markdown
#region Traceability [C:3] [TYPE ADR] [SEMANTICS traceability,rtm,agent-chat]
|
|
@defgroup Trace Matrix Requirements → Model → API → Fixture → Task → Test for Gradio Agent Chat.
|
|
|
|
## Traceability Matrix
|
|
|
|
| Story | Screen | Model | Fixture | API Endpoint | Backend Task | Frontend Task | Test |
|
|
|-------|--------|-------|---------|-------------|:-----------:|:------------:|------|
|
|
| **US1**: Streaming Chat | AssistantChatPanel | AgentChat.Model | FX_AgentChat.Model.SendMessage.Valid | `submit("/chat")` | T015, T017 | T018, T019 | Test.AgentChat.Model |
|
|
| **US1**: Cancel | AssistantChatPanel | AgentChat.Model | FX_AgentChat.Model.CancelGeneration | `submission.cancel()` | — | T020 | Test.AgentChat.Model |
|
|
| **US1**: Reconnect | AssistantChatPanel | AgentChat.Model | — | `Client.connect()` | — | T022 | Test.AgentChat.Model |
|
|
| **US2**: Tool Selection | `/agent` | AgentChat.Tools | — | FastAPI REST via native `@tool` | T026, T028, T097 | T031 | Test.AgentChat.Tools |
|
|
| **US2**: Tool Context Budget | `/agent` | AgentChat.Tools | — | Hybrid `get_tools_for_query()` before `create_agent()` | T098, T099, T105 | — | Test.AgentChat.Tools, Test.IntentKeyword.Edges |
|
|
| **US2**: HITL Confirm | `/agent` | AgentChat.Model | FX_AgentChat.Model.ResumeConfirm | `submit("/chat",...,[convId,"confirm"])` | T029, T100 | T031 | Test.AgentChat.Model |
|
|
| **US2**: HITL Deny | `/agent` | AgentChat.Model | FX_AgentChat.Model.ResumeDeny | `submit("/chat",...,[convId,"deny"])` | T029, T100 | T031 | Test.AgentChat.Model |
|
|
| **US2**: Negation Guard | `/agent` | AgentChat.ToolResolver | — | `fast_confirmation_tool()` regex pre-check | T104 | — | Test.IntentKeyword.Edges |
|
|
| **US3**: Tool Visibility | AssistantChatPanel | AgentChat.Model | — | — | — | T040, T041 | Test.AgentChat.ToolCallCard |
|
|
| **US4**: Context | `/agent` | AgentChat.LangGraph | — | `thread_id=conversation_id` + PostgreSQL persistence/checkpoints | T045 | — | Test.AgentChat.LangGraph |
|
|
| **US5**: List Conversations | ConversationList | AgentChat.Model | FX_AgentChat.Conversations.ListValid | `GET /api/assistant/conversations` | T052, T053 | T059 | Test.AgentChat.Api |
|
|
| **US5**: List Empty | ConversationList | AgentChat.Model | FX_AgentChat.Conversations.ListEmpty | `GET /api/assistant/conversations` | T052 | T059 | Test.AgentChat.Api |
|
|
| **US5**: Load History | AssistantChatPanel | AgentChat.Model | FX_AgentChat.History.Valid | `GET /api/assistant/history` | T054 | T019 | Test.AgentChat.Api |
|
|
| **US5**: Delete/Archive | ConversationList | AgentChat.Model | FX_AgentChat.Delete.Valid | `DELETE /api/assistant/conversations/{id}` | T055 | T058 | Test.AgentChat.Api |
|
|
| **US5**: Delete Not Owner | ConversationList | — | FX_AgentChat.Delete.NotOwner | `DELETE /api/assistant/conversations/{id}` | T055 | — | Test.AgentChat.Api |
|
|
| **US6**: File Upload | AssistantChatPanel | AgentChat.Model | FX_AgentChat.Document.ParsePdf.Valid | `submit("/chat", {text, files})` | T065, T066 | T068, T069 | Test.AgentChat.Document |
|
|
| **US6**: PDF Encrypted | — | AgentChat.Document | FX_AgentChat.Document.ParsePdf.Encrypted | — | T065 | — | Test.AgentChat.Document |
|
|
| **US6**: XLSX Password | — | AgentChat.Document | FX_AgentChat.Document.ParseXlsx.PasswordProtected | — | T065 | — | Test.AgentChat.Document |
|
|
| **—**: Hidden Runtime Context | `/agent` | AgentChat.Handler | — | `submit("/chat")` LLM-facing message | T106 | T108 | Test.Agent.App.HiddenContext |
|
|
| **—**: Env Sync | `/agent` | AgentChat.Model | — | `submit("/chat", ..., env_id)` | T107 | T107 | Browser snapshot |
|
|
| **—**: First Activity Recovery | `/agent` | AgentChat.Model | — | Gradio stream watchdog | T109 | T109 | Test.AgentChat.Model |
|
|
| **—**: Operator Status Strip | `/agent` | AgentChat.Model | — | UI-derived state | T110 | T110 | Test.AgentChat.Model + Browser snapshot |
|
|
| **—**: Diagnostics Menu | `/agent` | AgentChat.Model | — | UI-derived state | T101 | T110 | Browser snapshot |
|
|
| **—**: DEV Mode Transport | `/agent` | AgentChat.GradioApp | — | `/api/agent/gradio` same-origin proxy | T102 | T073 | Browser snapshot + run tests |
|
|
| **—**: Service Auth | — | — | FX_AgentChat.ServiceToken.Valid | `POST /api/auth/service-token` | T080 | — | Test.AgentChat.Api |
|
|
| **—**: Rejected Paths | — | AgentChat.Model | FX_AgentChat.Model.RejectedPath | — | — | — | Test.AgentChat.Model.RejectedPaths |
|
|
|
|
## Impact Analysis Quick Reference
|
|
|
|
| If you change... | These fixtures verify it | These tests verify it | These screens depend |
|
|
|-----------------|------------------------|----------------------|---------------------|
|
|
| `AgentChat.Model.sendMessage()` | FX_AgentChat.Model.SendMessage.Valid, ResumeConfirm, ResumeDeny, CancelGeneration | Test.AgentChat.Model | AssistantChatPanel, /agent |
|
|
| `POST /api/assistant/conversations` | FX_AgentChat.Conversations.ListValid, ListEmpty | Test.AgentChat.Api | ConversationList, AssistantChatPanel |
|
|
| `GET /api/assistant/history` | FX_AgentChat.History.Valid, NotFound | Test.AgentChat.Api | AssistantChatPanel |
|
|
| `DELETE /api/assistant/conversations/{id}` | FX_AgentChat.Delete.Valid, NotOwner, NotFound | Test.AgentChat.Api | ConversationList |
|
|
| `@tool` functions in tools.py | — | Test.AgentChat.Tools | Gradio agent handler |
|
|
| `get_tools_for_query()` hybrid router behavior | — | Test.AgentChat.Tools / Test.IntentKeyword.Edges | Gradio agent handler |
|
|
| `_embedding_router.py` fallback logic | — | Test.EmbeddingRouter | Gradio agent handler |
|
|
| `fast_confirmation_tool()` negation guard | — | Test.IntentKeyword.Edges | Gradio agent handler |
|
|
| Document parser | FX_AgentChat.Document.ParsePdf.Valid, ParseXlsx.Valid | Test.AgentChat.Document | Gradio agent handler |
|
|
| `@gradio/client` transport | FX_AgentChat.Model.RejectedPath (WebSocket guardrail) | Test.AgentChat.Model.RejectedPaths | AssistantChatPanel |
|
|
| Hidden runtime context / visible text cleaning | — | Test.Agent.App.HiddenContext, Test.AgentChat.Model | /agent, ConversationList |
|
|
| First-activity timeout and recovery card | — | Test.AgentChat.Model + browser snapshot | /agent |
|
|
| Diagnostics menu and process strip | — | Test.AgentChat.Model + browser snapshot | /agent |
|
|
| `POST /api/auth/service-token` | FX_AgentChat.ServiceToken.Valid, InvalidSecret | Test.AgentChat.Api | Gradio container startup |
|
|
|
|
## Fixture Count
|
|
|
|
| Category | Count |
|
|
|----------|:-----:|
|
|
| API fixtures | 14 |
|
|
| Model fixtures | 5 |
|
|
| **Total** | **19** |
|
|
|
|
## Current Verification Snapshot (2026-07-03)
|
|
|
|
| Slice | Command | Result |
|
|
|-------|---------|--------|
|
|
| Backend hidden context | `AUTH_SECRET_KEY=test-secret JWT_SECRET=test-secret backend/.venv/bin/python -m pytest backend/tests/test_agent/test_app.py::TestAgentHandler::test_normal_send_hides_runtime_context_from_saved_history -q` | 1 passed |
|
|
| Frontend model | `cd frontend && npm run test -- AgentChatModel.test.ts` | 88 passed |
|
|
| Frontend build | `cd frontend && npm run build` | Passed; existing unrelated Svelte warnings |
|
|
| Browser UX | Chrome DevTools snapshot/screenshot of `http://localhost:5173/agent` | Process strip visible; diagnostics menu opens; system titles normalized |
|
|
|
|
#endregion Traceability
|