a2ui-project / a2ui-project/a2ui
Modularize SchemaManager class into Catalog-focused components
- Ngôn ngữ chính
- TypeScript
- Star
- 16.4k
- Fork
- 1.3k
- Merge trung bình
- 3 ngày 15 giờ
- Pull request đã merge (30 ngày)
- 134
Mô tả
## Overview
Currently, `A2uiSchemaManager` in `agent_sdks/python/a2ui_agent/src/a2ui/schema/manager.py` combines multiple responsibilities:
1. Loading and holding raw schema dictionaries and component catalog files.
2. Negotiating client capabilities (`supportedCatalogIds` and `inlineCatalogs`).
3. Performing component, message, and schema reachability pruning.
4. Loading and validating catalog example payloads.
5. Assembling and rendering system prompt instructions for LLMs.
We want to move away from a stateful schema manager as the primary representation of catalogs in A2UI Python SDKs, favoring the pure `Catalog` data object in `agent_sdks/python/a2ui_core/src/a2ui/core/catalog/catalog.py`.
## Proposed Component Breakdown
To improve modularity and testability, `A2uiSchemaManager` will be split into single-responsibility classes:
* **`CatalogRepository`**: Manages specification-version schemas (`server_to_client.json`, `common_types.json`) and registered pristine `Catalog` instances.
* **`CatalogResolver`**: Negotiates client capabilities (`a2uiClientCapabilities`) to select matching discrete `Catalog` instances (well-known or inline) according to protocol specification.
* **`CatalogTransformer`**: Abstract interface and pipeline implementations (e.g. `PruningTransformer`, `ComponentAliasTransformer`) performing bidirectional schema and message transformations.
* **`ExampleManager`**: Loads example JSON files and validates them against catalog schemas.
* **`PromptGenerator`**: Formats `Catalog` data objects, workflow rules, and examples into system instruction text. Supports optional schema relaxation (`relax_strict_validation=True`) for LLM prompt rendering without mutating base catalog objects.
* **`A2uiValidator`**: Handles payload and example validation with initializer-level strictness settings (`strict=True\|False`).
* **`A2uiSchemaManager` (Backward Compatibility Facade)**: Retains existing API signatures for existing callers and tests by delegating internally to the new components.
## Sample Integration (`samples/agent/adk/restaurant_finder`)
In sample agents like `samples/agent/adk/restaurant_finder/agent.py`, initializing catalogs and generating prompts becomes clear and explicit:
```python
# 1. Initialize repository and helpers
repository = CatalogRepository(
version=version,
catalogs=[BasicCatalog.get_config(version=version)],
)
example_manager = ExampleManager({repository.default_catalog().catalog_id: f"examples/{version}"})
prompt_generator = PromptGenerator(relax_strict_validation=True)
# 2. Get target Catalog data object
catalog = repository.default_catalog()
# 3. Generate system prompt directly from Catalog data object
instruction = prompt_generator.generate_prompt(
catalog=catalog,
role_description=ROLE_DESCRIPTION,
ui_description=UI_DESCRIPTION,
examples=example_manager.load_examples(catalog, validate=True),
include_schema=True,
)
```
Hướng dẫn đóng góp
Hướng nghiên cứu
Tệp chính là agent_sdks/python/a2ui_agent/src/a2ui/schema/manager.py. Hãy xem xét class A2uiSchemaManager hiện tại và đối tượng dữ liệu Catalog trong agent_sdks/python/a2ui_core/src/a2ui/core/catalog/catalog.py. Hãy tìm hiểu cách phân chia component được đề xuất và cách chúng tương tác với nhau. Phần tích hợp mẫu trong samples/agent/adk/restaurant_finder/agent.py cho thấy cách sử dụng dự kiến. Hãy bắt đầu bằng cách kiểm tra các test hiện có để hiểu hành vi hiện tại.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- python
- Lĩnh vực
- backend-api-design
- Loại issue
- Tái cấu trúc
- Độ khó
- 4/5
- Thời gian dự kiến
- 3-5 ngày
- Mức độ hoạt động
- Ít trao đổi
- Độ rõ ràng
- Đặc tả rõ ràng
- Mức phù hợp với người mới
- 35/100