planar 0.5.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

planar/_version.py

@@ -1 +1 @@
-VERSION = "0.5.0"
+VERSION = "0.7.0"

planar/ai/agent.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
+import abc
 import inspect
 from dataclasses import dataclass, field
 from typing import (
     Any,
     Callable,
+    Coroutine,
     Dict,
     List,
     Type,
@@ -37,7 +39,7 @@ from planar.ai.models import (
 from planar.ai.providers import Anthropic, Gemini, Model, OpenAI
 from planar.logging import get_logger
 from planar.modeling.field_helpers import JsonSchema
-from planar.utils import utc_now
+from planar.utils import P, R, T, U, utc_now
 from planar.workflows import as_step
 from planar.workflows.models import StepType
 
@@ -65,11 +67,11 @@ def _parse_model_string(model_str: str) -> Model:
 
 
 @dataclass
-class Agent[
+class AgentBase[
     # TODO: add `= str` default when we upgrade to 3.13
     TInput: BaseModel | str,
     TOutput: BaseModel | str,
-]:
+](abc.ABC):
     """An LLM-powered agent that can be called directly within workflows."""
 
     name: str
@@ -77,10 +79,11 @@ class Agent[
     output_type: Type[TOutput] | None = None
     input_type: Type[TInput] | None = None
     user_prompt: str = ""
-    model: Union[str, Model] = "openai:gpt-4.1"
     tools: List[Callable] = field(default_factory=list)
     max_turns: int = 2
     model_parameters: Dict[str, Any] = field(default_factory=dict)
+    event_emitter: AgentEventEmitter | None = None
+    durable: bool = True
 
     # TODO: move here to serialize to frontend
     #
@@ -125,33 +128,37 @@ class Agent[
         )
         return self.output_type.model_json_schema()
 
-    def to_config(self) -> AgentConfig:
-        return AgentConfig(
-            system_prompt=self.system_prompt,
-            user_prompt=self.user_prompt,
-            model=str(self.model),
-            max_turns=self.max_turns,
-            model_parameters=self.model_parameters,
-        )
-
     @overload
     async def __call__(
-        self: "Agent[TInput, str]",
+        self: "AgentBase[TInput, str]",
         input_value: TInput,
-        event_emitter: AgentEventEmitter | None = None,
     ) -> AgentRunResult[str]: ...
 
     @overload
     async def __call__(
-        self: "Agent[TInput, TOutput]",
+        self: "AgentBase[TInput, TOutput]",
         input_value: TInput,
-        event_emitter: AgentEventEmitter | None = None,
     ) -> AgentRunResult[TOutput]: ...
 
+    def as_step_if_durable(
+        self,
+        func: Callable[P, Coroutine[T, U, R]],
+        step_type: StepType,
+        display_name: str | None = None,
+        return_type: Type[R] | None = None,
+    ) -> Callable[P, Coroutine[T, U, R]]:
+        if not self.durable:
+            return func
+        return as_step(
+            func,
+            step_type=step_type,
+            display_name=display_name or self.name,
+            return_type=return_type,
+        )
+
     async def __call__(
         self,
         input_value: TInput,
-        event_emitter: AgentEventEmitter | None = None,
     ) -> AgentRunResult[Any]:
         if self.input_type is not None and not isinstance(input_value, self.input_type):
             raise ValueError(
@@ -165,31 +172,53 @@ class Agent[
             )
 
         if self.output_type is None:
-            run_step = as_step(
+            run_step = self.as_step_if_durable(
                 self.run_step,
                 step_type=StepType.AGENT,
                 display_name=self.name,
                 return_type=AgentRunResult[str],
             )
         else:
-            run_step = as_step(
+            run_step = self.as_step_if_durable(
                 self.run_step,
                 step_type=StepType.AGENT,
                 display_name=self.name,
                 return_type=AgentRunResult[self.output_type],
             )
 
-        result = await run_step(
-            input_value=input_value,
-            event_emitter=event_emitter,
-        )
+        result = await run_step(input_value=input_value)
         # Cast the result to ensure type compatibility
         return cast(AgentRunResult[TOutput], result)
 
+    @abc.abstractmethod
+    async def run_step(
+        self,
+        input_value: TInput,
+    ) -> AgentRunResult[TOutput]: ...
+
+    @abc.abstractmethod
+    def get_model_str(self) -> str: ...
+
+    def to_config(self) -> AgentConfig:
+        return AgentConfig(
+            system_prompt=self.system_prompt,
+            user_prompt=self.user_prompt,
+            model=self.get_model_str(),
+            max_turns=self.max_turns,
+            model_parameters=self.model_parameters,
+        )
+
+
+@dataclass
+class Agent[
+    TInput: BaseModel | str,
+    TOutput: BaseModel | str,
+](AgentBase[TInput, TOutput]):
+    model: Union[str, Model] = "openai:gpt-4.1"
+
     async def run_step(
         self,
         input_value: TInput,
-        event_emitter: AgentEventEmitter | None = None,
     ) -> AgentRunResult[TOutput]:
         """Execute the agent with the provided inputs.
 
@@ -200,8 +229,12 @@ class Agent[
         Returns:
             AgentRunResult containing the agent's response
         """
+        event_emitter = self.event_emitter
         logger.debug(
-            "agent run_step called", agent_name=self.name, input_type=type(input_value)
+            "agent run_step called",
+            agent_name=self.name,
+            input_type=type(input_value),
+            config=self.to_config(),
         )
         result = None
 
@@ -309,7 +342,7 @@ class Agent[
                 model=model.model_spec,
                 output_type=output_type_for_provider,
             )
-            response = await as_step(
+            response = await self.as_step_if_durable(
                 model.provider_class.complete,
                 step_type=StepType.AGENT,
                 return_type=CompletionResponse[output_type_for_provider or str],
@@ -336,7 +369,7 @@ class Agent[
                 logger.debug("agent turn", agent_name=self.name, turns_left=turns_left)
 
                 # Get model response
-                response = await as_step(
+                response = await self.as_step_if_durable(
                     model.provider_class.complete,
                     step_type=StepType.AGENT,
                     return_type=CompletionResponse[output_type_for_provider or str],
@@ -397,7 +430,7 @@ class Agent[
                         )
                     else:
                         # Execute the tool with the provided arguments
-                        tool_result = await as_step(
+                        tool_result = await self.as_step_if_durable(
                             tool_fn,
                             step_type=StepType.TOOL_CALL,
                         )(**tool_call.arguments)
@@ -439,7 +472,8 @@ class Agent[
                     expected_type=self.output_type,
                 )
                 raise ValueError(
-                    f"Expected result of type {self.output_type} but got none after tool interactions."
+                    f"Reached max turns without the expected result of type {self.output_type}. "
+                    "You may need to increase the max_turns parameter or update the Agent instructions."
                 )
 
         if event_emitter:
@@ -455,3 +489,6 @@ class Agent[
             final_result_type=type(result),
         )
         return AgentRunResult[TOutput](output=cast(TOutput, result))
+
+    def get_model_str(self) -> str:
+        return str(self.model)