ss-tools/specs/017-llm-analysis-plugin/data-model.md

Data Model: LLM Analysis Plugin

Feature: 017-llm-analysis-plugin

Entities

LLMProviderConfig

Stores configuration for different LLM providers.

Field	Type	Required	Description
id	UUID	Yes	Unique identifier
provider_type	Enum	Yes	openai, openrouter, kilo
name	String	Yes	Display name (e.g., "Production GPT-4")
base_url	String	Yes	API Endpoint URL
api_key	String	Yes	Encrypted API Key
default_model	String	Yes	Model identifier (e.g., gpt-4o)
is_active	Boolean	Yes	Whether this provider is currently enabled

ValidationResult

Stores the outcome of a dashboard validation task.

Field	Type	Required	Description
id	UUID	Yes	Unique identifier
dashboard_id	String	Yes	Reference to the dashboard
timestamp	DateTime	Yes	When the validation ran
status	Enum	Yes	PASS, WARN, FAIL
screenshot_path	String	No	Path to the captured screenshot (if stored)
screenshot_metadata	JSON	No	{width: 1920, height: dynamic, tabs_processed: []}
issues	JSON	Yes	List of detected issues [{severity, message, location}]
raw_response	Text	No	Full LLM response for debugging

TaskConfiguration (Extension)

Extends existing Task model to support validation-specific params.

Field	Type	Required	Description
task_type	String	Yes	dashboard_validation
parameters	JSON	Yes	{dashboard_id, provider_id, screenshot_strategy}

API Contracts

See contracts/ directory for OpenAPI specifications.

Key Interactions

1. Configure Provider: POST /api/settings/llm/providers
2. Trigger Validation: POST /api/tasks/dispatch (payload: {type: "dashboard_validation", ...})
3. Get Results: GET /api/tasks/{task_id}/result (or via WebSocket stream)
4. Generate Documentation: POST /api/tasks/dispatch (payload: {type: "dataset_documentation", ...})
5. Generate Commit: POST /api/git/generate-message