agentframe-py 0.1.0__py3-none-any.whl

agentframe/__init__.py

@@ -0,0 +1,170 @@
+"""AgentFrame: define agents with Python, communicate through A2A."""
+
+from typing import TYPE_CHECKING
+
+from agentframe.authoring.agent import Agent
+from agentframe.authoring.context import RunContext
+from agentframe.authoring.decorators import agent, skill, tool
+from agentframe.authoring.definitions import SkillDefinition, ToolDefinition
+from agentframe.authoring.services import Inject, Services
+from agentframe.errors import (
+    AgentFrameError,
+    AuthenticationError,
+    CancelledError,
+    DefinitionError,
+    IncompleteOutputError,
+    InputValidationError,
+    LimitExceededError,
+    ModelCallLimitExceededError,
+    ModelError,
+    ModelRefusalError,
+    OutputValidationError,
+    PermissionDeniedError,
+    PolicyUnavailableError,
+    ProviderError,
+    TimeoutLimitExceededError,
+    TokenLimitExceededError,
+    ToolCallLimitExceededError,
+    UnsupportedCapabilityError,
+)
+from agentframe.hosting.app import AgentApp
+from agentframe.hosting.dedup import MessageDedupStore
+from agentframe.hosting.host import A2AConfig, HostConfig
+from agentframe.hosting.model_router import ModelRouter
+from agentframe.hosting.routing import (
+    Clarification,
+    RoutingContext,
+    SkillCall,
+    SkillRouter,
+)
+from agentframe.models.base import (
+    Message,
+    Model,
+    ModelCapabilities,
+    ModelRequest,
+    ModelResponse,
+    ModelSettings,
+    OutputSchema,
+    Role,
+    ToolCall,
+    ToolSpec,
+)
+from agentframe.runtime.limits import RunLimits
+from agentframe.runtime.options import RunOptions
+from agentframe.runtime.runtime import RunResult, Runtime
+from agentframe.runtime.usage import FinishReason, Usage
+from agentframe.security.authentication import (
+    AllowAnonymous,
+    APIKey,
+    APIKeyAuth,
+    Authenticator,
+    DeclaresCardSecurity,
+    VerifiedCaller,
+)
+from agentframe.security.authorization import (
+    AuthorizationPolicy,
+    ToolAuthorizationPolicy,
+)
+from agentframe.security.execution_policy import (
+    ExecutionPolicy,
+    InputCheck,
+    ModelRequestCheck,
+    OutputCheck,
+    ToolCheck,
+)
+from agentframe.security.principal import Principal
+
+if TYPE_CHECKING:
+    from agentframe.models.foundry import FoundryModel as FoundryModel
+    from agentframe.models.ollama import OllamaModel as OllamaModel
+    from agentframe.security.entra import EntraIDAuth as EntraIDAuth
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "A2AConfig",
+    "APIKey",
+    "APIKeyAuth",
+    "Agent",
+    "AgentApp",
+    "AgentFrameError",
+    "AllowAnonymous",
+    "AuthenticationError",
+    "Authenticator",
+    "AuthorizationPolicy",
+    "CancelledError",
+    "Clarification",
+    "DeclaresCardSecurity",
+    "DefinitionError",
+    "ExecutionPolicy",
+    "FinishReason",
+    "HostConfig",
+    "IncompleteOutputError",
+    "Inject",
+    "InputCheck",
+    "InputValidationError",
+    "LimitExceededError",
+    "Message",
+    "MessageDedupStore",
+    "Model",
+    "ModelCallLimitExceededError",
+    "ModelCapabilities",
+    "ModelError",
+    "ModelRefusalError",
+    "ModelRequest",
+    "ModelRequestCheck",
+    "ModelResponse",
+    "ModelRouter",
+    "ModelSettings",
+    "OutputCheck",
+    "OutputSchema",
+    "OutputValidationError",
+    "PermissionDeniedError",
+    "PolicyUnavailableError",
+    "Principal",
+    "ProviderError",
+    "Role",
+    "RoutingContext",
+    "RunContext",
+    "RunLimits",
+    "RunOptions",
+    "RunResult",
+    "Runtime",
+    "Services",
+    "SkillCall",
+    "SkillDefinition",
+    "SkillRouter",
+    "TimeoutLimitExceededError",
+    "TokenLimitExceededError",
+    "ToolAuthorizationPolicy",
+    "ToolCall",
+    "ToolCallLimitExceededError",
+    "ToolCheck",
+    "ToolDefinition",
+    "ToolSpec",
+    "UnsupportedCapabilityError",
+    "Usage",
+    "VerifiedCaller",
+    "__version__",
+    "agent",
+    "skill",
+    "tool",
+]
+
+
+def __getattr__(name: str) -> object:
+    # Provider adapters and EntraIDAuth are imported on first use so that
+    # ``import agentframe`` works without their optional extras installed.
+    if name == "FoundryModel":
+        from agentframe.models.foundry import FoundryModel as FoundryModel
+
+        return FoundryModel
+    if name == "OllamaModel":
+        from agentframe.models.ollama import OllamaModel as OllamaModel
+
+        return OllamaModel
+    if name == "EntraIDAuth":
+        from agentframe.security.entra import EntraIDAuth as EntraIDAuth
+
+        return EntraIDAuth
+    raise AttributeError(f"module 'agentframe' has no attribute {name!r}")

agentframe/authoring/__init__.py

@@ -0,0 +1 @@
+"""Authoring: the Agent base class, decorators, definitions, context and services."""

agentframe/authoring/agent.py

@@ -0,0 +1,75 @@
+"""The Agent base class."""
+
+from collections.abc import Callable, Iterable, Mapping
+from types import MappingProxyType
+from typing import Any, ClassVar
+
+from agentframe.authoring.definitions import (
+    AgentDefinition,
+    ToolDefinition,
+    tools_by_name,
+)
+from agentframe.errors import DefinitionError
+from agentframe.models.base import Model, ModelSettings
+from agentframe.runtime.limits import RunLimits
+
+DEFINITION_ATTRIBUTE = "__agentframe_definition__"
+
+
+class Agent:
+    """Base class for agents: declare skills with @skill, describe it with @agent.
+
+    Args:
+        model: The model ``ctx.generate`` calls. Model-free agents omit it.
+            The application owns the model and closes it.
+        tools: ``@tool`` functions this agent's ``ctx.generate`` calls may
+            select. Registering grants nothing by itself: each call names the
+            tools it offers the model. Tools are never advertised as skills.
+
+    Raises:
+        DefinitionError: A tool is not decorated with ``@tool``, or two tools
+            share a name.
+
+    Attributes:
+        limits: Default execution limits for this agent's skills. Fields it
+            sets override the library defaults; fields a skill or run sets
+            override it in turn.
+        instructions: Trusted instructions sent as the first ``system`` message
+            of every ``ctx.generate`` call. Never put untrusted content here.
+        model_settings: Default settings for this agent's model calls, merged
+            field by field like ``limits``.
+        model: The model passed to the constructor, or ``None``.
+        tools: The registered tools by name, read-only.
+    """
+
+    limits: ClassVar[RunLimits] = RunLimits()
+    instructions: ClassVar[str | None] = None
+    model_settings: ClassVar[ModelSettings] = ModelSettings()
+    # Class defaults keep subclasses that do not call super().__init__() working.
+    model: Model | None = None
+    tools: Mapping[str, ToolDefinition] = MappingProxyType({})
+
+    def __init__(
+        self,
+        *,
+        model: Model | None = None,
+        tools: Iterable[Callable[..., Any]] = (),
+    ) -> None:
+        self.model = model
+        self.tools = tools_by_name(tools)
+
+    @classmethod
+    def definition(cls) -> AgentDefinition:
+        """Return the validated definition created by ``@agent``.
+
+        Raises:
+            DefinitionError: If this exact class was not decorated with ``@agent``.
+        """
+        # Look only at this class so an undecorated subclass cannot silently
+        # reuse its parent's definition and skills.
+        definition = cls.__dict__.get(DEFINITION_ATTRIBUTE)
+        if not isinstance(definition, AgentDefinition):
+            raise DefinitionError(
+                f"Agent '{cls.__name__}' is not decorated with @agent"
+            )
+        return definition

agentframe/authoring/context.py

@@ -0,0 +1,123 @@
+"""Per-run context passed to skills."""
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from typing import Any, overload
+
+from pydantic import BaseModel
+
+from agentframe.runtime.generation import GenerationState
+from agentframe.security.principal import Principal
+
+
+@dataclass(frozen=True)
+class RunContext:
+    """Per-run information passed to every skill. Never shared between runs.
+
+    Attributes:
+        invocation_id: Library-generated identifier of this run.
+        principal: Verified caller identity, or ``None`` when none was supplied.
+        deadline: Event-loop time (``loop.time()``) when the run times out.
+    """
+
+    invocation_id: str
+    principal: Principal | None
+    deadline: float
+    # Private per-run model state; the context is frozen but its accounting
+    # must change as the run makes model calls.
+    _generation: GenerationState = field(repr=False, compare=False)
+
+    @overload
+    async def generate(
+        self,
+        text: str,
+        *,
+        instructions: str | None = None,
+        tools: Iterable[Callable[..., Any]] = (),
+    ) -> str: ...
+
+    @overload
+    async def generate[T: BaseModel](
+        self,
+        text: str,
+        *,
+        instructions: str | None = None,
+        output: type[T],
+        tools: Iterable[Callable[..., Any]] = (),
+    ) -> T: ...
+
+    async def generate(
+        self,
+        text: str,
+        *,
+        instructions: str | None = None,
+        output: type[BaseModel] | None = None,
+        tools: Iterable[Callable[..., Any]] = (),
+    ) -> str | BaseModel:
+        """Generate text, or a validated ``output`` instance, with the agent's model.
+
+        The agent's ``instructions`` and then ``instructions`` are sent as
+        trusted ``system`` messages; ``text`` is sent as a separate ``user``
+        message and never merged into them. Keeping them separate does not
+        guarantee resistance to prompt injection.
+
+        Args:
+            text: Untrusted content for the model, such as caller input.
+            instructions: Trusted instructions for this call only. Never put
+                untrusted content here.
+            output: A Pydantic ``BaseModel`` subclass. When given, the model
+                is asked for JSON matching its schema and the reply is
+                validated into an instance. Invalid output is never repaired
+                or re-requested.
+            tools: ``@tool`` functions to offer the model, each registered on
+                the agent and selected once. Omitted or empty offers no
+                tools; registered tools are never offered unless selected
+                here. The model's tool calls run one at a time, in its
+                order, and their results are sent back until it answers.
+                A call naming a tool that was not offered, or with invalid
+                arguments, runs nothing; the model is told what was wrong.
+                Tools whose ``requires_permissions`` the caller lacks are
+                not offered, and every call is authorized before it runs.
+
+        Returns:
+            The model's complete answer, or an ``output`` instance when
+            ``output`` is given. With tools, the answer after the tool calls.
+
+        Raises:
+            DefinitionError: ``output`` is not a ``BaseModel`` subclass, or is
+                a ``RootModel``, or a selected tool is not registered on the
+                agent or is selected twice. Raised before anything is sent.
+            UnsupportedCapabilityError: The agent has no model configured, or
+                the model lacks something the request needs, such as
+                structured output or tool calling. Raised before anything is
+                sent.
+            OutputValidationError: The structured reply is not valid JSON or
+                does not match ``output``, or a tool returned a value that
+                does not match its return annotation.
+            ModelRefusalError: The model refused, or a content filter blocked
+                its output.
+            IncompleteOutputError: The output was cut short at the token
+                limit or was empty. Partial text or objects are never returned;
+                for text cut short at the limit, the error's ``partial_text``
+                holds what arrived, and a skill may catch it and use it.
+            ProviderError: The model provider call failed.
+            PermissionDeniedError: The model called a tool the caller lacks
+                a required permission for, or the runtime's tool
+                authorization policy denied a call. The model is never told.
+                Also raised, before anything is sent, when an execution
+                policy model-request check blocks a request.
+            PolicyUnavailableError: The tool authorization policy or an
+                execution policy model-request check raised an error or did
+                not answer before the run's deadline.
+            LimitExceededError: A model call does not fit the run's limits,
+                the run has made ``max_tool_calls`` tool calls, or the run's
+                timeout expired during a model or tool call.
+
+        Exceptions raised by a tool propagate unchanged and fail the run;
+        their text is never sent to the model.
+        """
+        if output is None:
+            return await self._generation.generate_text(self, text, instructions, tools)
+        return await self._generation.generate_output(
+            self, text, instructions, output, tools
+        )

agentframe/authoring/decorators.py

@@ -0,0 +1,202 @@
+"""The ``@agent``, ``@skill`` and ``@tool`` decorators."""
+
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from agentframe.authoring.agent import DEFINITION_ATTRIBUTE, Agent
+from agentframe.authoring.definitions import (
+    TOOL_ATTRIBUTE,
+    AgentDefinition,
+    SkillDefinition,
+    SkillMetadata,
+    build_skill_definition,
+    build_tool_definition,
+    class_docstring,
+)
+from agentframe.errors import DefinitionError
+from agentframe.models.base import ModelSettings
+from agentframe.runtime.limits import RunLimits
+
+_SKILL_ATTRIBUTE = "_skill_metadata"
+
+
+# noinspection PyShadowingBuiltins
+def skill[F: Callable[..., Any]](
+    id: str,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    tags: Iterable[str] = (),
+    requires_permissions: Iterable[str] = (),
+    limits: RunLimits | None = None,
+    model_settings: ModelSettings | None = None,
+) -> Callable[[F], F]:
+    """Mark an async ``Agent`` method as an advertised skill.
+
+    The method is inspected later by ``@agent``, once its class exists.
+
+    Args:
+        id: Stable skill identifier that callers select.
+        name: Display name. Defaults to the title-cased method name.
+        description: What the skill does. Defaults to the method docstring.
+        tags: Descriptive discovery tags. At least one non-blank tag is
+            required (A2A 1.0); ``@agent`` rejects a skill without one.
+        requires_permissions: Permissions the caller must all hold.
+        limits: Execution limits for this skill. Each field it sets overrides
+            the agent's value; unset fields are inherited.
+        model_settings: Model settings for this skill. Each field it sets
+            overrides the agent's value; unset fields are inherited.
+
+    Returns:
+        A decorator that records the metadata and returns the same function.
+
+    Raises:
+        DefinitionError: If ``id`` is empty, or ``tags`` or
+            ``requires_permissions`` is a single string.
+    """
+    if not id:
+        raise DefinitionError("Skill id must not be empty")
+    if isinstance(tags, str) or isinstance(requires_permissions, str):
+        raise DefinitionError(
+            f"Skill '{id}': tags and requires_permissions must be lists of strings"
+        )
+    metadata = SkillMetadata(
+        id=id,
+        name=name,
+        description=description,
+        tags=tuple(tags),
+        requires_permissions=frozenset(requires_permissions),
+        limits=limits,
+        model_settings=model_settings,
+    )
+
+    def decorator(func: F) -> F:
+        setattr(func, _SKILL_ATTRIBUTE, metadata)
+        return func
+
+    return decorator
+
+
+def agent[A: type[Agent]](
+    version: str, *, name: str | None = None, description: str | None = None
+) -> Callable[[A], A]:
+    """Describe an ``Agent`` subclass and validate its skills.
+
+    Args:
+        version: Agent version string, for example ``"0.1.0"``.
+        name: Agent name. Defaults to the class name.
+        description: What the agent does. Defaults to the class docstring.
+
+    Returns:
+        A decorator that stores the definition and returns the same class.
+
+    Raises:
+        DefinitionError: If the class or any of its skills is invalid.
+    """
+
+    def decorator(cls: A) -> A:
+        if not (isinstance(cls, type) and issubclass(cls, Agent)):
+            raise DefinitionError("@agent can only decorate Agent subclasses")
+        agent_name = name or cls.__name__
+        agent_description = description or class_docstring(cls)
+        if not agent_description:
+            raise DefinitionError(
+                f"Agent '{agent_name}' needs a description or docstring"
+            )
+        definition = AgentDefinition(
+            name=agent_name,
+            description=agent_description,
+            version=version,
+            skills=_collect_skills(agent_name, cls),
+        )
+        setattr(cls, DEFINITION_ATTRIBUTE, definition)
+        return cls
+
+    return decorator
+
+
+def _collect_skills(agent_name: str, cls: type) -> dict[str, SkillDefinition]:
+    skill_methods = _skill_methods(agent_name, cls)
+    if not skill_methods:
+        raise DefinitionError(f"Agent '{agent_name}' has no skills")
+
+    skills: dict[str, SkillDefinition] = {}
+    for method in skill_methods.values():
+        metadata: SkillMetadata = getattr(method, _SKILL_ATTRIBUTE)
+        if metadata.id in skills:
+            raise DefinitionError(
+                f"Agent '{agent_name}': skill id '{metadata.id}' is used by both "
+                f"'{skills[metadata.id].method_name}' and '{method.__name__}'"
+            )
+        skills[metadata.id] = build_skill_definition(agent_name, method, metadata)
+    return skills
+
+
+def _skill_methods(agent_name: str, cls: type) -> dict[str, Callable[..., Any]]:
+    """Return skill methods by name, walking from the base class to ``cls``."""
+    methods: dict[str, Callable[..., Any]] = {}
+    for klass in reversed(cls.__mro__):
+        for attribute_name, value in vars(klass).items():
+            if hasattr(value, _SKILL_ATTRIBUTE):
+                methods[attribute_name] = value
+            elif attribute_name in methods:
+                raise DefinitionError(
+                    f"Agent '{agent_name}': '{klass.__name__}.{attribute_name}' "
+                    "overrides a skill without @skill"
+                )
+    return methods
+
+
+def tool[F: Callable[..., Any]](
+    *,
+    description: str | None = None,
+    side_effects: bool = False,
+    idempotent: bool = False,
+    requires_permissions: Iterable[str] = (),
+) -> Callable[[F], F]:
+    """Mark a typed function as a tool a model may call.
+
+    Always call it with parentheses: ``@tool()`` or ``@tool(description=...)``.
+    The function is validated immediately and stays directly callable. Sync
+    functions run inline on the event loop, so use ``async def`` for any I/O.
+    Decorating grants nothing: the tool must still be registered on an agent
+    (``Agent(tools=[...])``) and selected by ``ctx.generate(..., tools=[...])``.
+
+    Args:
+        description: What the tool does, shown to the model. Defaults to the
+            function docstring; one of them is required.
+        side_effects: Whether a call has consequential effects, such as
+            cancelling an order.
+        idempotent: Whether repeating a call with the same arguments has no
+            further effect. Not a retry grant: tools are never auto-retried.
+        requires_permissions: Permissions the caller must all hold. A tool
+            the caller lacks any of is not offered to the model and fails the
+            run if the model calls it anyway.
+
+    Returns:
+        A decorator that attaches a ``ToolDefinition`` and returns the same
+        function (or ``staticmethod``).
+
+    Raises:
+        DefinitionError: If the function breaks a tool rule: it is a lambda or
+            method, is a generator, has an invalid name, unannotated,
+            ``*args``/``**kwargs`` or positional-only parameters, an
+            unsupported type, or no description; or if
+            ``requires_permissions`` is a single string.
+    """
+    if isinstance(requires_permissions, str):
+        raise DefinitionError("Tool requires_permissions must be a list of strings")
+    permissions = frozenset(requires_permissions)
+
+    def decorator(func: F) -> F:
+        definition = build_tool_definition(
+            func,
+            description=description,
+            side_effects=side_effects,
+            idempotent=idempotent,
+            requires_permissions=permissions,
+        )
+        setattr(definition.function, TOOL_ATTRIBUTE, definition)
+        return func
+
+    return decorator