Info PPAAI App

Viz Deck

Agentic visualization library with 9 chart types for dynamic generation

Viz Deck

Viz Deck is an agentic visualization library that enables AI systems to generate contextual, safe, and effective data visualizations dynamically. It provides 9 visualization types, a structured vocabulary of chart types, guardrails for safe generation, and production-ready React components following scientific visualization best practices.

Overview

Viz Deck provides a "deck of cards" approach where AI agents can:

  • Select appropriate visualizations based on user intent and data shape
  • Generate charts dynamically during conversations
  • Enforce safety guardrails to prevent arbitrary generation
  • Maintain consistency across the entire webapp

Key Features

🎯 Visualization Vocabulary

A small, explicit set of chart types with defined data shapes and constraints:

  • Time Series (line/area) - Trends over time with confidence intervals
  • Category Bar - Compare discrete categories (horizontal/vertical)
  • Comparison Matrix - Heatmap-style multi-criteria comparison
  • Histogram - Distribution analysis
  • KPI Card - Single metric display with context
  • Network Graph 2D - Visualize relationships between entities (nodes and edges)
  • Network Graph 3D - Interactive 3D force-directed graph with WebGL
  • Sankey Diagram - Flow visualization showing magnitude of connections
  • Scatter Plot - Display relationships between two continuous variables

🛡️ Guardrails Engine

Automatic enforcement of best practices:

  • Composition Simplicity - Max 4 visualizations per view
  • Data Provenance - Auto-adds data source indicators
  • Uncertainty Quantification - Requires confidence intervals for projections
  • Temporal Freshness - Flags stale data
  • Stakeholder Coverage - Ensures multiple perspectives

🎨 React Components

Production-ready visualizations built with:

  • visx for chart rendering
  • D3 for scales and data transformations
  • shadcn/Tailwind for UI components
  • React 19 optimized (no manual memoization)

🎨 Theme System

Configurable color palettes and styling:

  • defaultTheme - Light theme with Tailwind colors
  • darkTheme - Dark mode variant
  • createTheme() - Create custom themes
  • All charts accept a theme prop

📊 Scientific Standards

All visualizations follow scientific best practices:

  • Proper axis labels with units (e.g., "Temperature (°C)")
  • Legends for multi-series/group charts
  • Tooltips showing precise values with units
  • Reusable Legend component for custom layouts

Installation

Add to your app's dependencies:

{
  "dependencies": {
    "@info-ppaai-app/viz-deck": "workspace:*"
  }
}

Basic Usage

Rendering a Visualization

import { 
  visualizationComponents, 
  type VisualizationId,
  type TimeSeriesSeries 
} from "@info-ppaai-app/viz-deck";

const vizId: VisualizationId = "timeSeries.line";
const Viz = visualizationComponents[vizId];

const series: TimeSeriesSeries[] = [
  {
    id: "series1",
    label: "Water Quality",
    data: [
      { x: "2024-01-01", y: 15.2 },
      { x: "2024-02-01", y: 16.1 },
      { x: "2024-03-01", y: 14.8 },
    ],
  },
];

<Viz 
  series={series} 
  variant="line" 
  xLabel="Date" 
  yLabel="Salinity (ppt)" 
  yUnit=" ppt"
  showLegend={true}
/>

Agent Integration Pattern

import {
  VISUALIZATIONS,
  VISUALIZATION_BY_ID,
  applyGuardrails,
  visualizationComponents,
  type PlannedLayout,
} from "@info-ppaai-app/viz-deck";

// 1. Agent selects visualization based on user query
const vizId = agentSelectVisualization(userQuery, VISUALIZATIONS);
const vizDef = VISUALIZATION_BY_ID[vizId];

// 2. Validate data shape
if (!validateDataShape(data, vizDef.dataShape)) {
  throw new Error("Data shape mismatch");
}

// 3. Build layout
const layout: PlannedLayout = {
  instances: [
    {
      componentId: "main-viz",
      visualizationId: vizId,
      dataSourceId: "databricks-query-123",
    },
  ],
};

// 4. Apply guardrails (automatic safety checks)
const { adjustedLayout, triggered, notes } = applyGuardrails(layout, {
  now: new Date(),
});

// 5. Render with guardrail-adjusted layout
const Component = visualizationComponents[adjustedLayout.instances[0].visualizationId];
return <Component {...chartProps} />;

Available Visualizations

Time Series Chart

Display trends over time with optional confidence intervals.

Data Shape:

  • Required: timestamp, value
  • Optional: seriesId, seriesLabel, confidenceLow, confidenceHigh

Constraints:

  • Max 5 series
  • Max 2000 points
  • Requires monotonically increasing timestamps

When to Use: Trends, evolution over time, before/after effects

Category Bar Chart

Compare values across discrete categories.

Data Shape:

  • Required: category, value
  • Optional: seriesId, seriesLabel

Constraints:

  • Max 10 categories recommended
  • Supports grouped or stacked bars

When to Use: Comparing discrete items, rankings, grouped comparisons

Comparison Matrix

Heatmap-style matrix for multi-criteria comparison.

Data Shape:

  • Required: entityId, dimensionId, value

Constraints:

  • Best with 3-10 entities and 3-8 dimensions

When to Use: Multi-criteria decision analysis, option comparison, performance dashboards

Histogram

Show distribution of values across bins.

Data Shape:

  • Required: value
  • Optional: bins

Constraints:

  • Max 10,000 points
  • Automatically bins continuous data

When to Use: Data distribution analysis, identifying outliers, understanding value ranges

KPI Card

Display a single key metric with context.

Data Shape:

  • Required: value
  • Optional: label, unit, baseline, target, trend, explanation

Constraints:

  • One metric per card
  • Optional trend indicator (up/down/stable)

When to Use: Highlighting key metrics, goals, important single values

Guardrails

Composition Simplicity

Limits the number of visualizations per view to avoid cognitive overload.

  • Rule: Maximum 4 visualization components per view
  • Auto-applied: Yes
  • Enforcement: Warning message when exceeded

Data Provenance Transparency

Ensures all visualizations indicate their data source.

  • Rule: All visualizations must show data source and last update time
  • Auto-applied: Yes
  • Enforcement: Auto-adds data source indicator component

Uncertainty Quantification

Requires confidence intervals for projections and estimates.

  • Rule: Projections must show confidence intervals or uncertainty ranges
  • Auto-applied: Yes
  • Enforcement: Requires confidence bounds in data or adds uncertainty indicator

Integration Examples

Dashboard Generation

import { visualizationComponents, applyGuardrails } from "@info-ppaai-app/viz-deck";

export const DynamicDashboard = ({ userContext, data }) => {
  const layout = agentBuildLayout(userContext, data);
  const { adjustedLayout } = applyGuardrails(layout, { now: new Date() });
  
  return (
    <div className="grid gap-4">
      {adjustedLayout.instances.map((instance) => {
        const Viz = visualizationComponents[instance.visualizationId];
        const props = prepareChartProps(instance, data);
        return <Viz key={instance.componentId} {...props} />;
      })}
    </div>
  );
};

Conversational Analytics

import { AgentDialoguePanel, AgentReasoningPanel } from "@info-ppaai-app/viz-deck";

export const AgentChat = () => {
  const [messages, setMessages] = useState([]);
  const [trace, setTrace] = useState(null);

  const handleMessage = async (text: string) => {
    const response = await trpc.agent.generateVisualization.mutate({
      query: text,
      context: currentContext,
    });
    
    setTrace(response.reasoning);
    // Render visualization based on response
  };

  return (
    <div className="grid grid-cols-2 gap-4">
      <AgentDialoguePanel messages={messages} onSend={handleMessage} />
      <AgentReasoningPanel trace={trace} />
    </div>
  );
};

Playground

Visit /playground/deck in the web app to explore:

  • Component catalog with metadata
  • Data source definitions
  • Guardrail rules and enforcement
  • Interactive agent demo with mock data

Visit /playground/examples for live examples of all visualization types with real data.

Testing

The package includes comprehensive tests:

cd packages/viz-deck
bun test

Tests cover:

  • Guardrail logic and enforcement
  • Visualization catalog integrity
  • Component registry mapping

Architecture

  • Pure Presentational Components - No data fetching, props in → SVG out
  • Type-Safe - Full TypeScript support with strict types
  • Domain-Agnostic - Core library is generic; extend with domain overlays
  • Extensible - Add custom visualizations and guardrails

Best Practices

  1. Always apply guardrails before rendering agent-generated layouts
  2. Validate data shapes against visualization requirements
  3. Use TRPC for backend-to-frontend communication
  4. Keep reasoning traces for debugging and transparency
  5. Test with mock data before connecting to Databricks
  6. Handle errors gracefully when data doesn't match expected shape
  7. Log guardrail triggers for monitoring agent behavior

Source Code

  • Package: packages/viz-deck/
  • Playground: apps/web/src/app/(auth)/playground/deck/
  • Examples: apps/web/src/app/(auth)/playground/examples/
  • Integration Guide: packages/viz-deck/INTEGRATION.md

Versioning and Releases

Explanation of the versioning and release process using Semantic Release.

On this page

Viz DeckOverviewKey Features🎯 Visualization Vocabulary🛡️ Guardrails Engine🎨 React Components🎨 Theme System📊 Scientific StandardsInstallationBasic UsageRendering a VisualizationAgent Integration PatternAvailable VisualizationsTime Series ChartCategory Bar ChartComparison MatrixHistogramKPI CardGuardrailsComposition SimplicityData Provenance TransparencyUncertainty QuantificationIntegration ExamplesDashboard GenerationConversational AnalyticsPlaygroundTestingArchitectureBest PracticesRelated DocumentationSource Code