agentframe-py 0.1.0__py3-none-any.whl

agentframe/authoring/definitions.py

@@ -0,0 +1,372 @@
+"""Validated agent, skill and tool definitions built from decorated code."""
+
+import inspect
+import re
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any, get_args, get_origin, get_type_hints
+
+from pydantic import (
+    ConfigDict,
+    PydanticSchemaGenerationError,
+    TypeAdapter,
+    create_model,
+)
+
+from agentframe.authoring.context import RunContext
+from agentframe.authoring.services import Inject
+from agentframe.errors import DefinitionError
+from agentframe.models.base import ModelSettings
+from agentframe.runtime.limits import RunLimits
+
+# Callers can never supply these as business arguments.
+_RESERVED_ARGUMENT_NAMES = frozenset({"ctx", "principal"})
+
+# Model providers accept tool names of this shape (OpenAI's function-name rule).
+_TOOL_NAME_PATTERN = re.compile(r"[a-zA-Z0-9_-]{1,64}")
+
+# Where ``@tool`` stores a function's ``ToolDefinition``.
+TOOL_ATTRIBUTE = "_tool_definition"
+
+
+@dataclass(frozen=True)
+class SkillMetadata:
+    """Metadata recorded by ``@skill`` before the class is complete."""
+
+    id: str
+    name: str | None
+    description: str | None
+    tags: tuple[str, ...]
+    requires_permissions: frozenset[str]
+    limits: RunLimits | None
+    model_settings: ModelSettings | None
+
+
+@dataclass(frozen=True)
+class SkillDefinition:
+    """A validated skill: advertised metadata plus its call contract."""
+
+    id: str
+    name: str
+    description: str
+    tags: tuple[str, ...]
+    requires_permissions: frozenset[str]
+    limits: RunLimits | None
+    model_settings: ModelSettings | None
+    method_name: str
+    argument_names: tuple[str, ...]
+    injected: dict[str, object]
+    arguments_adapter: TypeAdapter[Any]
+    return_adapter: TypeAdapter[Any]
+
+
+@dataclass(frozen=True)
+class ToolDefinition:
+    """A validated model-callable tool: its description, flags and call contract.
+
+    Built by ``@tool`` when a function is decorated. Building one grants
+    nothing: a tool is only offered to a model once registered on an agent
+    and selected by a ``ctx.generate`` call.
+    """
+
+    name: str
+    description: str
+    side_effects: bool
+    idempotent: bool
+    requires_permissions: frozenset[str]
+    function: Callable[..., Any]
+    takes_context: bool
+    argument_names: tuple[str, ...]
+    injected: dict[str, object]
+    arguments_adapter: TypeAdapter[Any]
+    return_adapter: TypeAdapter[Any]
+
+    def json_schema(self) -> dict[str, Any]:
+        """Return the JSON Schema of the business arguments a model supplies.
+
+        ``ctx`` and ``Inject[T]`` parameters never appear in it.
+        """
+        return self.arguments_adapter.json_schema()
+
+
+@dataclass(frozen=True)
+class AgentDefinition:
+    """A validated agent: identity plus its skills keyed by skill id."""
+
+    name: str
+    description: str
+    version: str
+    skills: dict[str, SkillDefinition]
+
+
+def build_skill_definition(
+    agent_name: str, method: Callable[..., Any], metadata: SkillMetadata
+) -> SkillDefinition:
+    """Inspect a decorated skill method and build its definition.
+
+    Raises:
+        DefinitionError: If the method breaks a skill rule.
+    """
+    method_name = method.__name__
+    where = f"Agent '{agent_name}': skill '{method_name}'"
+
+    if not inspect.iscoroutinefunction(method):
+        raise DefinitionError(f"{where} is not async")
+    # Drop ``self``: skills are always instance methods.
+    parameters = _named_parameters(
+        where, list(inspect.signature(method).parameters.values())[1:]
+    )
+    hints = _type_hints(where, method)
+    _check_annotations(where, parameters, hints)
+    if "ctx" not in {parameter.name for parameter in parameters}:
+        raise DefinitionError(f"{where} needs a 'ctx: RunContext' parameter")
+    _check_tags(where, metadata.tags)
+    arguments, injected = _split_parameters(where, parameters, hints)
+
+    description = metadata.description or _docstring(method)
+    if not description:
+        raise DefinitionError(f"{where} needs a description or docstring")
+
+    try:
+        arguments_adapter = _arguments_adapter(method_name, arguments, hints)
+        return_adapter = TypeAdapter(hints["return"])
+    except PydanticSchemaGenerationError:
+        raise DefinitionError(f"{where} uses an unsupported type annotation") from None
+
+    return SkillDefinition(
+        id=metadata.id,
+        name=metadata.name or method_name.replace("_", " ").title(),
+        description=description,
+        tags=metadata.tags,
+        requires_permissions=metadata.requires_permissions,
+        limits=metadata.limits,
+        model_settings=metadata.model_settings,
+        method_name=method_name,
+        argument_names=tuple(parameter.name for parameter in arguments),
+        injected=injected,
+        arguments_adapter=arguments_adapter,
+        return_adapter=return_adapter,
+    )
+
+
+def build_tool_definition(
+    target: object,
+    *,
+    description: str | None,
+    side_effects: bool,
+    idempotent: bool,
+    requires_permissions: frozenset[str],
+) -> ToolDefinition:
+    """Inspect a module-level or static function and build its tool definition.
+
+    Args:
+        target: The decorated function, or a ``staticmethod`` wrapping one.
+        description: Explicit description; defaults to the docstring.
+        side_effects: Whether calling the tool has consequential effects.
+        idempotent: Whether repeating a call has no further effect.
+        requires_permissions: Permissions the caller must all hold.
+
+    Raises:
+        DefinitionError: If the function breaks a tool rule.
+    """
+    function = _tool_function(target)
+    name = function.__name__
+    where = f"Tool '{name}'"
+    if not _TOOL_NAME_PATTERN.fullmatch(name):
+        raise DefinitionError(
+            f"{where}: name must be 1-64 ASCII letters, digits, '_' or '-'"
+        )
+
+    parameters = _named_parameters(
+        where, list(inspect.signature(function).parameters.values())
+    )
+    hints = _type_hints(where, function)
+    _check_annotations(where, parameters, hints)
+    arguments, injected = _split_parameters(where, parameters, hints)
+
+    tool_description = description or _docstring(function)
+    if not tool_description:
+        raise DefinitionError(f"{where} needs a description or docstring")
+
+    try:
+        arguments_adapter = _arguments_adapter(name, arguments, hints)
+        return_adapter = TypeAdapter(hints["return"])
+    except PydanticSchemaGenerationError:
+        raise DefinitionError(f"{where} uses an unsupported type annotation") from None
+
+    return ToolDefinition(
+        name=name,
+        description=tool_description,
+        side_effects=side_effects,
+        idempotent=idempotent,
+        requires_permissions=requires_permissions,
+        function=function,
+        takes_context="ctx" in {parameter.name for parameter in parameters},
+        argument_names=tuple(parameter.name for parameter in arguments),
+        injected=injected,
+        arguments_adapter=arguments_adapter,
+        return_adapter=return_adapter,
+    )
+
+
+def _tool_function(target: object) -> Callable[..., Any]:
+    """Return the plain function behind ``target``; no lambdas or methods."""
+    is_static = isinstance(target, staticmethod)
+    # Repeats the isinstance check because mypy cannot narrow through is_static.
+    function = target.__func__ if isinstance(target, staticmethod) else target
+    if not inspect.isfunction(function):
+        raise DefinitionError(
+            f"@tool needs a module-level or static function, got {function!r}"
+        )
+    if function.__name__ == "<lambda>":
+        raise DefinitionError("@tool cannot decorate a lambda; use a named function")
+    if inspect.isgeneratorfunction(function) or inspect.isasyncgenfunction(function):
+        raise DefinitionError(
+            f"Tool '{function.__name__}': generators cannot be tools; return a value"
+        )
+    # A function written directly in a class body has a qualname "Class.name";
+    # one nested in a function has "outer.<locals>.name".
+    enclosing = function.__qualname__.split(".")[:-1]
+    if not is_static and enclosing and enclosing[-1] != "<locals>":
+        raise DefinitionError(
+            f"Tool '{function.__name__}': methods cannot be tools; use a "
+            "module-level function, or put @tool above @staticmethod"
+        )
+    return function
+
+
+def tool_definition(function: Callable[..., Any]) -> ToolDefinition:
+    """Return the definition ``@tool`` attached to ``function``.
+
+    Raises:
+        DefinitionError: If ``function`` is not decorated with ``@tool``.
+    """
+    definition = getattr(function, TOOL_ATTRIBUTE, None)
+    if not isinstance(definition, ToolDefinition):
+        raise DefinitionError(f"{function!r} is not decorated with @tool")
+    return definition
+
+
+def tools_by_name(
+    tools: Iterable[Callable[..., Any]],
+) -> Mapping[str, ToolDefinition]:
+    """Build an agent's read-only tool registry from ``@tool`` functions.
+
+    Raises:
+        DefinitionError: A function is not decorated with ``@tool``, or two
+            tools share a name.
+    """
+    registered: dict[str, ToolDefinition] = {}
+    for function in tools:
+        definition = tool_definition(function)
+        if definition.name in registered:
+            raise DefinitionError(
+                f"Tool name '{definition.name}' is registered more than once"
+            )
+        registered[definition.name] = definition
+    return MappingProxyType(registered)
+
+
+def _check_tags(where: str, tags: tuple[str, ...]) -> None:
+    """Require at least one non-blank tag.
+
+    A2A 1.0 marks ``AgentSkill.tags`` REQUIRED, and required arrays must
+    contain at least one element (spec section 5.7).
+    """
+    if not tags:
+        raise DefinitionError(
+            f"{where} needs at least one tag; A2A 1.0 requires skill tags"
+        )
+    if any(not tag.strip() for tag in tags):
+        raise DefinitionError(f"{where} has a blank tag")
+
+
+def _named_parameters(
+    where: str, parameters: list[inspect.Parameter]
+) -> list[inspect.Parameter]:
+    """Return ``parameters``, rejecting ``*args``, ``**kwargs`` and positional-only."""
+    for parameter in parameters:
+        if parameter.kind not in (
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            inspect.Parameter.KEYWORD_ONLY,
+        ):
+            raise DefinitionError(
+                f"{where}: parameter '{parameter.name}' must be a named parameter"
+            )
+    return parameters
+
+
+def _split_parameters(
+    where: str, parameters: list[inspect.Parameter], hints: dict[str, Any]
+) -> tuple[list[inspect.Parameter], dict[str, object]]:
+    """Separate business arguments from ``Inject[T]`` services.
+
+    ``ctx`` belongs to neither group: it is supplied by the runtime.
+
+    Returns:
+        The business parameters, and the injected service types by parameter name.
+    """
+    arguments: list[inspect.Parameter] = []
+    injected: dict[str, object] = {}
+    for parameter in parameters:
+        annotation = hints[parameter.name]
+        if parameter.name == "ctx":
+            if annotation is not RunContext:
+                raise DefinitionError(f"{where}: 'ctx' must be annotated RunContext")
+        elif get_origin(annotation) is Inject:
+            injected[parameter.name] = get_args(annotation)[0]
+        elif parameter.name in _RESERVED_ARGUMENT_NAMES:
+            raise DefinitionError(f"{where}: '{parameter.name}' is a reserved name")
+        else:
+            arguments.append(parameter)
+    return arguments, injected
+
+
+def _type_hints(where: str, method: Callable[..., Any]) -> dict[str, Any]:
+    try:
+        return get_type_hints(method, include_extras=True)
+    except (NameError, TypeError) as error:
+        raise DefinitionError(
+            f"{where}: cannot resolve annotations ({error})"
+        ) from None
+
+
+def _check_annotations(
+    where: str, parameters: list[inspect.Parameter], hints: dict[str, Any]
+) -> None:
+    for parameter in parameters:
+        if parameter.name not in hints:
+            raise DefinitionError(f"{where}: parameter '{parameter.name}' needs a type")
+    if "return" not in hints:
+        raise DefinitionError(f"{where} needs a return annotation")
+
+
+def _arguments_adapter(
+    method_name: str, arguments: list[inspect.Parameter], hints: dict[str, Any]
+) -> TypeAdapter[Any]:
+    """Build a validator for the business arguments; unknown names are rejected."""
+    fields: dict[str, Any] = {}
+    for parameter in arguments:
+        default = (
+            ... if parameter.default is inspect.Parameter.empty else parameter.default
+        )
+        fields[parameter.name] = (hints[parameter.name], default)
+    model = create_model(
+        f"{method_name}_arguments",
+        __config__=ConfigDict(extra="forbid"),
+        **fields,
+    )
+    return TypeAdapter(model)
+
+
+def _docstring(target: object) -> str:
+    # Read __doc__ directly: inspect.getdoc would inherit a parent's docstring.
+    doc = getattr(target, "__doc__", None)
+    return inspect.cleandoc(doc) if doc else ""
+
+
+def class_docstring(cls: type) -> str:
+    """Return the docstring written on ``cls`` itself, not inherited."""
+    doc = cls.__dict__.get("__doc__")
+    return inspect.cleandoc(doc) if doc else ""

agentframe/authoring/services.py

@@ -0,0 +1,176 @@
+"""Service registration and per-run resolution for ``Inject[T]`` parameters."""
+
+import asyncio
+import inspect
+from collections.abc import AsyncGenerator, AsyncIterator, Awaitable, Callable, Mapping
+from contextlib import AsyncExitStack
+from types import MappingProxyType
+from typing import Annotated, cast
+
+from agentframe.errors import DefinitionError
+
+
+class _InjectMarker:
+    """Marks a skill parameter as an injected service."""
+
+
+# Type checkers treat ``Inject[T]`` as ``T``. At runtime AgentFrame detects the
+# parameter by checking ``typing.get_origin(annotation) is Inject``.
+type Inject[T] = Annotated[T, _InjectMarker()]
+
+type ScopedFactory[T] = (
+    Callable[[], T] | Callable[[], Awaitable[T]] | Callable[[], AsyncIterator[T]]
+)
+
+
+class Services:
+    """Registry of services that skills receive through ``Inject[T]``.
+
+    Pass an instance to ``Runtime(services=...)``.
+    """
+
+    def __init__(self) -> None:
+        self._singletons: dict[object, object] = {}
+        self._scoped: dict[object, Callable[[], object]] = {}
+
+    def add[T](self, service_type: type[T], instance: T) -> None:
+        """Register an application-owned service shared by all runs.
+
+        AgentFrame never closes this instance; the application owns its lifecycle.
+
+        Args:
+            service_type: Type that skills request with ``Inject[service_type]``.
+            instance: The service instance to inject.
+
+        Raises:
+            DefinitionError: If ``service_type`` is already registered.
+        """
+        self._check_not_registered(service_type)
+        self._singletons[service_type] = instance
+
+    def add_scoped[T](self, service_type: type[T], factory: ScopedFactory[T]) -> None:
+        """Register a service created freshly for each run.
+
+        The factory may be a sync function, an async function, or an async
+        generator function. For a generator, the code after its single ``yield``
+        is cleanup and runs when the run ends, whether it succeeded or failed.
+
+        Args:
+            service_type: Type that skills request with ``Inject[service_type]``.
+            factory: Zero-argument callable that creates the service.
+
+        Raises:
+            DefinitionError: If ``service_type`` is already registered.
+        """
+        self._check_not_registered(service_type)
+        self._scoped[service_type] = factory
+
+    def is_registered(self, service_type: object) -> bool:
+        """Return whether ``service_type`` has been registered."""
+        return service_type in self._singletons or service_type in self._scoped
+
+    def scope(self, stack: AsyncExitStack) -> "ServiceScope":
+        """Return the services of one run, cleaned up when ``stack`` closes.
+
+        Args:
+            stack: Exit stack that lives exactly as long as the run.
+        """
+        return ServiceScope(
+            MappingProxyType(self._singletons), MappingProxyType(self._scoped), stack
+        )
+
+    def _check_not_registered(self, service_type: object) -> None:
+        if self.is_registered(service_type):
+            raise DefinitionError(
+                f"Service {_type_name(service_type)} is already registered"
+            )
+
+
+class ServiceScope:
+    """The services of one run, shared by its skill and the tools it calls.
+
+    Created by ``Services.scope``. Scoped services are created at most once
+    per type for the run, even when concurrent ``ctx.generate`` calls resolve
+    them at the same time. Their cleanup is registered on the run's exit
+    stack; singletons are never closed.
+
+    Args:
+        singletons: Registered shared instances by type.
+        scoped: Registered scoped factories by type.
+        stack: Exit stack that lives exactly as long as the run.
+    """
+
+    def __init__(
+        self,
+        singletons: Mapping[object, object],
+        scoped: Mapping[object, Callable[[], object]],
+        stack: AsyncExitStack,
+    ) -> None:
+        self._singletons = singletons
+        self._scoped = scoped
+        self._stack = stack
+        self._created: dict[object, object] = {}
+        self._creating = asyncio.Lock()
+
+    async def resolve(self, needed: Mapping[str, object]) -> dict[str, object]:
+        """Return service instances keyed by parameter name.
+
+        Args:
+            needed: Parameter name to requested service type.
+
+        Raises:
+            DefinitionError: If a requested service type is not registered, or a
+                generator factory does not yield exactly once.
+        """
+        resolved: dict[str, object] = {}
+        for parameter_name, service_type in needed.items():
+            if service_type in self._singletons:
+                resolved[parameter_name] = self._singletons[service_type]
+                continue
+            if service_type not in self._scoped:
+                raise DefinitionError(
+                    f"Service {_type_name(service_type)} is not registered"
+                )
+            resolved[parameter_name] = await self._scoped_instance(service_type)
+        return resolved
+
+    async def _scoped_instance(self, service_type: object) -> object:
+        # A factory may await, so without the lock two concurrent resolves
+        # could both see the type missing and create it twice.
+        async with self._creating:
+            if service_type not in self._created:
+                factory = self._scoped[service_type]
+                self._created[service_type] = await _create_scoped(factory, self._stack)
+            return self._created[service_type]
+
+
+async def _create_scoped(
+    factory: Callable[[], object], stack: AsyncExitStack
+) -> object:
+    if inspect.isasyncgenfunction(factory):
+        generator = factory()
+        instance = await anext(generator)
+        stack.push_async_callback(_finish_generator, generator)
+        return instance
+    if inspect.iscoroutinefunction(factory):
+        return await cast(Callable[[], Awaitable[object]], factory)()
+    return factory()
+
+
+async def _finish_generator(generator: AsyncGenerator[object]) -> None:
+    # Resume the generator instead of throwing the run's exception into it (as
+    # contextlib.asynccontextmanager would), so the code after ``yield`` always
+    # runs, like a pytest yield fixture.
+    try:
+        await anext(generator)
+    except StopAsyncIteration:
+        return
+    await generator.aclose()
+    raise DefinitionError("A scoped service factory must yield exactly once")
+
+
+def _type_name(service_type: object) -> str:
+    qualname = getattr(service_type, "__qualname__", None)
+    # Keys without a __qualname__, such as generic aliases, have a useful repr.
+    # noinspection PyStringConversionWithoutDunderMethod
+    return qualname if isinstance(qualname, str) else repr(service_type)