Skip to content

Latest commit

 

History

History
435 lines (345 loc) · 10.7 KB

MANIFEST_SPEC.md

File metadata and controls

435 lines (345 loc) · 10.7 KB

Manifest Specification

The dashboard manifest is a YAML file that provides metadata about your dashboard to the AI assistant. It enables enhanced context (Level 1+) and defines available actions and data sources.

Quick Reference

name: "Dashboard Name"
version: "1.0.0"
description: "Brief description"
capabilityLevel: "level-3"  # level-0 | level-1 | level-2 | level-3

aiInstructions: |
  Custom instructions for the AI assistant.

glossary: [...]      # Business term definitions
navigation: [...]    # Tab/page structure
pages: [...]         # Page and component details
dataSources: [...]   # Data schema (Level 3)
actions: [...]       # Available actions (Level 2+)
componentGroups: [...] # Logical component groupings

Root Properties

Property Type Required Description
name string Yes Dashboard display name
version string No Semantic version (e.g., "1.0.0")
description string No Brief description for AI context
author string No Author or team name
capabilityLevel string Yes One of: level-0, level-1, level-2, level-3
aiInstructions string No Custom instructions appended to AI system prompt

Example

name: "Sales Analytics Dashboard"
version: "1.0.0"
description: "Enterprise sales performance tracking"
author: "Analytics Team"
capabilityLevel: "level-3"

aiInstructions: |
  This dashboard tracks B2B SaaS sales metrics.
  All revenue figures are in USD.
  Fiscal quarters: Q1=Jan-Mar, Q2=Apr-Jun, Q3=Jul-Sep, Q4=Oct-Dec.

  Data is available for 2024 only (2024-01-01 to 2024-12-31).

Glossary

Defines business terms the AI should understand. The AI uses these definitions when interpreting user queries.

Schema

glossary:
  - term: string       # Required: The term
    definition: string # Required: Plain-language definition
    synonyms: [string] # Optional: Alternative terms users might use

Example

glossary:
  - term: "ARR"
    definition: "Annual Recurring Revenue - total yearly subscription value"
    synonyms: ["annual revenue", "yearly recurring"]

  - term: "MRR"
    definition: "Monthly Recurring Revenue - ARR divided by 12"
    synonyms: ["monthly revenue"]

  - term: "Churn Rate"
    definition: "Percentage of customers who cancel subscriptions in a period"
    synonyms: ["attrition", "customer loss"]

  - term: "Enterprise"
    definition: "Customer segment with 500+ employees"
    synonyms: ["large enterprise"]

Navigation

Describes the dashboard's navigation structure for the Navigate agent.

Schema

navigation:
  - id: string          # Required: Unique identifier (used in navigate_to)
    label: string       # Required: Display name
    path: string        # Required: URL path or tab value
    description: string # Optional: What this page shows

Example

navigation:
  - id: "overview"
    label: "Executive Overview"
    path: "/overview"
    description: "High-level KPIs and trends"

  - id: "regional"
    label: "Regional Analysis"
    path: "/regional"
    description: "Performance by geographic region"

  - id: "details"
    label: "Transaction Details"
    path: "/details"
    description: "Individual transaction data"

Pages

Detailed information about each page and its components.

Schema

pages:
  - id: string           # Required: Must match navigation id
    title: string        # Required: Page title
    description: string  # Optional: Page purpose
    components: [...]    # Optional: List of components

Component Schema

components:
  - id: string           # Required: HTML element ID
    label: string        # Required: Human-readable name
    type: string         # Required: Component type
    subtype: string      # Optional: Framework-specific type
    description: string  # Optional: What this component shows
    dataBinding:         # Optional: Data connection info
      source: string     # Data source ID
      fields: [string]   # Fields used

Component Types

Type Description
kpi Single value metric card
chart Visualization (line, bar, pie, etc.)
table Data table or grid
form Input form
card Information card
filter Filter control

Example

pages:
  - id: "overview"
    title: "Executive Overview"
    description: "Key metrics for leadership"
    components:
      - id: "kpi_revenue"
        label: "Total Revenue (ARR)"
        type: "kpi"
        description: "Sum of annual recurring revenue"
        dataBinding:
          source: "sales_data"
          fields: ["arr"]

      - id: "revenue_chart"
        label: "Revenue Trend"
        type: "chart"
        subtype: "plotly"
        description: "Monthly ARR over time"
        dataBinding:
          source: "sales_data"
          fields: ["date", "arr"]

      - id: "recent_activity"
        label: "Recent Transactions"
        type: "table"
        description: "Latest 10 closed deals"

Data Sources (Level 3)

Defines available data sources and their schemas for the Data agent.

Schema

dataSources:
  - id: string           # Required: Unique identifier
    name: string         # Required: Display name
    description: string  # Optional: What data this contains
    fields: [...]        # Required: Field definitions

Field Schema

fields:
  - name: string         # Required: Field/column name
    type: string         # Required: Data type
    description: string  # Optional: Field description
    filterable: boolean  # Optional: Can be used in filters
    aggregatable: boolean # Optional: Can be used in aggregations
    values: [string]     # Optional: Enum values for categorical fields
    unit: string         # Optional: Unit of measurement (e.g., "USD")

Field Types

Type Description
string Text value
number Numeric value
date Date value
boolean True/false value

Example

dataSources:
  - id: "sales_data"
    name: "Sales Transactions"
    description: "All closed deals with customer and product details"
    fields:
      - name: "transaction_id"
        type: "string"
        description: "Unique transaction identifier"

      - name: "date"
        type: "date"
        description: "Transaction close date"
        filterable: true

      - name: "region"
        type: "string"
        description: "Geographic region"
        filterable: true
        values: ["North America", "EMEA", "APAC", "LATAM"]

      - name: "arr"
        type: "number"
        description: "Annual contract value"
        aggregatable: true
        unit: "USD"

      - name: "product"
        type: "string"
        description: "Product tier"
        filterable: true
        values: ["Enterprise", "Pro", "Starter"]

Actions (Level 2+)

Defines actions the AI can execute on the dashboard.

Schema

actions:
  - id: string              # Required: Action type ID (used in handlers)
    name: string            # Required: Display name
    description: string     # Optional: What this action does
    category: string        # Required: Action category
    parameters: [...]       # Optional: Required parameters
    requiresConfirmation: boolean  # Optional: Ask before executing

Categories

Category Description
navigation Page/tab navigation
update Modify dashboard state (filters, etc.)
query Read data or state
create Create new elements
delete Remove elements

Parameter Schema

parameters:
  - name: string        # Required: Parameter name
    type: string        # Required: Data type
    required: boolean   # Optional: Is this required (default: false)
    description: string # Optional: Parameter description
    values: [string]    # Optional: Allowed values for enums
    default: any        # Optional: Default value

Example

actions:
  - id: "navigate_to"
    name: "Navigate to Page"
    description: "Switch to a different page"
    category: "navigation"
    parameters:
      - name: "target"
        type: "string"
        required: true
        description: "Target page ID"
        values: ["overview", "regional", "details", "explorer"]

  - id: "set_filter"
    name: "Set Filter"
    description: "Apply a filter value"
    category: "update"
    parameters:
      - name: "filterId"
        type: "string"
        required: true
        description: "Filter input ID"
      - name: "value"
        type: "string"
        required: true
        description: "Filter value"

  - id: "set_date_range"
    name: "Set Date Range"
    description: "Filter data to a date range"
    category: "update"
    parameters:
      - name: "start"
        type: "string"
        required: true
        description: "Start date (YYYY-MM-DD)"
      - name: "end"
        type: "string"
        required: true
        description: "End date (YYYY-MM-DD)"

  - id: "reset_filters"
    name: "Reset Filters"
    description: "Clear all filters"
    category: "update"
    parameters: []

  - id: "query_data"
    name: "Query Data"
    description: "Execute a data query"
    category: "query"
    parameters:
      - name: "filter"
        type: "array"
        required: false
      - name: "groupBy"
        type: "array"
        required: false
      - name: "aggregate"
        type: "array"
        required: false
      - name: "limit"
        type: "number"
        required: false

Component Groups

Optional logical groupings of components for AI context.

Schema

componentGroups:
  - id: string           # Required: Group identifier
    label: string        # Required: Display name
    description: string  # Optional: Group purpose
    componentIds: [string] # Required: Component IDs in this group

Example

componentGroups:
  - id: "filters"
    label: "Global Filters"
    description: "Filters affecting all visualizations"
    componentIds: ["date_filter", "region_filter", "product_filter"]

  - id: "kpis"
    label: "Key Performance Indicators"
    description: "Top-level business metrics"
    componentIds: ["kpi_revenue", "kpi_mrr", "kpi_customers"]

File Location

Place the manifest file in your Shiny app's www/ directory or specify an absolute path:

# Relative to www/
aiAssistantWidget(
  apiUrl = "http://localhost:3000/api/chat",
  manifest = "dashboard-manifest.yaml"
)

# Absolute path
aiAssistantWidget(
  apiUrl = "http://localhost:3000/api/chat",
  manifest = "/path/to/manifest.yaml"
)

Complete Example

See examples/demo-dashboard/dashboard-manifest.yaml for a full working example with all features.