ss-tools/specs/021-llm-project-assistant/data-model.md

Data Model: LLM Chat Assistant for Project Operations

Feature: 021-llm-project-assistant
Spec: spec.md
Research: 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.