Merge pull request #678 from nteract/support-ai

Support AI

Author: emeeks

.cursorrules

@@ -5,6 +5,47 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+#### AI Enablement — Phase 2
+
+Five features to deepen AI integration with Semiotic.
+
+**Compact System Prompt** (`ai/system-prompt.md`):
+- ~30-line prompt listing all 24 components grouped by data shape (flat array, hierarchical, network, realtime)
+- Marks required and distinguishing props per component
+- Designed for pasting into custom instructions or system prompts
+
+**Embeddings-Friendly Examples** (`ai/examples.md`):
+- Copy-paste-ready examples for 13 chart types covering all 4 data shapes
+- Each example includes import, realistic inline data, and key props annotation
+- Covers: LineChart (single + multi-line), Scatterplot, Heatmap, BarChart, StackedBarChart, GroupedBarChart, TreeDiagram, Treemap, CirclePack, ForceDirectedGraph, SankeyDiagram, ChordDiagram
+
+**`validateProps` Function** (exported from `semiotic/ai`):
+- `validateProps(componentName, props)` returns `{ valid: boolean, errors: string[] }`
+- Validates: component name, required props, prop types, enum values, unknown props (typo detection)
+- Delegates data shape validation to existing `validateArrayData`/`validateObjectData`/`validateNetworkData`
+- Static validation map covering all 24 components with per-prop type and enum constraints
+
+**CLI Tool** (`ai/cli.js`):
+- `npx semiotic-ai` — dumps CLAUDE.md to stdout
+- `npx semiotic-ai --schema` — dumps ai/schema.json
+- `npx semiotic-ai --compact` — dumps ai/system-prompt.md
+- `npx semiotic-ai --examples` — dumps ai/examples.md
+- Plain Node.js, no dependencies, no build step
+
+**MCP Server** (`ai/mcp-server.ts`):
+- Exposes 20 SVG-renderable chart components as MCP tools
+- Renders to static SVG via `ReactDOMServer.renderToStaticMarkup`
+- Uses `ai/schema.json` for tool definitions, `validateProps` for error reporting
+- Component registry maps names to React components
+- Separate build: `npm run build:mcp` (TypeScript → `ai/dist/`)
+- Usage: `npx semiotic-mcp` in Claude Desktop or any MCP client
+
+---
+
 ## [3.0.0-beta.1] - 2026-02-28
 
 ### Added

CHANGELOG.md

@@ -36,11 +36,22 @@ Frame API without giving up the simpler interface.
 Sankey diagrams, chord diagrams, tree layouts, treemaps, and circle packing
 are all React components with the same clean prop API as LineChart.
 
-**When to use something else.** Need a line chart for a dashboard?
-[Recharts](https://recharts.org) is simpler and has a larger ecosystem.
-Semiotic is built for projects that need network diagrams, statistical
-summaries, annotation systems, or custom mark rendering alongside
-standard charts — all in one library.
+**What Semiotic does that other libraries don't:**
+- Force-directed graphs, Sankey diagrams, chord diagrams, treemaps, and circle packing — as React components with the same clean API as LineChart
+- Real-time streaming charts rendered on canvas at 60fps
+- Built-in annotation system with hover, click, and custom annotation types
+- Server-side SVG rendering for email, OG images, and PDFs
+
+**When to use something else.** Need a standard line or bar chart for a dashboard?
+[Recharts](https://recharts.org) has a larger ecosystem and more community examples.
+Semiotic is built for projects that need network visualization, statistical summaries,
+or custom mark rendering — capabilities that general-purpose charting libraries don't offer.
+
+**AI-ready.** Semiotic ships with structured schemas (`ai/schema.json`), an
+`import from "semiotic/ai"` entry point, and an MCP server — all designed for
+LLM code generation. AI coding assistants can generate correct Semiotic code on
+the first try. Run `npx semiotic-ai --help` for CLI options or add `semiotic-mcp`
+to your MCP client config for tool-based chart rendering.
 
 ## Install
 
@@ -145,6 +156,7 @@ Import only what you need:
 import { LineChart } from "semiotic/xy"        // 125 KB (vs 218 KB full)
 import { BarChart } from "semiotic/ordinal"     // 140 KB
 import { ForceDirectedGraph } from "semiotic/network"  // 133 KB
+import { LineChart } from "semiotic/ai"           // HOC-only surface for AI generation
 ```
 
 ## TypeScript

CLAUDE.md

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+"use strict"
+
+const fs = require("fs")
+const path = require("path")
+
+const pkgRoot = path.resolve(__dirname, "..")
+
+const FILES = {
+  default: path.join(pkgRoot, "CLAUDE.md"),
+  "--schema": path.join(__dirname, "schema.json"),
+  "--compact": path.join(__dirname, "system-prompt.md"),
+  "--examples": path.join(__dirname, "examples.md"),
+}
+
+const HELP = `
+semiotic-ai — Dump Semiotic AI context to stdout
+
+Usage:
+  npx semiotic-ai              Print CLAUDE.md (full reference)
+  npx semiotic-ai --schema     Print ai/schema.json (tool definitions)
+  npx semiotic-ai --compact    Print ai/system-prompt.md (compact prompt)
+  npx semiotic-ai --examples   Print ai/examples.md (copy-paste examples)
+  npx semiotic-ai --help       Show this help message
+`.trim()
+
+const flag = process.argv[2]
+
+if (flag === "--help" || flag === "-h") {
+  console.log(HELP)
+  process.exit(0)
+}
+
+const filePath = flag ? FILES[flag] : FILES.default
+
+if (!filePath) {
+  console.error(`Unknown flag: ${flag}\n`)
+  console.error(HELP)
+  process.exit(1)
+}
+
+try {
+  const content = fs.readFileSync(filePath, "utf-8")
+  process.stdout.write(content)
+} catch (err) {
+  console.error(`Error reading ${filePath}: ${err.message}`)
+  process.exit(1)
+}

README.md

@@ -0,0 +1,58 @@
+/**
+ * Maps component names to their React component + category.
+ * Used by the MCP server to look up components for rendering.
+ */
+import type { ComponentType } from "react"
+
+import { LineChart } from "../src/components/charts/xy/LineChart"
+import { AreaChart } from "../src/components/charts/xy/AreaChart"
+import { StackedAreaChart } from "../src/components/charts/xy/StackedAreaChart"
+import { Scatterplot } from "../src/components/charts/xy/Scatterplot"
+import { BubbleChart } from "../src/components/charts/xy/BubbleChart"
+import { Heatmap } from "../src/components/charts/xy/Heatmap"
+
+import { BarChart } from "../src/components/charts/ordinal/BarChart"
+import { StackedBarChart } from "../src/components/charts/ordinal/StackedBarChart"
+import { GroupedBarChart } from "../src/components/charts/ordinal/GroupedBarChart"
+import { SwarmPlot } from "../src/components/charts/ordinal/SwarmPlot"
+import { BoxPlot } from "../src/components/charts/ordinal/BoxPlot"
+import { DotPlot } from "../src/components/charts/ordinal/DotPlot"
+import { PieChart } from "../src/components/charts/ordinal/PieChart"
+import { DonutChart } from "../src/components/charts/ordinal/DonutChart"
+
+import { ForceDirectedGraph } from "../src/components/charts/network/ForceDirectedGraph"
+import { ChordDiagram } from "../src/components/charts/network/ChordDiagram"
+import { SankeyDiagram } from "../src/components/charts/network/SankeyDiagram"
+import { TreeDiagram } from "../src/components/charts/network/TreeDiagram"
+import { Treemap } from "../src/components/charts/network/Treemap"
+import { CirclePack } from "../src/components/charts/network/CirclePack"
+
+export interface RegistryEntry {
+  component: ComponentType<any>
+  category: "xy" | "ordinal" | "network"
+}
+
+export const COMPONENT_REGISTRY: Record<string, RegistryEntry> = {
+  LineChart: { component: LineChart, category: "xy" },
+  AreaChart: { component: AreaChart, category: "xy" },
+  StackedAreaChart: { component: StackedAreaChart, category: "xy" },
+  Scatterplot: { component: Scatterplot, category: "xy" },
+  BubbleChart: { component: BubbleChart, category: "xy" },
+  Heatmap: { component: Heatmap, category: "xy" },
+
+  BarChart: { component: BarChart, category: "ordinal" },
+  StackedBarChart: { component: StackedBarChart, category: "ordinal" },
+  GroupedBarChart: { component: GroupedBarChart, category: "ordinal" },
+  SwarmPlot: { component: SwarmPlot, category: "ordinal" },
+  BoxPlot: { component: BoxPlot, category: "ordinal" },
+  DotPlot: { component: DotPlot, category: "ordinal" },
+  PieChart: { component: PieChart, category: "ordinal" },
+  DonutChart: { component: DonutChart, category: "ordinal" },
+
+  ForceDirectedGraph: { component: ForceDirectedGraph, category: "network" },
+  ChordDiagram: { component: ChordDiagram, category: "network" },
+  SankeyDiagram: { component: SankeyDiagram, category: "network" },
+  TreeDiagram: { component: TreeDiagram, category: "network" },
+  Treemap: { component: Treemap, category: "network" },
+  CirclePack: { component: CirclePack, category: "network" },
+}