a4ui-agent 0.1.0__tar.gz

a4ui_agent-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Local Entra token for the swel copilot (Lever A) — NEVER commit
+.doc/swel/.copilot_token
+.copilot_token
+
+# Secrets / credentials
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.pfx
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+
+# Terraform (state + downloaded provider binaries are not source)
+.terraform/
+*.tfstate
+*.tfstate.*
+*.tfvars
+
+# Binaries
+*.exe
+*.dll
+*.so
+*.dylib
+
+# Node
+node_modules/
+dist/
+build/
+
+# OS / editor
+.DS_Store
+Thumbs.db

a4ui_agent-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.5
+Name: a4ui-agent
+Version: 0.1.0
+Summary: Agent-side A2UI chart runtime for @haystackedai/a4react clients. One function (answer(prompt)->rows,answer) gives an AgentCore agent a validated, drillable A2UI chart surface — no a2ui-core, catalog assembly, surface-message building, validation or rechart/drill wiring to write. Contract (catalogId + schemas) is baked, overridable.
+Requires-Python: >=3.10
+Requires-Dist: a2ui-core<0.3.0,>=0.2.0
+Requires-Dist: bedrock-agentcore>=1.9.1
+Requires-Dist: pydantic>=2.7
+Requires-Dist: strands-agents>=1.15.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# a4ui-agent
+
+Agent-side A2UI chart runtime for [`@haystackedai/a4react`](../A4React) clients.
+
+Write one function — `answer(prompt) -> (rows, columns, text)` — and
+`make_a4ui_agent(answer)` returns a ready AgentCore app that turns a prompt into a
+validated, drillable A2UI chart surface. No `a2ui-core`, catalog assembly, surface-message
+building, validation, or rechart/drill wiring to write. The contract (catalogId + schemas)
+is baked and overridable.
+
+```python
+from a4ui_agent import make_a4ui_agent
+
+def answer(prompt: str):
+    rows, columns, text = my_data_lookup(prompt)
+    return rows, columns, text
+
+app = make_a4ui_agent(answer)          # deterministic charts, zero config
+if __name__ == "__main__":
+    app.run()
+```
+
+See **instruction_agent.md** for the full DO list, LLM mode, and the contract rules.

a4ui_agent-0.1.0/README.md

@@ -0,0 +1,23 @@
+# a4ui-agent
+
+Agent-side A2UI chart runtime for [`@haystackedai/a4react`](../A4React) clients.
+
+Write one function — `answer(prompt) -> (rows, columns, text)` — and
+`make_a4ui_agent(answer)` returns a ready AgentCore app that turns a prompt into a
+validated, drillable A2UI chart surface. No `a2ui-core`, catalog assembly, surface-message
+building, validation, or rechart/drill wiring to write. The contract (catalogId + schemas)
+is baked and overridable.
+
+```python
+from a4ui_agent import make_a4ui_agent
+
+def answer(prompt: str):
+    rows, columns, text = my_data_lookup(prompt)
+    return rows, columns, text
+
+app = make_a4ui_agent(answer)          # deterministic charts, zero config
+if __name__ == "__main__":
+    app.run()
+```
+
+See **instruction_agent.md** for the full DO list, LLM mode, and the contract rules.

a4ui_agent-0.1.0/instruction_agent.md

@@ -0,0 +1,63 @@
+# a4ui-agent
+
+The agent-side twin of `@haystackedai/a4react`. a4react hides A2UI from the **frontend**
+dev; this hides it from the **agent** dev.
+
+*What the package gives you:*
+- `make_a4ui_agent` — one call returns a ready AgentCore app (the whole turn: prompt → data → validated A2UI chart surface, streamed in the frames a4react parses)
+- `Contract`, `DEFAULT_CONTRACT`, `DEFAULT_CATALOG_ID` — the baked contract + the type to override it
+- `build_catalog`, `SurfaceEngine`, `build_series`, `pick_and_shape`, `format_answer` — lower-level blocks (only if you assemble it yourself)
+
+*What it hides (you write none of these):*
+- a2ui-core, catalog assembly, the A2UI_Chart schema, surface-message building, validation, rechart/drill routing, the AgentCore entrypoint.
+
+*What it does NOT bring:*
+- your data (you supply `answer()`), a deployment, or an LLM (optional — deterministic by default).
+
+*What the agent dev must do:*
+
+1. Install:
+   `pip install a4ui-agent`
+
+2. Write ONE function — your only job — returning the rows for a prompt:
+   ```python
+   def answer(prompt: str):
+       rows, columns, text = my_data_lookup(prompt)   # SQL, API, anything
+       return rows, columns, text        # or (rows, text) · or {"rows":…, "columns":…, "answer":…}
+   ```
+   `rows` = list of dicts; `columns` optional (inferred from the first row); `text` = the prose answer. Sync or async both work.
+
+3. Build the agent — nothing else to stand up:
+   ```python
+   from a4ui_agent import make_a4ui_agent
+   app = make_a4ui_agent(answer)
+   # app = make_a4ui_agent(answer, model="global.anthropic.claude-sonnet-4-5-20250929-v1:0")
+   ```
+   No `model` = deterministic chart choice (zero config). A `model` id = the LLM picks chart type + column roles (your data still stays in code, never sent to the model).
+
+4. Run it (AgentCore):
+   ```python
+   if __name__ == "__main__":
+       app.run()
+   ```
+   The package handles `rechart` (layout-only re-emit) and `drill` (scoped re-query) actions automatically.
+
+That is all. The chart renders in any `@haystackedai/a4react` client pointed at this agent — provided the contract byte-matches (step 5).
+
+## Contract — must byte-match the client
+The package bakes `DEFAULT_CONTRACT` (catalogId + plotType enum + series shape), so a client on the **same** default just works. For a custom catalog, pass your own and keep BOTH ends in sync:
+```python
+from a4ui_agent import make_a4ui_agent, Contract
+make_a4ui_agent(answer, contract=Contract(
+    catalog_id="https://…/catalog.json",   # == the client's catalogId
+    control_model=MyControl,                # pydantic: has a plotType Literal
+    datashape_model=MySeries,
+    control_version="…", datashape_version="…",
+))
+```
+Both ends are regenerated from one `A2UI_catalog_src` build — don't hand-edit either side.
+
+## If no chart shows
+- **Blank client** — the client renders nothing until a surface arrives; it must `send()` a prompt AND reach this agent's endpoint. a4ui-agent is the agent half only.
+- **"Catalog not found" on the client** — the baked contract here and the client's `catalogId` differ. Match them (step 5).
+- **Deployment** — `app.run()` is the AgentCore runtime; it still has to be deployed where the client's `/api/v1/a2ui` gateway can invoke it.

a4ui_agent-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "a4ui-agent"
+version = "0.1.0"
+description = "Agent-side A2UI chart runtime for @haystackedai/a4react clients. One function (answer(prompt)->rows,answer) gives an AgentCore agent a validated, drillable A2UI chart surface — no a2ui-core, catalog assembly, surface-message building, validation or rechart/drill wiring to write. Contract (catalogId + schemas) is baked, overridable."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "a2ui-core >= 0.2.0, < 0.3.0",
+    "bedrock-agentcore >= 1.9.1",
+    "strands-agents >= 1.15.0",
+    "pydantic >= 2.7",
+]
+
+[project.optional-dependencies]
+# The deterministic path needs none of these; dev installs what their answer() uses.
+dev = ["pytest", "pytest-asyncio"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/a4ui_agent"]

a4ui_agent-0.1.0/src/a4ui_agent/__init__.py

@@ -0,0 +1,31 @@
+# a4ui-agent — public surface.
+#
+# The agent-side twin of @haystackedai/a4react, WITH the runtime included. A4 hid the
+# whole A2UI loop from the FRONTEND dev; this hides it from the AGENT dev. They write
+# ONE function — answer(prompt) -> (rows, columns, text) — and get a ready AgentCore
+# app that turns a prompt into a validated, drillable A2UI chart surface. No a2ui-core,
+# no catalog assembly, no surface messages, no validation, no rechart/drill wiring.
+#
+#   from a4ui_agent import make_a4ui_agent
+#   app = make_a4ui_agent(answer)              # deterministic charts, zero config
+#   app = make_a4ui_agent(answer, model="…")   # LLM-chosen charts
+#
+# The contract (catalogId + schemas) is baked (DEFAULT_CONTRACT) so install → it works;
+# pass a custom Contract to match a client on a different catalog.
+
+# The one-call runtime.
+from ._runtime import make_a4ui_agent
+
+# The contract: the baked default + the type for overriding it.
+from ._contract import Contract, DEFAULT_CONTRACT, DEFAULT_CATALOG_ID
+
+# Lower-level building blocks (for an agent that assembles the catalog/surface itself).
+from ._catalog import build_catalog, BuiltCatalog
+from ._surface import SurfaceEngine, build_series, pick_and_shape, format_answer
+
+__all__ = [
+    "make_a4ui_agent",
+    "Contract", "DEFAULT_CONTRACT", "DEFAULT_CATALOG_ID",
+    "build_catalog", "BuiltCatalog",
+    "SurfaceEngine", "build_series", "pick_and_shape", "format_answer",
+]

a4ui_agent-0.1.0/src/a4ui_agent/_catalog.py

@@ -0,0 +1,66 @@
+"""Assemble the A2UI catalog + validator from a Contract — the a2ui-core plumbing.
+
+Hidden from the dev entirely. We take the contract's control/datashape models, build
+the custom A2UI_Chart component against a2ui-core's CatalogComponentCommon, add it to
+a2ui-core's BasicCatalog (v0_9), and build the PayloadValidator run on every surface
+component before emit. This is the agent-side mirror of a4react's A4_makeCatalog.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, get_args
+
+from pydantic import BaseModel, Field, create_model
+
+from a2ui.core import PayloadValidator, STRICT_VALIDATION
+from a2ui.core.basic_catalog.v0_9 import BasicCatalog
+from a2ui.core.basic_catalog.v0_9.components import CatalogComponentCommon
+from a2ui.core.catalog import ModelComponentApi
+from a2ui.core.schema.v0_9.common_types import DataBinding, DynamicString
+
+from ._contract import Contract
+
+
+@dataclass
+class BuiltCatalog:
+    """Everything the surface engine needs, derived once from the Contract."""
+    catalog_id: str
+    validator: PayloadValidator
+    series_model: type[BaseModel]        # the datashape model (A2UIChartSeries)
+    plot_types: list[str]
+    schema_desc: str
+
+
+def build_catalog(contract: Contract) -> BuiltCatalog:
+    """Build the full catalog (basic + A2UI_Chart) and its validator from the contract."""
+    # plotType vocabulary comes FROM the contract's control model — single-sourced.
+    plot_type_annotation = contract.control_model.model_fields["plotType"].annotation
+    series_model = contract.datashape_model
+
+    # Build the custom component dynamically from the injected schemas. create_model
+    # lets plotType/series be contract-driven types (a class body can't take type vars).
+    chart_component: type[BaseModel] = create_model(
+        "A2UIChartComponent",
+        __base__=CatalogComponentCommon,
+        component=(Literal["A2UI_Chart"], "A2UI_Chart"),
+        plotType=(plot_type_annotation, Field(..., description="The chart type to render.")),
+        title=(DynamicString | None, Field(None, description="Optional chart title.")),
+        series=(series_model | DataBinding, Field(
+            ..., description="The chart data (a {path} binding, or an inline series object).")),
+    )
+    chart_api = ModelComponentApi(chart_component)
+
+    # Start from a2ui-core's basic catalog (standard components); set our catalog id;
+    # add the custom A2UI_Chart → the full catalog.
+    catalog = BasicCatalog()
+    catalog.catalog_id = contract.catalog_id
+    catalog.components["A2UI_Chart"] = chart_api
+    validator = PayloadValidator(catalog, STRICT_VALIDATION)
+
+    plot_types = list(get_args(plot_type_annotation))
+    required = [n for n, f in chart_component.model_fields.items() if f.is_required()]
+    schema_desc = (
+        f"A2UI_Chart{{plotType∈{plot_types}, title?:DynamicString, "
+        f"series:A2UIChartSeries|DataBinding}} required={required}"
+    )
+    return BuiltCatalog(contract.catalog_id, validator, series_model, plot_types, schema_desc)

a4ui_agent-0.1.0/src/a4ui_agent/_contract.py

@@ -0,0 +1,42 @@
+"""The contract — catalogId + the two schema models + versions — INJECTED, not hard-coded.
+
+The contract is the one thing the agent package and the frontend package
+(@haystackedai/a4react) MUST byte-match: the `catalog_id` the client puts on
+createSurface, the plotType vocabulary, and the series shape. The package ships a
+DEFAULT_CONTRACT (the baked A2UI_catalog_src generation) so install → it works; a host
+with its own catalog passes a custom Contract to make_a4ui_agent(..., contract=...).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pydantic import BaseModel
+
+from ._generated.chart_control import A2UIChartControl
+from ._generated.chart_datashape import A2UIChartDataShape
+from ._generated.contract_version import CONTROL_VERSION, DATASHAPE_VERSION
+
+# The default catalog id. MUST byte-match the client's createSurface.catalogId
+# (@haystackedai/a4react's catalogId / the frontend's A2UI_CATALOG_ID).
+DEFAULT_CATALOG_ID = "https://voa.sanofi.com/a2ui/catalogs/voa/v0_9/catalog.json"
+
+
+@dataclass(frozen=True)
+class Contract:
+    """What the agent and client agree on. `control_model` must expose a `plotType`
+    field (a Literal enum); `datashape_model` is the series shape. Both are Pydantic
+    models, mirroring @haystackedai/a4react's injected controlSchema/datashapeSchema."""
+    catalog_id: str
+    control_model: type[BaseModel]
+    datashape_model: type[BaseModel]
+    control_version: str
+    datashape_version: str
+
+
+# The baked default — the A2UI_catalog_src generation this package ships.
+DEFAULT_CONTRACT = Contract(
+    catalog_id=DEFAULT_CATALOG_ID,
+    control_model=A2UIChartControl,
+    datashape_model=A2UIChartDataShape,
+    control_version=CONTROL_VERSION,
+    datashape_version=DATASHAPE_VERSION,
+)

a4ui_agent-0.1.0/src/a4ui_agent/_generated/__init__.py

@@ -0,0 +1,8 @@
+"""Baked contract artifacts — the package's DEFAULT contract.
+
+GENERATED from A2UI_catalog_src/chart.*.json by A2UI_gen_pydantic.py. These are the
+single-source contract pieces the agent and the frontend (@haystackedai/a4react) must
+byte-match: the plotType vocabulary, the series shape, and the contract versions. The
+package SHIPS them so a dev who installs it gets a working contract with no setup;
+override via a4ui_agent.Contract only for a custom catalog.
+"""

a4ui_agent-0.1.0/src/a4ui_agent/_generated/chart_control.py

@@ -0,0 +1,17 @@
+# GENERATED from A2UI_catalog_src/chart.control.json by A2UI_gen_pydantic.py — DO NOT EDIT.
+# Change the JSON and re-run the script to regenerate.
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class A2UIChartControl(BaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    plotType: Literal[
+        'scatter', 'bar', 'column', 'line', 'area', 'pie', 'donut', 'KPI_CARD', 'table'
+    ] = Field(..., description='The chart type to render.')

a4ui_agent-0.1.0/src/a4ui_agent/_generated/chart_datashape.py

@@ -0,0 +1,35 @@
+# GENERATED from A2UI_catalog_src/chart.datashape.json by A2UI_gen_pydantic.py — DO NOT EDIT.
+# Change the JSON and re-run the script to regenerate.
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Point(BaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    x: float
+    y: float
+
+
+class Item(BaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    label: str
+    value: float
+
+
+class A2UIChartDataShape(BaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    points: list[Point] | None = None
+    items: list[Item] | None = None
+    value: float | str | None = None
+    columns: list[str] | None = None
+    rows: list[dict[str, Any]] | None = None

a4ui_agent-0.1.0/src/a4ui_agent/_generated/contract_version.py

@@ -0,0 +1,4 @@
+# GENERATED from A2UI_catalog_src/chart.*.json by A2UI_gen_pydantic.py — DO NOT EDIT.
+# Change the JSON and re-run the script to regenerate.
+CONTROL_VERSION = "20261007.01"
+DATASHAPE_VERSION = "20261007.01"

a4ui_agent-0.1.0/src/a4ui_agent/_prompt.py

@@ -0,0 +1,56 @@
+"""System prompt + few-shot for LLM-generated A2UI surfaces — DATA-OUTSIDE variant.
+
+Only used when make_a4ui_agent(..., model=...) opts into LLM chart composition. The
+model composes the surface STRUCTURE and picks the chart, but never touches the data:
+it sees only the question + column NAMES and returns {surface, roles}. Code then fills
+updateDataModel (series from the real rows, note from the answer) behind the {path}
+bindings — so the dev's values reach the chart unaltered.
+"""
+from __future__ import annotations
+
+import json
+
+# The exact OUTPUT shape the model must return: the 2 structure messages (NO data,
+# NO updateDataModel) + a roles map. Code appends updateDataModel afterwards.
+_ROLE = (
+    "You are a data-visualization agent. Given a user question and the COLUMN NAMES of a "
+    "SQL result, you compose ONE A2UI chart surface. You never receive or emit the data "
+    "values — the system fills those in from the real SQL rows behind the {path} bindings."
+)
+
+_RULES = """Output ONLY a JSON object (no prose, no code fences) with exactly two keys:
+
+"surface": an array of exactly TWO A2UI messages — createSurface and updateComponents —
+           copied EXACTLY from the example (same surfaceId, same catalogId, same component
+           tree with Text bound to /note and A2UI_Chart bound to /series). Change ONLY the
+           A2UI_Chart `plotType`.
+"roles":   which columns feed the chart, chosen EXACTLY from the provided column names.
+
+Do NOT emit updateDataModel, data values, series arrays, or note text — the system adds
+updateDataModel (series from the SQL rows, note from the ANSWER) itself.
+
+Pick `plotType` to fit the data, and set the matching roles (null for unused):
+  * category + number        -> "column" (few) or "bar" (many/long labels/ranking); set label_column + value_column
+  * one row, one number      -> "KPI_CARD"; set value_column
+  * time + number            -> "line" (trend) or "area"; set x_column=time col + value_column
+  * parts of a whole (<=8)   -> "pie" / "donut"; set label_column + value_column
+  * two numeric columns      -> "scatter"; set x_column + y_column
+  * doesn't fit a chart      -> "table"; roles may be null"""
+
+
+def build_system_prompt(catalog_id: str) -> str:
+    """Role + rules + the exact output example (structure + roles, no data)."""
+    fewshot_output = {
+        "surface": [
+            {"version": "v0.9", "createSurface": {"surfaceId": "A2UI_dev", "catalogId": catalog_id}},
+            {"version": "v0.9", "updateComponents": {"surfaceId": "A2UI_dev", "components": [
+                {"id": "root", "component": "Column", "children": ["n", "c"]},
+                {"id": "n", "component": "Text", "text": {"path": "/note"}},
+                {"id": "c", "component": "A2UI_Chart", "plotType": "bar", "series": {"path": "/series"}},
+            ]}},
+        ],
+        "roles": {"label_column": "ACTIVITY_SCHEDULE_STATUS", "value_column": "ACTIVITY_COUNT",
+                  "x_column": None, "y_column": None},
+    }
+    example = json.dumps(fewshot_output, indent=2)
+    return f"{_ROLE}\n\n{_RULES}\n\n---BEGIN EXAMPLE OUTPUT---\n{example}\n---END EXAMPLE OUTPUT---"

a4ui_agent-0.1.0/src/a4ui_agent/_runtime.py

@@ -0,0 +1,159 @@
+"""make_a4ui_agent — the full agent runtime, packaged.
+
+This is what the package adds over a surface-builder library: the dev no longer wires
+a catalog, builds surface messages, validates, handles rechart/drill, or hand-rolls the
+AgentCore entrypoint. They write ONE function — answer(prompt) -> (rows, columns, text)
+— and get a ready BedrockAgentCoreApp whose turn mirrors nslswel's: prompt → data →
+A2UI surface, streamed in the exact frames @haystackedai/a4react parses.
+
+    from a4ui_agent import make_a4ui_agent
+
+    def answer(prompt: str):
+        rows, columns, text = my_data_lookup(prompt)
+        return rows, columns, text
+
+    app = make_a4ui_agent(answer)        # deterministic charts, zero config
+    # app = make_a4ui_agent(answer, model="global.anthropic.claude-sonnet-4-5-...")  # LLM-chosen charts
+    if __name__ == "__main__":
+        app.run()
+"""
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+
+from ._catalog import build_catalog
+from ._contract import Contract, DEFAULT_CONTRACT
+from ._surface import SurfaceEngine, format_answer, pick_and_shape
+from ._trace import trace_frame
+
+
+def _normalize_dataset(res) -> dict:
+    """Accept the dev's answer() return in any ergonomic form and normalize to
+    {ok, rows, columns, answer, error}. Columns are inferred from the first row if
+    the dev didn't supply them."""
+    rows = columns = answer = error = None
+    if isinstance(res, dict):
+        rows, columns, answer, error = res.get("rows"), res.get("columns"), res.get("answer"), res.get("error")
+    elif isinstance(res, (tuple, list)):
+        if len(res) == 3:
+            rows, columns, answer = res
+        elif len(res) == 2:
+            rows, answer = res
+        elif res:
+            rows = res[0]
+    else:
+        rows = res
+    rows = list(rows or [])
+    if not columns:
+        columns = list(rows[0].keys()) if rows and isinstance(rows[0], dict) else []
+    return {"ok": bool(rows), "rows": rows, "columns": list(columns or []),
+            "answer": answer or "", "error": error}
+
+
+async def _call_answer(answer, prompt: str) -> dict:
+    """Call the dev's answer() — async or sync (sync runs off-thread) — and normalize."""
+    if inspect.iscoroutinefunction(answer):
+        res = await answer(prompt)
+    else:
+        res = await asyncio.to_thread(answer, prompt)
+        if inspect.isawaitable(res):
+            res = await res
+    return _normalize_dataset(res)
+
+
+async def _run_turn(payload, context, *, engine: SurfaceEngine, answer, contract: Contract, use_llm: bool):
+    """The data turn: handle rechart/version/drill actions, else prompt → data → surface."""
+    name = engine.agent_name
+    action = payload.get("action") if isinstance(payload, dict) else None
+
+    # rechart — layout-only re-emit; the client already holds the data model.
+    if action and action.get("name") == "rechart":
+        plot_type = (action.get("context") or {}).get("plotType", "bar")
+        yield trace_frame(name, "rechart action — layout-only re-emit (no data)",
+                          f"action={json.dumps(action)} → plotType={plot_type}")
+        yield {"kind": "a2ui", "a2ui_messages": [engine.rechart_message(plot_type)], "usage": {}}
+        return
+
+    # version — contract handshake; the client compares to its baked version.
+    if action and action.get("name") == "version":
+        yield {"kind": "version", "version": {"control": contract.control_version,
+                                              "datashape": contract.datashape_version}}
+        return
+
+    session_id = getattr(context, "session_id", "a2ui-session")
+    prompt = payload.get("prompt", "") if isinstance(payload, dict) else ""
+
+    # drill — a scoped NEW data turn. The click carries the clicked value + the original
+    # question (no server memory); compose a scoped follow-up and run it below.
+    if action and action.get("name") == "drill":
+        ctx = action.get("context") or {}
+        value, question = ctx.get("value") or "", ctx.get("question") or ""
+        prompt = (f"{question}\n\nNow focus ONLY on '{value}' and show its breakdown one level "
+                  f"deeper (e.g. by phase, status, or sub-category) as a chart.")
+        yield trace_frame(name, f"drill action → scoped new query for '{value}'", f"composed prompt: {prompt!r}")
+
+    yield trace_frame(f"{name} → data source", "fetch the data for the prompt", f"prompt={prompt!r}")
+    dataset = await _call_answer(answer, prompt)
+
+    if dataset["ok"] and dataset["rows"]:
+        yield trace_frame(f"data source → {name}",
+                          f"returned {len(dataset['rows'])} rows ({len(dataset['columns'])} cols)",
+                          json.dumps(dataset["rows"][:10], default=str))
+        if use_llm:
+            yield trace_frame("orchestrator", "split data — columns → LLM, rows → code",
+                              f"LLM path: columns={dataset['columns']}\n"
+                              f"DATA path: {json.dumps(dataset['rows'][:10], default=str)}")
+            try:
+                async for frame in engine.generate(prompt, dataset):
+                    yield frame
+                return
+            except Exception as exc:
+                yield trace_frame(name, "LLM generate failed → deterministic fallback", str(exc))
+                plot_type, series = pick_and_shape(dataset)
+                messages = engine.build_surface(plot_type, series, format_answer(dataset["answer"]))
+        else:
+            plot_type, series = pick_and_shape(dataset)
+            messages = engine.build_surface(plot_type, series, format_answer(dataset["answer"]))
+    else:
+        yield trace_frame(f"data source → {name}", "no rows / error", dataset.get("error") or "")
+        messages = engine.build_surface("bar", {"items": []}, format_answer(dataset["answer"]))
+
+    yield trace_frame(name, "emit A2UI surface", f"{len(messages)} messages")
+    yield {"kind": "a2ui", "a2ui_messages": messages, "usage": {}}
+
+
+def make_a4ui_agent(answer, *, contract: Contract = DEFAULT_CONTRACT, model=None,
+                    agent_name: str = "a4ui chart agent", chart_type_buttons=None):
+    """Build the ready AgentCore app from the dev's answer() function.
+
+    answer(prompt)  -> (rows, columns, answer_text) | (rows, answer_text)
+                       | {"rows":..., "columns":..., "answer":...}; sync or async.
+    model           -> None = deterministic charts (zero config). A model_id str or a
+                       Strands model = LLM-composed charts (chart type/roles chosen by
+                       the model; data stays in code).
+    contract        -> defaults to the baked contract; pass a custom Contract to match
+                       a client on a different catalog.
+    """
+    from bedrock_agentcore.runtime import BedrockAgentCoreApp
+
+    use_llm = model is not None
+    resolved_model = model
+    if isinstance(model, str):
+        from strands.models.bedrock import BedrockModel
+        resolved_model = BedrockModel(model_id=model)
+
+    built = build_catalog(contract)
+    engine = SurfaceEngine(built, model=resolved_model, agent_name=agent_name,
+                           chart_type_buttons=chart_type_buttons)
+
+    app = BedrockAgentCoreApp()
+
+    @app.entrypoint
+    async def invoke(payload, context):
+        async for frame in _run_turn(payload, context, engine=engine, answer=answer,
+                                     contract=contract, use_llm=use_llm):
+            yield frame
+
+    return app

a4ui_agent-0.1.0/src/a4ui_agent/_surface.py

@@ -0,0 +1,251 @@
+"""Chart/surface producer — turns (rows, columns, answer) into A2UI wire messages.
+
+This is the heart of what the package hides. Two paths:
+
+PRIMARY (model set): LLM composes the surface STRUCTURE + picks plotType + column roles
+from the question + COLUMN NAMES only (never the rows); then CODE fills updateDataModel
+(series from the real rows, note from the answer) behind the {path} bindings. The model
+never sees a data value, so the dev's numbers reach the chart unaltered.
+
+DETERMINISTIC (no model): pick_and_shape() + build_surface() build a surface with no LLM
+— the zero-config default so install → chart.
+"""
+from __future__ import annotations
+
+import json
+import re
+
+from ._catalog import BuiltCatalog
+from ._prompt import build_system_prompt
+from ._trace import trace_frame
+
+# Chart types offered as a toggle row under the chart. All share the same label/value
+# series, so switching is layout-only (rechart action → updateComponents, same /series).
+# v0.9 Button uses `child` (a Text node) for its label + action.event.{name,context}.
+DEFAULT_CHART_TYPE_BUTTONS = [
+    ("donut", "Donut"), ("pie", "Pie"), ("bar", "Bar"), ("column", "Column"), ("table", "Table"),
+]
+
+_SURFACE_ID = "A2UI_dev"
+
+
+# ── pure data helpers (plotType vocabulary is the standard chart set) ──────────────
+def format_answer(text: str) -> str:
+    """Normalize prose into clean, renderable markdown: blank line around a
+    '**... Insights:**' header and each spaced-hyphen bullet on its own line."""
+    if not text:
+        return text
+    t = text.strip()
+    t = re.sub(r"\s*\*\*([^*]*Insights[^*]*)\*\*\s*", r"\n\n**\1**\n\n", t, flags=re.I)
+    t = re.sub(r"[ \t]+-[ \t]+", "\n- ", t)
+    return t.strip()
+
+
+def _col(columns: list, name) -> str | None:
+    """Case-insensitive column match (SQL engines often upper-case)."""
+    if name:
+        for c in columns:
+            if str(c).lower() == str(name).lower():
+                return c
+    return None
+
+
+def build_series(intent: dict, dataset: dict):
+    """Build the chart series from the chosen plotType + column roles + the REAL rows.
+    Every value is copied straight from dataset['rows'] — never recomputed. Returns
+    (plot_type, series); may fall back to 'table' if the roles don't resolve."""
+    cols = dataset.get("columns") or []
+    rows = dataset.get("rows") or []
+    pt = intent.get("plotType")
+    if pt == "table":
+        return "table", {"columns": cols, "rows": rows[:50]}
+    if pt in ("line", "area"):
+        xc = _col(cols, intent.get("x_column")) or _col(cols, intent.get("label_column"))
+        vc = _col(cols, intent.get("value_column"))
+        if xc and vc:
+            return pt, {"items": [{"label": str(r.get(xc)), "value": r.get(vc)} for r in rows[:100]]}
+    if pt in ("pie", "donut"):
+        lc, vc = _col(cols, intent.get("label_column")), _col(cols, intent.get("value_column"))
+        if lc and vc:
+            return pt, {"items": [{"label": str(r.get(lc)), "value": r.get(vc)} for r in rows[:12]]}
+    if pt == "column":
+        lc, vc = _col(cols, intent.get("label_column")), _col(cols, intent.get("value_column"))
+        if lc and vc:
+            return "column", {"items": [{"label": str(r.get(lc)), "value": r.get(vc)} for r in rows[:100]]}
+    if pt == "KPI_CARD":
+        vc = _col(cols, intent.get("value_column")) or (cols[0] if cols else None)
+        return "KPI_CARD", {"value": rows[0].get(vc) if rows and vc else None}
+    if pt == "scatter":
+        xc, yc = _col(cols, intent.get("x_column")), _col(cols, intent.get("y_column"))
+        if xc and yc:
+            return "scatter", {"points": [{"x": r.get(xc), "y": r.get(yc)} for r in rows[:150]]}
+    lc, vc = _col(cols, intent.get("label_column")), _col(cols, intent.get("value_column"))
+    if not (lc and vc):
+        return "table", {"columns": cols, "rows": rows[:50]}   # honest fallback: show rows, don't fake a bar
+    return "bar", {"items": [{"label": str(r.get(lc)), "value": r.get(vc)} for r in rows[:100]]}
+
+
+def pick_and_shape(dataset: dict):
+    """Infer a chart type + series from column shapes (no LLM, no roles)."""
+    cols = dataset.get("columns") or []
+    rows = dataset.get("rows") or []
+    isnum = lambda v: isinstance(v, (int, float)) and not isinstance(v, bool)
+    nums = [c for c in cols if any(isnum(r.get(c)) for r in rows)]
+    cats = [c for c in cols if c not in nums]
+    if len(rows) == 1 and nums:                                   # single_value → KPI
+        return "KPI_CARD", {"value": rows[0].get(nums[0])}
+    if len(nums) >= 2 and not cats:                               # xy_point → scatter
+        x, y = nums[0], nums[1]
+        return "scatter", {"points": [{"x": r.get(x), "y": r.get(y)} for r in rows[:150]]}
+    val = nums[0] if nums else (cols[1] if len(cols) > 1 else (cols[0] if cols else None))  # label_value → bar
+    lab = next((c for c in cols if c != val), (cols[0] if cols else None))
+    items = [{"label": str(r.get(lab)), "value": r.get(val)} for r in rows[:100]] if (lab and val) else []
+    return "bar", {"items": items}
+
+
+class SurfaceEngine:
+    """Builds + validates A2UI surfaces for one Contract. Holds the catalog_id, the
+    validator and the series model so the surface functions stay contract-bound."""
+
+    def __init__(self, built: BuiltCatalog, *, model=None, agent_name="a4ui chart agent",
+                 chart_type_buttons=None):
+        self._built = built
+        self.catalog_id = built.catalog_id
+        self.validator = built.validator
+        self.series_model = built.series_model
+        self.schema_desc = built.schema_desc
+        self.model = model
+        self.agent_name = agent_name
+        self.chart_type_buttons = chart_type_buttons or DEFAULT_CHART_TYPE_BUTTONS
+
+    # ── surface structure ─────────────────────────────────────────────────────────
+    def _button_row(self):
+        ids, nodes = [], []
+        for pt, label in self.chart_type_buttons:
+            bid, lid = f"btn_{pt}", f"lbl_{pt}"
+            nodes.append({"id": bid, "component": "Button", "child": lid,
+                          "action": {"event": {"name": "rechart", "context": {"plotType": pt}}}})
+            nodes.append({"id": lid, "component": "Text", "text": label})
+            ids.append(bid)
+        return ids, nodes
+
+    def _components(self, plot_type: str):
+        """Canonical surface tree: chart on top, a toggle Row of chart-type buttons, then the note."""
+        btn_ids, btn_nodes = self._button_row()
+        return [
+            {"id": "root", "component": "Column", "children": ["c", "btns", "n"]},
+            {"id": "c", "component": "A2UI_Chart", "plotType": plot_type, "series": {"path": "/series"}},
+            {"id": "btns", "component": "Row", "children": btn_ids},
+            {"id": "n", "component": "Text", "text": {"path": "/note"}},
+            *btn_nodes,
+        ]
+
+    def rechart_message(self, plot_type: str) -> dict:
+        """Layout-only update for the rechart action: same tree, new plotType, same
+        bindings (no createSurface, no data — the client already holds the data model)."""
+        return {"version": "v0.9", "updateComponents": {"surfaceId": _SURFACE_ID,
+                                                         "components": self._components(plot_type)}}
+
+    def build_surface(self, plot_type: str, series: dict, note: str) -> list[dict]:
+        """Assemble the 3-message surface (createSurface + updateComponents + updateDataModel)."""
+        return [
+            {"version": "v0.9", "createSurface": {"surfaceId": _SURFACE_ID, "catalogId": self.catalog_id}},
+            {"version": "v0.9", "updateComponents": {"surfaceId": _SURFACE_ID, "components": self._components(plot_type)}},
+            {"version": "v0.9", "updateDataModel": {"surfaceId": _SURFACE_ID, "path": "/",
+                                                    "value": {"note": note, "series": series}}},
+        ]
+
+    # ── validation guardrail ────────────────────────────────────────────────────
+    def _validate_surface(self, messages: list) -> list[str]:
+        """Every component on-catalog/valid, and the code-built series matches the
+        A2UI_Chart series shape. Returns a per-item description for the trace."""
+        checked: list[str] = []
+        for msg in messages:
+            for comp in (msg.get("updateComponents") or {}).get("components") or []:
+                self.validator.validate_component(comp)
+                d = f"{comp.get('component')}#{comp.get('id')}"
+                if comp.get("component") == "A2UI_Chart":
+                    d += f"(plotType={comp.get('plotType')!r})"
+                checked.append(d)
+            series = ((msg.get("updateDataModel") or {}).get("value") or {}).get("series")
+            if series is not None:
+                self.series_model.model_validate(series)
+                shape = next((f"{k}×{len(series[k])}" for k in ("items", "points", "rows")
+                              if series.get(k) is not None), "value")
+                checked.append(f"series:{shape}")
+        return checked
+
+    # ── PRIMARY: LLM-generated, data-outside ──────────────────────────────────────
+    @staticmethod
+    def _extract_object(text: str) -> dict:
+        t = (text or "").strip()
+        m = re.search(r"```(?:json)?\s*(.*?)```", t, re.S)
+        if m:
+            t = m.group(1).strip()
+        s, e = t.find("{"), t.rfind("}")
+        if s != -1 and e != -1:
+            t = t[s:e + 1]
+        return json.loads(t)
+
+    @staticmethod
+    def _find_chart(components: list) -> dict:
+        for c in components:
+            if c.get("component") == "A2UI_Chart":
+                return c
+        raise ValueError("generated surface has no A2UI_Chart component")
+
+    @staticmethod
+    def _usage_from_result(result) -> dict:
+        try:
+            u = result.metrics.accumulated_usage
+            return {"input_tokens": int(u.get("inputTokens", 0)), "output_tokens": int(u.get("outputTokens", 0))}
+        except Exception:
+            return {}
+
+    async def generate(self, prompt: str, dataset: dict):
+        """Async generator: yields a trace frame per sub-step, then the final a2ui frame.
+        The model composes STRUCTURE + roles from the question + COLUMN NAMES; CODE fills
+        the data. One retry; raises if still invalid (the runtime catches → fallback)."""
+        from strands import Agent
+        from strands.agent.conversation_manager.null_conversation_manager import NullConversationManager
+
+        agent = Agent(model=self.model, system_prompt=build_system_prompt(self.catalog_id),
+                      conversation_manager=NullConversationManager())
+        user_msg = f"Question: {prompt}\nColumns: {dataset.get('columns')}"
+        note = format_answer(dataset.get("answer") or "")
+        last_err = None
+        for attempt in range(2):
+            msg = user_msg if attempt == 0 else (
+                f"{user_msg}\n\nYour previous output was INVALID: {last_err}\n"
+                "Return ONLY the corrected JSON object with keys 'surface' and 'roles'."
+            )
+            result = await agent.invoke_async(msg)
+            try:
+                obj = self._extract_object(str(result))
+                surface = obj["surface"]
+                roles = obj.get("roles") or {}
+                comps = surface[1]["updateComponents"]["components"]
+                chart = self._find_chart(comps)
+                sid = surface[0]["createSurface"]["surfaceId"]
+                plot_type, series = build_series({**roles, "plotType": chart.get("plotType")}, dataset)
+                chart["plotType"] = plot_type
+                surface[1]["updateComponents"]["components"] = self._components(plot_type)
+                messages = surface + [{"version": "v0.9", "updateDataModel": {
+                    "surfaceId": sid, "path": "/", "value": {"note": note, "series": series}}}]
+                yield trace_frame("A2UI surface", "composed A2UI surface → validate via A2UI catalog",
+                                  f"LLM: plotType={plot_type}, roles={roles}\n"
+                                  f"DATA path: series = {json.dumps(series, default=str)}")
+                checked = self._validate_surface(messages)
+                yield trace_frame("A2UI catalog", "validated against the A2UI catalog",
+                                  f"schema {self.schema_desc} · checked: {', '.join(checked)} → all OK")
+                _emitted = "\n".join(
+                    f"{next((k for k in ('createSurface', 'updateComponents', 'updateDataModel') if k in m), 'message')}: "
+                    f"{json.dumps(m, default=str)}" for m in messages)
+                yield trace_frame("A2UI surface", "emit A2UI messages → A2UI client creates the surface",
+                                  "agent emits the surface SPEC; the client's processMessages creates it:\n" + _emitted)
+                yield {"kind": "a2ui", "a2ui_messages": messages, "usage": self._usage_from_result(result)}
+                return
+            except Exception as exc:
+                last_err = str(exc)[:300]
+                yield trace_frame("A2UI catalog", "validation failed — retrying" if attempt == 0 else "validation failed", last_err)
+        raise ValueError(f"LLM surface generation failed after retry: {last_err}")

a4ui_agent-0.1.0/src/a4ui_agent/_trace.py

@@ -0,0 +1,20 @@
+"""Flow-trace frame builder. One entry per pipeline step → forwarded to the browser
+flow panel (@haystackedai/a4react's RightPane reads these). Part of the TRANSPORT
+contract the frontend package parses, so the frame shape is frozen here."""
+from __future__ import annotations
+
+import time
+
+# Cap each detail string so a frame stays under the AgentCore event-size limit.
+# Large enough to show the emitted A2UI surface (3 messages) in full.
+TRACE_DETAIL_CAP = 3000
+
+
+def trace_frame(actor: str, action: str, detail: str = "") -> dict:
+    """Build one 'trace' frame (kind:'trace'); the gateway re-wraps it as a meta part."""
+    return {"kind": "trace", "entry": {
+        "ts": int(time.time() * 1000),
+        "actor": actor,
+        "action": action,
+        "detail": str(detail)[:TRACE_DETAIL_CAP],
+    }}

a4ui_agent-0.1.0/tests/test_surface.py

@@ -0,0 +1,53 @@
+"""Deterministic-path smoke test: no AWS, no model, no AgentCore — just prove the
+baked contract assembles a valid catalog and that a built surface passes the a2ui-core
+validator. Run with a Python that has a2ui-core installed:
+
+    python tests/test_surface.py            # plain asserts
+    pytest tests/test_surface.py            # if pytest present
+"""
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+
+from a4ui_agent import build_catalog, DEFAULT_CONTRACT, SurfaceEngine, pick_and_shape, format_answer
+
+DATASET = {
+    "columns": ["STATUS", "CNT"],
+    "rows": [{"STATUS": "Active", "CNT": 5}, {"STATUS": "Closed", "CNT": 3}],
+    "answer": "Two statuses - Active and Closed.",
+}
+
+
+def test_deterministic_surface_validates():
+    built = build_catalog(DEFAULT_CONTRACT)
+    engine = SurfaceEngine(built)
+
+    plot_type, series = pick_and_shape(DATASET)
+    assert plot_type in built.plot_types
+    assert series.get("items")  # category + number → bar with items
+
+    messages = engine.build_surface(plot_type, series, format_answer(DATASET["answer"]))
+    assert len(messages) == 3
+    assert messages[0]["createSurface"]["catalogId"] == DEFAULT_CONTRACT.catalog_id
+
+    checked = engine._validate_surface(messages)   # raises if any component is off-catalog
+    assert any("A2UI_Chart" in c for c in checked)
+    assert any(c.startswith("series:") for c in checked)
+    return plot_type, checked
+
+
+def test_rechart_message_is_layout_only():
+    engine = SurfaceEngine(build_catalog(DEFAULT_CONTRACT))
+    msg = engine.rechart_message("donut")
+    assert "createSurface" not in msg and "updateComponents" in msg
+    chart = next(c for c in msg["updateComponents"]["components"] if c.get("component") == "A2UI_Chart")
+    assert chart["plotType"] == "donut"
+
+
+if __name__ == "__main__":
+    pt, checked = test_deterministic_surface_validates()
+    test_rechart_message_is_layout_only()
+    print("plotType:", pt)
+    print("validated:", checked)
+    print("ALL OK")