pyagentic-core 2.1.0a3__tar.gz → 2.2.0__tar.gz

{pyagentic_core-2.1.0a3 → pyagentic_core-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyagentic-core
-Version: 2.1.0a3
+Version: 2.2.0
 Summary: Build LLM Agents in a Pythonic way
 Author-email: Ryan Mikulec <rmikulec.dev@gmail.com>
 License: MIT
@@ -20,6 +20,7 @@ Requires-Dist: typeguard>=4.4.4
 Requires-Dist: c3linearize>=0.1.0
 Requires-Dist: anthropic>=0.62.0
 Requires-Dist: google-generativeai>=0.8.0
+Requires-Dist: transitions>=0.9.3
 Dynamic: license-file
 
 # PyAgentic

{pyagentic_core-2.1.0a3 → pyagentic_core-2.2.0}/pyagentic/_base/_agent/_agent.py

@@ -13,6 +13,7 @@ from typing import (
     Union,
 )
 
+from transitions import Machine
 from pydantic import BaseModel, ValidationError
 
 from pyagentic.logging import get_logger
@@ -165,6 +166,7 @@ class BaseAgent(metaclass=AgentMeta):
     __description__: ClassVar[str]  # Optional: description for linked agents
     __input_template__: ClassVar[str] = None  # Optional: template for user input
     __response_format__: ClassVar[Type[BaseModel]] = None  # Optional: structured output format
+    phases: ClassVar[list[tuple[str, str, Callable]]] = None
 
     # Generated Class Attributes (built by metaclass)
     __response_model__: ClassVar[Type[AgentResponse]] = None  # Pydantic response model
@@ -251,6 +253,9 @@ class BaseAgent(metaclass=AgentMeta):
         """
         self._check_llm_provider()
 
+        if self.phases:
+            self.state._build_phase_machine(self.phases)
+
         # Use BasicTracer as default if no tracer provided
         if not self.tracer:
             self.tracer = BasicTracer()
@@ -315,7 +320,14 @@ class BaseAgent(metaclass=AgentMeta):
             self.state._messages.append(
                 Message(role="assistant", content="Failed to generate a response")
             )
-            return LLMResponse(text=f"The LLM failed to generate a response: {e}", tool_calls=[])
+            response = LLMResponse(
+                text=f"The LLM failed to generate a response: {e}", tool_calls=[]
+            )
+
+        if self.phases:
+            self.state._update_state_machine(phases=self.phases)
+
+        return response
 
     @traced(SpanKind.AGENT)
     async def _process_agent_call(self, tool_call: ToolCall) -> AgentResponse:
@@ -362,6 +374,8 @@ class BaseAgent(metaclass=AgentMeta):
         self.state._messages.append(
             self.provider.to_tool_call_result_message(result=stringified_result, id_=tool_call.id)
         )
+        if self.phases:
+            self.state._update_state_machine(phases=self.phases)
         return response
 
     @traced(SpanKind.TOOL)
@@ -426,6 +440,8 @@ class BaseAgent(metaclass=AgentMeta):
             self.provider.to_tool_call_result_message(result=stringified_result, id_=tool_call.id)
         )
 
+        if self.phases:
+            self.state._update_state_machine(phases=self.phases)
         # Build and return the structured tool response
         ToolResponseModel = self.__tool_response_models__[tool_call.name]
         return ToolResponseModel(
@@ -447,7 +463,12 @@ class BaseAgent(metaclass=AgentMeta):
         # Add all @tool decorated methods
         for tool_def in self.__tool_defs__.values():
             # Resolve StateRefs in parameters (e.g., ref.self.user_name -> actual value)
-            tool_defs.append(tool_def.resolve(self.agent_reference))
+
+            if self.phases and tool_def.phases:
+                if self.state.phase in tool_def.phases:
+                    tool_defs.append(tool_def.resolve(self.agent_reference))
+            else:
+                tool_defs.append(tool_def.resolve(self.agent_reference))
 
         # Add linked agents as tools
         for name, linked_def in self.__linked_agents__.items():

{pyagentic_core-2.1.0a3 → pyagentic_core-2.2.0}/pyagentic/_base/_agent/_agent_state.py

@@ -1,9 +1,10 @@
 import asyncio
 import threading
 from typing import Any, Type, Self, Optional, ClassVar
-from pydantic import BaseModel, create_model, Field, PrivateAttr
+from pydantic import BaseModel, create_model, Field, PrivateAttr, computed_field
 from jinja2 import Template
-from typing import Optional, Literal
+from typing import Optional, Literal, Callable
+from transitions import Machine
 
 from pyagentic._base._exceptions import InvalidStateRefNotFoundInState
 from pyagentic._base._state import _StateDefinition
@@ -30,12 +31,41 @@ class _AgentState(BaseModel):
 
     instructions: str
     input_template: Optional[str] = "{{ user_message }}"
+    _machine: Machine = PrivateAttr(default=None)
     _messages: list[Message] = PrivateAttr(default_factory=list)
     _instructions_template: Template = PrivateAttr(default_factory=lambda: Template(source=""))
     _input_template: Template = PrivateAttr(
         default_factory=lambda: Template(source="{{ user_message }}")
     )
 
+    def _build_phase_machine(self, phases: list[tuple[str, str, Callable]]) -> Machine:
+        if not phases:
+            return None
+
+        states = []
+        for source, dest, _ in phases:
+            if source not in states:
+                states.append(source)
+            if dest not in states:
+                states.append(dest)
+
+        machine = Machine(states=states, initial=states[0])
+
+        for source, dest, _ in phases:
+            machine.add_transition(
+                trigger=f"{source}_to_{dest}",
+                source=source,
+                dest=dest,
+            )
+
+        self._machine = machine
+
+    def _update_state_machine(self, phases):
+        for to_, from_, condition in phases:
+            if condition(self):
+                trigger = f"{to_}_to_{from_}"
+                getattr(self._machine, trigger)()
+
     def model_post_init(self, state):
         self._instructions_template = Template(source=self.instructions)
         if self.input_template:
@@ -221,6 +251,10 @@ class _AgentState(BaseModel):
         # now build the dataclass
         return create_model(f"AgentState[{name}]", __base__=cls, **pydantic_fields)
 
+    @property
+    def phase(self) -> str:
+        return self._machine.state if self._machine else None
+
     @property
     def recent_message(self) -> Message:
         """
@@ -242,7 +276,10 @@ class _AgentState(BaseModel):
         # start with all the normal dataclass fields
 
         # now format your instruction template
-        return self._instructions_template.render(**self.model_dump())
+        if self.phase:
+            return self._instructions_template.render(phase=self.phase, **self.model_dump())
+        else:
+            return self._instructions_template.render(**self.model_dump())
 
     @property
     def messages(self) -> list[Message]:
@@ -270,7 +307,10 @@ class _AgentState(BaseModel):
         if self.input_template:
             data = self.model_dump()
             data["user_message"] = message
-            content = self._input_template.render(**data)
+            if self.phase:
+                content = self._input_template.render(phase=self.phase, **self.model_dump())
+            else:
+                content = self._input_template.render(**self.model_dump())
         else:
             content = message
         self._messages.append(Message(role="user", content=content))

{pyagentic_core-2.1.0a3 → pyagentic_core-2.2.0}/pyagentic/_base/_tool.py

@@ -43,12 +43,14 @@ class _ToolDefinition:
         parameters: dict[str, tuple[TypeVar, ParamInfo]],
         return_type: Type[Any],
         condition: Callable[[Any], bool] = None,
+        phases: list[str] = None,
     ):
         self.name: str = name
         self.description: str = description
         self.parameters: dict[str, tuple[TypeVar, ParamInfo]] = parameters
         self.condition = condition
         self.return_type = return_type
+        self.phases = phases if phases else []
 
     def resolve(self, agent_reference: dict) -> Self:
         new_parameters = {}
@@ -67,6 +69,7 @@ class _ToolDefinition:
             parameters=new_parameters,
             condition=self.condition,
             return_type=self.return_type,
+            phases=self.phases,
         )
 
     def to_openai_spec(self) -> dict:
@@ -210,10 +213,7 @@ class _ToolDefinition:
         return compiled_args
 
 
-def tool(
-    description: str,
-    condition: Callable[[Any], bool] = None,
-):
+def tool(description: str, condition: Callable[[Any], bool] = None, phases: list[str] = None):
     """
     Decorator to mark an agent method as a tool that the LLM can call.
 
@@ -281,6 +281,7 @@ def tool(
             parameters=params,
             condition=condition,
             return_type=return_type,
+            phases=phases,
         )
         return fn
 

{pyagentic_core-2.1.0a3 → pyagentic_core-2.2.0}/pyagentic_core.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyagentic-core
-Version: 2.1.0a3
+Version: 2.2.0
 Summary: Build LLM Agents in a Pythonic way
 Author-email: Ryan Mikulec <rmikulec.dev@gmail.com>
 License: MIT
@@ -20,6 +20,7 @@ Requires-Dist: typeguard>=4.4.4
 Requires-Dist: c3linearize>=0.1.0
 Requires-Dist: anthropic>=0.62.0
 Requires-Dist: google-generativeai>=0.8.0
+Requires-Dist: transitions>=0.9.3
 Dynamic: license-file
 
 # PyAgentic

{pyagentic_core-2.1.0a3 → pyagentic_core-2.2.0}/pyagentic_core.egg-info/requires.txt

@@ -8,3 +8,4 @@ typeguard>=4.4.4
 c3linearize>=0.1.0
 anthropic>=0.62.0
 google-generativeai>=0.8.0
+transitions>=0.9.3

{pyagentic_core-2.1.0a3 → pyagentic_core-2.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyagentic-core"
-version = "2.1.0-a.3"
+version = "2.2.0"
 description = "Build LLM Agents in a Pythonic way"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -23,6 +23,7 @@ dependencies = [
     "c3linearize>=0.1.0",
     "anthropic>=0.62.0",
     "google-generativeai>=0.8.0",
+    "transitions>=0.9.3",
 ]
 
 [dependency-groups]
@@ -105,4 +106,4 @@ include = ["pyagentic*"]
 compile-diagrams = "for file in docs/diagrams/source/*.d2; do d2 --layout elk \"$file\" \"docs/diagrams/$(basename \"$file\" .d2).svg\"; done"
 build-docs  = "task compile-diagrams && mkdocs build --clean"
 serve-docs  = "task compile-diagrams && mkdocs serve"
-deploy-docs = "task compile-diagrams && mkdocs gh-deploy --force"
+deploy-docs = "task compile-diagrams && mkdocs gh-deploy --force"