a2ui-project / a2ui-project/a2ui

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

Aperta
#2,415 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
component: agent_sdk P2 type: feature/enhancement
Lingua principale
TypeScript
Stelle
16.4k
Fork
1.3k
Merge medio
2g 13h
PR unite (30g)
134

Descrizione

- [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."

Guida per i contributori

Apri la guida per i contributori

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.