nteract/semiotic

Added

• semiotic/ai subpath — the AI-facing API surface as a first-class entry point. 211 KB gzip; the heuristic engine works without any LLM call, but every primitive returns LLM-friendly structured context so a model can ride on top. The entry covers four families of capability:
  • Recommendation. suggestCharts(data, options?) returns ranked chart suggestions for a profiled dataset and optional intent; each suggestion carries a runnable props object, an intent-score breakdown, the chart's rubric (familiarity / accuracy / precision), human-readable reasons[], and caveats[]. suggestDashboard returns a multi-panel composite covering distinct analytical intents (with intentsMissing for honesty about what the data can't show). suggestStretchCharts returns the literacy-growth surface — charts the audience is unfamiliar with but the data actually supports. scoreChart and explainCapabilityFit give single-chart introspection. useChartSuggestions is the React hook wrapping the same engine for live UI.
  • Profiling. profileData(data) returns a ChartDataProfile with candidate fields per role (x / y / size / category / series / time), distinct counts, monotonicity, structure detection (hierarchy / network / geo). diffProfile reports schema changes between two profiles. inferIntent is a zero-dependency regex classifier that maps natural-language phrases ("why is X different?", "compare these", "trend over time") to one of 13 built-in intents.
  • Audience calibration. AudienceProfile is a serializable per-organization config — familiarity (chart → 1-5 number map) and targets (chart → {direction: "increase" | "decrease", weight, reason}) — that biases recommendations toward what a specific audience already knows AND toward charts the organization is trying to grow into. Three built-in personas (executivePersona, analystPersona, dataScientistPersona) ship as starting points; bias is meaningful (target weight 2 = ±2.0 on a 5-point composite score) and visible (the audience's verbatim rationale string lands on reasons[] so the policy is auditable in the UI).
  • Capability descriptors per chart. Every chart now ships a <ChartName>.capability.ts next to its TSX, declaring family, rubric, fits(profile) → reason | null, intentScores, optional variants, caveats, and buildProps. The registry is runtime-extensible via registerChartCapability / unregisterChartCapability so consumers can add their own charts to the recommendation pool without forking the engine.
  • 13 built-in intents in intents.ts: trend, compare-series, compare-categories, rank, part-to-whole, distribution, correlation, flow, hierarchy, geo, outlier-detection, composition-over-time, change-detection. Each carries a descriptor with synonyms, alias phrases, and a default scorer; registerIntent extends the taxonomy at runtime.
• useChartInterrogation and useChartFocus hooks (semiotic/ai) — the headless conversational primitives. useChartInterrogation gives consumers a { ask, history, summary, annotations, loading, error, reset } surface; the consumer brings their own LLM via onQuery, and the hook supplies it with the profiled summary, the suggestion list, and the current focus datum as structured context. Returned annotations route directly to the chart's standard annotations prop so the AI's response can render as callouts, threshold lines, and bands, not just text. useChartFocus subscribes to the chart's observation store and returns the current point-of-focus ({ datum, x, y, source }), with configurable event-type filtering for sticky-focus UIs.
• semiotic-mcp server — Model Context Protocol server (npx semiotic-mcp) exposing renderChart, interrogateChart, suggestCharts, and diagnoseConfig as MCP tools so agents inside Claude Code, Cursor, Windsurf, and other MCP-aware environments can drive Semiotic directly. The interrogation tool returns the same statistical summary and AI-facing instructions the hook produces; the suggestion tool returns ranked structured content with runnable props.
• semiotic-ai CLI extensions — --doctor validates a {component, props, data} JSON spec against validateProps + diagnoseConfig; --schema emits the chart-schema JSON; --compact and --examples produce LLM-prompt-sized context. Pair with the MCP server for agent workflows that need both schema and validation in one place.
• Three case-study blog posts — /blog/charts-that-know-what-theyre-for (the recommendation engine and audience layer), /blog/anchored-conversations (point-anchored AI conversation via useChartFocus + useChartInterrogation), and /blog/live-conversational-dashboard (the streaming + interrogation + annotation composition). The three together describe the product surface 3.6.0 makes possible.

Changed

• AreaChart is now a single-series chart. Multi-series area overlays are an occlusion nightmare; the capability rejects the multi-series intent scores it previously claimed and buildProps subselects to the leading series (largest cumulative y) when the input has 2+ groups, surfacing a caveats[] line so the reader knows they're looking at one slice. Gradient (gradientFill: true, areaOpacity: 0.55) is the baseline default. trend score is 5 for clean single-series and 3 when subselected. LineChart.trend yields to AreaChart on single-series (4 vs AreaChart's 5) but still wins on multi-series (5 vs AreaChart's 3) because LineChart shows the whole dataset.
• DifferenceChart accepts 2+ series via top-2 subselection. Previously rejected anything other than seriesCount === 2; now picks the two series with the highest cumulative y from the input and emits a caveats[] line when subselecting from 3+ series. Same ordered-x guard the other time-series capabilities apply (xProvenance === "scatter" && !monotonicX is rejected) so the chart no longer shows up for scatter-shaped data with two categorical groups.
• Scatterplot and ConnectedScatterplot prefer the canonical 2-numeric form when a sequence axis is present. With a strong-x (time or named) AND 2+ other numerics in the dataset, both charts plot the two numerics against each other (revenue × profit) instead of recapitulating a line chart on the sequence axis. ConnectedScatterplot threads the sequence as orderAccessor so the path encodes temporal progression. ConnectedScatterplot's correlation intent scores 5 when canonical (vs 4 otherwise), and Scatterplot's correlation steps back to 4 when canonical is available so ConnectedScatterplot wins the tiebreak — both charts fit, but the one with the temporal annotation is strictly more informative.
• X_FIELD_HINT recognizes calendar-segment field names. The profiler's x-axis name regex now matches quarter, qtr, fiscal, and week in addition to the existing year / month / day / date / time / timestamp. Without this, data shaped as {quarter, revenue, region} fell into scatter-fallback provenance and series detection never fired — lineBy / areaBy were silently dropped and multi-series time-series charts zigzagged across regions.