157 lines
5.2 KiB
Markdown
157 lines
5.2 KiB
Markdown
# Data Model: LLM Chat Assistant for Project Operations
|
|
|
|
**Feature**: [`021-llm-project-assistant`](specs/021-llm-project-assistant)
|
|
**Spec**: [`spec.md`](specs/021-llm-project-assistant/spec.md)
|
|
**Research**: [`research.md`](specs/021-llm-project-assistant/research.md)
|
|
|
|
## 1. Entity: AssistantMessage
|
|
|
|
Represents one chat message in assistant conversation.
|
|
|
|
### Fields
|
|
|
|
| Field | Type | Required | Description |
|
|
|---|---|---|---|
|
|
| message_id | string | Yes | Unique message identifier. |
|
|
| conversation_id | string | Yes | Logical chat session/thread identifier. |
|
|
| role | enum | Yes | `user`, `assistant`, `system`. |
|
|
| text | string | Yes | Message content. |
|
|
| created_at | datetime | Yes | Message timestamp. |
|
|
| metadata | object | No | Additional structured metadata (state badge, task link, etc.). |
|
|
|
|
### Validation Rules
|
|
|
|
- `text` must be non-empty.
|
|
- `role` must be one of allowed values.
|
|
- `conversation_id` must be bound to authenticated user scope.
|
|
|
|
---
|
|
|
|
## 2. Entity: CommandIntent
|
|
|
|
Represents parsed intent from user message.
|
|
|
|
### Fields
|
|
|
|
| Field | Type | Required | Description |
|
|
|---|---|---|---|
|
|
| intent_id | string | Yes | Parsed intent identifier. |
|
|
| domain | enum | Yes | `git`, `migration`, `backup`, `llm`, `status`, `report`, `unknown`. |
|
|
| operation | string | Yes | Normalized operation key (e.g., `create_branch`, `execute_migration`). |
|
|
| entities | object | No | Parsed parameters (`dashboard_id`, `env`, `task_id`, etc.). |
|
|
| confidence | number | Yes | Confidence score `0.0..1.0`. |
|
|
| risk_level | enum | Yes | `safe`, `guarded`, `dangerous`. |
|
|
| requires_confirmation | boolean | Yes | Indicates confirmation gate requirement. |
|
|
|
|
### Validation Rules
|
|
|
|
- `confidence` must be in `[0.0, 1.0]`.
|
|
- `requires_confirmation=true` when `risk_level=dangerous`.
|
|
- Missing mandatory entities triggers `needs_clarification` decision.
|
|
|
|
---
|
|
|
|
## 3. Entity: ExecutionRequest
|
|
|
|
Validated request ready for dispatch to existing backend action.
|
|
|
|
### Fields
|
|
|
|
| Field | Type | Required | Description |
|
|
|---|---|---|---|
|
|
| execution_id | string | Yes | Execution request identifier. |
|
|
| actor_user_id | string | Yes | Authenticated user initiating request. |
|
|
| intent_id | string | Yes | Source `CommandIntent` reference. |
|
|
| dispatch_target | string | Yes | Internal route/service/plugin target identifier. |
|
|
| payload | object | Yes | Validated action payload. |
|
|
| status | enum | Yes | `pending`, `dispatched`, `failed`, `denied`, `cancelled`. |
|
|
| task_id | string | No | Linked async task id if created. |
|
|
|
|
### Validation Rules
|
|
|
|
- Dispatch target must map to known execution backend.
|
|
- Permission checks must pass before `dispatched`.
|
|
|
|
---
|
|
|
|
## 4. Entity: ConfirmationToken
|
|
|
|
One-time confirmation artifact for dangerous operations.
|
|
|
|
### Fields
|
|
|
|
| Field | Type | Required | Description |
|
|
|---|---|---|---|
|
|
| confirmation_id | string | Yes | Unique confirmation token id. |
|
|
| actor_user_id | string | Yes | User who must confirm/cancel. |
|
|
| intent_snapshot | object | Yes | Immutable normalized intent snapshot. |
|
|
| expires_at | datetime | Yes | Token expiry timestamp. |
|
|
| state | enum | Yes | `pending`, `confirmed`, `cancelled`, `expired`, `consumed`. |
|
|
| created_at | datetime | Yes | Creation time. |
|
|
| consumed_at | datetime | No | Time of finalization. |
|
|
|
|
### Validation Rules
|
|
|
|
- Only token owner can confirm/cancel.
|
|
- `confirmed` token transitions to `consumed` after one dispatch.
|
|
- Expired token cannot transition to `confirmed`.
|
|
|
|
---
|
|
|
|
## 5. Entity: AssistantExecutionLog
|
|
|
|
Structured audit record of assistant decision and outcome.
|
|
|
|
### Fields
|
|
|
|
| Field | Type | Required | Description |
|
|
|---|---|---|---|
|
|
| log_id | string | Yes | Unique audit id. |
|
|
| user_id | string | Yes | Actor user id. |
|
|
| conversation_id | string | Yes | Conversation reference. |
|
|
| raw_message | string | Yes | Original user message. |
|
|
| normalized_intent | object | No | Parsed intent snapshot. |
|
|
| decision | enum | Yes | `executed`, `needs_confirmation`, `needs_clarification`, `denied`, `failed`. |
|
|
| outcome | enum | Yes | `success`, `error`, `started`, `cancelled`, `n/a`. |
|
|
| task_id | string | No | Linked async task id. |
|
|
| created_at | datetime | Yes | Audit timestamp. |
|
|
|
|
### Validation Rules
|
|
|
|
- Audit entry required for every command-processing attempt.
|
|
- `task_id` required when `outcome=started` for async operations.
|
|
|
|
---
|
|
|
|
## 6. Relationships
|
|
|
|
- `AssistantMessage` (user role) -> may produce one `CommandIntent`.
|
|
- `CommandIntent` -> may produce one `ExecutionRequest` or `ConfirmationToken`.
|
|
- `ConfirmationToken` (confirmed) -> produces one `ExecutionRequest`.
|
|
- `ExecutionRequest` -> may link to one async `task_id` in existing task manager.
|
|
- Every processed command -> one `AssistantExecutionLog`.
|
|
|
|
---
|
|
|
|
## 7. State Flows
|
|
|
|
### Command Decision Flow
|
|
|
|
`received` -> `parsed` -> (`needs_clarification` | `denied` | `needs_confirmation` | `dispatch`)
|
|
|
|
### Confirmation Flow
|
|
|
|
`pending` -> (`confirmed` -> `consumed`) | `cancelled` | `expired`
|
|
|
|
### Execution Flow
|
|
|
|
`pending` -> (`dispatched` -> `started/success`) | `failed` | `denied` | `cancelled`
|
|
|
|
---
|
|
|
|
## 8. Scale Assumptions
|
|
|
|
- Conversation history is moderate per user and can be paginated.
|
|
- Command audit retention aligns with existing operational retention policies.
|
|
- Assistant parse step must remain lightweight and avoid blocking task execution system.
|