AI Features¶
DashForge is designed from the ground up to work with LLM agents. The non-polymorphic JSON format, semantic data layer, and validation system make it easy for AI to generate valid dashboard configurations.
Why AI-First?¶
Non-polymorphic JSON¶
Traditional dashboard formats use polymorphic schemas:
// Polymorphic (hard for AI)
{
"type": "chart",
"config": { ... } // Structure depends on chart type
}
DashForge uses flat, explicit structures:
// Non-polymorphic (easy for AI)
{
"type": "chart",
"config": {
"geometry": "line",
"encodings": { "x": "date", "y": "revenue" },
"style": { "smooth": true }
}
}
Semantic Context¶
Cube.js provides business context that helps AI understand the data:
Raw SQL (confusing):
SELECT DATE_TRUNC('month', o.created_at), SUM(o.amount)
FROM orders o GROUP BY 1
Semantic (clear):
Orders.totalRevenue by Orders.createdAt (monthly)
Validated Generation¶
All AI-generated configurations are validated before use:
AI Capabilities¶
1. Generate Dashboard from Description¶
Create a complete dashboard from a natural language description:
User: "Create a sales dashboard with revenue by region and monthly trends"
Generated:
- Title: "Sales Dashboard"
- Widgets:
- Revenue by Region (bar chart)
- Monthly Revenue Trend (line chart)
- Total Revenue (metric)
- Top Products (table)
2. Add Widget from Description¶
Add a single widget to an existing dashboard:
User: "Add a pie chart showing sales by category"
Generated widget:
{
"type": "chart",
"title": "Sales by Category",
"position": { "x": 0, "y": 6, "w": 4, "h": 3 },
"config": {
"geometry": "pie",
"encodings": { "category": "category", "value": "sales" }
}
}
3. Modify Existing Widget¶
Update a widget based on instructions:
User: "Change the bar chart to show percentages"
Before:
{ "geometry": "bar", "encodings": { "y": "revenue" } }
After:
{ "geometry": "bar", "encodings": { "y": "revenue_pct" }, "style": { "format": "percent" } }
4. Natural Language Queries¶
Generate Cube.js queries from questions:
User: "Which products had the highest profit margin last quarter?"
Generated query:
{
"measures": ["Products.profitMargin"],
"dimensions": ["Products.name"],
"timeDimensions": [{
"dimension": "Orders.createdAt",
"dateRange": "last quarter"
}],
"order": { "Products.profitMargin": "desc" },
"limit": 10
}
5. Question Assistant¶
The Question builder includes an LLM chat panel for GrokifyQL. Users can ask for query rewrites, summaries, or recommended filters:
User: "Show initiatives where MoSCoW is empty"
Assistant:
- summarizes the current query
- returns a complete GrokifyQL replacement
- notes which fields or assumptions it used
Applied assistant output switches the SQL pane into edit mode so the user can review the generated GrokifyQL before running or saving it.
AI provider configuration is optional. When no provider is configured, the builder still supports manual Question editing, running, saving, exporting, and dashboard use. Local Ollama can be enabled through the server CLI for offline development.
JSON Schemas¶
The AI uses JSON Schema definitions to ensure valid output.
Dashboard Schema¶
{
"type": "object",
"required": ["title", "widgets"],
"properties": {
"title": { "type": "string" },
"layout": {
"type": "object",
"properties": {
"type": { "enum": ["grid"] },
"columns": { "type": "integer", "default": 12 }
}
},
"widgets": {
"type": "array",
"items": { "$ref": "#/$defs/Widget" }
}
}
}
Widget Schema¶
{
"type": "object",
"required": ["type", "position"],
"properties": {
"type": { "enum": ["chart", "metric", "table", "text"] },
"title": { "type": "string" },
"position": {
"type": "object",
"properties": {
"x": { "type": "integer", "minimum": 0 },
"y": { "type": "integer", "minimum": 0 },
"w": { "type": "integer", "minimum": 1, "maximum": 12 },
"h": { "type": "integer", "minimum": 1 }
}
}
}
}
ChartConfig Schema¶
{
"type": "object",
"required": ["geometry"],
"properties": {
"geometry": { "enum": ["line", "bar", "pie", "scatter", "area"] },
"encodings": {
"type": "object",
"properties": {
"x": { "type": "string" },
"y": { "type": "string" },
"color": { "type": "string" },
"value": { "type": "string" },
"category": { "type": "string" }
}
},
"style": {
"type": "object",
"properties": {
"showLegend": { "type": "boolean" },
"smooth": { "type": "boolean" },
"stack": { "type": "boolean" }
}
}
}
}
System Prompts¶
The builder includes optimized prompts for dashboard generation.
Dashboard Generation Prompt¶
You are a dashboard design assistant. You help users create data dashboards
by generating JSON configurations.
You output JSON that follows the DashboardIR specification. Key rules:
- Use a 12-column grid layout
- Position widgets using x, y, w, h coordinates
- Common widget sizes: metrics (2x2), charts (4x3 or 6x3), tables (6x4)
- Align widgets to avoid overlap
- Use descriptive titles for widgets
Chart types: line, bar, pie, scatter, area
Widget types: chart, metric, table, text
Always respond with valid JSON only.
Widget Generation Prompt¶
The prompt includes:
- Schema definition
- Existing widget positions (to avoid overlap)
- Available data fields (from Cube.js schema)
- User's request
Validation¶
All AI-generated output is validated before use.
For Questions, validation includes GrokifyQL parsing and catalog-aware policy checks before save or execution. Agents and assistant flows do not bypass the same backend checks used by manual queries.
Validation Steps¶
- JSON Parse: Ensure valid JSON syntax
- Schema Validation: Check against JSON Schema
- Semantic Validation: Verify field references exist
- Layout Validation: Check for widget overlaps
Auto-fix¶
Common issues are automatically fixed:
- Missing IDs are generated
- Negative positions are set to 0
- Widths exceeding 12 are capped
- Missing required fields use defaults
Error Feedback¶
If validation fails, errors are returned to the AI for retry:
{
"valid": false,
"errors": [
"Position x cannot be negative",
"Chart geometry must be one of: line, bar, pie, scatter, area"
],
"warnings": [
"Widget has no title"
]
}
API Integration¶
AI Generation Endpoint¶
POST /api/v1/ai/generate
Content-Type: application/json
{
"prompt": "Create a sales dashboard",
"type": "dashboard",
"schema": { ... }, // Optional: Cube.js schema for context
"options": {
"model": "claude-3-sonnet",
"temperature": 0.7
}
}
Response¶
Mock Generation¶
For development without an AI backend, the builder includes mock generation:
import { mockGenerateWidget } from './api/ai'
const result = await mockGenerateWidget(
"Add a line chart showing trends",
existingWidgets
)
// Returns a basic widget based on keyword matching
Best Practices¶
For Prompt Engineering¶
- Be specific about data fields: "revenue by region" not "sales data"
- Specify chart types when possible: "bar chart" not "visualization"
- Include time ranges: "last 6 months" not "recent"
- Mention comparisons: "vs previous period"
For AI Integration¶
- Always validate generated output
- Provide schema context from Cube.js
- Include existing widget positions to avoid overlap
- Use temperature 0.7 for creativity, 0.3 for precision
- Implement retry logic for validation failures
Example Prompts¶
Dashboard Generation¶
"Create an executive dashboard with:
- Revenue and profit KPIs at the top
- Monthly trend chart in the middle
- Top 10 products table on the right
- Revenue by region pie chart"