busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
49e4ac0fe25dd5e2622fc08487cc21ccc0405ce2
ss-tools/specs/035-agent-chat-context/quickstart.md
busya ff60865183 feat(agent-chat): 035-agent-chat-context — контекст, guardrails, tools, database discovery 
== 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
2026-07-04 22:47:17 +03:00

2.9 KiB
Raw Blame History

Quickstart: Agent Chat Context & Guardrails

Feature: 035-agent-chat-context Branch: 035-agent-chat-context

Development Setup

# Backend (terminal 1)
cd backend
source .venv/bin/activate
pip install -r requirements.txt
python -m uvicorn src.app:app --reload --port 8000

# Gradio Agent (terminal 2 — separate process)
cd backend
source .venv/bin/activate
python src/agent/run.py
# Gradio listens on http://0.0.0.0:7860

# Frontend (terminal 3)
cd frontend
npm install
npm run dev -- --port 5173
# → http://localhost:5173

Verification

# Backend tests
cd backend && source .venv/bin/activate && python -m pytest -v

# Frontend tests (L1 model + L2 component)
cd frontend && npm run test

# Lint
cd backend && python -m ruff check .
cd frontend && npm run lint

Docker

docker compose up --build
# Frontend: http://localhost:8000
# Backend API: http://localhost:8001

Manual Test Flow

  1. Open http://localhost:5173/dashboards/10?env_id=ss-dev
  2. Click "Ask Agent" → navigates to /agent?objectType=dashboard&objectId=10&envId=ss-dev
  3. Verify: Process steps pill shows «📋 Дашборд #10 · ss-dev»
  4. Verify: Debug panel (ℹ️ → Показать) shows UIContext JSON + tool affinity
  5. Type: «Расскажи про этот дашборд» → agent responds with dashboard-specific info
  6. Type: «Задеплой на prod» → confirmation card with «PRODUCTION» badge
  7. Switch EnvSelector to prod → chat background changes to warning tint + red banner
  8. Guardrails test: Type «Удали дашборд #10» → dangerous confirmation card with 10s countdown
  9. Tool test: Trigger a tool that times out → ToolCallCard shows ⏱️ + retry button

Key Files Changed

File What
backend/src/agent/app.py agent_handler extended with uicontext; _inject_uicontext()
backend/src/agent/_tool_filter.py NEW — context-aware tool filtering
backend/src/agent/tools.py Retry wrapper, summarise, timeout helpers
backend/src/agent/_confirmation.py Extended confirmation metadata
frontend/src/lib/models/AgentChatModel.svelte.ts New atoms: uiContext, toolAffinity, dangerousCountdown, isProdContext
frontend/src/lib/models/AgentChat.StreamProcessor.svelte.ts New handlers: tool_retry, tool_timeout, extended confirm_required
frontend/src/lib/models/AgentChatTypes.ts New types: UIContext, ToolAffinityEntry, ConfirmMetadataV2
frontend/src/lib/components/agent/AgentChat.svelte Prod background + banner + context pill
frontend/src/lib/components/assistant/ConfirmationCard.svelte 7 states: read/write/dangerous/denied + countdown
frontend/src/lib/components/assistant/ToolCallCard.svelte retrying/timeout/cancelled states + retry button
frontend/src/routes/agent/+page.svelte onMount context init from URL params
frontend/src/lib/stores/assistantChat.svelte.ts initialContext field