64 lines
5.9 KiB
Markdown
64 lines
5.9 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 |
|
|
| **—**: Debug Info | `/agent` | AgentChat.Model | — | UI-derived state | T101 | T073 | 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 |
|
|
| `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-06-30)
|
|
|
|
| Slice | Command | Result |
|
|
|-------|---------|--------|
|
|
| Backend agent | `cd backend && source .venv/bin/activate && python -m pytest tests/test_agent/ -v` | 375 passed, 18 warnings |
|
|
| Frontend model | `cd frontend && npm run test -- src/lib/models/__tests__/AgentChatModel.test.ts --run` | 73 passed |
|
|
| Frontend build | `cd frontend && npm run build` | Passed; existing unrelated Svelte warnings |
|
|
|
|
#endregion Traceability
|