Index of every page on this site: llms.txt
All skills
a2ui-project avatar

/a2ui-generate-pydantic-models

@6bf4cc2
by A2UIa2ui-project/a2ui18k stars
1,430
Run it yourself

Automated generator for strongly typed Pydantic v2 data models and basic catalogs across any A2UI protocol version (v0.8, v0.9, v0.9.1, v1.0, etc.).

  • 7 files
  • 198.3 KB
  • Updated 2 days ago
  • GitHub
Use this Skill: https://skilld.dev/gh/a2ui-project/a2ui/a2ui-generate-pydantic-models

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈45 tokens for metadata: the name and description. ≈2.5k when used: this file.

Description uses 2.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈180 characters, or 2.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

A2UI Pydantic Model Generation Skill

This skill provides an automated code generation tool that produces strongly typed Pydantic v2 data models and basic catalog definitions for python/a2ui_core directly from the schemas and catalogs in specification/<version>/.


Agent Execution Steps

When given a prompt like "Generate Pydantic model classes for A2UI spec v1.0":

  1. Extract the target version parameter from the prompt (e.g. v1.0 -> v1.0).

  2. Execute the generator script exactly once for that target version:

    uv run python .agents/skills/a2ui-generate-pydantic-models/scripts/codegen_pydantic.py --version <TARGET_VERSION>

    (Replace <TARGET_VERSION> with the single requested version, e.g. --version v1.0).

  3. Format generated Python code:

    cd python/a2ui_core
    uv run pyink .
  4. Verify the generated files by running pytest:

    cd python/a2ui_core
    uv run pytest tests/test_codegen_pydantic.py
  5. Stop and report completion to the user.


Generated Output Files per Version

When executed for a target version <version> (e.g. v1.0 -> v1_0), the script generates:

  1. python/a2ui_core/src/a2ui/core/schema/<version>/:

    • constants.py
    • common_types.py: strongly typed shared models and the COMMON_TYPES_DEFS manifest, which maps each spec $defs name to its symbol in spec order. No spec schema is copied verbatim; the published common types schema is rebuilt from these symbols.
      • Type aliases such as ComponentId, Child, ChildList and the Dynamic* unions are registered as Annotated[..., Field(description=...)] with the spec descriptions, so the runtime JSON schema generator needs no per-def special cases. Dynamic unions list their members in spec order.
      • When a Dynamic* def constrains its function-call branch with a returnType const, the branch is Annotated[FunctionCall, ReturnType("<type>")], which validates the return type and emits the spec's allOf in both modes. Any other branch shape fails generation.
      • Every model extends SpecBaseModel (hand-written in schema/common_types.py) and has no generated methods. Keywords that fields cannot produce are declared in the model config as json_schema_extra=SchemaKeywords(...): it drops additionalProperties where the spec leaves it out and adds returnType, unevaluatedProperties, title, allowedParents and oneOf required-alternatives (see _SPEC_KEYWORDS). The keywords apply only to the declaring model, not to subclasses. SpecBaseModel validates a declared oneOf whose branches only list required fields (for example FunctionResponse's value/error), requiring exactly one branch.
      • Only composition that references the catalog's function union is limited to spec_schema() (SchemaKeywords(..., spec_only=True)), which the published common types schema uses: v0.9's FunctionCall oneOf, v1.0's FunctionCall allOf over FunctionCommon and anyFunction (replace=True, since the spec def is pure composition), and v0.9's precise args shape (a schema-only JsonSchemaAs annotation requested through the x-python-type property override). Catalogs keep the flat model shape there. References inside declared keywords are the markers def_ref("<Def>") and catalog_functions() from the internal a2ui.core.schema._json_schema module, which the schema builder resolves to $refs. FunctionCall itself is a flat model that validates any call without the catalog.
      • Nested object properties with their own properties become helper models named <Parent><Property> (for example ComponentCommonMetadata, IndexSystemFunctionArgs, FunctionResponseError), which schemas inline. Wrapper unions such as Action are TypeAliasTypes, so fields reference them by def name. Each branch gets a <Def><Property>Wrapper model, and a branch property that is an object becomes <Def><Property> (ActionEvent, ActionEventWrapper, ActionFunctionCallWrapper). A generated name that collides with a def, a base symbol or another helper fails generation.
      • A def that the spec leaves open (no additionalProperties and no unevaluatedProperties: false) allows extra keys. ComponentCommon is the exception (_SUBCLASSED_DEFS): generated catalog components subclass it and must stay closed.
      • Optional fields are typed X | None so they can be absent. SpecBaseModel rejects an explicit null for such a field unless X accepts null itself (Any), under both the spec name and the Python field name; it does not change the JSON schema. Catalog components inherit this rule through ComponentCommon. v0.9's FunctionCall.args also rejects null values.
      • Primitive defs such as CallId are TypeAliasTypes, so local references keep their $ref. References from other documents to a primitive def map to its Python type through _CROSS_DOCUMENT_REF_TYPES in engine.py.
      • patternProperties objects (Extensions) are TypeAliasTypes over a key-checking validator, and their pattern is published in the spec schema and in catalogs. Python's re cannot compile \p{...}, so the SDK validates JSON schemas with a2ui.core.validation.SchemaValidator (powered by regex). The DynamicValue literal-object branch carries the spec's propertyNames and not clauses through a SchemaKeywords annotation in both modes.
      • Common types keep component properties (Surface) and emit required consts without defaults (skip_component_property and required_const_default on the engine). Spec defaults are emitted as JSON schema default values (schema_defaults), not as description notes.
      • Common types are generated in strict mode: a schema shape the models would not enforce (an unknown or non-local $ref, siblings next to $ref/const/composition, an unsupported keyword next to properties, a required property that is not declared, an empty union) raises instead of loosening validation. Output is deterministic and does not depend on string hashing.
    • agent_to_renderer.py / server_to_client.py: strongly typed outbound message models and the AGENT_TO_RENDERER_DEFS manifest, which maps each spec $defs (or v0.8 properties) name to its symbol in spec order so get_agent_to_renderer_schema_map / get_agent_to_renderer_schema_json can rebuild server_to_client.json / agent_to_renderer.json from the models. Nested payload objects and array item objects become helper models marked with INLINE_DEF_MARKER (for example CreateSurfaceMetadata, SurfaceUpdateComponentsItem), and non-message $defs (Component, ComponentsList) are emitted as TypeAliasTypes with SchemaKeywords.
    • renderer_to_agent.py / client_to_server.py
    • renderer_capabilities.py / client_capabilities.py
    • agent_capabilities.py / server_capabilities.py (when present in spec)
    • catalog_definition.py (when present in spec)
    • __init__.py
  2. python/a2ui_core/src/a2ui/core/basic_catalog/<version>/:

    • components.py (strongly typed components & ModelComponentApi registrations)
    • function_apis.py (strongly typed function schemas & FunctionApi classes)
    • styles.py (theme schema, generated when the catalog defines styles or an unreferenced $defs.theme / $defs.Theme)
    • __init__.py
    • The models and the generated BasicCatalog carry everything Catalog.to_json() needs to rebuild the published catalog document from them, with no catalog JSON copied into Python or read at runtime:
      • BasicCatalog passes the document's top-level fields to Catalog: $schema, $id, title, description, protocolVersion (None when the document declares none), catalogId when it declares none, instructions, where it writes its theme (theme_location), its unions (union_defs, which must list the catalog's entries) and the document its common types references point into (common_types_uri). The theme is passed as theme_model.
      • Without common types (v0.8), nested objects become models that keep the document's shapes: two nested objects of different shapes never share a model (the later one is prefixed with its component or parent model, for example SliderValueItem), and their descriptions stay on the fields, with line breaks, rather than becoming docstrings. Catalog.to_json() writes them inline, as the v0.8 document does.
    • For versions with a common types schema (v0.9+), the models carry everything Catalog.validation_schema and Catalog.to_json() need to rebuild the specification's catalog.json shape from them:
      • A component's allOf references to common types defs (for example Checkable) become base classes, and catalog defs (CatalogComponentCommon) become base models. A component with more than one base sets extra="forbid", because Pydantic would otherwise inherit an open base's config. A component description becomes the class docstring and fails generation if it cannot be one.
      • A function's description becomes the FunctionApi.description attribute. Keywords on the args object that fields cannot produce (unevaluatedProperties, additionalProperties, required-alternative anyOf) are declared with SchemaKeywords as the model's json_schema_extra, and an unknown keyword fails generation.
      • Field constraints (minItems, minimum, ...) are emitted as Field arguments, so they are validated and published; format and default are published through json_schema_extra. An allOf member that only adds keywords becomes a SpecAllOf annotation.
    • The conformance cases test_v08_basic_catalog_to_json, test_v09_basic_catalog_to_json and test_v10_basic_catalog_to_json, and python/a2ui_core/tests/test_basic_catalog_documents.py, compare BasicCatalog().to_json() with the published files, so any drift fails the tests.
  3. python/a2ui_core/src/a2ui/core/schema/__init__.py:

    • Registers the version in A2uiProtocolVersion enum and updates envelope unions.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 6bf4cc2. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 days ago
metadata
{
  "internal": true
}

README badge

README badge for a2ui-project/a2ui/a2ui-generate-pydantic-models