Shiny AI Assistant

A universal, embeddable AI assistant widget that enables natural language interaction with any R Shiny dashboard.

Overview

The Shiny AI Assistant provides a floating chat interface that can:

• Answer questions about charts, metrics, and dashboard data
• Navigate between pages/tabs on command
• Find and highlight UI elements
• Execute dashboard actions (set filters, export data)
• Query data and provide analytical insights
• Generate guided tours of the dashboard

Architecture

┌─────────────────────────────────────────────────────────-────────────┐
│                         Chat Widget (React)                          │
│                    Floating UI with message history                  │
└─────────────────────────────────┬────────────────────────-───────────┘
                                  │ SSE Stream
                                  ▼
┌───────────────────────────────────────────────────────────-──────────┐
│                       API Server (Next.js)                           │
│                                                                      │
│   ┌─────────┐                                                        │
│   │ Router  │──┬──▶ ExplainAgent (Q&A, image analysis)               │
│   │ Agent   │  ├──▶ NavigateAgent (page/tab navigation)              │
│   └─────────┘  ├──▶ ActionAgent (filters, exports)                   │
│                ├──▶ LocateAgent (find & highlight)                   │
│                ├──▶ DataAgent (queries, analytics)                   │
│                └──▶ TourAgent (guided tours)                         │
└─────────────────────────────────┬──────────────────────────-─────────┘
                                  │ Tool Calls
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Dashboard Bridge Protocol                         │
│              (Platform-agnostic abstraction layer)                   │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         Shiny Adapter                                │
│                   (JavaScript ↔ R communication)                     │
└─────────────────────────────────────────────────────────────────────┘

Packages

Package	Description
@shiny-ai/bridge	Dashboard bridge protocol and Shiny adapter
@shiny-ai/widget	React chat widget components
@shiny-ai/agents	AI agents using Vercel AI SDK
@shiny-ai/server	Next.js API server
shinyAIAssistant	R package for Shiny integration

Capability Levels

Level	Features	Requirements
0	Navigation, highlighting, basic Q&A	Widget only
1	Enhanced context, glossary	+ Manifest YAML
2	Action execution (filters, exports)	+ Action handlers in R
3	Data queries, analytics	+ Data source config

Quick Start

1. Start the API Server

cd packages/server
pnpm install
pnpm dev

2. Add to Your Shiny App

library(shiny)
library(shinyAIAssistant)

ui <- fluidPage(
  # Your dashboard UI...

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

server <- function(input, output, session) {
  # Your server logic...

  # Register action handlers (Level 2+)
  aiAssistantHandler(session, handlers = list(
    set_filter = function(params) {
      updateSelectInput(session, params$filterId, selected = params$value)
      list(success = TRUE)
    }
  ))
}

Documentation

Document	Description
ARCHITECTURE.md	System design, agents, bridge protocol
INTEGRATION_GUIDE.md	Step-by-step integration guide
MANIFEST_SPEC.md	Dashboard manifest YAML specification

Technology Stack

Component	Technology
Widget	React, Tailwind CSS
Agents	Vercel AI SDK, Claude (Anthropic)
Server	Next.js API routes
Bridge	TypeScript, Shiny bindings
R Package	shinyAIAssistant

Demo

See examples/demo-dashboard/ for a complete working example.

cd examples/demo-dashboard
Rscript -e "shiny::runApp()"

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck