[nan-yu]

Important

Stacked PR, 2 of 3. Stack: #3567 → this PR → #3569.
The base branch is #3567's branch (stack/prompt-layout), so the diff shows only this PR's changes. When #3567 merges, GitHub retargets this PR to main.

Summary

This PR gives Python one shared function that builds both prompt snippets and monolithic skills. PromptGenerator.generate() becomes a method that subclasses can't override. It's the "shared assembler + fixed generate()" item in #3416, Python only.

Changes

• a2ui.prompt.assemble_instructions(generator, catalogs=None) joins the base rules, the catalog instructions and the examples (under EXAMPLES_HEADING), and caches the snippet for each generator's own catalogs (weakly keyed on the generator, so the cache keeps nothing alive beyond it).
  • For the generator's own catalogs, it calls generate_catalog_instructions() and generate_examples() once each, so a format can still render shared content once. Express's multi-catalog # Catalog headings and Elemental's shared type definitions rely on this.
  • For any other set of catalogs, it renders each catalog separately and drops repeated examples, as SkillGenerator did.
• PromptGenerator:
  • generate() is marked @typing.final and returns assemble_instructions(self).
  • catalogs is a new abstract property.
  • The three hooks stay public for third-party formats.
• Removed generate() overrides from the Express, Direct JSON, Elemental and Atom generators. Their snippets don't change: the prompt conformance fixtures and every existing test pass unchanged.
• SkillGenerator.generate_skill() builds its body with assemble_instructions, so a monolithic skill for the format's own catalogs holds the prompt snippet.
• No longer exported: ExpressPromptGenerator, DirectJsonPromptGenerator, ElementalPromptGenerator and AtomPromptGenerator are removed from a2ui.inference_formats and their format packages. Use InferenceFormat.prompt_generator to reach a format's generator.
• Tests: added tests/test_prompt_assembler.py and updated the two test subclasses of PromptGenerator to the new contract.
• Docs: CHANGELOG (two BREAKING entries) and README.
• Blueprints: the a2ui_agent module blueprint and the skill_generator feature blueprint describe the new PromptGenerator contract and assemble_instructions.

Impact & Risks

• Breaking for third-party PromptGenerator subclasses: they must implement catalogs and stop overriding generate(). mypy reports an override as an error; at runtime the override still runs.
• Breaking for code that imported the per-format generator classes. Nothing in the repo does.
• The cache assumes a generator doesn't change after construction. That holds for every generator in the repo. Text for other catalog sets isn't cached.
• Prompt output is unchanged.

Testing

• uv run pytest python/a2ui_agent/tests python/a2ui_adk/tests python/a2ui_a2a/tests: all passed, plus 9 new tests in test_prompt_assembler.py.
  • The new tests include a check that the monolithic skill body equals the prompt snippet for Express and Direct JSON with one and two catalogs.
• uv run mypy python/a2ui_agent and uv run pyink are clean.

Refs #3416.

[gemini-code-assist]

Code Review

This pull request refactors the prompt generation system by making PromptGenerator.generate() a final method that delegates to a new shared assemble_instructions function. Subclasses of PromptGenerator are now required to implement an abstract catalogs property and three hook methods (generate_base_rules, generate_catalog_instructions, and generate_examples) instead of overriding generate(). Specific format prompt generators are no longer exported directly from a2ui.inference_formats. Additionally, SkillGenerator has been updated to use assemble_instructions to prevent logic duplication, caching has been introduced for generator instructions, and comprehensive unit tests have been added. As there are no review comments, I have no feedback to provide.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[ditman]

Should this also update the blueprints?

[nan-yu]

@ditman Good call, done in 3a387f3:

• blueprints/modules/a2ui_agent.blueprint.md, PromptGenerator section: describes the abstract catalogs property, the three hooks, the final generate() returning assemble_instructions(self), and assemble_instructions itself (layout, the own-catalogs vs. other-catalogs paths, caching). It also notes that the per-format generator classes are internal. The DirectJsonPromptGenerator sketch now shows the hooks instead of a generate() override, with the protocol schemas in the base rules.
• blueprints/features/skill_generator.blueprint.md: the base contract and the assembly steps replace the old generate(role_description, workflow_description, ...) template method, which no SDK had anymore. generate_skill documents that its body comes from assemble_instructions, base rules may hold shared protocol schemas instead of being strictly "catalog-agnostic", and the implementation steps say to make generate() final.

validate_blueprints.py passes. I left the codebase blueprints' module_blueprint_commit alone for now, since the squash merge will change the hash.

[ditman]

Thanks for updating the blueprints as well! Centralizing prompt and monolithic skill assembly in assemble_instructions(), marking PromptGenerator.generate() @final, and hiding the format-specific PromptGenerator subclasses behind InferenceFormat.prompt_generator is a great simplification.

Left a few minor comments on a docstring contradiction in PromptGenerator.generate_catalog_instructions, a small caching docstring clarification, and an optional cleanup in SkillGenerator.generate_skill.