a2ui-project / a2ui-project/a2ui

[Python SDK] Use abstract collection types (Sequence, Mapping) for parameters in schema manager and inference formats

Đang mở Phù hợp với người mới
#2,415 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
component: agent_sdk P2 type: feature/enhancement
Ngôn ngữ chính
TypeScript
Star
16.4k
Fork
1.3k
Merge trung bình
2 ngày 13 giờ
Pull request đã merge (30 ngày)
134

Mô tả

- [x] I have searched the existing issues to make sure this feature has not already been requested.

## Is your feature request related to a problem? Please describe.

In the Python SDK (`agent_sdks/python/a2ui_agent`), several core function parameters and schema models currently specify concrete, invariant collection types (`list[T]` and `dict[K, V]`) in signatures where only iteration or read-only lookup is performed:

1. **`agent_sdks/python/a2ui_agent/src/a2ui/schema/manager.py` & `agent_sdks/python/a2ui_agent/src/a2ui/inference_formats/direct_json/format.py`**:
- `catalogs`: Typed as `Optional[list[CatalogConfig]] = None`. Callers passing immutable collections (e.g., `tuple[CatalogConfig, ...]`) fail static type checking due to collection invariance (PEP 484).
- `schema_modifiers`: Typed as `Optional[list[Callable[[dict[str, Any]], dict[str, Any]]]] = None`. Callers passing tuples or other sequences of modifier functions fail type checks unless converted to mutable `list`.
- `client_ui_capabilities`: Typed as `Optional[Union[dict[str, Any], V09Capabilities]] = None`. Callers passing read-only mappings, immutable dictionaries, or protobuf `Mapping[str, Any]` structures fail type checking.
2. **`agent_sdks/python/a2ui_agent/src/a2ui/schema/catalog.py`**:
- `common_types_schema`: Defined as `Dict[str, Any]` without an optional fallback, requiring dummy empty dictionaries when common types are not defined.

Under strict static type checkers (e.g., Mypy, Pyre, Pytype), callers are forced to perform defensive `list(...)` and `dict(...)` conversions at every call site.

## Describe the Proposed Solution

Adopt abstract container protocols (`Sequence`, `Mapping`) from `typing` / `collections.abc` for read-only input parameters across the Python SDK:

1. **`schema/manager.py` & `inference_formats/direct_json/format.py`**:
- `catalogs: Optional[Sequence[CatalogConfig]] = None`
- `schema_modifiers: Optional[Sequence[Callable[..., Any]]] = None`
- `client_ui_capabilities: Optional[Union[dict[str, Any], Mapping[str, Any], V09Capabilities]] = None`
2. **`schema/catalog.py`**:
- `common_types_schema: Optional[Dict[str, Any]] = None` (or `Optional[Mapping[str, Any]] = None`)

## Describe Alternatives Considered

- Keep `list` and `dict` concrete types, requiring all downstream callers to convert tuples/mappings to mutable lists and dicts prior to calling `create_schema_manager()` and format generators. This adds boilerplate and runtime copying overhead.

## Additional Context

Per standard Python typing guidelines (PEP 484):
> "Arguments should be annotated with abstract collection types (such as `Sequence`, `Mapping`, `Iterable`) rather than concrete collection types (such as `list`, `dict`), unless mutation of the object is required."

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

The issue specifies the exact files to change: agent_sdks/python/a2ui_agent/src/a2ui/schema/manager.py, inference_formats/direct_json/format.py, and schema/catalog.py. Start by reading the current type annotations in those files. Understand the difference between concrete types (list, dict) and abstract types (Sequence, Mapping) from the typing module. Change the parameter types as described, then run the project's type checker (likely mypy) to verify the changes are correct. Look for existing tests related to schema creation to ensure nothing breaks.

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
api, backend, tooling
Loại issue
Tái cấu trúc
Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức độ hoạt động
Sôi nổi
Độ rõ ràng
Đặc tả rõ ràng
Mức phù hợp với người mới
70/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.