a2ui-project / a2ui-project/a2ui

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

Open Beginner friendly
#2,415 0 comments 0 reactions 0 assignees View on GitHub
component: agent_sdk P2 type: feature/enhancement
Dominant language
TypeScript
Stars
16.4k
Forks
1.3k
Avg merge
2d 13h
Merged PRs (30d)
134

Description

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

Contributor guide

Open the contributing guide

Research direction

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.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend, tooling
Issue type
Refactor
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
70/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.