Skip to main content

A2UI Core Library (a2ui_core)

a2ui_core is a framework-agnostic Python library containing the core data models, reactive state management, and JSON schema validation logic for the A2UI protocol (v0.9 and onwards).

It provides the logic-neutral, visual-agnostic layer used by python-based server agents, rendering backends, and conformance testing frameworks.

Features

  • Protocol Handling: Symmetrical processing and validation of A2UI specification envelope messages (CreateSurface, UpdateComponents, UpdateDataModel, and DeleteSurface).
  • State Management: Reactive state tracking driven by a high-performance custom Signal implementation and decoupled hierarchical models (SurfaceGroupModel, SurfaceModel, and SurfaceComponentsModel).
  • DataContext: Advanced data binding and function execution environment with support for dynamic path resolution and automatic dependency updates.
  • Catalog System: Extensible catalog registry supporting compiled object models (ModelCatalog) and raw text-based schemas (JsonCatalog) for LLM prompt integration.
  • Validation & Integrity: Strict validation engine combining Pydantic (compiled envelopes) and JSON Schema Draft 2020-12 (dynamic catalogs) with advanced topological and integrity checks (cyclic layout detection, reachability analysis, orphan tracking, and recursive reference verification).

Architecture

The a2ui_core architecture aligns symmetrically with the client-side @a2ui/web_core engine, allowing exact parity when evaluating state representations and resolving dynamic layout values.

graph TD
    MP[MessageProcessor] -->|Executes Messages| SGM[SurfaceGroupModel]
    SGM -->|Manages active surfaces| SM[SurfaceModel]
    SM -->|Dynamic Components| SCM[SurfaceComponentsModel]
    SM -->|State Context| DM[DataModel]
    SCM --> GB[GenericBinder]
    DM --> GB

Core Packages

1. State Layer (src/a2ui/core/state)

  • Signal: Thread-safe (where applicable) core reactive primitive. Allows components and rendering pipelines to subscribe to precise state increments.
  • DataModel: Active state key-value dictionary path observer supporting reactive wildcard queries and path resolution.
  • SurfaceComponentsModel: Manages the adjacency map of component configurations and topological validation for a surface.
  • SurfaceModel: Orchestrates components and data model pipelines for a single viewport surface.
  • SurfaceGroupModel: Manages a collection of active client rendering surfaces.

2. Resolution Engine (src/a2ui/core/resolution)

  • DataContext: Coordinates lexical scopes, resolves data paths (e.g., /some/data), and handles dynamic expressions.
  • GenericBinder: Subscribes to relevant data path models and binds component properties dynamically.
  • ComponentContext: Connects standard component models with their target DataContext execution environments.

3. Message Processing (src/a2ui/core/processing)

  • MessageProcessor: A stateless protocol processor. Translates raw incoming A2UI messages into structural mutations across the SurfaceGroupModel layer.

4. Catalogs (src/a2ui/core/catalog)

  • JsonCatalog: Loads raw JSON schemas directly, compiling schema-validated references dynamically for prompt injection.
  • ModelCatalog: Compiles catalog rules based on structured Pydantic or standard object class configurations.
  • Catalog.derive: Builds a catalog under a new ID from named entries of an existing catalog and new entries. It does not keep the source's $id, title, description or instructions, since the basic catalog's instructions, for example, name its ID in their examples.

5. Basic Catalog (src/a2ui/core/basic_catalog)

  • Basic Component Models: Symmetrical declarations of core out-of-the-box components (TextComponent, ButtonComponent, CardComponent, etc.) conforming directly to standard schema configurations.
  • BasicCatalog: Factory provider initializing standard schemas and layout parameters.

6. Symmetrical Schemas (src/a2ui/core/schema)

  • Pydantic Message Wrappers: Compiled Pydantic models representing A2uiMessage, envelopes, and capabilities configuration structures.
  • constants: Spec constants defining default reachability links and single/list component reference parameters.

Development & Testing

We use uv for extremely fast and reliable environment management and task execution.

Setup Environment

To synchronize the virtual environment and dependencies, run the following from the python/ directory:

uv sync

Running Tests

Run all unit, conformance, and structural integrity test suites:

# From the package directory (python/a2ui_core)
uv run pytest

Code Formatting

Format and lint source files before committing changes:

uv run pyink .

Metadata

Release files for a2ui-core 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for a2ui-core 0.7.0
File Size Uploaded Provenance Actions
a2ui_core-0.7.0.tar.gz 421.0 kB With provenance Details for a2ui_core-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for a2ui-core 0.7.0
File Interpreter ABI Platform Actions
a2ui_core-0.7.0-py3-none-any.whl Python 3 none any Details for a2ui_core-0.7.0-py3-none-any.whl

Total release size: 745.5 kB

Release files / a2ui_core-0.7.0.tar.gz

Download URL a2ui_core-0.7.0.tar.gz
Size 421.0 kB
Tags Source
SHA-256 checksum
How to use checksums
fc414e1b961203e29cfd55d53d3d183b884fa40745c5b981fa7afa2ec0aeb396
BLAKE2b-256 checksum
How to use checksums
6c0b1b796669e106078d351f7524f99c7b209855248b9d0310f64846e9d45c76
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.2.0 CPython/3.11.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by Google Cloud, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / a2ui_core-0.7.0-py3-none-any.whl

Download URL a2ui_core-0.7.0-py3-none-any.whl
Size 324.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c69d43dce8f6aea7b6dcc8b17248d6e003d68cfa1d6f772d7ab8e120efab35da
BLAKE2b-256 checksum
How to use checksums
aff36673b80cf73d127b6f9caf970eee8e64721bbc455b5375d0f0370a976b1f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.2.0 CPython/3.11.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by Google Cloud, verified by PyPI on Nov 17, 2026.

Transparency log

Security for a2ui-core 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for a2ui_core-0.7.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by Google Cloud, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page