semiotic 3.5.4 → 3.6.0

package/dist/components/data/DataSummarizer.d.ts

@@ -0,0 +1,45 @@
+import type { Datum } from "../charts/shared/datumTypes";
+export type FieldType = "numeric" | "categorical" | "date" | "unknown";
+export interface NumericFieldSummary {
+    type: "numeric";
+    min: number;
+    max: number;
+    mean: number;
+    median: number;
+}
+export interface DateFieldSummary {
+    type: "date";
+    min: string;
+    max: string;
+}
+export interface CategoricalFieldSummary {
+    type: "categorical";
+    distinctCount: number;
+    topValues: ReadonlyArray<{
+        value: string;
+        count: number;
+    }>;
+    distinctValues?: ReadonlyArray<string>;
+}
+export interface UnknownFieldSummary {
+    type: "unknown";
+}
+export type FieldSummary = NumericFieldSummary | DateFieldSummary | CategoricalFieldSummary | UnknownFieldSummary;
+export interface DataSummary {
+    rowCount: number;
+    fields: Record<string, FieldSummary>;
+    sample: ReadonlyArray<Datum>;
+}
+export interface SummarizeOptions {
+    maxDistinct?: number;
+    sampleSize?: number;
+    /** Scan up to this many rows when discovering field keys (handles ragged rows). */
+    keyScanRows?: number;
+}
+/**
+ * Summarize a dataset for an LLM. Returns row count, per-field statistics, and a small sample.
+ *
+ * Designed so a model can answer questions about ranges, peaks, distributions, and categories
+ * without seeing the full dataset.
+ */
+export declare function summarizeData(data: ReadonlyArray<Datum> | null | undefined, options?: SummarizeOptions): DataSummary;

package/dist/components/semiotic-ai.d.ts

@@ -66,6 +66,41 @@ export { serializeSelections, deserializeSelections } from "./export/selectionSe
 export type { SerializedSelections, SerializedSelection, SerializedFieldSelection } from "./export/selectionSerializer";
 export { fromVegaLite } from "./data/fromVegaLite";
 export type { VegaLiteSpec, VegaLiteEncoding } from "./data/fromVegaLite";
+export { useChartInterrogation } from "./store/useChartInterrogation";
+export type { UseChartInterrogationOptions, UseChartInterrogationResult, InterrogationContext, InterrogationFocus, InterrogationResult, InterrogationQuery, InterrogationMessage, } from "./store/useChartInterrogation";
+export { useChartFocus } from "./store/useChartFocus";
+export type { UseChartFocusOptions } from "./store/useChartFocus";
+export { summarizeData } from "./data/DataSummarizer";
+export type { DataSummary, FieldSummary, FieldType, NumericFieldSummary, DateFieldSummary, CategoricalFieldSummary, UnknownFieldSummary, SummarizeOptions, } from "./data/DataSummarizer";
+export { profileData } from "./ai/profileData";
+export type { ProfileDataOptions } from "./ai/profileData";
+export { suggestCharts, scoreChart, explainCapabilityFit } from "./ai/suggestCharts";
+export type { SuggestChartsOptions, RejectedCapability, ExplainCapabilityFitResult, } from "./ai/suggestCharts";
+export { inferIntent } from "./ai/inferIntent";
+export type { InferIntentResult } from "./ai/inferIntent";
+export { suggestDashboard } from "./ai/suggestDashboard";
+export type { DashboardPanel, DashboardSuggestion, SuggestDashboardOptions, } from "./ai/suggestDashboard";
+export { applyAudienceBias, effectiveFamiliarity, stretchFamiliarityCeiling, } from "./ai/audienceProfile";
+export type { AudienceProfile, AudienceTarget, AudienceBiasResult, } from "./ai/audienceProfile";
+export { executivePersona, analystPersona, dataScientistPersona, BUILT_IN_AUDIENCES, } from "./ai/audiences";
+export { suggestStretchCharts } from "./ai/suggestStretchCharts";
+export type { StretchSuggestion, SuggestStretchChartsOptions, } from "./ai/suggestStretchCharts";
+export { suggestStreamCharts, registerStreamChartCapability, unregisterStreamChartCapability, getStreamCapabilities, } from "./ai/suggestStreamCharts";
+export type { SuggestStreamChartsOptions } from "./ai/suggestStreamCharts";
+export type { StreamSchema, StreamFieldSchema, StreamFieldKind, StreamChartCapability, StreamIntentScorer, StreamSuggestion, } from "./ai/streamingTypes";
+export { diffProfile } from "./ai/diffProfile";
+export type { ProfileDiff, FieldTypeChange, PrimaryRoleChange, PrimaryRole } from "./ai/diffProfile";
+export { repairChartConfig } from "./ai/repairChartConfig";
+export type { RepairResult, RepairOkResult, RepairAlternativeResult, RepairUnknownResult, RepairOptions, } from "./ai/repairChartConfig";
+export { runQualityScorecard } from "./ai/qualityScorecard";
+export type { ScorecardFixture, ScorecardReport, PerCapabilityScore, PerFixtureScore, } from "./ai/qualityScorecard";
+export { CANONICAL_FIXTURES } from "./ai/qualityFixtures";
+export { useChartSuggestions } from "./ai/useChartSuggestions";
+export type { UseChartSuggestionsOptions, UseChartSuggestionsResult } from "./ai/useChartSuggestions";
+export { getCapabilities, getCapability, registerChartCapability, unregisterChartCapability, LineChartCapability, AreaChartCapability, StackedAreaChartCapability, ScatterplotCapability, ConnectedScatterplotCapability, BubbleChartCapability, QuadrantChartCapability, MultiAxisLineChartCapability, MinimapChartCapability, DifferenceChartCapability, CandlestickChartCapability, HeatmapCapability, BarChartCapability, GroupedBarChartCapability, StackedBarChartCapability, DotPlotCapability, PieChartCapability, DonutChartCapability, FunnelChartCapability, GaugeChartCapability, LikertChartCapability, SwimlaneChartCapability, HistogramCapability, BoxPlotCapability, SwarmPlotCapability, ViolinPlotCapability, RidgelinePlotCapability, ForceDirectedGraphCapability, SankeyDiagramCapability, ChordDiagramCapability, ProcessSankeyCapability, TreeDiagramCapability, TreemapCapability, CirclePackCapability, OrbitDiagramCapability, ChoroplethMapCapability, ProportionalSymbolMapCapability, FlowMapCapability, DistanceCartogramCapability, } from "./ai/chartCapabilities";
+export type { ChartCapability, ChartDataProfile, ChartFamily, ChartImportPath, ChartRubric, ChartVariant, FieldCandidate, FieldKind, FitResult, IntentScorer, Suggestion, } from "./ai/chartCapabilityTypes";
+export { listIntents, getIntent, registerIntent, BUILT_IN_INTENT_IDS } from "./ai/intents";
+export type { BuiltInIntentId, IntentId, IntentDescriptor } from "./ai/intents";
 export { useChartObserver } from "./store/useObservation";
 export type { UseChartObserverOptions, UseChartObserverResult } from "./store/useObservation";
 export type { ChartObservation, OnObservationCallback, HoverObservation, HoverEndObservation, BrushObservation, BrushEndObservation, SelectionObservation, SelectionEndObservation, ClickObservation, ClickEndObservation } from "./store/ObservationStore";

package/dist/components/semiotic-xy.d.ts

@@ -28,7 +28,7 @@ export type { ScatterplotProps } from "./charts/xy/Scatterplot";
 export type { ConnectedScatterplotProps } from "./charts/xy/ConnectedScatterplot";
 export type { BubbleChartProps } from "./charts/xy/BubbleChart";
 export type { HeatmapProps } from "./charts/xy/Heatmap";
-export type { QuadrantChartProps } from "./charts/xy/QuadrantChart";
+export type { QuadrantChartProps, QuadrantsConfig, QuadrantsConfigOverride, QuadrantConfig, CenterlineStyle } from "./charts/xy/QuadrantChart";
 export type { MultiAxisLineChartProps } from "./charts/xy/MultiAxisLineChart";
 export type { CandlestickChartProps } from "./charts/xy/CandlestickChart";
 export type { XYCustomChartProps } from "./charts/custom/XYCustomChart";

package/dist/components/semiotic.d.ts

@@ -25,7 +25,7 @@ import { RealtimeWaterfallChart } from "./charts/realtime/RealtimeWaterfallChart
 import { RealtimeHeatmap } from "./charts/realtime/RealtimeHeatmap";
 export { StreamXYFrame, StreamOrdinalFrame, StreamNetworkFrame, Scatterplot, ConnectedScatterplot, LineChart, AreaChart, DifferenceChart, StackedAreaChart, Heatmap, BubbleChart, BarChart, StackedBarChart, LikertChart, SwarmPlot, BoxPlot, Histogram, ViolinPlot, RidgelinePlot, DotPlot, ForceDirectedGraph, ChordDiagram, SankeyDiagram, ProcessSankey, TreeDiagram, PieChart, DonutChart, GaugeChart, FunnelChart, GroupedBarChart, SwimlaneChart, Treemap, CirclePack, OrbitDiagram, ScatterplotMatrix, MinimapChart, QuadrantChart, MultiAxisLineChart, CandlestickChart, XYCustomChart, NetworkCustomChart, OrdinalCustomChart, LinkedCharts, ThemeProvider, useTheme, exportChart, toConfig, fromConfig, toURL, fromURL, copyConfig, configToJSX, serializeSelections, deserializeSelections, fromVegaLite, ChartErrorBoundary, ChartContainer, ChartGrid, CategoryColorProvider, useCategoryColors, ContextLayout, DetailsPanel, Tooltip, MultiLineTooltip, normalizeTooltip, RingBuffer, IncrementalExtent, RealtimeLineChart, RealtimeTemporalHistogram, RealtimeHistogram, TemporalHistogram, RealtimeSwarmChart, RealtimeWaterfallChart, RealtimeHeatmap, createHatchPattern };
 export type { LegendLayout } from "./types/legendTypes";
-export { ScatterplotProps, ConnectedScatterplotProps, LineChartProps, AreaChartProps, SemanticGradientStop, DifferenceChartProps, StackedAreaChartProps, HeatmapProps, BubbleChartProps, BarChartProps, StackedBarChartProps, LikertChartProps, SwarmPlotProps, BoxPlotProps, HistogramProps, ViolinPlotProps, DotPlotProps, PieChartProps, DonutChartProps, GaugeChartProps, GaugeThreshold, FunnelChartProps, GroupedBarChartProps, SwimlaneChartProps, RidgelinePlotProps, OrbitDiagramProps, OrbitNode, ForceDirectedGraphProps, ChordDiagramProps, SankeyDiagramProps, ProcessSankeyProps, ProcessSankeyTick, TreeDiagramProps, TreemapProps, CirclePackProps, ScatterplotMatrixProps, MinimapChartProps, MinimapConfig, QuadrantChartProps, MultiAxisLineChartProps, MultiAxisSeriesConfig, CandlestickChartProps, QuadrantsConfig, QuadrantConfig, CenterlineStyle, BaseChartProps, AxisConfig, Accessor, ChartAccessor, ChartMode } from "./charts";
+export { ScatterplotProps, ConnectedScatterplotProps, LineChartProps, AreaChartProps, SemanticGradientStop, DifferenceChartProps, StackedAreaChartProps, HeatmapProps, BubbleChartProps, BarChartProps, StackedBarChartProps, LikertChartProps, SwarmPlotProps, BoxPlotProps, HistogramProps, ViolinPlotProps, DotPlotProps, PieChartProps, DonutChartProps, GaugeChartProps, GaugeThreshold, FunnelChartProps, GroupedBarChartProps, SwimlaneChartProps, RidgelinePlotProps, OrbitDiagramProps, OrbitNode, ForceDirectedGraphProps, ChordDiagramProps, SankeyDiagramProps, ProcessSankeyProps, ProcessSankeyTick, TreeDiagramProps, TreemapProps, CirclePackProps, ScatterplotMatrixProps, MinimapChartProps, MinimapConfig, QuadrantChartProps, MultiAxisLineChartProps, MultiAxisSeriesConfig, CandlestickChartProps, QuadrantsConfig, QuadrantsConfigOverride, QuadrantConfig, CenterlineStyle, BaseChartProps, AxisConfig, Accessor, ChartAccessor, ChartMode } from "./charts";
 export type { StreamXYFrameProps, StreamXYFrameHandle, StreamChartType, RuntimeMode, SceneNode, Changeset, StreamScales, StreamLayout, CurveType, CanvasRendererFn, XYFrameAxisConfig, BandConfig } from "./stream/types";
 export type { StreamRendererFn } from "./stream/renderers/types";
 export type { StreamOrdinalFrameProps, StreamOrdinalFrameHandle, OrdinalChartType, OrdinalScales, OrdinalSceneNode } from "./stream/ordinalTypes";

package/dist/components/store/useChartFocus.d.ts

@@ -0,0 +1,43 @@
+import type { ChartObservation } from "./ObservationStore";
+import type { InterrogationFocus } from "./useChartInterrogation";
+export interface UseChartFocusOptions {
+    /** Limit attention to a specific chart instance. Required when the page has more than one. */
+    chartId?: string;
+    /**
+     * Which observation types count as "focused." Default is hover + click +
+     * selection — anything that signals user attention. Set to ["click"] for
+     * sticky-focus UIs where hover doesn't change the AI's reference point.
+     */
+    types?: ChartObservation["type"][];
+}
+/**
+ * Convenience hook: returns the latest `InterrogationFocus` for use with
+ * `useChartInterrogation`'s `focus` option. Internally subscribes to the
+ * observation store and converts the latest matching observation into the
+ * focus shape.
+ *
+ * Pair with `<Chart onObservation={…} chartId="myChart" />` and an
+ * `<ObservationProvider>` ancestor.
+ *
+ * Returns `null` when no qualifying observation has fired yet.
+ *
+ * @example
+ * function ChartWithChat({ data }) {
+ *   const focus = useChartFocus({ chartId: "sales" })
+ *   const { ask, history, annotations } = useChartInterrogation({
+ *     data,
+ *     focus,                    // ← latest hovered/clicked datum threads in
+ *     onQuery: async (q, ctx) => {
+ *       // ctx.focus is the same `focus` value passed above
+ *       return askLLM({ question: q, focus: ctx.focus, summary: ctx.summary })
+ *     },
+ *   })
+ *   return (
+ *     <>
+ *       <LineChart data={data} chartId="sales" annotations={annotations} />
+ *       <YourChatUI history={history} onAsk={ask} />
+ *     </>
+ *   )
+ * }
+ */
+export declare function useChartFocus(options?: UseChartFocusOptions): InterrogationFocus | null;

package/dist/components/store/useChartInterrogation.d.ts

@@ -0,0 +1,141 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import { type DataSummary } from "../data/DataSummarizer";
+import type { ChartDataProfile, Suggestion } from "../ai/chartCapabilityTypes";
+import type { IntentId } from "../ai/intents";
+/**
+ * Identifies a single point of interest on the chart — typically the datum
+ * the user is currently hovering, clicked, or otherwise focused on. When
+ * provided, the LLM gets the explicit signal that the user is asking
+ * "about *this specific point*" rather than the chart at large.
+ */
+export interface InterrogationFocus {
+    /** The row the user is focused on. */
+    datum: Datum;
+    /** Pixel x coordinate, when known. Useful for anchoring response annotations. */
+    x?: number;
+    /** Pixel y coordinate, when known. */
+    y?: number;
+    /** Optional source label — "hover" / "click" / "selection". Surfaces in the LLM prompt. */
+    source?: "hover" | "click" | "selection" | "manual";
+}
+export interface InterrogationContext {
+    /** The data extracted from the chart (or whatever caller passed in). */
+    data: ReadonlyArray<Datum>;
+    /** Statistical summary, ready to send to an LLM. */
+    summary: DataSummary;
+    /** Shape profile — present when `includeProfile` or `includeSuggestions` is enabled. */
+    profile?: ChartDataProfile;
+    /** Heuristic chart suggestions — present when `includeSuggestions` is enabled. */
+    suggestions?: ReadonlyArray<Suggestion>;
+    /** Optional caller-supplied chart component name (e.g. "LineChart"). */
+    componentName?: string;
+    /** Optional caller-supplied chart props (accessor names, scales, etc.). */
+    props?: Record<string, unknown>;
+    /**
+     * The current focused datum — what the user is interactively pointing at.
+     * Lets the LLM tailor responses to a specific point ("why is *this* one
+     * higher than the rest?") and to anchor visual responses (callouts,
+     * comments) back at the same coordinates.
+     */
+    focus?: InterrogationFocus;
+}
+export interface InterrogationResult {
+    /** Natural-language answer to display to the user. */
+    answer: string;
+    /** Optional Semiotic annotations to overlay on the chart. */
+    annotations?: ReadonlyArray<Datum>;
+}
+export type InterrogationQuery = (query: string, context: InterrogationContext) => Promise<InterrogationResult>;
+export interface InterrogationMessage {
+    role: "user" | "assistant";
+    text: string;
+}
+export interface UseChartInterrogationOptions {
+    /** Data backing the chart. Use whatever shape the chart consumes (rows, nodes, etc.). */
+    data: ReadonlyArray<Datum> | null | undefined;
+    /** Async handler — typically calls your LLM with the query + summary. */
+    onQuery: InterrogationQuery;
+    /** Annotations to seed the merged set (e.g. existing chart annotations). */
+    initialAnnotations?: ReadonlyArray<Datum>;
+    /** Optional context passed through to onQuery for richer prompts. */
+    componentName?: string;
+    /** Optional context passed through to onQuery. */
+    props?: Record<string, unknown>;
+    /**
+     * Include the shape `profile` in the interrogation context. Required to let an LLM
+     * reason about candidate axes, distinct counts, hierarchy/network/geo detection, etc.
+     */
+    includeProfile?: boolean;
+    /**
+     * Include heuristic chart `suggestions` in the interrogation context. Implies `includeProfile`.
+     * Lets an LLM answer "would another chart show this better?" without re-deriving rules.
+     */
+    includeSuggestions?: boolean;
+    /** When `includeSuggestions` is true, rank by this intent. */
+    suggestionsIntent?: IntentId | IntentId[];
+    /** When `includeSuggestions` is true, cap the suggestion list. Default 5. */
+    suggestionsMax?: number;
+    /**
+     * The point on the chart the user is currently focused on. Forwarded to
+     * onQuery so an LLM can answer "about this specific datum" rather than
+     * "about the chart in general." Typically wired from a chart's
+     * `onObservation` callback or the convenience `useChartFocus` hook.
+     */
+    focus?: InterrogationFocus | null;
+}
+export interface UseChartInterrogationResult {
+    /** Ask a question. Updates history, annotations, loading, and error. */
+    ask: (query: string) => Promise<void>;
+    /**
+     * Append an AI-initiated message to the transcript without a user query.
+     *
+     * Use for proactive narration — a streaming watcher that detected an
+     * anomaly, a background analysis that surfaced an insight, an LLM that
+     * decided to volunteer information mid-session. Synchronous; no `onQuery`
+     * call. Annotations merge into the chart's `annotations` array like
+     * any other AI response.
+     *
+     * @example
+     * announce({
+     *   text: "Spike detected at 14:32 — 3.2σ above rolling mean.",
+     *   annotations: [{ type: "callout", ts: now, value: 850, note: "Slow query?" }],
+     * })
+     */
+    announce: (message: {
+        text: string;
+        annotations?: ReadonlyArray<Datum>;
+    }) => void;
+    /** Conversation history, oldest first. */
+    history: ReadonlyArray<InterrogationMessage>;
+    /** Statistical summary of the data — memoized, safe to pass to a prompt. */
+    summary: DataSummary;
+    /** Merged annotations: initial + latest AI response. Pass to the chart's `annotations` prop. */
+    annotations: ReadonlyArray<Datum>;
+    /** True while onQuery is in flight. */
+    loading: boolean;
+    /** Last error from onQuery, if any. */
+    error: Error | null;
+    /** Clear history, AI annotations, and error. */
+    reset: () => void;
+}
+/**
+ * Headless interrogation hook — a sibling to `useChartObserver`.
+ *
+ * Generates an LLM-friendly statistical summary of your chart's data, runs queries through
+ * a caller-supplied `onQuery`, and merges any annotations the response returns so the chart
+ * can highlight what the model is talking about.
+ *
+ * The hook owns no UI. Render whatever input/transcript surface fits your product.
+ *
+ * @example
+ * const { ask, history, annotations, loading } = useChartInterrogation({
+ *   data,
+ *   onQuery: async (q, ctx) => {
+ *     const res = await fetch("/api/chat", { method: "POST", body: JSON.stringify({ q, summary: ctx.summary }) })
+ *     return res.json()
+ *   },
+ * })
+ *
+ * <LineChart data={data} annotations={annotations} ... />
+ */
+export declare function useChartInterrogation(options: UseChartInterrogationOptions): UseChartInterrogationResult;