Intelligence — Reader Grounding — Semiotic

Home · Getting Started · Charts · Features · Playground

This page requires JavaScript for interactive chart demos.

AI / Machine-readable docs: llms.txt · llms-full.txt · CLAUDE.md · schema.json · API Reference · Examples

View on GitHub · npx semiotic-ai for CLI access

Machine-readable page content

Canonical: https://semiotic.nteract.io/intelligence/reader-grounding

Agent-Reader Grounding

A capability descriptor says how a chart should be used — which intents it serves, what data it fits. That's the author side. The reader side is the inverse question: handed a specific chart, how does an agent (or a screen-reader user — they're the same consumer) recover what it means without seeing the pixels?buildReaderGrounding() answers that with a single payload.

It composes the three reception artifacts the accessibility layer already builds:

description — thelayered L1–L3 description(encoding, statistics, trend).
intent — the L4 communicative act: what the chart is asking the reader to do (This is an alerting chart; the spike at 11:00 is the point to investigate), derived from the chart's capability intent.
structure — thenavigation tree(chart → axes/series → datum) the agent can traverse node by node.

Try it

Each row is one part of the payload; the bottom line is the combined prose an LLM reads. Computed live in your browser.

descriptionA line chart of sales by month. sales ranges from 4,200 (Jan) to 9,100 (Apr), with a mean of 6,300 across 4 points. Overall sales rises from 4,200 (Jan) to a peak of 9,100 (Apr).

intent · trackingThis is a trend chart; read it for the trajectory of sales, which rises from 4,200 (Jan) to 9,100 (Apr).

structure7 navigable nodes — chart → axis / datum → datum

grounding.text (what an LLM reads):
A line chart of sales by month. sales ranges from 4,200 (Jan) to 9,100 (Apr), with a mean of 6,300 across 4 points. Overall sales rises from 4,200 (Jan) to a peak of 9,100 (Apr). This is a trend chart; read it for the trajectory of sales, which rises from 4,200 (Jan) to 9,100 (Apr).

Programmatic API

JSX

import { buildReaderGrounding } from "semiotic/utils" import { LineChartCapability } from "semiotic/ai" // optional, for precise L4 const grounding = buildReaderGrounding("LineChart", chartProps, { capability: LineChartCapability, // or a resolved { family, intentScores } audience: screenReaderAudience, // optional reception tuning }) grounding.description.text // "A line chart of sales by month. sales ranges from …" grounding.intent.act // "tracking" | "alerting" | "comparing" | … grounding.intent.sentence // "This is a trend chart; read it for the trajectory of sales …" grounding.structure // NavTreeNode (chart → axes/series → datum) grounding.physics // Physics runtime: seed, gravity, bodies, sensors, sediment, aggregates grounding.text // L1–L4 joined — feed this straight to the model // Token-budget mode: skip the structure buildReaderGrounding("PieChart", props, { includeStructure: false }) // Physics token-budget mode: omit simulation details buildReaderGrounding("PhysicsCustomChart", props, { physics: false })

Capability context: precise vs best-effort

The capability input drives the L4 act. Pass a full capability descriptor (from semiotic/ai) or a resolved{ family, intentScores } — asuggestion's already-resolved scores are the most precise source. Without any capability, the act is inferred from the component's family (a line chart reads as tracking), best-effort. A chart whose primary intents are computed at suggestion time (a line's trend scorer is a function) falls back to the family rather than mislabeling from leftover static scores.

Why a single payload

The thesis is that the non-visual reader and the AI reader face the same problem — meaning has to survive without the rendering — so they deserve the same evidence. Standardizing on one grounding payload means an agent that reads a chart faithfully and a screen reader that announces it are reading the same structured account, and an evaluator can check an agent's interpretation against it. It's the reader-side complement to thecapability descriptor and partialrender evidence for tool-using models.

Chart Descriptions — the L1–L3 + L4 layers
Structured Navigation — the structure half
Capability Matrix — the author-side descriptor
Interrogation — the LLM-backed Q&A path