pyagentic-core 1.2.1__tar.gz → 1.3.0__tar.gz

{pyagentic_core-1.2.1 → pyagentic_core-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyagentic-core
-Version: 1.2.1
+Version: 1.3.0
 Summary: Build LLM Agents in a Pythonic way
 Author-email: Ryan Mikulec <rmikulec.dev@gmail.com>
 License: MIT
@@ -17,6 +17,7 @@ Requires-Dist: taskipy>=1.14.1
 Requires-Dist: openai>=1.99.3
 Requires-Dist: pydantic>=2.11.7
 Requires-Dist: typeguard>=4.4.4
+Requires-Dist: c3linearize>=0.1.0
 Dynamic: license-file
 
 # PyAgentic

pyagentic_core-1.3.0/pyagentic/__init__.py

@@ -0,0 +1,15 @@
+from pyagentic._base._agent import Agent, AgentExtension
+from pyagentic._base._params import Param, ParamInfo
+from pyagentic._base._tool import tool
+from pyagentic._base._context import computed_context, ContextRef, ContextItem
+
+__all__ = [
+    "Agent",
+    "AgentExtension",
+    "Param",
+    "ParamInfo",
+    "tool",
+    "computed_context",
+    "ContextRef",
+    "ContextItem",
+]

{pyagentic_core-1.2.1 → pyagentic_core-1.3.0}/pyagentic/_base/_agent.py

@@ -1,10 +1,12 @@
 import inspect
 import json
 import openai
-from typing import Callable, Any, TypeVar, ClassVar, Type
+from functools import wraps
+from typing import Callable, Any, TypeVar, ClassVar, Type, Self, dataclass_transform
 
 from pyagentic.logging import get_logger
-from pyagentic._base._tool import _ToolDefinition
+from pyagentic._base._params import ParamInfo
+from pyagentic._base._tool import _ToolDefinition, tool
 from pyagentic._base._context import ContextItem
 from pyagentic._base._metaclasses import AgentMeta
 
@@ -25,6 +27,29 @@ async def _safe_run(fn, *args, **kwargs):
     return result
 
 
+@dataclass_transform(field_specifiers=(ContextItem,))
+class AgentExtension:
+    """Inherit this in any mixin that contributes fields to the Agent __init__."""
+
+    __annotations__: dict[str, Any] = {}
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+
+        # Merge annotations from all AgentExtension bases (oldest first),
+        # then let the subclass' own annotations win on key conflicts.
+        merged: dict[str, Any] = {}
+        for base in reversed(cls.__mro__[1:]):  # skip cls, walk up towards object
+            if issubclass(base, AgentExtension):
+                ann = getattr(base, "__annotations__", None)
+                if ann:
+                    merged.update(ann)
+
+        merged.update(getattr(cls, "__annotations__", {}))
+        # Assign a fresh dict so we don't mutate a base class' annotations
+        cls.__annotations__ = dict(merged)
+
+
 class Agent(metaclass=AgentMeta):
     __abstract_base__ = ClassVar[True]
     """
@@ -48,9 +73,12 @@ class Agent(metaclass=AgentMeta):
     __tool_defs__: ClassVar[dict[str, _ToolDefinition]]
     __context_attrs__: ClassVar[dict[str, tuple[TypeVar, ContextItem]]]
     __system_message__: ClassVar[str]
+    __description__: ClassVar[str]
     __input_template__: ClassVar[str] = None
     __response_model__: ClassVar[Type[AgentResponse]] = None
     __tool_response_models__: ClassVar[dict[str, Type[ToolResponse]]]
+    __linked_agents__: ClassVar[dict[str, Type[Self]]]
+    __call_params__: ClassVar[dict[str, tuple[TypeVar, ParamInfo]]]
 
     # Base Attributes
     model: str
@@ -60,9 +88,22 @@ class Agent(metaclass=AgentMeta):
     def __post_init__(self):
         self.client: openai.AsyncOpenAI = openai.AsyncOpenAI(api_key=self.api_key)
 
+    async def _process_agent_call(self, tool_call) -> AgentResponse:
+        logger.info(f"Calling {tool_call.name} with kwargs: {tool_call.arguments}")
+        self.context._messages.append(tool_call)
+        try:
+            agent = getattr(self, tool_call.name)
+            kwargs = json.loads(tool_call.arguments)
+            response = await agent(**kwargs)
+            result = f"Agent {tool_call.name}: {response.final_output}"
+        except Exception as e:
+            result = f"Agent `{tool_call.name}` failed: {e}. Please kindly state to the user that is failed, provide context, and ask if they want to try again."  # noqa E501
+        self.context._messages.append(
+            {"type": "function_call_output", "call_id": tool_call.call_id, "output": result}
+        )
+        return response
+
     async def _process_tool_call(self, tool_call) -> ToolResponse:
-        if tool_call.type != "function_call":
-            return False
         self.context._messages.append(tool_call)
         logger.info(f"Calling {tool_call.name} with kwargs: {tool_call.arguments}")
         # Lookup the bound method
@@ -98,8 +139,8 @@ class Agent(metaclass=AgentMeta):
         self.context._messages.append(
             {"type": "function_call_output", "call_id": tool_call.call_id, "output": result}
         )
-        ToolCalledModel = self.__tool_response_models__[tool_call.name]
-        return ToolCalledModel(
+        ToolResponseModel = self.__tool_response_models__[tool_call.name]
+        return ToolResponseModel(
             raw_kwargs=tool_call.arguments, call_depth=0, output=result, **compiled_args
         )
 
@@ -110,6 +151,9 @@ class Agent(metaclass=AgentMeta):
             # Check if any of the tool params use a ContextRef
             # convert to openai schema
             tool_defs.append(tool_def.to_openai(self.context))
+        for name, agent in self.__linked_agents__.items():
+            tool_def = agent.get_tool_definition(name)
+            tool_defs.append(tool_def.to_openai(self.context))
         return tool_defs
 
     async def run(self, input_: str) -> str:
@@ -168,9 +212,16 @@ class Agent(metaclass=AgentMeta):
 
         # Dispatch any tool calls
         tool_responses = []
+        agent_responses = []
         for tool_call in tool_calls:
-            tool_response = await self._process_tool_call(tool_call)
-            tool_responses.append(tool_response)
+            if tool_call.type != "function_call":
+                continue
+            elif tool_call.name in self.__tool_defs__:
+                tool_response = await self._process_tool_call(tool_call)
+                tool_responses.append(tool_response)
+            elif tool_call.name in self.__linked_agents__:
+                agent_response = await self._process_agent_call(tool_call)
+                agent_responses.append(agent_response)
 
         # If tools ran, re-invoke LLM for natural reply
         if tool_responses:
@@ -198,8 +249,26 @@ class Agent(metaclass=AgentMeta):
         if self.emitter:
             await _safe_run(self.emitter, AiUpdate(status=Status.SUCCEDED, message=ai_message))
 
-        return self.__response_model__(
-            response=response,
-            final_output=ai_message,
-            tool_responses=tool_responses,
-        )
+        response_fields = {"final_output": ai_message}
+        if self.__tool_defs__:
+            response_fields["tool_responses"] = tool_responses
+        if self.__linked_agents__:
+            response_fields["agent_responses"] = agent_responses
+
+        return self.__response_model__(**response_fields)
+
+    async def __call__(self, user_input: str):
+        return await self.run(input_=user_input)
+
+    @classmethod
+    def get_tool_definition(cls, name: str) -> _ToolDefinition:
+        desc = getattr(cls, "__description__", "") or ""
+
+        # fresh async wrapper so each class gets its own function object
+        @wraps(cls.__call__)
+        async def _invoke(self, *args, **kwargs):
+            return await cls.__call__(self, *args, **kwargs)
+
+        td = tool(desc)(_invoke).__tool_def__  # decorator attaches metadata to the wrapper
+        td.name = name
+        return td

pyagentic_core-1.3.0/pyagentic/_base/_metaclasses.py

@@ -0,0 +1,378 @@
+import inspect
+import threading
+import warnings
+from typing import dataclass_transform, TypeVar, Mapping
+from types import MappingProxyType
+from collections import ChainMap
+from c3linearize import linearize
+from typeguard import check_type, TypeCheckError
+
+from pyagentic._base._validation import _AgentConstructionValidator
+from pyagentic._base._exceptions import SystemMessageNotDeclared, UnexpectedContextItemType
+from pyagentic._base._context import _AgentContext, ContextItem, computed_context
+from pyagentic._base._tool import _ToolDefinition
+
+from pyagentic.models.response import AgentResponse, ToolResponse
+
+from pyagentic._utils._typing import analyze_type
+
+
+# Placeholder class for Agent type annotation
+# Can't import actual agent as it would cause a circular import error
+class Agent:
+    pass
+
+
+@dataclass_transform(field_specifiers=(ContextItem,))
+class AgentMeta(type):
+    """
+    Metaclass that applies only to Agent subclasses:
+      - Ensures @system_message was declared
+      - Collects @tool definitions and ContextItem attributes
+      - Initializes class __tool_defs__ and __context_items__
+      - Dynamically injects an __init__ signature based on class __annotations__
+    """
+
+    __BaseAgent__ = None
+    _lock = threading.RLock()
+
+    @staticmethod
+    def _inherited_namespace_from_bases(bases: tuple[type, ...]) -> dict[str, object]:
+        """
+        Build the inherited (raw) namespace you'd see via MRO lookup for a class with `bases`.
+        Returns a dict where earlier bases in the MRO win.
+        """
+        # Build a graph: any hashable node -> list of parents.
+        # We'll use a sentinel NEW for the (not-yet-created) class.
+        NEW = object()
+        graph = {NEW: list(bases)}
+
+        # Add all reachable base classes and their parents.
+        stack = list(bases)
+        seen = set()
+        while stack:
+            cls = stack.pop()
+            if cls in seen or cls is object:
+                continue
+            seen.add(cls)
+            parents = [b for b in cls.__bases__ if b is not object]
+            graph[cls] = parents
+            stack.extend(parents)
+
+        # C3 linearize starting from NEW
+        order = linearize(graph)[NEW]
+        mro_bases = [c for c in order if isinstance(c, type) and c is not object]
+
+        # Chain the raw class dicts in MRO precedence (leftmost wins)
+        return dict(ChainMap(*(vars(c) for c in mro_bases)))
+
+    @staticmethod
+    def _extract_tool_defs(namespace) -> Mapping[str, _ToolDefinition]:
+        """
+        Extracts tool definitions from a given namespace
+
+        Any method with the `@tool` descriptor will be attached to the `__tool_defs__` class
+            attribute
+        """
+        tools: dict[str, _ToolDefinition] = {}
+        for attr_name, attr_value in namespace.items():
+            if hasattr(attr_value, "__tool_def__"):
+                tools[attr_name] = attr_value.__tool_def__
+        return MappingProxyType(tools)
+
+    @staticmethod
+    def _extract_annotations(namespace, bases) -> dict[str, TypeVar]:
+        """
+        Extracts all annotations from current class and all its subclasses. Combines them into
+            one dictionary, with class order respected (subclasses overide parent classes.)
+        """
+        annotations = {}
+        for base in reversed(bases):
+            if hasattr(base, "__annotations__"):
+                for name, type_ in base.__annotations__.items():
+                    if not name.startswith("__"):
+                        annotations[name] = type_
+        for name, type_ in namespace.get("__annotations__", {}).items():
+            if not name.startswith("__"):
+                annotations[name] = type_
+        return annotations
+
+    @staticmethod
+    def _extract_context_attrs(
+        annotations, namespace
+    ) -> Mapping[str, tuple[TypeVar, ContextItem]]:
+        """
+        Extracts any class field from annotations and namespace where the value is that of
+            `ContextItem`, these will later be appeneded to the agents context. This will return
+            both the type and the user defined context item.
+        """
+        context_attrs: dict[str, tuple[TypeVar, ContextItem]] = {}
+        for attr_name, attr_type in annotations.items():
+            default = namespace.get(attr_name, None)
+            if isinstance(default, ContextItem):
+                context_attrs[attr_name] = (attr_type, default)
+
+        for name, value in namespace.items():
+            if getattr(value, "_is_context", False):
+                context_attrs[name] = (computed_context, value)
+        return MappingProxyType(context_attrs)
+
+    @staticmethod
+    def _extract_linked_agents(annotations, Agent) -> Mapping[str, "Agent"]:
+        """
+        Extracts any class field from annotations and namespace where the value is that of
+            `ContextItem`, these will later be appeneded to the agents context. This will return
+            both the type and the user defined context item.
+        """
+        linked_agents: dict[str, "Agent"] = {}
+        for attr_name, attr_type in annotations.items():
+            type_info = analyze_type(attr_type, Agent)
+            if type_info.has_forward_ref:
+                msg = (
+                    f"Forward reference for agents are unsupported: '{attr_name}': {attr_type!r}. "
+                    "Make sure the forward ref was not used for an agent, or a TypeError may occur"
+                )
+                warnings.warn(msg, RuntimeWarning, stacklevel=2)
+            elif type_info.is_subclass:
+                linked_agents[attr_name] = attr_type
+
+        return MappingProxyType(linked_agents)
+
+    @staticmethod
+    def _build_init_signature(cls) -> inspect.Signature:
+        """
+        Build __init__ signature with all non-default (required) params
+        before any defaulted (optional) params.
+        """
+        self_param = inspect.Parameter("self", inspect.Parameter.POSITIONAL_ONLY)
+
+        required: list[inspect.Parameter] = []
+        optional: list[inspect.Parameter] = []
+        agents: list[inspect.Parameter] = []  # Agents go last in signature for better order
+
+        for field_name, field_type in cls.__annotations__.items():
+            if field_name in cls.__context_attrs__:
+                param = inspect.Parameter(
+                    field_name,
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    default=cls.__context_attrs__[field_name][1].get_default_value(),
+                    annotation=field_type,
+                )
+                optional.append(param)
+            elif field_name in cls.__linked_agents__:
+                # Treat linked agents as optional by default
+                param = inspect.Parameter(
+                    field_name,
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    default=None,
+                    annotation=field_type,
+                )
+                agents.append(param)
+            else:
+                default = getattr(cls, field_name, inspect._empty)
+                param = inspect.Parameter(
+                    field_name,
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    default=default,
+                    annotation=field_type,
+                )
+
+                if default is inspect._empty:
+                    required.append(param)
+                else:
+                    optional.append(param)
+
+        return inspect.Signature([self_param, *required, *optional, *agents])
+
+    @staticmethod
+    def _build_init(sig):
+        """
+        Builds the init function for the class. This init will automatically have user-defined
+            context items as arguements, allow for easy initialization of agents for a variety
+            of different tasks.
+        """
+
+        def __init__(self, *args, **kwargs):
+
+            # -------- ContextClass Construction --------------------
+            ContextClass = _AgentContext.make_ctx_class(
+                name=self.__class__.__name__, ctx_map=self.__context_attrs__
+            )
+
+            compiled = {}
+            for attr_name, (attr_type, attr_default) in self.__context_attrs__.items():
+                # Skip compted contexts, this validaiton will happen with the validator
+                #   using a dry run with supplied default values
+                if attr_type == computed_context:
+                    continue
+                # Add all ContextItems to the kwargs, checking type as it goes
+                if attr_name in kwargs:
+                    val = kwargs[attr_name]
+                    try:
+                        check_type(val, attr_type)
+                    except TypeCheckError:
+                        raise UnexpectedContextItemType(
+                            name=attr_name, expected=attr_type, recieved=type(val)
+                        )
+                    compiled[attr_name] = val
+                else:
+                    compiled[attr_name] = attr_default.get_default_value()
+
+            self.context = ContextClass(
+                instructions=self.__system_message__,
+                input_template=self.__input_template__,
+                **compiled,
+            )
+            # ------------- Retrieve Linked Agents -------------------
+            for agent_name in self.__linked_agents__.keys():
+                agent_instance = kwargs.get(agent_name, None)
+                compiled[agent_name] = agent_instance
+
+            bound = sig.bind(self, *args, **(kwargs | compiled))
+            # Add all other arguements to instance
+            for name, val in list(bound.arguments.items())[1:]:  # skip 'self'
+                if name in self.__context_attrs__:
+                    continue
+                setattr(self, name, val)
+
+            self.__post_init__()
+
+        __init__.__signature__ = sig
+        __init__.__annotations__ = {
+            p.name: p.annotation for p in sig.parameters.values() if p.name != "self"
+        }
+        return __init__
+
+    def __new__(mcs, name, bases, namespace, **kwargs):
+        """
+        This metaclass is attached to the Agent base class, so that when a new subclass of Agent
+            is created, then this class will automatically set up class variables that define
+            the functionality of the agent.
+
+            - __tool_defs__: dictionary holding all tool defintions registered by @tool
+            - __context_attrs__: dictionary holding tuple of type and item for all attributes
+                that are either have a default of ContextItem or use @computed_context
+            - __tool_response_models__: dictionary holding pydantic response models for each tool
+            - __response_model__: The response model of the current agent that is being built
+
+        Inhertance is repected in MRO order. Tools, context attributes, computed contexts and
+            linked agents can all be inherited, from other agents or mixins.
+            __system_message__ and __input_template__ are *not* inherited
+        """
+
+        """
+        Create an inherited namespace by combining all bases in MRO order.
+        This uses c3linearize to determine the order, allowing uses to extend other Agents
+            and / or any mixins.
+        Mixins are classes that do not extend Agent, but can offer Agent attributes, like
+            tools, context items, and/or linked agents
+        """
+        inherited_namespace = mcs._inherited_namespace_from_bases(bases)
+
+        """
+        Declare the new Agent subclass.
+        If this is the base agent being declared (usually on import), then the initializtion of
+            tools, context items, etc.. will be skipped, and this class will be stored in the meta
+            for future use.
+        All other Agent subclasses will have __abstract_base__ marked as False, so that future
+            implementions "know" it is not the base.
+        Since system message is not inherited, an exception is raised if the user does not
+            supply one
+        """
+        with mcs._lock:
+            cls = super().__new__(mcs, name, bases, namespace, **kwargs)
+            # If it is a base Agent, then return
+            if namespace.get("__abstract_base__", False):
+                mcs.__BaseAgent__ = cls
+                return cls
+            cls.__abstract_base__ = False
+            # Verify system message is set
+            if "__system_message__" not in namespace:
+                raise SystemMessageNotDeclared()
+
+        """
+        Extract and attach Agent attributes
+
+        __tool_defs__: Tool definitions (from any method marked with an @tool decorator) are
+            extracted from both the current namespace and the MRO ordered inherited namespace
+
+        __annotations__: Python annotations are extracted using the namespace and the inherited
+            namespace
+
+        __context_attrs__: Context attributes (from any class attribute with a ContextItem in
+            the namespace, or any method marked with a @computed_context decorator) are extracted
+            from both the current namespace and the inherited namespace. This also needs the
+            classes annotations, in order to attach the annotation to the context attribute for
+            later validation
+
+        __linked_agents__: Linked agents work a bit differently, since they cannot have default
+            values, the namespaces are not used. Instead, it relies on the MRO ordered annotations
+            to build a dict of any agents are are linked.
+        """
+        tool_defs = mcs._extract_tool_defs(inherited_namespace | namespace)
+        annotations = mcs._extract_annotations(inherited_namespace | namespace, bases)
+        context_attrs = mcs._extract_context_attrs(annotations, inherited_namespace | namespace)
+        linked_agents = mcs._extract_linked_agents(annotations, mcs.__BaseAgent__)
+        with mcs._lock:
+            cls.__tool_defs__ = tool_defs
+            cls.__annotations__ = annotations
+            cls.__context_attrs__ = context_attrs
+            cls.__linked_agents__ = linked_agents
+
+        """
+        Create response models. Response models are created on class declaration to give the agent
+            a predetermined output. This allows developers to know exactly what the output of the
+            agent will be, before even creating an instance of the agent.
+
+        __tool_response_models__: All tools have their own pydantic response model, these need
+            to be build using their Tool Definition. This needs to be stored on the agent, so that
+            it can create instances of the tool response after calling the tool.
+
+        __response_model__: The final pydantic response model of the agent. This is constructed
+            using the tool definition models, and any response model of linked agents.
+        """
+        tool_response_models = {
+            tool_name: ToolResponse.from_tool_def(tool_def)
+            for tool_name, tool_def in cls.__tool_defs__.items()
+        }
+        tool_response_model_list = list(tool_response_models.values())
+        linked_agent_response_model_list = [
+            agent.__response_model__ for agent in cls.__linked_agents__.values()
+        ]
+        ResponseModel = AgentResponse.from_tool_defs(
+            agent_name=cls.__name__,
+            tool_response_models=tool_response_model_list,
+            linked_agents_response_models=linked_agent_response_model_list,
+        )
+        with mcs._lock:
+            cls.__tool_response_models__ = MappingProxyType(tool_response_models)
+            cls.__response_model__ = ResponseModel
+
+        """
+        Build the new init
+
+        The base init just accepts *args and **kwargs, this is changed by building a new init
+            signature. The new signature combines any context attributes, agents, and any other
+            dataclass field in the following order:
+                1. required: any dataclass field with no value in the namespace
+                2. optional: mostly context attributes, can include dataclass fields with values in
+                    the namespace
+                3. linked agents: These come last in order to keep a clear order in the init. They
+                    all default to None. So if the user does not supply a linked agent, then the
+                    parent agent will ignore it.
+
+        The new init function then creates a new AgentContext class, using the context attributes
+            as its attributes. It loads in all the context items in it using the specified defaults
+            and attaches it to the agent.
+            After that it attaches any linked agents to the parent agent.
+        """
+        sig = mcs._build_init_signature(cls)
+        __init__ = mcs._build_init(sig)
+        with mcs._lock:
+            cls.__init__ = __init__
+
+        """
+        Validate and return
+        """
+        _AgentConstructionValidator(cls).validate()
+        return cls

{pyagentic_core-1.2.1 → pyagentic_core-1.3.0}/pyagentic/_base/_params.py

@@ -103,7 +103,7 @@ class Param:
                 case TypeCategory.LIST_PRIMITIVE:
                     setattr(self, field_name, value)
                 case TypeCategory.SUBCLASS:
-                    value = field_type(**value) if type(value) == dict else value
+                    value = field_type(**value) if type(value) is dict else value
                     setattr(self, field_name, value)
                 case TypeCategory.LIST_SUBCLASS:
                     listed_value = (

{pyagentic_core-1.2.1 → pyagentic_core-1.3.0}/pyagentic/_base/_tool.py

@@ -142,7 +142,7 @@ def tool(
         # Check return type
         types = get_type_hints(fn)
         return_type = types.pop("return", None)
-        if return_type != str:
+        if return_type != str and fn.__name__ != "__call__":
             raise ToolDeclarationFailed(
                 tool_name=fn.__name__, message="Method must have a return type of `str`"
             )

{pyagentic_core-1.2.1 → pyagentic_core-1.3.0}/pyagentic/_base/_validation.py

@@ -27,10 +27,7 @@ class _AgentConstructionValidator:
     def __init__(self, AgentClass: Type["Agent"]):
         self.problems = []
         self.AgentClass = AgentClass
-        self.sample_agent = self.AgentClass(
-            model="testing",
-            api_key="validation",
-        )
+        self.sample_agent = self.AgentClass(model="validation", api_key="validation")
 
     def validate(self):
         """

pyagentic_core-1.3.0/pyagentic/_utils/_typing.py

@@ -0,0 +1,97 @@
+from typing import get_origin, get_args, Any, Optional, ForwardRef
+from dataclasses import dataclass
+from enum import Enum
+
+
+PRIMITIVES = (bool, str, int, float, type(None))
+
+
+def is_primitive(type_: Any) -> bool:
+    """
+    Helper function to check if a type is a python primitive
+    """
+    return type_ in PRIMITIVES
+
+
+class TypeCategory(Enum):
+    PRIMITIVE = "primitive"
+    LIST_PRIMITIVE = "list_primitive"
+    SUBCLASS = "subclass"
+    LIST_SUBCLASS = "list_subclass"
+    UNSUPPORTED = "unsupported"
+
+
+@dataclass
+class TypeInfo:
+    """Normalized information about a type"""
+
+    category: TypeCategory
+    base_type: type
+    inner_type: Optional[type] = None  # For list types
+
+    @property
+    def is_list(self) -> bool:
+        return self.category in [TypeCategory.LIST_PRIMITIVE, TypeCategory.LIST_SUBCLASS]
+
+    @property
+    def is_subclass(self) -> bool:
+        return self.category in [TypeCategory.SUBCLASS, TypeCategory.LIST_SUBCLASS]
+
+    @property
+    def effective_type(self) -> type:
+        """Returns the type to work with (inner type for lists, base type otherwise)"""
+        return self.inner_type if self.is_list else self.base_type
+
+    @property
+    def has_forward_ref(self) -> bool:
+        """
+        True if either base_type or inner_type is a forward reference
+        (e.g., a string annotation or typing.ForwardRef). Safe across Python versions.
+        """
+
+        def _is_forward_ref(t) -> bool:
+            if t is None:
+                return False
+            # Strings from deferred annotations / forward refs
+            if isinstance(t, str):
+                return True
+            # typing.ForwardRef in 3.8+ (internal shape has varied, so duck-type too)
+            if isinstance(t, ForwardRef):
+                return True
+            # Fallback: anything that looks like a ForwardRef (duck-typing)
+            return hasattr(t, "__forward_arg__")  # covers older/private ForwardRef variants
+
+        return _is_forward_ref(self.base_type) or _is_forward_ref(self.inner_type)
+
+
+def analyze_type(type_: type, base_class: type) -> TypeInfo:
+    """
+    Analyze a type and return normalized information about it.
+
+    Args:
+        type_: The type to analyze
+        is_primitive_func: Function to check if a type is primitive
+        param_base_class: Base class for Param types (e.g., Param)
+    """
+    origin = get_origin(type_)
+
+    try:
+        if origin == list:
+            inner_type = get_args(type_)[0]
+            if is_primitive(inner_type):
+                return TypeInfo(TypeCategory.LIST_PRIMITIVE, type_, inner_type)
+            elif issubclass(inner_type, base_class):
+                return TypeInfo(TypeCategory.LIST_SUBCLASS, type_, inner_type)
+            else:
+                return TypeInfo(TypeCategory.UNSUPPORTED, type_, inner_type)
+
+        elif is_primitive(type_):
+            return TypeInfo(TypeCategory.PRIMITIVE, type_)
+
+        elif issubclass(type_, base_class):
+            return TypeInfo(TypeCategory.SUBCLASS, type_)
+
+        else:
+            return TypeInfo(TypeCategory.UNSUPPORTED, type_)
+    except TypeError:
+        return TypeInfo(TypeCategory.UNSUPPORTED, type_)

{pyagentic_core-1.2.1 → pyagentic_core-1.3.0}/pyagentic/models/response.py

@@ -1,8 +1,6 @@
 from pydantic import BaseModel, Field, create_model
 from typing import Type, Self, Union
 
-from openai.types.responses import Response
-
 from pyagentic._base._tool import _ToolDefinition
 from pyagentic._base._params import Param
 
@@ -114,24 +112,24 @@ class AgentResponse(BaseModel):
         a fastapi app. This is done by calling `from_tool_defs`.
     """
 
-    response: Response
     final_output: str
 
     @classmethod
     def from_tool_defs(
-        cls, agent_name: str, tool_response_models: list[Type[ToolResponse]]
+        cls,
+        agent_name: str,
+        tool_response_models: list[Type[ToolResponse]],
+        linked_agents_response_models: list[Type[Self]],
     ) -> Type[Self]:
         """
         Creates a subclass of `AgentResponse`, using Tool Definitions to create a predetermined
             schema of what the response will look like.
         """
+        fields = {}
         if tool_response_models:
             ToolResult = Union[tuple(tool_response_models)]
-            return create_model(
-                f"{agent_name}Response", __base__=cls, tool_responses=(list[ToolResult], ...)
-            )
-        else:
-            return create_model(
-                f"{agent_name}Response",
-                __base__=cls,
-            )
+            fields["tool_responses"] = (list[ToolResult], ...)
+        if linked_agents_response_models:
+            AgentResult = Union[tuple(linked_agents_response_models)]
+            fields["agent_responses"] = (list[AgentResult], ...)
+        return create_model(f"{agent_name}Response", __base__=cls, **fields)

{pyagentic_core-1.2.1 → pyagentic_core-1.3.0}/pyagentic_core.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyagentic-core
-Version: 1.2.1
+Version: 1.3.0
 Summary: Build LLM Agents in a Pythonic way
 Author-email: Ryan Mikulec <rmikulec.dev@gmail.com>
 License: MIT
@@ -17,6 +17,7 @@ Requires-Dist: taskipy>=1.14.1
 Requires-Dist: openai>=1.99.3
 Requires-Dist: pydantic>=2.11.7
 Requires-Dist: typeguard>=4.4.4
+Requires-Dist: c3linearize>=0.1.0
 Dynamic: license-file
 
 # PyAgentic

{pyagentic_core-1.2.1 → pyagentic_core-1.3.0}/pyagentic_core.egg-info/requires.txt

@@ -5,3 +5,4 @@ taskipy>=1.14.1
 openai>=1.99.3
 pydantic>=2.11.7
 typeguard>=4.4.4
+c3linearize>=0.1.0

{pyagentic_core-1.2.1 → pyagentic_core-1.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyagentic-core"
-version = "1.2.1"
+version = "1.3.0"
 description = "Build LLM Agents in a Pythonic way"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -20,6 +20,7 @@ dependencies = [
     "openai>=1.99.3",
     "pydantic>=2.11.7",
     "typeguard>=4.4.4",
+    "c3linearize>=0.1.0",
 ]
 
 [dependency-groups]
@@ -28,6 +29,7 @@ dev = [
     "coverage>=7.10.2",
     "deepdiff>=8.5.0",
     "flake8>=7.3.0",
+    "pytest-asyncio>=1.1.0",
     "pytest>=8.4.1",
     "python-semantic-release>=10.3.1",
 ]

pyagentic_core-1.2.1/pyagentic/__init__.py

@@ -1,6 +0,0 @@
-from pyagentic._base._agent import Agent
-from pyagentic._base._params import Param, ParamInfo
-from pyagentic._base._tool import tool
-from pyagentic._base._context import computed_context, ContextRef, ContextItem
-
-__all__ = ["Agent", "Param", "ParamInfo", "tool", "computed_context", "ContextRef", "ContextItem"]

pyagentic_core-1.2.1/pyagentic/_base/_metaclasses.py

@@ -1,179 +0,0 @@
-import inspect
-from typing import dataclass_transform, TypeVar
-from typeguard import check_type, TypeCheckError
-
-from pyagentic._base._validation import _AgentConstructionValidator
-from pyagentic._base._exceptions import SystemMessageNotDeclared, UnexpectedContextItemType
-from pyagentic._base._context import _AgentContext, ContextItem, computed_context
-from pyagentic._base._tool import _ToolDefinition
-
-from pyagentic.models.response import AgentResponse, ToolResponse
-
-
-@dataclass_transform(field_specifiers=(ContextItem,))
-class AgentMeta(type):
-    """
-    Metaclass that applies only to Agent subclasses:
-      - Ensures @system_message was declared
-      - Collects @tool definitions and ContextItem attributes
-      - Initializes class __tool_defs__ and __context_items__
-      - Dynamically injects an __init__ signature based on class __annotations__
-    """
-
-    @staticmethod
-    def _extract_tool_defs(namespace) -> dict[str, _ToolDefinition]:
-        """
-        Extracts tool definitions from a given namespace
-
-        Any method with the `@tool` descriptor will be attached to the `__tool_defs__` class
-            attribute
-        """
-        tools = {}
-        for attr_name, attr_value in namespace.items():
-            if hasattr(attr_value, "__tool_def__"):
-                tools[attr_name] = attr_value.__tool_def__
-        return tools
-
-    @staticmethod
-    def _extract_annotations(bases, namespace) -> dict[str, TypeVar]:
-        """
-        Extracts all annotations from current class and all its subclasses. Combines them into
-            one dictionary, with class order respected (subclasses overide parent classes.)
-        """
-        annotations = {}
-        for base in reversed(bases):
-            if hasattr(base, "__annotations__"):
-                for name, type_ in base.__annotations__.items():
-                    if not name.startswith("__"):
-                        annotations[name] = type_
-        for name, type_ in namespace.get("__annotations__", {}).items():
-            if not name.startswith("__"):
-                annotations[name] = type_
-        return annotations
-
-    @staticmethod
-    def _extract_context_attrs(annotations, namespace) -> dict[str, tuple[TypeVar, ContextItem]]:
-        """
-        Extracts any class field from annotations and namespace where the value is that of
-            `ContextItem`, these will later be appeneded to the agents context. This will return
-            both the type and the user defined context item.
-        """
-        context_attrs = {}
-        for attr_name, attr_type in annotations.items():
-            default = namespace.get(attr_name, None)
-            if isinstance(default, ContextItem):
-                context_attrs[attr_name] = (attr_type, default)
-
-        for name, value in namespace.items():
-            if getattr(value, "_is_context", False):
-                context_attrs[name] = (computed_context, value)
-        return context_attrs
-
-    @staticmethod
-    def _build_init_signature(cls) -> inspect.Signature:
-        """
-        Builds the signature for the classes __init__, injecting any context item attributes
-            defined by the user properly into the inits signature. This allows IDE's to be able
-            to recognize user-defined class attributes when initializing a class.
-        """
-        params = [inspect.Parameter("self", inspect.Parameter.POSITIONAL_ONLY)]
-        for field_name, field_type in cls.__annotations__.items():
-            if field_name in cls.__context_attrs__:
-                default_val = cls.__context_attrs__[field_name][1].get_default_value()
-            else:
-                default_val = getattr(cls, field_name, inspect._empty)
-            param = inspect.Parameter(
-                field_name,
-                inspect.Parameter.POSITIONAL_OR_KEYWORD,
-                default=default_val,
-                annotation=field_type,
-            )
-            params.append(param)
-        return inspect.Signature(params)
-
-    @staticmethod
-    def _build_init(sig):
-        """
-        Builds the init function for the class. This init will automatically have user-defined
-            context items as arguements, allow for easy initialization of agents for a variety
-            of different tasks.
-        """
-
-        def __init__(self, *args, **kwargs):
-
-            # -------- ContextClass Construction --------------------
-            ContextClass = _AgentContext.make_ctx_class(
-                name=self.__class__.__name__, ctx_map=self.__context_attrs__
-            )
-
-            context_kwargs = {}
-            for attr_name, (attr_type, attr_default) in self.__context_attrs__.items():
-                # Skip compted contexts, this validaiton will happen with the validator
-                #   using a dry run with supplied default values
-                if attr_type == computed_context:
-                    continue
-                # Add all ContextItems to the kwargs, checking type as it goes
-                if attr_name in kwargs:
-                    val = kwargs[attr_name]
-                    try:
-                        check_type(val, attr_type)
-                    except TypeCheckError:
-                        raise UnexpectedContextItemType(
-                            name=attr_name, expected=attr_type, recieved=type(val)
-                        )
-                    context_kwargs[attr_name] = val
-                else:
-                    context_kwargs[attr_name] = attr_default.get_default_value()
-
-            self.context = ContextClass(
-                instructions=self.__system_message__,
-                input_template=self.__input_template__,
-                **context_kwargs,
-            )
-
-            bound = sig.bind(self, *args, **kwargs)
-
-            # Add all other arguements to instance
-            for name, val in list(bound.arguments.items())[1:]:  # skip 'self'
-                if name in self.__context_attrs__:
-                    pass
-                setattr(self, name, val)
-
-            self.__post_init__()
-
-        __init__.__signature__ = sig  # type: ignore
-        return __init__
-
-    def __new__(mcs, name, bases, namespace, **kwargs):
-        # Create a new Agent class
-        cls = super().__new__(mcs, name, bases, namespace, **kwargs)
-        # If it is a base Agent, then return
-        if namespace.get("__abstract_base__", False):
-            return cls
-        # Verify system message is set
-        if "__system_message__" not in namespace:
-            raise SystemMessageNotDeclared()
-        # Attach tool definitions
-        cls.__tool_defs__ = mcs._extract_tool_defs(namespace)
-        # Attach new annotations
-        cls.__annotations__ = mcs._extract_annotations(bases, namespace)
-        # Attach context attributes (ContextItems and computed_context)
-        cls.__context_attrs__ = mcs._extract_context_attrs(cls.__annotations__, namespace)
-        # Create tool response models
-        cls.__tool_response_models__ = {
-            tool_name: ToolResponse.from_tool_def(tool_def)
-            for tool_name, tool_def in cls.__tool_defs__.items()
-        }
-        # Create final Agent response model, using the tool response models
-        cls.__response_model__ = AgentResponse.from_tool_defs(
-            cls.__name__, list(cls.__tool_response_models__.values())
-        )
-
-        # Build the new init
-        sig = mcs._build_init_signature(cls)
-        cls.__init__ = mcs._build_init(sig)
-
-        # Validate agent
-        _AgentConstructionValidator(cls).validate()
-
-        return cls

pyagentic_core-1.2.1/pyagentic/_utils/_typing.py

@@ -1,73 +0,0 @@
-from typing import get_origin, get_args, Any, Optional
-from dataclasses import dataclass
-from enum import Enum
-
-
-PRIMITIVES = (bool, str, int, float, type(None))
-
-
-def is_primitive(type_: Any) -> bool:
-    """
-    Helper function to check if a type is a python primitive
-    """
-    return type_ in PRIMITIVES
-
-
-class TypeCategory(Enum):
-    PRIMITIVE = "primitive"
-    LIST_PRIMITIVE = "list_primitive"
-    SUBCLASS = "subclass"
-    LIST_SUBCLASS = "list_subclass"
-    UNSUPPORTED = "unsupported"
-
-
-@dataclass
-class TypeInfo:
-    """Normalized information about a type"""
-
-    category: TypeCategory
-    base_type: type
-    inner_type: Optional[type] = None  # For list types
-
-    @property
-    def is_list(self) -> bool:
-        return self.category in [TypeCategory.LIST_PRIMITIVE, TypeCategory.LIST_SUBCLASS]
-
-    @property
-    def is_subclass(self) -> bool:
-        return self.category in [TypeCategory.SUBCLASS, TypeCategory.LIST_SUBCLASS]
-
-    @property
-    def effective_type(self) -> type:
-        """Returns the type to work with (inner type for lists, base type otherwise)"""
-        return self.inner_type if self.is_list else self.base_type
-
-
-def analyze_type(type_: type, base_class: type) -> TypeInfo:
-    """
-    Analyze a type and return normalized information about it.
-
-    Args:
-        type_: The type to analyze
-        is_primitive_func: Function to check if a type is primitive
-        param_base_class: Base class for Param types (e.g., Param)
-    """
-    origin = get_origin(type_)
-
-    if origin == list:
-        inner_type = get_args(type_)[0]
-        if is_primitive(inner_type):
-            return TypeInfo(TypeCategory.LIST_PRIMITIVE, type_, inner_type)
-        elif issubclass(inner_type, base_class):
-            return TypeInfo(TypeCategory.LIST_SUBCLASS, type_, inner_type)
-        else:
-            return TypeInfo(TypeCategory.UNSUPPORTED, type_, inner_type)
-
-    elif is_primitive(type_):
-        return TypeInfo(TypeCategory.PRIMITIVE, type_)
-
-    elif issubclass(type_, base_class):
-        return TypeInfo(TypeCategory.SUBCLASS, type_)
-
-    else:
-        return TypeInfo(TypeCategory.UNSUPPORTED, type_)