feat(python): implement A2UI synchronous template expansion engine with version 0.1 validation

[jacobsimionato]

Summary

[Part 2 of 4 in Templates Stack - Depends on #2380]

This PR implements the A2UI Server-Side Template Engine in the Python Agent SDK under experimental inference formats (agent_sdks/python/a2ui_agent/src/a2ui/inference_formats/experimental/template/).

It provides synchronous template expansion, synthetic component catalog synthesis for LLM prompt generators, support for static YAML templates, dynamic data-binding resolvers, and programmatic Python render functions.

---

Architectural Highlights

• Experimental Inference Format: Housed in a2ui.inference_formats.experimental.template and decorated with @experimental to communicate preview status.
• Matching Directory Structure: Both source code and unit tests follow the unified modular path under inference_formats/experimental/template/.
• Catalog-Agnostic Engine: TemplateProcessor operates independently with zero hardcoded primitives or catalog fallbacks (base_catalog: Optional[CatalogSchema] = None). Primitives and catalog IDs are dynamically derived from the provided catalog or left empty for template-only generation.
• Strong Semantic Type Aliases: Explicit type definitions for identifiers (TemplateId, InstanceId, ComponentId, ParamPath), template evaluation (TemplateParams, TemplateNodeDict), wire-format outputs (A2UIComponent, A2UIComponentList, A2UIMessage), and catalog schemas (CatalogSchema, JSONSchemaDict).
• Private Helper Encapsulation: Private helpers (_resolve_param_path, _substitute_params, _validate_templates) with backward-compatible deprecation aliases.
• Strict Template Versioning (0.1): Validates that all ingested templates declare version == "0.1" and serializes the version tag across dict and YAML outputs.
• Polymorphic Dynamic Templates:
  • Data-Binding Mode: Secure server-side callbacks (resolver) query databases/APIs and inject sensitive data directly into presentation layouts, keeping confidential numbers out of prompt contexts.
  • Programmatic AST Mode: Developers write native Python functions returning component trees using arbitrary Python loops, math calculations, and conditionals.
• Duck-Typing & Dataclass Normalization: normalize_node() automatically recognizes dataclasses or any class implementing .to_dict(), enabling seamless future integration with fluent builders.
• Deterministic ID Synthesis: Flattens nested layout trees into canonical primitives with collision-free synthetic IDs ({parent}_{slot}_{index}_{type}).
• Cycle & Recursion Guards: Call-stack tracking raises immediate ValueError on circular template references and enforces MAX_EXPANSION_DEPTH = 32.
• Inference Integration: TemplateInferenceFormat bridges registered templates into system prompt instructions and parses LLM outputs synchronously.

---

Testing & Verification

• Comprehensive unit test suite in agent_sdks/python/a2ui_agent/tests/inference_formats/experimental/template/test_template_format.py.
• 29 pytest tests pass cleanly, verifying:
  • Multi-doc YAML loading and forward referencing
  • Exact parameter substitution with native type preservation (int, bool, dict)
  • Loop unrolling and nested collection components
  • Higher-order container slots (child, children)
  • Dynamic resolver execution
  • Programmatic render functions and duck-typing AST / dataclass normalization
  • Version validation (0.1 success vs. unsupported version rejection)
  • Completely optional base_catalog=None behavior and custom domain catalogs
  • End-to-end prompt generation and response parsing with Express DSL

---

Stack Context

• PR 1 of 4: feat(spec): add core A2UI templates specification, version 0.1 schema, and examples #2380 (Core Specification, Schema & Test Fixtures)
• PR 2 of 4: Python Agent SDK Template Engine (This PR)
• PR 3 of 4: Community Templates Sample App & Interactive Studio (feat(samples): add community templates sample app with version 0.1 templates and interactive studio #2382)
• PR 4 of 4: Future Proposals (Client-Expanded Templates & Python Fluent Builders) (docs(spec): add proposals for client-expanded templates and Python fluent builders #2383)

[gemini-code-assist]

Code Review

This pull request introduces the a2ui.template package, providing a robust server-side UI template engine for the A2UI Python Agent SDK. It includes support for static YAML-based templates, dynamic resolvers, and programmatic render functions, along with a synthetic catalog generation system for LLM integration. The review identified several critical issues, including potential runtime errors with asynchronous resolver execution, incomplete dataclass normalization, inefficient helper function definitions, missing circular reference detection, and overly simplistic parameter inference logic. These issues have been addressed to ensure robustness and compliance with the project's specification.

[jacobsimionato]

Addressed reviewer feedback and synced with updated specification:

1. Resolver Dict Return: Ensured DynamicTemplate.resolve() always falls back to an empty dict {} if the resolver returns None or non-dict, avoiding unpacking TypeError.
2. A2UI Expressions in Primitive Parameters: Added expression guard (is_expression) in TemplateProcessor.expand_template so that dynamic DataBinding or format expressions (e.g. {"path": "..."}) passed to primitive string/number params pass validation.
3. Lifted Recursive Helpers: Refactored _check_val and _check_path to class methods on StaticTemplate, and _map_id, _resolve_slot, and _map_child_list to class methods on TemplateProcessor to avoid inner closure reallocations.
4. Defensive Kwarg Filtering: render_fn inspects signature parameters and filters extra parameters if the function does not accept **kwargs.
5. Schema & Models: Synced updated schema and added 4 new unit tests (23 pytest tests passing).