busya
ff60865183
== User stories == US1: Контекст с дашборда/датасета → /agent с URL params US2: Guardrails card — env badge, 7 risk tones, countdown, permission_denied US3: Tools optimization — retry, timeout, summarise, RBAC + context affinity == Backend == - _context.py (NEW): UIContext validation (7 checks) - _tool_filter.py (NEW): RBAC + context affinity pipeline - _confirmation.py: build_confirmation_contract_v2, permission_denied_payload - tools.py: superset_list_databases, retry/summarise/timeout wrappers - app.py: _inject_uicontext, _inject_env_id_into_tools, database prefetch в runtime context - _persistence.py: prefetch_databases() - agent_superset_explore.py: GET /databases endpoint - _llm_async_http.py, _persistence.py: fix double /v1 в LLM URL (LM Studio Unexpected endpoint) == Frontend == - AgentChatModel.svelte.ts: 5 atoms, 3 actions, countdown, context - AgentChat.svelte: production banner, process steps, debug panel - ConfirmationCard.svelte: 7 risk tones, permission_denied, countdown - ToolCallCard.svelte: retrying/timeout/cancelled states - StreamProcessor.svelte.ts: tool_retry, timeout, permission_denied - TopNavbar: sparkles icon + Ассистент - sidebarNavigation: AI section - DashboardHeader, datasets/+page: contextual AI buttons - Icon: sparkles, brain, cpu icons - tailwind: assistant category colors - i18n: en/ru nav keys == Tests == - 159 backend agent tests (+16 US3: retry, timeout, summarise, contracts) - 2544 frontend tests (+11 model + component tests) - 15 JSON fixtures (10 API + 5 model) == Specs == - specs/035-agent-chat-context/: spec, UX, plan, tasks, research, data-model, contracts, quickstart, traceability, fixtures, checklists Closes #035
44 lines
4.0 KiB
Markdown
44 lines
4.0 KiB
Markdown
# Implementation Plan: Agent Chat Context & Guardrails Refinement
|
|
|
|
**Branch**: `035-agent-chat-context` | **Date**: 2026-07-04 | **Spec**: [spec.md](./spec.md)
|
|
**Input**: Feature specification from `/specs/035-agent-chat-context/spec.md`
|
|
|
|
## Summary
|
|
|
|
Refinement of the agent chat system across three vectors:
|
|
1. **Context enrichment** (P1): Frontend captures structured `UIContext` JSON from page state and passes it to the Gradio agent on each `sendMessage`. Agent uses context for (a) contextual responses without explicit object naming, (b) tool filtering by `objectType`. Context is route-level — transferred once when navigating to `/agent` page.
|
|
2. **Guardrails refinement** (P2): Risk classification extended from tool-name prefixes to include environment context and tool danger level. ConfirmationCard gains environment badges, destructive-operation countdown (10s), permission-denied state with alternatives, and visual risk toning.
|
|
3. **Tool optimisation** (P3): Backend: RBAC tool filtering, auto-retry on transient HTTP errors, semantic response summarisation, configurable tool timeout, context-aware tool affinity. Frontend: ToolCallCard extended with retry/timeout/cancelled states.
|
|
|
|
## Technical Context
|
|
|
|
**Language/Version**: Python 3.9+ (backend), TypeScript (frontend Svelte 5 runes-only)
|
|
**Primary Dependencies**: FastAPI, Gradio, LangChain (`create_react_agent`), LangGraph, LangChain-OpenAI (backend); SvelteKit 5, Svelte 5, Tailwind CSS 3, @gradio/client (frontend)
|
|
**Storage**: PostgreSQL 16 (checkpoints via PostgresSaver, conversations via SQLAlchemy)
|
|
**Testing**: pytest (backend), vitest (frontend — L1 model invariants without render + L2 UX with @testing-library/svelte)
|
|
**Target Platform**: Linux server (Docker), modern browsers
|
|
**Project Type**: web application (FastAPI REST + Gradio SSE backend, SvelteKit SPA frontend)
|
|
**Frontend Architecture**: TypeScript-first, model-first (Screen Models via `.svelte.ts`), runes-only (`$state`, `$derived`, `$effect`), typed callback props
|
|
**Performance Goals**: Context pill update <50ms, confirmation card render <200ms, tool retry <5s added latency
|
|
**Constraints**: RBAC enforcement (analyst cannot invoke write tools), backward-compat with existing Gradio submit API, no new database tables
|
|
**Scale/Scope**: ~10 concurrent agent chats, ~20 tools, 3 context types (dashboard/dataset/migration)
|
|
|
|
## Constitution Check
|
|
|
|
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
|
|
| Principle | Status | Evidence |
|
|
|-----------|:------:|----------|
|
|
| **I. Semantic Contract First** | ✅ PASS | All new modules/contracts annotated with `#region`/[C:N]/`@RELATION`. Existing contracts extended, not broken. |
|
|
| **II. Decision Memory** | ✅ PASS | `@RATIONALE`/`@REJECTED` recorded for: context-as-JSON (not URL-parsing), tool affinity mapping, dangerous countdown, retry strategy. |
|
|
| **III. External Orchestrator** | ✅ PASS | Agent remains external over Superset — no change to orchestration boundary. |
|
|
| **IV. Module Discipline** | ✅ PASS | New file `_tool_filter.py` (~40 LOC). Extended files: `AgentChatModel.svelte.ts` (~+60 LOC, stays under 400), `AgentChat.svelte` (~+15 LOC, stays under 1050 — near limit, monitor). No new module exceeds 400 LOC. |
|
|
| **V. RBAC Enforcement** | ✅ PASS | Tool RBAC filtering (AGTL-FR-001) extends existing role model per ADR-0005. Permission-denied confirmation card enforces role gates. |
|
|
| **VI. Frontend — Svelte 5 Runes Only** | ✅ PASS | All new state uses `$state`/`$derived`. No legacy `writable`/`$:` syntax introduced. |
|
|
| **VII. Test-Driven for C3+ Contracts** | ✅ PASS | Fixtures generated for C3+ contracts. `@TEST_EDGE` declarations enable TDD. |
|
|
| **VIII. Attention-Optimized Contracts** | ✅ PASS | All contract IDs hierarchical: `AgentChat.Context`, `AgentChat.Confirmation`, `AgentChat.ToolFilter`. Shared `[SEMANTICS agent-chat,...]` keyword. |
|
|
|
|
**No blocking violations.** Re-check after Phase 1: verify no contract exceeds 150 lines, no module exceeds 400 lines post-extension.
|
|
|
|
#endregion — plan metadata section
|