a2ui-project / a2ui-project/a2ui

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

Đang mở
#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

Đánh giá

Issue này chưa được đánh giá.

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.