# 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.