a2ui-core 0.0.1__tar.gz

a2ui_core-0.0.1/.gitignore

@@ -0,0 +1,127 @@
+node_modules
+.DS_Store
+.wireit
+dist
+.env
+.idx
+.idea/
+*.pyc
+.angular/
+*.tsbuildinfo
+
+# MkDocs build output
+site/
+
+# Python virtual environment
+.venv/
+coverage/
+
+# Generated spec assets in the agent SDK
+## old agent SDK path
+a2a_agents/python/a2ui_agent/src/a2ui/assets/**/*.json
+agent_sdks/python/src/a2ui/assets/**/*.json
+## new agent SDK path
+agent_sdks/python/a2ui_agent/src/a2ui/assets/**/*.json
+## Generated files for sandbox frame.
+samples/client/angular/projects/mcp_calculator/public/mcp_apps_inner_iframe/
+
+# Yarn Modern
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/sdks
+.yarn/cache
+
+## Generated files for a2ui-in-mcpapps
+samples/mcp/a2ui-in-mcpapps/server/apps/dist
+samples/mcp/a2ui-in-mcpapps/server/apps/public
+
+# Vite cache
+.vite/
+
+# Git worktrees
+worktrees/
+
+# TypeScript incremental build info
+*.tsbuildinfo
+
+# Local-only scratch files.
+.local/
+
+# Diagrams, produced by https://pub.dev/packages/layerlens.
+DEPS.md
+
+# Firebase
+google-services.json
+**/lib/firebase_options.dart
+firebase.json
+GoogleService-Info.plist
+.firebase
+.firebaserc
+
+# This package's specific logs.
+*.log.*
+*.log
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+venv/
+ENV/
+build/
+*.egg-info/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# ==============================================================================
+#
+# STANDARD FLUTTER GITIGNORE
+#
+# ==============================================================================
+
+# Miscellaneous
+*.class
+*.swp
+.atom/
+.build/
+.buildlog/
+.history
+.svn/
+.swiftpm/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+
+# Flutter/Dart/Pub related
+**/doc/api/
+**/ios/Flutter/.last_build_id
+.dart_tool/
+.flutter-plugins-dependencies
+.pub-cache/
+.pub/
+/build/
+
+# iOS/macOS generated files
+**/ios/Runner/GeneratedPluginRegistrant.h
+**/ios/Runner/GeneratedPluginRegistrant.m
+**/ios/Runner/GeneratedPluginRegistrant.swift
+**/macos/Flutter/GeneratedPluginRegistrant.swift
+
+/coverage/
+pubspec.lock
+
+# Symbolication related
+app.*.symbols
+
+# Obfuscation related
+app.*.map.json
+
+# Android Studio will place build artifacts here
+/android/app/debug
+/android/app/profile
+/android/app/release

a2ui_core-0.0.1/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: a2ui-core
+Version: 0.0.1
+Summary: A2UI Python SDK - Core Library
+Requires-Python: >=3.14
+Requires-Dist: jsonschema>=4.26.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: referencing>=0.37.0
+Description-Content-Type: text/markdown
+
+# 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 `ComponentNode` layers).
+- **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).
+
+> [!IMPORTANT]
+> **Specification Support**: The `a2ui_core` library strictly targets the **A2UI specification v0.9 and onwards**. Unlike client-side renderers that may support legacy v0.8 layouts for backward compatibility, this Python core library does not support legacy v0.8 protocol definitions.
+
+## 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.
+
+```mermaid
+graph TD
+    MP[MessageProcessor] -->|Executes Messages| SGM[SurfaceGroupModel]
+    SGM -->|Manages active surfaces| SM[SurfaceModel]
+    SM -->|Dynamic Components| SCM[Components Model]
+    SM -->|State Context| DM[DataModel]
+    SCM --> GB[GenericBinder]
+    DM --> GB
+    GB -->|Re-resolves dynamic values| CN[ComponentNode<br/>Resolved Tree]
+```
+
+### 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.
+- **`ComponentNode`**: Represents a live, reactively bound component instance in the final visual tree hierarchy. Automatically disposes of nested resources and subscriptions when unmounted.
+- **`SurfaceModel`**: Orchestrates components and data model pipelines for a single viewport surface.
+- **`SurfaceGroupModel`**: Manages a collection of active client rendering surfaces.
+
+#### 2. Rendering Engine (`src/a2ui/core/rendering`)
+
+- **`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.
+
+#### 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](https://github.com/astral-sh/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 `agent_sdks/python` directory:
+
+```bash
+uv sync
+```
+
+### Running Tests
+
+Run all unit, conformance, and structural integrity test suites:
+
+```bash
+# From the package directory (agent_sdks/python/a2ui_core)
+uv run pytest
+```
+
+### Code Formatting
+
+Format and lint source files before committing changes:
+
+```bash
+uv run pyink .
+```

a2ui_core-0.0.1/README.md

@@ -0,0 +1,95 @@
+# 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 `ComponentNode` layers).
+- **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).
+
+> [!IMPORTANT]
+> **Specification Support**: The `a2ui_core` library strictly targets the **A2UI specification v0.9 and onwards**. Unlike client-side renderers that may support legacy v0.8 layouts for backward compatibility, this Python core library does not support legacy v0.8 protocol definitions.
+
+## 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.
+
+```mermaid
+graph TD
+    MP[MessageProcessor] -->|Executes Messages| SGM[SurfaceGroupModel]
+    SGM -->|Manages active surfaces| SM[SurfaceModel]
+    SM -->|Dynamic Components| SCM[Components Model]
+    SM -->|State Context| DM[DataModel]
+    SCM --> GB[GenericBinder]
+    DM --> GB
+    GB -->|Re-resolves dynamic values| CN[ComponentNode<br/>Resolved Tree]
+```
+
+### 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.
+- **`ComponentNode`**: Represents a live, reactively bound component instance in the final visual tree hierarchy. Automatically disposes of nested resources and subscriptions when unmounted.
+- **`SurfaceModel`**: Orchestrates components and data model pipelines for a single viewport surface.
+- **`SurfaceGroupModel`**: Manages a collection of active client rendering surfaces.
+
+#### 2. Rendering Engine (`src/a2ui/core/rendering`)
+
+- **`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.
+
+#### 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](https://github.com/astral-sh/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 `agent_sdks/python` directory:
+
+```bash
+uv sync
+```
+
+### Running Tests
+
+Run all unit, conformance, and structural integrity test suites:
+
+```bash
+# From the package directory (agent_sdks/python/a2ui_core)
+uv run pytest
+```
+
+### Code Formatting
+
+Format and lint source files before committing changes:
+
+```bash
+uv run pyink .
+```

a2ui_core-0.0.1/pyproject.toml

@@ -0,0 +1,42 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+[project]
+name = "a2ui-core"
+version = "0.0.1"
+description = "A2UI Python SDK - Core Library"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "jsonschema>=4.26.0",
+    "pydantic>=2.10.0",
+    "referencing>=0.37.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pyink>=24.10.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/a2ui"]
+
+[[tool.uv.index]]
+url = "https://pypi.org/simple"
+default = true