93 lines
3.9 KiB
Markdown
93 lines
3.9 KiB
Markdown
# Quickstart: LLM Chat Assistant for Project Operations
|
|
|
|
## Purpose
|
|
|
|
Implement and validate assistant-driven project operations defined in:
|
|
- Spec: [`spec.md`](specs/021-llm-project-assistant/spec.md)
|
|
- UX reference: [`ux_reference.md`](specs/021-llm-project-assistant/ux_reference.md)
|
|
- Plan: [`plan.md`](specs/021-llm-project-assistant/plan.md)
|
|
- Data model: [`data-model.md`](specs/021-llm-project-assistant/data-model.md)
|
|
- Contracts: [`contracts/modules.md`](specs/021-llm-project-assistant/contracts/modules.md), [`contracts/assistant-api.openapi.yaml`](specs/021-llm-project-assistant/contracts/assistant-api.openapi.yaml)
|
|
|
|
## 1) Backend implementation flow
|
|
|
|
1. Add assistant route module (`/api/assistant/*`).
|
|
2. Implement intent parser service (hybrid deterministic + LLM fallback).
|
|
3. Implement security guard and confirmation token workflow.
|
|
4. Implement execution adapter mapping intents to existing Git/migration/backup/LLM/tasks operations.
|
|
5. Add structured assistant audit logging.
|
|
|
|
## 2) Frontend implementation flow
|
|
|
|
1. Add assistant chat panel component and open/close controls in main layout.
|
|
2. Add assistant API client using existing frontend API wrapper.
|
|
3. Render assistant response states (`needs_confirmation`, `started`, `denied`, etc.).
|
|
4. Add confirm/cancel actions and task tracking chips linking to Task Drawer/reports.
|
|
5. Add i18n keys for RU/EN assistant labels and status texts.
|
|
|
|
## 3) Safety checks (must pass)
|
|
|
|
- Unauthorized command execution is denied.
|
|
- Dangerous operations require confirmation and do not auto-run.
|
|
- Expired/cancelled confirmation never executes.
|
|
- Confirm endpoint is idempotent (single execution).
|
|
|
|
## 4) UX conformance checks (must pass)
|
|
|
|
- Chat interaction available in app shell.
|
|
- Immediate "started" response with `task_id` for long jobs.
|
|
- Clear clarification prompt on ambiguous commands.
|
|
- Clear error text and recovery guidance on failed dispatch.
|
|
|
|
## 5) Contract checks (must pass)
|
|
|
|
- Assistant endpoints conform to [`assistant-api.openapi.yaml`](specs/021-llm-project-assistant/contracts/assistant-api.openapi.yaml).
|
|
- Response states always included and valid enum values.
|
|
- Confirmation flow returns deterministic machine-readable output.
|
|
|
|
## 6) Suggested validation commands
|
|
|
|
Backend tests:
|
|
```bash
|
|
cd backend && .venv/bin/python3 -m pytest
|
|
```
|
|
|
|
Frontend tests:
|
|
```bash
|
|
cd frontend && npm test
|
|
```
|
|
|
|
Targeted assistant tests (when implemented):
|
|
```bash
|
|
cd backend && .venv/bin/python3 -m pytest tests -k assistant
|
|
cd frontend && npm test -- assistant
|
|
```
|
|
|
|
## 7) Done criteria for planning handoff
|
|
|
|
- All planning artifacts for `021` exist and are mutually consistent.
|
|
- Risk confirmation and RBAC enforcement are explicit in spec and contracts.
|
|
- Task-tracking integration through existing Task Drawer/reports is reflected in contracts and tasks.
|
|
- Ready for implementation via `tasks.md`.
|
|
|
|
## 8) Validation Log (2026-02-23)
|
|
|
|
### Frontend
|
|
|
|
- `cd frontend && npx vitest run src/lib/components/assistant/__tests__/assistant_chat.integration.test.js src/lib/components/assistant/__tests__/assistant_confirmation.integration.test.js src/lib/stores/__tests__/assistantChat.test.js`
|
|
- Result: **PASS** (`11 passed`)
|
|
- `cd frontend && npm run build`
|
|
- Result: **PASS** (build successful; project has pre-existing non-blocking a11y warnings outside assistant scope)
|
|
|
|
### Backend
|
|
|
|
- `python3 -m py_compile backend/src/api/routes/assistant.py backend/src/models/assistant.py backend/src/api/routes/__tests__/test_assistant_api.py backend/src/api/routes/__tests__/test_assistant_authz.py`
|
|
- Result: **PASS**
|
|
- `cd backend && .venv/bin/python -m pytest -q src/api/routes/__tests__/test_assistant_api.py src/api/routes/__tests__/test_assistant_authz.py`
|
|
- Result: **BLOCKED in current env** (runtime hang during request execution after heavy app bootstrap; collection succeeds)
|
|
|
|
### Semantics
|
|
|
|
- `python3 generate_semantic_map.py`
|
|
- Result: **PASS** (updated semantic artifacts: `.ai/PROJECT_MAP.md`, `.ai/MODULE_MAP.md`, `semantics/semantic_map.json`)
|