openai-agents-python/integration_tests/_contract_surface.py

1362 lines
53 KiB
Python

"""Parse release policy and describe public API surfaces for generation and validation."""
from __future__ import annotations
import ast
import dataclasses
import enum
import importlib
import inspect
import json
import sys
import typing
from collections.abc import Callable, Iterable, Mapping
from importlib.util import find_spec
from pathlib import Path
from types import FunctionType, ModuleType, UnionType
from typing import (
Any,
ForwardRef,
Literal,
TypeAlias,
Union,
cast,
get_args,
get_origin,
)
import typing_extensions
from pydantic import BaseModel
from typing_extensions import NotRequired, Required
@dataclasses.dataclass(frozen=True)
class OptionalDependencyInstallation:
dependency_module: str
extra: str | None = None
requirement: str | None = None
unsupported_platforms: tuple[str, ...] = ()
def is_supported_on_current_platform(self) -> bool:
return sys.platform not in self.unsupported_platforms
@dataclasses.dataclass(frozen=True)
class SubmoduleExportPolicy:
modules: dict[str, dict[str, dict[str, str]]]
dependency_installations: tuple[OptionalDependencyInstallation, ...]
canonical_imports: tuple[dict[str, str], ...] = ()
public_class_contracts: tuple[dict[str, Any], ...] = ()
public_properties: tuple[dict[str, Any], ...] = ()
public_type_aliases: tuple[dict[str, str], ...] = ()
public_typed_dicts: tuple[dict[str, Any], ...] = ()
def load_api_contract(path: Path) -> dict[str, Any]:
contract = cast(dict[str, Any], json.loads(path.read_text(encoding="utf-8")))
_add_legacy_literal_types(contract)
return contract
def load_submodule_export_policy(path: Path) -> SubmoduleExportPolicy:
value = json.loads(path.read_text(encoding="utf-8"))
if not isinstance(value, dict):
raise ValueError("submodule export policy must be an object")
unknown_top_level_fields = sorted(
set(value)
- {
"canonical_imports",
"modules",
"optional_dependencies",
"public_class_contracts",
"public_properties",
"public_type_aliases",
"public_typed_dicts",
}
)
if unknown_top_level_fields:
raise ValueError(
f"submodule export policy has unknown fields: {unknown_top_level_fields!r}"
)
modules = value.get("modules")
if not isinstance(modules, dict):
raise ValueError("submodule export policy modules must be an object keyed by module name")
policy: dict[str, dict[str, dict[str, str]]] = {}
for module_name, declarations in modules.items():
if type(module_name) is not str or not module_name:
raise ValueError("submodule export policy module names must be non-empty strings")
if not isinstance(declarations, dict):
raise ValueError(f"submodule export policy for {module_name} must be an object")
unknown_fields = sorted(set(declarations) - {"optional_bindings", "optional_exports"})
if unknown_fields:
raise ValueError(
f"submodule export policy for {module_name} has unknown fields: {unknown_fields!r}"
)
policy[module_name] = {
"optional_bindings": _optional_dependency_modules(
declarations.get("optional_bindings", {}), field_name="optional_bindings"
),
"optional_exports": _optional_dependency_modules(
declarations.get("optional_exports", {}), field_name="optional_exports"
),
}
dependencies = value.get("optional_dependencies")
if not isinstance(dependencies, dict):
raise ValueError("submodule export policy optional_dependencies must be an object")
dependency_installations: list[OptionalDependencyInstallation] = []
for module_name, installation in dependencies.items():
if type(module_name) is not str or not module_name:
raise ValueError("optional dependency module names must be non-empty strings")
if not isinstance(installation, dict):
raise ValueError(
f"optional dependency installation for {module_name} must be an object"
)
unknown_fields = sorted(
set(installation) - {"extra", "requirement", "unsupported_platforms"}
)
if unknown_fields:
raise ValueError(
f"optional dependency installation for {module_name} has unknown fields: "
f"{unknown_fields!r}"
)
configured = [field for field in ("extra", "requirement") if field in installation]
if len(configured) != 1:
raise ValueError(
f"optional dependency installation for {module_name} must declare exactly one "
"of extra or requirement"
)
field_name = configured[0]
install_value = installation[field_name]
if type(install_value) is not str or not install_value:
raise ValueError(
f"optional dependency installation {field_name} for {module_name} must be a "
"non-empty string"
)
unsupported_platforms = installation.get("unsupported_platforms", [])
if (
not isinstance(unsupported_platforms, list)
or not all(type(platform) is str and platform for platform in unsupported_platforms)
or len(unsupported_platforms) != len(set(unsupported_platforms))
):
raise ValueError(
f"optional dependency installation unsupported_platforms for {module_name} "
"must be a list of unique non-empty strings"
)
dependency_installations.append(
OptionalDependencyInstallation(
dependency_module=module_name,
extra=install_value if field_name == "extra" else None,
requirement=install_value if field_name == "requirement" else None,
unsupported_platforms=tuple(unsupported_platforms),
)
)
referenced_dependencies = {
dependency
for module_policy in policy.values()
for declarations in module_policy.values()
for dependency in declarations.values()
}
missing_installations = sorted(referenced_dependencies - set(dependencies))
unused_installations = sorted(set(dependencies) - referenced_dependencies)
if missing_installations:
raise ValueError(
"submodule export policy dependencies are missing installation declarations: "
f"{missing_installations!r}"
)
if unused_installations:
raise ValueError(
"submodule export policy has unused dependency installation declarations: "
f"{unused_installations!r}"
)
return SubmoduleExportPolicy(
modules=policy,
dependency_installations=tuple(
sorted(
dependency_installations, key=lambda installation: installation.dependency_module
)
),
canonical_imports=_canonical_import_policy(value.get("canonical_imports", [])),
public_class_contracts=_public_class_contract_policy(
value.get("public_class_contracts", [])
),
public_properties=_public_property_policy(value.get("public_properties", [])),
public_type_aliases=_public_type_alias_policy(value.get("public_type_aliases", [])),
public_typed_dicts=_public_typed_dict_policy(value.get("public_typed_dicts", [])),
)
def _canonical_import_policy(value: object) -> tuple[dict[str, str], ...]:
if not isinstance(value, list):
raise ValueError("submodule export policy canonical_imports must be a list")
required_fields = {"canonical_module", "canonical_name", "module", "name"}
entries: list[dict[str, str]] = []
identities: set[tuple[str, str]] = set()
for entry in value:
if not isinstance(entry, dict) or set(entry) != required_fields:
raise ValueError(
"submodule export policy canonical_imports entries must contain exactly "
"canonical_module, canonical_name, module, and name"
)
if not all(type(entry[field]) is str and entry[field] for field in required_fields):
raise ValueError(
"submodule export policy canonical_imports values must be non-empty strings"
)
identity = (entry["module"], entry["name"])
if identity in identities:
raise ValueError(
"submodule export policy canonical_imports must not repeat "
f"{entry['module']}.{entry['name']}"
)
identities.add(identity)
entries.append({field: entry[field] for field in sorted(required_fields)})
return tuple(entries)
def _public_property_policy(value: object) -> tuple[dict[str, Any], ...]:
if not isinstance(value, list):
raise ValueError("submodule export policy public_properties must be a list")
entries: list[dict[str, Any]] = []
identities: set[tuple[str, str, str]] = set()
for entry in value:
if not isinstance(entry, dict):
raise ValueError("submodule export policy public_properties entries must be objects")
owner_fields = {"class_name", "factory_name"} & set(entry)
required_fields = {"module", "names", *owner_fields}
if len(owner_fields) != 1 or set(entry) != required_fields:
raise ValueError(
"submodule export policy public_properties entries must contain exactly "
"module, names, and one of class_name or factory_name"
)
owner_field = next(iter(owner_fields))
module_name = entry["module"]
owner_name = entry[owner_field]
names = entry["names"]
if type(module_name) is not str or not module_name:
raise ValueError(
"submodule export policy public_properties module must be a non-empty string"
)
if type(owner_name) is not str or not owner_name:
raise ValueError(
f"submodule export policy public_properties {owner_field} must be a non-empty "
"string"
)
if (
not isinstance(names, list)
or not names
or not all(type(name) is str and name for name in names)
or len(names) != len(set(names))
):
raise ValueError(
"submodule export policy public_properties names must be a non-empty list of "
"unique non-empty strings"
)
identity = (owner_field, module_name, owner_name)
if identity in identities:
raise ValueError(
"submodule export policy public_properties must not repeat "
f"{module_name}.{owner_name}"
)
identities.add(identity)
normalized_entry = {
owner_field: owner_name,
"module": module_name,
"names": list(names),
}
entries.append(normalized_entry)
return tuple(entries)
def _public_class_contract_policy(value: object) -> tuple[dict[str, Any], ...]:
if not isinstance(value, list):
raise ValueError("submodule export policy public_class_contracts must be a list")
required_fields = {"class_name", "module"}
contract_fields = {"abstract", "abstract_members"}
entries: list[dict[str, Any]] = []
identities: set[tuple[str, str]] = set()
for entry in value:
if (
not isinstance(entry, dict)
or not required_fields.issubset(entry)
or not set(entry).issubset(required_fields | contract_fields)
or not (set(entry) & contract_fields)
):
raise ValueError(
"submodule export policy public_class_contracts entries must contain exactly "
"module, class_name, and at least one of abstract or abstract_members"
)
module_name = entry["module"]
class_name = entry["class_name"]
if type(module_name) is not str or not module_name:
raise ValueError(
"submodule export policy public_class_contracts module must be a non-empty string"
)
if type(class_name) is not str or not class_name:
raise ValueError(
"submodule export policy public_class_contracts class_name must be a non-empty "
"string"
)
if "abstract" in entry and type(entry["abstract"]) is not bool:
raise ValueError(
"submodule export policy public_class_contracts abstract must be a boolean"
)
abstract_members = entry.get("abstract_members")
if "abstract_members" in entry and (
not isinstance(abstract_members, list)
or not abstract_members
or not all(type(name) is str and name for name in abstract_members)
or len(abstract_members) != len(set(abstract_members))
):
raise ValueError(
"submodule export policy public_class_contracts abstract_members must be a "
"non-empty list of unique non-empty strings"
)
identity = (module_name, class_name)
if identity in identities:
raise ValueError(
"submodule export policy public_class_contracts must not repeat "
f"{module_name}.{class_name}"
)
identities.add(identity)
normalized_entry: dict[str, Any] = {
"class_name": class_name,
"module": module_name,
}
if "abstract" in entry:
normalized_entry["abstract"] = entry["abstract"]
if "abstract_members" in entry:
normalized_entry["abstract_members"] = sorted(abstract_members)
entries.append(normalized_entry)
return tuple(entries)
def _public_typed_dict_policy(value: object) -> tuple[dict[str, Any], ...]:
if not isinstance(value, list):
raise ValueError("submodule export policy public_typed_dicts must be a list")
required_fields = {"class_name", "module", "names"}
entries: list[dict[str, Any]] = []
identities: set[tuple[str, str]] = set()
for entry in value:
if not isinstance(entry, dict) or set(entry) != required_fields:
raise ValueError(
"submodule export policy public_typed_dicts entries must contain exactly "
"class_name, module, and names"
)
module_name = entry["module"]
class_name = entry["class_name"]
names = entry["names"]
if type(module_name) is not str or not module_name:
raise ValueError(
"submodule export policy public_typed_dicts module must be a non-empty string"
)
if type(class_name) is not str or not class_name:
raise ValueError(
"submodule export policy public_typed_dicts class_name must be a non-empty string"
)
if (
not isinstance(names, list)
or not names
or not all(type(name) is str and name for name in names)
or len(names) != len(set(names))
):
raise ValueError(
"submodule export policy public_typed_dicts names must be a non-empty list of "
"unique non-empty strings"
)
identity = (module_name, class_name)
if identity in identities:
raise ValueError(
"submodule export policy public_typed_dicts must not repeat "
f"{module_name}.{class_name}"
)
identities.add(identity)
entries.append({"class_name": class_name, "module": module_name, "names": list(names)})
return tuple(entries)
def _public_type_alias_policy(value: object) -> tuple[dict[str, str], ...]:
if not isinstance(value, list):
raise ValueError("submodule export policy public_type_aliases must be a list")
required_fields = {"module", "name"}
entries: list[dict[str, str]] = []
identities: set[tuple[str, str]] = set()
for entry in value:
if not isinstance(entry, dict) or set(entry) != required_fields:
raise ValueError(
"submodule export policy public_type_aliases entries must contain exactly "
"module and name"
)
if not all(type(entry[field]) is str and entry[field] for field in required_fields):
raise ValueError(
"submodule export policy public_type_aliases values must be non-empty strings"
)
identity = (entry["module"], entry["name"])
if identity in identities:
raise ValueError(
"submodule export policy public_type_aliases must not repeat "
f"{entry['module']}.{entry['name']}"
)
identities.add(identity)
entries.append({"module": entry["module"], "name": entry["name"]})
return tuple(entries)
def _add_legacy_literal_types(value: object) -> None:
if isinstance(value, dict):
if value.get("kind") == "literal" and "value" in value and "type" not in value:
literal = value["value"]
value["type"] = f"{type(literal).__module__}.{type(literal).__qualname__}"
for child in value.values():
_add_legacy_literal_types(child)
elif isinstance(value, list):
for child in value:
_add_legacy_literal_types(child)
def _default_contract(value: object) -> dict[str, object]:
if value is inspect.Parameter.empty or value is dataclasses.MISSING:
return {"kind": "required"}
if value.__class__.__name__ == "_HAS_DEFAULT_FACTORY_CLASS":
return {"kind": "factory"}
if value is None or isinstance(value, bool | int | float | str):
return {
"kind": "literal",
"type": f"{type(value).__module__}.{type(value).__qualname__}",
"value": value,
}
voice_testing = sys.modules.get("agents.voice.testing")
if voice_testing is not None and value is getattr(voice_testing, "_START_NOT_CONFIGURED", None):
return {
"kind": "sentinel",
"identity": "agents.voice.testing._START_NOT_CONFIGURED",
}
value_type = f"{type(value).__module__}.{type(value).__qualname__}"
from agents.mcp.server import _UNSET as mcp_failure_error_unset
from agents.retry import _UNSET as retry_unset
from agents.tool import _UNSET_FAILURE_ERROR_FUNCTION as failure_error_function_unset
from agents.tool_context import _MISSING as tool_context_missing
sentinel_identities = (
(retry_unset, "agents.retry._UNSET"),
(mcp_failure_error_unset, "agents.mcp.server._UNSET"),
(failure_error_function_unset, "agents.tool._UNSET_FAILURE_ERROR_FUNCTION"),
(tool_context_missing, "agents.tool_context._MISSING"),
)
for sentinel, identity in sentinel_identities:
if value is sentinel:
return {"kind": "sentinel", "identity": identity}
if value_type == "pydantic.fields.FieldInfo":
return {"kind": "repr", "type": value_type, "value": repr(value)}
if isinstance(value, enum.Enum):
return {
"kind": "enum",
"type": value_type,
"name": value.name,
"value": _default_contract(value.value),
}
if isinstance(value, type):
return {
"kind": "type",
"identity": f"{value.__module__}.{value.__qualname__}",
}
if isinstance(value, tuple | list):
return {
"kind": "sequence",
"type": value_type,
"items": [_default_contract(item) for item in value],
}
if isinstance(value, dict):
return {
"kind": "mapping",
"type": value_type,
"items": [
[_default_contract(key), _default_contract(item)] for key, item in value.items()
],
}
if value_type.startswith("agents.") and callable(getattr(value, "model_dump", None)):
dumped = value.model_dump(mode="python") # type: ignore[attr-defined]
return {
"kind": "model",
"type": value_type,
"value": _default_contract(dumped),
}
if dataclasses.is_dataclass(value) and not isinstance(value, type):
return {
"kind": "dataclass",
"type": value_type,
"fields": [
{"name": field.name, "value": _default_contract(getattr(value, field.name))}
for field in dataclasses.fields(value)
],
}
if type(value) is FunctionType and value.__module__.startswith("agents."):
return {
"kind": "callable",
"identity": f"{value.__module__}.{value.__qualname__}",
}
raise TypeError(f"Unsupported public API default value: {value_type}")
def _parameter_records(
parameters: Iterable[inspect.Parameter],
) -> list[dict[str, object]]:
return [
{
"name": parameter.name,
"kind": parameter.kind.name,
"default": _default_contract(parameter.default),
}
for parameter in parameters
]
def _signature(value: Callable[..., Any]) -> inspect.Signature:
return inspect.signature(value)
def _parameter_contract(value: Callable[..., Any]) -> list[dict[str, object]]:
parameters = list(_signature(value).parameters.values())
if issubclass(type(value), type) and issubclass(cast(type, value), enum.Enum):
parameters = list(_signature(value.__new__).parameters.values())[1:]
return _parameter_records(parameters)
def _dataclass_field_contract(value: object) -> list[dict[str, object]]:
if not dataclasses.is_dataclass(value):
return []
result: list[dict[str, object]] = []
for field in dataclasses.fields(value):
if field.name.startswith("_"):
continue
if field.default_factory is not dataclasses.MISSING:
factory = cast(Callable[..., Any], field.default_factory)
default_contract: dict[str, object] = {
"kind": "factory",
"factory": f"{factory.__module__}.{factory.__qualname__}",
}
else:
default_contract = _default_contract(field.default)
result.append(
{
"name": field.name,
"init": field.init,
"default": default_contract,
}
)
return result
def _pydantic_model_field_contract(value: object) -> list[dict[str, object]] | None:
if not (isinstance(value, type) and issubclass(value, BaseModel)):
return None
result: list[dict[str, object]] = []
for name, field in value.model_fields.items():
if name.startswith("_"):
continue
if field.is_required():
default_contract: dict[str, object] = {"kind": "required"}
elif field.default_factory is not None:
factory = field.default_factory
default_contract = {
"kind": "factory",
"factory": f"{factory.__module__}.{factory.__qualname__}",
}
else:
default_contract = _default_contract(field.default)
result.append({"name": name, "default": default_contract})
return result
def _callable_kind(value: Callable[..., Any]) -> str | None:
if issubclass(type(value), type):
return "class"
if type(value) is FunctionType:
return "function"
return None
def _is_sdk_owned_callable(value: object) -> bool:
module_name = getattr(value, "__module__", None)
return (
_callable_kind(cast(Callable[..., Any], value)) is not None
and isinstance(module_name, str)
and (module_name == "agents" or module_name.startswith("agents."))
)
def _enum_member_contract(value: object) -> list[dict[str, object]] | None:
if not (issubclass(type(value), type) and issubclass(cast(type, value), enum.Enum)):
return None
enum_type = cast(type[enum.Enum], value)
members: list[dict[str, object]] = []
for name, member in enum_type.__members__.items():
member_value = member.value
if member_value is None or isinstance(member_value, bool | int | float | str):
value_contract: dict[str, object] = {
"kind": "literal",
"type": f"{type(member_value).__module__}.{type(member_value).__qualname__}",
"value": member_value,
}
else:
raise TypeError(
f"Unsupported public enum value for "
f"{enum_type.__module__}.{enum_type.__qualname__}."
f"{name}: {type(member_value).__module__}.{type(member_value).__qualname__}"
)
members.append({"name": name, "value": value_contract})
return members
def _class_member_contract(descriptor: object) -> dict[str, object] | None:
descriptor_type = type(descriptor)
if descriptor_type is staticmethod:
binding = "static"
function = object.__getattribute__(descriptor, "__func__")
skip_first = False
elif descriptor_type is classmethod:
binding = "class"
function = object.__getattribute__(descriptor, "__func__")
skip_first = True
elif type(descriptor) is FunctionType:
binding = "instance"
function = descriptor
skip_first = True
else:
return None
if type(function) is not FunctionType:
return None
try:
parameters = list(_signature(function).parameters.values())
except (TypeError, ValueError):
return None
if skip_first:
if not parameters:
return None
parameters = parameters[1:]
return {
"binding": binding,
"execution_kind": _function_execution_kind(function),
"parameters": _parameter_records(parameters),
}
def _function_execution_kind(value: object) -> str:
if inspect.isasyncgenfunction(value):
return "async_generator"
if inspect.iscoroutinefunction(value):
return "coroutine"
if inspect.isgeneratorfunction(value):
return "generator"
return "sync"
def _sdk_public_class_descriptor(value: type, name: str) -> object | None:
for owner in value.__mro__:
namespace = vars(owner)
if name not in namespace:
continue
owner_module = owner.__module__
if owner is value or (
isinstance(owner_module, str)
and (owner_module == "agents" or owner_module.startswith("agents."))
):
return cast(object, inspect.getattr_static(value, name))
return None
return None
def _public_class_member_contract(value: object) -> dict[str, dict[str, object]]:
if not issubclass(type(value), type):
return {}
class_value = cast(type, value)
value_identity = f"{class_value.__module__}.{class_value.__qualname__}"
candidate_names: list[str] = []
seen_names: set[str] = set()
def add_candidate_names(namespace: Mapping[str, object]) -> None:
for name in namespace:
if name in seen_names:
continue
seen_names.add(name)
candidate_names.append(name)
add_candidate_names(vars(class_value))
for base in class_value.__mro__[1:]:
base_module = base.__module__
if isinstance(base_module, str) and (
base_module == "agents" or base_module.startswith("agents.")
):
add_candidate_names(vars(base))
members: dict[str, dict[str, object]] = {}
for name in candidate_names:
if name.startswith("_"):
continue
descriptor = _sdk_public_class_descriptor(class_value, name)
if descriptor is None:
continue
try:
member = _class_member_contract(descriptor)
except TypeError as error:
raise TypeError(
f"Unable to contract public method {value_identity}.{name}: {error}"
) from None
if member is not None:
members[name] = member
return members
def _callable_contract(value: Callable[..., Any]) -> dict[str, Any]:
kind = _callable_kind(value)
if kind is None:
raise TypeError(f"Unsupported public callable type: {type(value)!r}")
contract: dict[str, Any] = {
"kind": kind,
"parameters": _parameter_contract(value),
"dataclass_fields": _dataclass_field_contract(value),
}
if kind == "function":
contract["execution_kind"] = _function_execution_kind(value)
model_fields = _pydantic_model_field_contract(value)
if model_fields is not None:
contract["model_fields"] = model_fields
enum_members = _enum_member_contract(value)
if enum_members is not None:
contract["enum_members"] = enum_members
if kind == "class":
contract["members"] = _public_class_member_contract(value)
return contract
def _public_property_identity(entry: Mapping[str, Any]) -> tuple[str, str, str]:
if "class_name" in entry:
return ("class_name", cast(str, entry["module"]), cast(str, entry["class_name"]))
return ("factory_name", cast(str, entry["module"]), cast(str, entry["factory_name"]))
def _annotation_contract(annotation: object) -> str:
if isinstance(annotation, ForwardRef):
annotation_text = annotation.__forward_arg__
elif isinstance(annotation, str):
annotation_text = annotation
else:
annotation_text = inspect.formatannotation(annotation)
for wrapper_name in ("Required", "NotRequired"):
for module_name in ("typing", "typing_extensions"):
qualified_prefix = f"{module_name}.{wrapper_name}["
if annotation_text.startswith(qualified_prefix):
return f"{wrapper_name}[{annotation_text.removeprefix(qualified_prefix)}"
return annotation_text
def _sorted_type_alias_members(members: Iterable[dict[str, object]]) -> list[dict[str, object]]:
return sorted(
members,
key=lambda member: (
cast(str, member["kind"]),
json.dumps(member, sort_keys=True, separators=(",", ":")),
),
)
def _is_type_alias_type(value: object) -> bool:
native_type_alias_type = getattr(typing, "TypeAliasType", typing_extensions.TypeAliasType)
return isinstance(value, typing_extensions.TypeAliasType | native_type_alias_type)
def _is_type_alias_annotation(annotation: object, module: object) -> bool:
if annotation is TypeAlias or annotation is typing_extensions.TypeAlias:
return True
if not isinstance(annotation, str):
return False
reference_parts = annotation.split(".")
if not reference_parts or not all(part.isidentifier() for part in reference_parts):
return False
missing = object()
resolved = getattr(module, reference_parts[0], missing)
for part in reference_parts[1:]:
if resolved is missing:
break
resolved = getattr(resolved, part, missing)
return resolved is TypeAlias or resolved is typing_extensions.TypeAlias
def _module_declares_type_alias(module: object, alias_name: str, value: object) -> bool:
annotations = getattr(module, "__annotations__", {})
if not isinstance(annotations, Mapping) or alias_name not in annotations:
return False
missing = object()
return (
_is_type_alias_annotation(annotations[alias_name], module)
and getattr(module, alias_name, missing) is value
)
class _ModuleBindingVisitor(ast.NodeVisitor):
def __init__(self, name: str):
self.name = name
self.count = 0
self.has_wildcard_import = False
self.from_imports: list[tuple[ast.ImportFrom, str]] = []
self._bindings_target_module = True
def _count(self, name: str | None) -> None:
if self._bindings_target_module:
self.count += name == self.name
def _visit_nested_scope(self, body: list[ast.stmt]) -> None:
bindings_target_module = _scope_declares_global(body, self.name)
previous_bindings_target_module = self._bindings_target_module
self._bindings_target_module = bindings_target_module
for statement in body:
self.visit(statement)
self._bindings_target_module = previous_bindings_target_module
def _visit_arguments(self, arguments: ast.arguments) -> None:
all_arguments = [
*arguments.posonlyargs,
*arguments.args,
*arguments.kwonlyargs,
]
if arguments.vararg is not None:
all_arguments.append(arguments.vararg)
if arguments.kwarg is not None:
all_arguments.append(arguments.kwarg)
for argument in all_arguments:
if argument.annotation is not None:
self.visit(argument.annotation)
for default in [*arguments.defaults, *arguments.kw_defaults]:
if default is not None:
self.visit(default)
def _visit_function_definition(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
self._count(node.name)
for decorator in node.decorator_list:
self.visit(decorator)
self._visit_arguments(node.args)
if node.returns is not None:
self.visit(node.returns)
def _visit_comprehension(
self, generators: list[ast.comprehension], values: list[ast.expr]
) -> None:
for generator in generators:
self.visit(generator.iter)
for condition in generator.ifs:
self.visit(condition)
for value in values:
self.visit(value)
def visit_Name(self, node: ast.Name) -> None:
if isinstance(node.ctx, ast.Store | ast.Del):
self._count(node.id)
def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
self._visit_function_definition(node)
self._visit_nested_scope(node.body)
def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
self._visit_function_definition(node)
self._visit_nested_scope(node.body)
def visit_ClassDef(self, node: ast.ClassDef) -> None:
self._count(node.name)
for decorator in node.decorator_list:
self.visit(decorator)
for base in node.bases:
self.visit(base)
for keyword in node.keywords:
self.visit(keyword.value)
self._visit_nested_scope(node.body)
def visit_Lambda(self, node: ast.Lambda) -> None:
self._visit_arguments(node.args)
def visit_ListComp(self, node: ast.ListComp) -> None:
self._visit_comprehension(node.generators, [node.elt])
def visit_SetComp(self, node: ast.SetComp) -> None:
self._visit_comprehension(node.generators, [node.elt])
def visit_DictComp(self, node: ast.DictComp) -> None:
self._visit_comprehension(node.generators, [node.key, node.value])
def visit_GeneratorExp(self, node: ast.GeneratorExp) -> None:
self._visit_comprehension(node.generators, [node.elt])
def visit_ExceptHandler(self, node: ast.ExceptHandler) -> None:
self._count(node.name)
self.generic_visit(node)
def visit_MatchAs(self, node: ast.MatchAs) -> None:
self._count(node.name)
self.generic_visit(node)
def visit_MatchStar(self, node: ast.MatchStar) -> None:
self._count(node.name)
def visit_MatchMapping(self, node: ast.MatchMapping) -> None:
self._count(node.rest)
self.generic_visit(node)
def visit_Import(self, node: ast.Import) -> None:
for imported in node.names:
self._count(imported.asname or imported.name.split(".", 1)[0])
def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
if not self._bindings_target_module:
return
for imported in node.names:
if imported.name == "*":
self.has_wildcard_import = True
continue
binding_name = imported.asname or imported.name
self._count(binding_name)
if binding_name == self.name:
self.from_imports.append((node, imported.name))
def _scope_declares_global(nodes: Iterable[ast.AST], name: str) -> bool:
for node in nodes:
if isinstance(node, ast.Global):
if name in node.names:
return True
continue
if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef | ast.Lambda):
continue
if _scope_declares_global(ast.iter_child_nodes(node), name):
return True
return False
def _direct_import_source(
module: object, export_name: str, *, package_root: str
) -> tuple[ModuleType, str] | None:
module_name = getattr(module, "__name__", None)
package_name = getattr(module, "__package__", None)
if not isinstance(module_name, str) or not isinstance(package_name, str):
return None
try:
module_tree = ast.parse(inspect.getsource(module))
except (OSError, SyntaxError, TypeError):
return None
bindings = _ModuleBindingVisitor(export_name)
bindings.visit(module_tree)
if bindings.count != 1 or bindings.has_wildcard_import or len(bindings.from_imports) != 1:
return None
statement, source_name = bindings.from_imports[0]
if statement.level:
relative_name = "." * statement.level + (statement.module or "")
try:
source_module_name = importlib.util.resolve_name(relative_name, package_name)
except ImportError:
return None
else:
source_module_name = statement.module
if source_module_name is None or not (
source_module_name == package_root or source_module_name.startswith(f"{package_root}.")
):
return None
source_module = sys.modules.get(source_module_name)
if not isinstance(source_module, ModuleType):
return None
return source_module, source_name
def _has_explicit_type_alias_declaration(
agents_module: object, export_name: str, value: object
) -> bool:
package_root = getattr(agents_module, "__name__", None)
module, alias_name = agents_module, export_name
visited_bindings: set[tuple[int, str]] = set()
missing = object()
while (id(module), alias_name) not in visited_bindings:
visited_bindings.add((id(module), alias_name))
if getattr(module, alias_name, missing) is not value:
return False
if _module_declares_type_alias(module, alias_name, value):
return True
if not isinstance(package_root, str):
return False
import_source = _direct_import_source(module, alias_name, package_root=package_root)
if import_source is None:
return False
module, alias_name = import_source
return False
def _is_public_type_alias(agents_module: object, export_name: str, value: object) -> bool:
return (
get_origin(value) is not None
or _is_type_alias_type(value)
or _has_explicit_type_alias_declaration(agents_module, export_name, value)
)
def _type_alias_definition(
value: object, *, visited_alias_ids: frozenset[int] = frozenset()
) -> dict[str, object]:
if value is Any:
return {"kind": "any"}
if _is_type_alias_type(value):
if value.__type_params__:
raise TypeError(f"generic public type alias is unsupported: {value.__name__}")
alias_id = id(value)
if alias_id in visited_alias_ids:
alias_name = getattr(value, "__name__", repr(value))
raise TypeError(f"recursive public type alias is unsupported: {alias_name}")
try:
alias_value = value.__value__
except Exception as error:
raise TypeError(
f"cannot resolve public type alias {value.__name__} at runtime: "
f"{type(error).__name__}: {error}"
) from None
return _type_alias_definition(alias_value, visited_alias_ids=visited_alias_ids | {alias_id})
origin = get_origin(value)
if origin is Literal:
literal_values: list[dict[str, object]] = []
for literal_value in get_args(value):
literal_contract = _default_contract(literal_value)
if literal_contract["kind"] not in {"literal", "enum"}:
raise TypeError(
"public type alias Literal members must use supported literal or enum values"
)
literal_values.append(literal_contract)
return {
"kind": "literal",
"values": _sorted_type_alias_members(literal_values),
}
if origin in {Union, UnionType}:
members = [
_type_alias_definition(member, visited_alias_ids=visited_alias_ids)
for member in get_args(value)
]
return {
"kind": "union",
"members": _sorted_type_alias_members(members),
}
if origin is Callable:
callable_args = get_args(value)
if len(callable_args) != 2:
raise TypeError(
"public Callable type aliases must declare parameters and a return type"
)
parameter_types, return_type = callable_args
if parameter_types is Ellipsis or not isinstance(parameter_types, list | tuple):
raise TypeError("public Callable type aliases must declare explicit parameter types")
return {
"kind": "callable",
"parameters": [
_type_alias_definition(parameter_type, visited_alias_ids=visited_alias_ids)
for parameter_type in parameter_types
],
"return": _type_alias_definition(return_type, visited_alias_ids=visited_alias_ids),
}
if origin is not None:
if not isinstance(origin, type) or not (
origin.__module__ == "agents" or origin.__module__.startswith("agents.")
):
raise TypeError(f"unsupported public generic type alias origin: {origin!r}")
return {
"kind": "generic",
"origin": f"{origin.__module__}.{origin.__qualname__}",
"arguments": [
_type_alias_definition(argument, visited_alias_ids=visited_alias_ids)
for argument in get_args(value)
],
}
if isinstance(value, type) and (
value.__module__ == "builtins"
or value.__module__ == "agents"
or value.__module__.startswith("agents.")
):
return {
"kind": "type",
"identity": f"{value.__module__}.{value.__qualname__}",
}
raise TypeError(f"unsupported public type alias member: {value!r}")
def _public_type_alias_contract(
policy_entries: Iterable[Mapping[str, str]],
agents_module: Any | None,
) -> list[dict[str, object]]:
entries: list[dict[str, object]] = []
missing = object()
for policy_entry in policy_entries:
module_name = policy_entry["module"]
alias_name = policy_entry["name"]
module = _import_contract_module(module_name, agents_module)
alias = getattr(module, alias_name, missing)
if alias is missing:
raise ValueError(
f"Cannot promote public type alias {module_name}.{alias_name} because it is missing"
)
try:
definition = _type_alias_definition(alias)
except TypeError as error:
raise ValueError(
f"Cannot promote public type alias {module_name}.{alias_name}: {error}"
) from None
entries.append({"definition": definition, "module": module_name, "name": alias_name})
return entries
def _typed_dict_field_is_required(typed_dict: type, name: str, annotation: object) -> bool:
if isinstance(annotation, ForwardRef):
annotation_text = annotation.__forward_arg__
if annotation_text.startswith(
("Required[", "typing.Required[", "typing_extensions.Required[")
):
return True
if annotation_text.startswith(
("NotRequired[", "typing.NotRequired[", "typing_extensions.NotRequired[")
):
return False
origin = get_origin(annotation)
if origin is Required:
return True
if origin is NotRequired:
return False
required_keys = getattr(typed_dict, "__required_keys__", frozenset())
optional_keys = getattr(typed_dict, "__optional_keys__", frozenset())
if name in required_keys:
return True
if name in optional_keys:
return False
return bool(getattr(typed_dict, "__total__", True))
def _typed_dict_field_contract(typed_dict: type, name: str) -> dict[str, object] | None:
annotation = getattr(typed_dict, "__annotations__", {}).get(name)
if annotation is None:
return None
return {
"name": name,
"required": _typed_dict_field_is_required(typed_dict, name, annotation),
"annotation": _annotation_contract(annotation),
}
def _public_typed_dict_contract(
policy_entries: Iterable[Mapping[str, Any]],
agents_module: Any | None,
) -> list[dict[str, Any]]:
entries: list[dict[str, Any]] = []
for policy_entry in policy_entries:
module_name = cast(str, policy_entry["module"])
class_name = cast(str, policy_entry["class_name"])
module = _import_contract_module(module_name, agents_module)
typed_dict = getattr(module, class_name, None)
if not typing_extensions.is_typeddict(typed_dict):
raise ValueError(
f"Cannot promote public TypedDict {module_name}.{class_name} because it is "
"missing or no longer a TypedDict"
)
fields: list[dict[str, object]] = []
for name in policy_entry["names"]:
field = _typed_dict_field_contract(typed_dict, name)
if field is None:
raise ValueError(
f"Cannot promote public TypedDict field {module_name}.{class_name}.{name} "
"because it is missing"
)
fields.append(field)
entries.append({"class_name": class_name, "fields": fields, "module": module_name})
return entries
def _optional_dependency_unsupported_platforms(
contract: Mapping[str, Any],
) -> dict[str, tuple[str, ...]]:
value = contract.get("optional_dependency_unsupported_platforms", {})
if not isinstance(value, dict):
raise ValueError("optional_dependency_unsupported_platforms must be an object")
result: dict[str, tuple[str, ...]] = {}
for dependency_module, platforms in value.items():
if type(dependency_module) is not str or not dependency_module:
raise ValueError(
"optional_dependency_unsupported_platforms keys must be non-empty strings"
)
if (
not isinstance(platforms, list)
or not all(type(platform) is str and platform for platform in platforms)
or len(platforms) != len(set(platforms))
):
raise ValueError(
"optional_dependency_unsupported_platforms values must be lists of unique "
"non-empty strings"
)
result[dependency_module] = tuple(platforms)
return result
def _optional_dependency_is_available_for_contract(
dependency_module: str,
unsupported_platforms: Mapping[str, tuple[str, ...]],
) -> bool:
return not _optional_dependency_is_unsupported_for_contract(
dependency_module, unsupported_platforms
) and _optional_dependency_is_available(dependency_module)
def _optional_dependency_is_unsupported_for_contract(
dependency_module: str,
unsupported_platforms: Mapping[str, tuple[str, ...]],
) -> bool:
return sys.platform in unsupported_platforms.get(dependency_module, ())
def _optional_dependency_for_binding(
contract: Mapping[str, Any], module_name: str, binding_name: str
) -> str | None:
dependency = _optional_dependency_for_binding_in_modules(
contract.get("required_submodule_exports", {}), module_name, binding_name
)
if dependency is not None:
return dependency
canonical_dependencies = {
_optional_dependency_for_binding_in_modules(
contract.get("required_submodule_exports", {}), entry["module"], entry["name"]
)
for entry in contract.get("canonical_imports", [])
if entry["canonical_module"] == module_name and entry["canonical_name"] == binding_name
}
if canonical_dependencies and len(canonical_dependencies) == 1:
return next(iter(canonical_dependencies))
return None
def _optional_dependency_for_binding_in_modules(
modules: Mapping[str, Any], module_name: str, binding_name: str
) -> str | None:
module_contract = modules.get(module_name, {})
for field_name in ("optional_bindings", "optional_exports"):
dependency_module = module_contract.get(field_name, {}).get(binding_name)
if dependency_module is not None:
return cast(str, dependency_module)
return None
def _optional_dependency_for_module_import(
contract: Mapping[str, Any], module_name: str
) -> str | None:
modules = contract.get("required_submodule_exports", {})
module_contract = modules.get(module_name, {})
names = module_contract.get("names", [])
try:
optional_bindings = _optional_dependency_modules(
module_contract.get("optional_bindings", {}), field_name="optional_bindings"
)
optional_exports = _optional_dependency_modules(
module_contract.get("optional_exports", {}), field_name="optional_exports"
)
except ValueError:
return None
dependencies = {optional_bindings.get(name) or optional_exports.get(name) for name in names}
if names and len(dependencies) == 1 and None not in dependencies:
return cast(str, next(iter(dependencies)))
if names:
return None
canonical_dependencies = {
_optional_dependency_for_binding(contract, entry["module"], entry["name"])
for entry in contract.get("canonical_imports", [])
if entry["canonical_module"] == module_name
}
if canonical_dependencies and len(canonical_dependencies) == 1:
dependency = next(iter(canonical_dependencies))
if dependency is not None:
return dependency
return None
def _import_contract_module(module_name: str, agents_module: Any | None) -> Any:
if module_name == "agents" and agents_module is not None:
return agents_module
return importlib.import_module(module_name)
def _submodule_export_contract(
module: object,
*,
optional_bindings: Mapping[str, str] | None = None,
optional_exports: Mapping[str, str] | None = None,
allowed_missing_optional_exports: Iterable[str] = (),
) -> dict[str, Any] | None:
exports = getattr(module, "__all__", None)
if exports is None:
return None
if not isinstance(exports, list | tuple) or not all(type(name) is str for name in exports):
raise ValueError("public module __all__ must contain only strings")
names = list(exports)
if len(names) != len(set(names)):
raise ValueError("public module __all__ must not contain duplicate exports")
optional_binding_modules = _optional_dependency_modules(
dict(optional_bindings or {}), field_name="optional_bindings"
)
optional_export_modules = _optional_dependency_modules(
dict(optional_exports or {}), field_name="optional_exports"
)
optional_binding_names = set(optional_binding_modules)
optional_export_names = set(optional_export_modules)
allowed_missing_names = set(allowed_missing_optional_exports)
unknown_optional_names = sorted(
(optional_binding_names | optional_export_names) - set(names) - allowed_missing_names
)
if unknown_optional_names:
raise ValueError(
f"optional submodule bindings are not exported: {unknown_optional_names!r}"
)
names.extend(
name
for name in optional_export_modules
if name in allowed_missing_names and name not in names
)
return {
"names": names,
"optional_bindings": {
name: optional_binding_modules[name] for name in names if name in optional_binding_names
},
"optional_exports": {
name: optional_export_modules[name] for name in names if name in optional_export_names
},
}
def _optional_dependency_modules(value: object, *, field_name: str) -> dict[str, str]:
if not isinstance(value, dict):
raise ValueError(
f"{field_name} must be an object mapping export names to dependency modules"
)
modules: dict[str, str] = {}
for name, module_name in value.items():
if type(name) is not str or not name:
raise ValueError(f"{field_name} export names must be non-empty strings")
if type(module_name) is not str or not module_name.strip():
raise ValueError(f"{field_name} dependency for {name!r} must be a non-empty string")
modules[name] = module_name
return modules
def _optional_dependency_is_available(module_name: str) -> bool:
if module_name in sys.modules:
return sys.modules[module_name] is not None
return find_spec(module_name) is not None
def _matches_platform_import_error(
contract: dict[str, Any], module_name: str, error: Exception
) -> bool:
allowed_error_types = {"ImportError": ImportError}
for entry in contract.get("platform_import_errors", []):
if entry["module"] != module_name or sys.platform not in entry["platforms"]:
continue
expected_error_type = allowed_error_types.get(entry["error_type"])
return (
expected_error_type is not None
and type(error) is expected_error_type
and entry["message_contains"] in str(error)
)
return False