grasp_agents 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

grasp_agents/__init__.py

@@ -0,0 +1,38 @@
+# pyright: reportUnusedImport=false
+
+
+from .agent_message import AgentMessage
+from .base_agent import BaseAgent
+from .comm_agent import CommunicatingAgent
+from .llm import LLM, LLMSettings
+from .llm_agent import LLMAgent
+from .run_context import RunArgs, RunContextWrapper
+from .typing.completion import Completion
+from .typing.content import Content, ImageData
+from .typing.io import AgentID, AgentState, LLMFormattedArgs, LLMPrompt, LLMPromptArgs
+from .typing.message import AssistantMessage, Conversation, SystemMessage, UserMessage
+from .typing.tool import BaseTool
+
+__all__ = [
+    "LLM",
+    "AgentID",
+    "AgentMessage",
+    "AgentState",
+    "AssistantMessage",
+    "BaseAgent",
+    "BaseTool",
+    "CommunicatingAgent",
+    "Completion",
+    "Content",
+    "Conversation",
+    "ImageData",
+    "LLMAgent",
+    "LLMFormattedArgs",
+    "LLMPrompt",
+    "LLMPromptArgs",
+    "LLMSettings",
+    "RunArgs",
+    "RunContextWrapper",
+    "SystemMessage",
+    "UserMessage",
+]

grasp_agents/cloud_llm.py

@@ -286,6 +286,7 @@ class CloudLLM(LLM[SettingsT, ConvertT], Generic[SettingsT, ConvertT]):
                 validate_obj_from_json_or_py_string(
                     message.content,
                     adapter=self._response_format_pyd,
+                    from_substring=True,
                 )
 
     async def generate_completion_stream(

grasp_agents/llm_agent.py

@@ -10,7 +10,7 @@ from .comm_agent import CommunicatingAgent
 from .llm import LLM, LLMSettings
 from .llm_agent_state import (
     LLMAgentState,
-    MakeCustomAgentState,
+    SetAgentState,
     SetAgentStateStrategy,
 )
 from .prompt_builder import (
@@ -25,7 +25,11 @@ from .run_context import (
     SystemRunArgs,
     UserRunArgs,
 )
-from .tool_orchestrator import ExitToolCallLoopHandler, ToolOrchestrator
+from .tool_orchestrator import (
+    ExitToolCallLoopHandler,
+    ManageAgentStateHandler,
+    ToolOrchestrator,
+)
 from .typing.content import ImageData
 from .typing.converters import Converters
 from .typing.io import (
@@ -43,9 +47,14 @@ from .typing.tool import BaseTool
 from .utils import get_prompt, validate_obj_from_json_or_py_string
 
 
-class ParseOutputHandler(Protocol[OutT, CtxT]):
+class ParseOutputHandler(Protocol[InT, OutT, CtxT]):
     def __call__(
-        self, *args: Any, ctx: RunContextWrapper[CtxT] | None, **kwargs: Any
+        self,
+        conversation: Conversation,
+        *,
+        rcv_args: InT | None,
+        batch_idx: int,
+        ctx: RunContextWrapper[CtxT] | None,
     ) -> OutT: ...
 
 
@@ -91,9 +100,15 @@ class LLMAgent(
         # Agent state
         self._state: LLMAgentState = LLMAgentState()
         self.set_state_strategy: SetAgentStateStrategy = set_state_strategy
-        self._make_custom_agent_state_impl: MakeCustomAgentState | None = None
+        self._set_agent_state_impl: SetAgentState | None = None
 
         # Tool orchestrator
+
+        self._using_default_llm_response_format: bool = False
+        if llm.response_format is None and tools is None:
+            llm.response_format = self.out_type
+            self._using_default_llm_response_format = True
+
         self._tool_orchestrator: ToolOrchestrator[CtxT] = ToolOrchestrator[CtxT](
             agent_id=self.agent_id,
             llm=llm,
@@ -152,16 +167,28 @@ class LLMAgent(
         conversation: Conversation,
         *,
         rcv_args: InT | None = None,
+        batch_idx: int = 0,
         ctx: RunContextWrapper[CtxT] | None = None,
-        **kwargs: Any,
     ) -> OutT:
         if self._parse_output_impl:
+            if self._using_default_llm_response_format:
+                # When using custom output parsing, the required LLM response format
+                # can differ from the final agent output type ->
+                # set it back to None unless it was specified explicitly at init.
+                self._tool_orchestrator.llm.response_format = None
+                self._using_default_llm_response_format = False
+
             return self._parse_output_impl(
-                conversation=conversation, rcv_args=rcv_args, ctx=ctx, **kwargs
+                conversation=conversation,
+                rcv_args=rcv_args,
+                batch_idx=batch_idx,
+                ctx=ctx,
             )
 
         return validate_obj_from_json_or_py_string(
-            str(conversation[-1].content), self._out_type_adapter
+            str(conversation[-1].content),
+            adapter=self._out_type_adapter,
+            from_substring=True,
         )
 
     @final
@@ -210,7 +237,7 @@ class LLMAgent(
             rcv_state=rcv_state,
             sys_prompt=formatted_sys_prompt,
             strategy=self.set_state_strategy,
-            make_custom_state_impl=self._make_custom_agent_state_impl,
+            set_agent_state_impl=self._set_agent_state_impl,
             ctx=ctx,
         )
 
@@ -234,7 +261,7 @@ class LLMAgent(
         else:
             # 4. Run tool call loop (new messages are added to the message
             #    history inside the loop)
-            await self._tool_orchestrator.run_loop(agent_state=state, ctx=ctx)
+            await self._tool_orchestrator.run_loop(state=state, ctx=ctx)
 
         # 5. Parse outputs
         batch_size = state.message_history.batch_size
@@ -324,15 +351,13 @@ class LLMAgent(
         return func
 
     def parse_output_handler(
-        self, func: ParseOutputHandler[OutT, CtxT]
-    ) -> ParseOutputHandler[OutT, CtxT]:
+        self, func: ParseOutputHandler[InT, OutT, CtxT]
+    ) -> ParseOutputHandler[InT, OutT, CtxT]:
         self._parse_output_impl = func
 
         return func
 
-    def make_custom_agent_state_handler(
-        self, func: MakeCustomAgentState
-    ) -> MakeCustomAgentState:
+    def set_agent_state_handler(self, func: SetAgentState) -> SetAgentState:
         self._make_custom_agent_state_impl = func
 
         return func
@@ -344,6 +369,13 @@ class LLMAgent(
 
         return func
 
+    def manage_agent_state_handler(
+        self, func: ManageAgentStateHandler[CtxT]
+    ) -> ManageAgentStateHandler[CtxT]:
+        self._tool_orchestrator.manage_agent_state_impl = func
+
+        return func
+
     # -- Override these methods in subclasses if needed --
 
     def _register_overridden_handlers(self) -> None:
@@ -356,15 +388,18 @@ class LLMAgent(
         if cur_cls._format_inp_args is not base_cls._format_inp_args:  # noqa: SLF001
             self._prompt_builder.format_inp_args_impl = self._format_inp_args
 
-        if cur_cls._make_custom_agent_state is not base_cls._make_custom_agent_state:  # noqa: SLF001
-            self._make_custom_agent_state_impl = self._make_custom_agent_state
+        if cur_cls._set_agent_state is not base_cls._set_agent_state:  # noqa: SLF001
+            self._set_agent_state_impl = self._set_agent_state
+
+        if cur_cls._manage_agent_state is not base_cls._manage_agent_state:  # noqa: SLF001
+            self._tool_orchestrator.manage_agent_state_impl = self._manage_agent_state
 
         if (
-            cur_cls._tool_call_loop_exit is not base_cls._tool_call_loop_exit  # noqa: SLF001
+            cur_cls._exit_tool_call_loop is not base_cls._exit_tool_call_loop  # noqa: SLF001
         ):
-            self._tool_orchestrator.exit_tool_call_loop_impl = self._tool_call_loop_exit
+            self._tool_orchestrator.exit_tool_call_loop_impl = self._exit_tool_call_loop
 
-        self._parse_output_impl: ParseOutputHandler[OutT, CtxT] | None = None
+        self._parse_output_impl: ParseOutputHandler[InT, OutT, CtxT] | None = None
 
     def _format_sys_args(
         self,
@@ -379,26 +414,29 @@ class LLMAgent(
 
     def _format_inp_args(
         self,
+        *,
         usr_args: LLMPromptArgs,
         rcv_args: InT,
+        batch_idx: int = 0,
         ctx: RunContextWrapper[CtxT] | None = None,
     ) -> LLMFormattedArgs:
         raise NotImplementedError(
             "LLMAgent._format_inp_args must be overridden by a subclass"
         )
 
-    def _make_custom_agent_state(
+    def _set_agent_state(
         self,
-        cur_state: LLMAgentState | None,
+        cur_state: LLMAgentState,
+        *,
         rcv_state: AgentState | None,
         sys_prompt: LLMPrompt | None,
         ctx: RunContextWrapper[Any] | None,
     ) -> LLMAgentState:
         raise NotImplementedError(
-            "LLMAgent._make_custom_agent_state_handler must be overridden by a subclass"
+            "LLMAgent._set_agent_state_handler must be overridden by a subclass"
         )
 
-    def _tool_call_loop_exit(
+    def _exit_tool_call_loop(
         self,
         conversation: Conversation,
         *,
@@ -408,3 +446,14 @@ class LLMAgent(
         raise NotImplementedError(
             "LLMAgent._tool_call_loop_exit must be overridden by a subclass"
         )
+
+    def _manage_agent_state(
+        self,
+        state: LLMAgentState,
+        *,
+        ctx: RunContextWrapper[CtxT] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        raise NotImplementedError(
+            "LLMAgent._manage_agent_state must be overridden by a subclass"
+        )

grasp_agents/llm_agent_state.py

@@ -10,10 +10,11 @@ from .typing.io import AgentState, LLMPrompt
 SetAgentStateStrategy = Literal["keep", "reset", "from_sender", "custom"]
 
 
-class MakeCustomAgentState(Protocol):
+class SetAgentState(Protocol):
     def __call__(
         self,
-        cur_state: Optional["LLMAgentState"],
+        cur_state: "LLMAgentState",
+        *,
         rcv_state: AgentState | None,
         sys_prompt: LLMPrompt | None,
         ctx: RunContextWrapper[Any] | None,
@@ -30,11 +31,12 @@ class LLMAgentState(AgentState):
     @classmethod
     def from_cur_and_rcv_states(
         cls,
-        cur_state: Optional["LLMAgentState"] = None,
+        cur_state: "LLMAgentState",
+        *,
         rcv_state: Optional["AgentState"] = None,
         sys_prompt: LLMPrompt | None = None,
         strategy: SetAgentStateStrategy = "from_sender",
-        make_custom_state_impl: MakeCustomAgentState | None = None,
+        set_agent_state_impl: SetAgentState | None = None,
         ctx: RunContextWrapper[Any] | None = None,
     ) -> "LLMAgentState":
         upd_mh = cur_state.message_history if cur_state else None
@@ -59,10 +61,10 @@ class LLMAgentState(AgentState):
                 upd_mh.reset(sys_prompt)
 
         elif strategy == "custom":
-            assert make_custom_state_impl is not None, (
-                "Custom message history handler implementation is not provided."
+            assert set_agent_state_impl is not None, (
+                "Agent state setter implementation is not provided."
             )
-            return make_custom_state_impl(
+            return set_agent_state_impl(
                 cur_state=cur_state,
                 rcv_state=rcv_state,
                 sys_prompt=sys_prompt,

grasp_agents/openai/__init__.py

@@ -81,3 +81,7 @@ from openai.types.shared_params.response_format_json_schema import (
 from openai.types.shared_params.response_format_text import (
     ResponseFormatText,
 )
+
+from .openai_llm import OpenAILLM, OpenAILLMSettings
+
+__all__ = ["OpenAILLM", "OpenAILLMSettings"]

grasp_agents/openai/openai_llm.py

@@ -3,10 +3,9 @@ from collections.abc import Iterable
 from copy import deepcopy
 from typing import Any, Literal
 
-from pydantic import BaseModel
-
 from openai import AsyncOpenAI
 from openai._types import NOT_GIVEN  # type: ignore[import]
+from pydantic import BaseModel
 
 from ..cloud_llm import APIProvider, CloudLLM, CloudLLMSettings
 from ..http_client import AsyncHTTPClientParams

grasp_agents/prompt_builder.py

@@ -33,8 +33,10 @@ class FormatSystemArgsHandler(Protocol[CtxT]):
 class FormatInputArgsHandler(Protocol[InT, CtxT]):
     def __call__(
         self,
+        *,
         usr_args: LLMPromptArgs,
         rcv_args: InT,
+        batch_idx: int,
         ctx: RunContextWrapper[CtxT] | None,
     ) -> LLMFormattedArgs: ...
 
@@ -75,13 +77,15 @@ class PromptBuilder(AutoInstanceAttributesMixin, Generic[InT, CtxT]):
 
     def _format_inp_args(
         self,
+        *,
         usr_args: LLMPromptArgs,
         rcv_args: InT,
+        batch_idx: int = 0,
         ctx: RunContextWrapper[CtxT] | None = None,
     ) -> LLMFormattedArgs:
         if self.format_inp_args_impl:
             return self.format_inp_args_impl(
-                usr_args=usr_args, rcv_args=rcv_args, ctx=ctx
+                usr_args=usr_args, rcv_args=rcv_args, batch_idx=batch_idx, ctx=ctx
             )
 
         if not isinstance(rcv_args, BaseModel) and rcv_args is not None:
@@ -100,6 +104,7 @@ class PromptBuilder(AutoInstanceAttributesMixin, Generic[InT, CtxT]):
     def make_sys_prompt(
         self,
         sys_args: LLMPromptArgs,
+        *,
         ctx: RunContextWrapper[CtxT] | None,
     ) -> LLMPrompt | None:
         if self.sys_prompt is None:
@@ -151,9 +156,11 @@ class PromptBuilder(AutoInstanceAttributesMixin, Generic[InT, CtxT]):
         ]
 
         formatted_inp_args_batch = [
-            self._format_inp_args(usr_args=val_usr_args, rcv_args=val_rcv_args, ctx=ctx)
-            for val_usr_args, val_rcv_args in zip(
-                val_usr_args_batch_, val_rcv_args_batch_, strict=False
+            self._format_inp_args(
+                usr_args=val_usr_args, rcv_args=val_rcv_args, batch_idx=i, ctx=ctx
+            )
+            for i, (val_usr_args, val_rcv_args) in enumerate(
+                zip(val_usr_args_batch_, val_rcv_args_batch_, strict=False)
             )
         ]
 

grasp_agents/tool_orchestrator.py

@@ -29,7 +29,7 @@ class ExitToolCallLoopHandler(Protocol[CtxT]):
 class ManageAgentStateHandler(Protocol[CtxT]):
     def __call__(
         self,
-        agent_state: LLMAgentState,
+        state: LLMAgentState,
         *,
         ctx: RunContextWrapper[CtxT] | None,
         **kwargs: Any,
@@ -93,13 +93,13 @@ class ToolOrchestrator(Generic[CtxT]):
 
     def _manage_agent_state(
         self,
-        agent_state: LLMAgentState,
+        state: LLMAgentState,
         *,
         ctx: RunContextWrapper[CtxT] | None = None,
         **kwargs: Any,
     ) -> None:
         if self.manage_agent_state_impl:
-            self.manage_agent_state_impl(agent_state=agent_state, ctx=ctx, **kwargs)
+            self.manage_agent_state_impl(state=state, ctx=ctx, **kwargs)
 
     async def generate_once(
         self,
@@ -119,10 +119,10 @@ class ToolOrchestrator(Generic[CtxT]):
 
     async def run_loop(
         self,
-        agent_state: LLMAgentState,
+        state: LLMAgentState,
         ctx: RunContextWrapper[CtxT] | None = None,
     ) -> None:
-        message_history = agent_state.message_history
+        message_history = state.message_history
         assert message_history.batch_size == 1, (
             "Batch size must be 1 for tool call loop"
         )
@@ -131,13 +131,13 @@ class ToolOrchestrator(Generic[CtxT]):
 
         tool_choice = "none" if self._react_mode else "auto"
         gen_message_batch = await self.generate_once(
-            agent_state, tool_choice=tool_choice, ctx=ctx
+            state, tool_choice=tool_choice, ctx=ctx
         )
 
         turns = 0
 
         while True:
-            self._manage_agent_state(agent_state=agent_state, ctx=ctx, num_turns=turns)
+            self._manage_agent_state(state=state, ctx=ctx, num_turns=turns)
 
             if self._exit_tool_call_loop(
                 message_history.batched_conversations[0], ctx=ctx, num_turns=turns
@@ -156,7 +156,7 @@ class ToolOrchestrator(Generic[CtxT]):
 
             tool_choice = "none" if (self._react_mode and msg.tool_calls) else "auto"
             gen_message_batch = await self.generate_once(
-                agent_state, tool_choice=tool_choice, ctx=ctx
+                state, tool_choice=tool_choice, ctx=ctx
             )
 
             turns += 1

grasp_agents/typing/content.py

@@ -1,6 +1,6 @@
 import base64
 import re
-from collections.abc import Iterable
+from collections.abc import Iterable, Mapping
 from enum import StrEnum
 from pathlib import Path
 from typing import Annotated, Any, Literal, TypeAlias
@@ -66,7 +66,7 @@ class Content(BaseModel):
     def from_formatted_prompt(
         cls,
         prompt_template: str,
-        prompt_args: dict[str, str | ImageData] | None = None,
+        prompt_args: Mapping[str, str | int | bool | ImageData] | None = None,
     ) -> "Content":
         prompt_args = prompt_args or {}
         image_args = {

grasp_agents/typing/io.py

@@ -1,3 +1,4 @@
+from collections.abc import Mapping
 from typing import TypeAlias, TypeVar
 
 from pydantic import BaseModel
@@ -20,5 +21,5 @@ OutT = TypeVar("OutT", covariant=True)  # noqa: PLC0105
 StateT = TypeVar("StateT", bound=AgentState, covariant=True)  # noqa: PLC0105
 
 LLMPrompt: TypeAlias = str
-LLMFormattedSystemArgs: TypeAlias = dict[str, str]
-LLMFormattedArgs: TypeAlias = dict[str, str | ImageData]
+LLMFormattedSystemArgs: TypeAlias = Mapping[str, str | int | bool]
+LLMFormattedArgs: TypeAlias = Mapping[str, str | int | bool | ImageData]

grasp_agents/typing/message.py

@@ -1,5 +1,5 @@
 import json
-from collections.abc import Hashable, Sequence
+from collections.abc import Hashable, Mapping, Sequence
 from enum import StrEnum
 from typing import Annotated, Any, Literal, TypeAlias
 from uuid import uuid4
@@ -79,7 +79,7 @@ class UserMessage(MessageBase):
     def from_formatted_prompt(
         cls,
         prompt_template: str,
-        prompt_args: dict[str, str | ImageData] | None = None,
+        prompt_args: Mapping[str, str | int | bool | ImageData] | None = None,
         model_id: str | None = None,
     ) -> "UserMessage":
         content = Content.from_formatted_prompt(

grasp_agents/typing/tool.py

@@ -1,8 +1,6 @@
 from __future__ import annotations
 
-import asyncio
 from abc import ABC, abstractmethod
-from collections.abc import Sequence
 from typing import TYPE_CHECKING, Any, ClassVar, Generic, Literal, TypeAlias, TypeVar
 
 from pydantic import BaseModel, PrivateAttr, TypeAdapter
@@ -60,11 +58,6 @@ class BaseTool(
     ) -> _ToolOutT:
         pass
 
-    async def run_batch(
-        self, inp_batch: Sequence[_ToolInT], ctx: RunContextWrapper[CtxT] | None = None
-    ) -> Sequence[_ToolOutT]:
-        return await asyncio.gather(*[self.run(inp, ctx=ctx) for inp in inp_batch])
-
     async def __call__(
         self, ctx: RunContextWrapper[CtxT] | None = None, **kwargs: Any
     ) -> _ToolOutT:

grasp_agents/utils.py

@@ -2,14 +2,13 @@ import ast
 import asyncio
 import json
 import re
-from collections.abc import Coroutine
+from collections.abc import Coroutine, Mapping
 from datetime import datetime
 from logging import getLogger
 from pathlib import Path
 from typing import Any, TypeVar
 
 from pydantic import (
-    BaseModel,
     GetCoreSchemaHandler,
     TypeAdapter,
     ValidationError,
@@ -19,72 +18,65 @@ from tqdm.autonotebook import tqdm
 
 logger = getLogger(__name__)
 
-T = TypeVar("T")
-
-
-def filter_fields(data: dict[str, Any], model: type[BaseModel]) -> dict[str, Any]:
-    return {key: data[key] for key in model.model_fields if key in data}
+_JSON_START_RE = re.compile(r"[{\[]")
 
-
-def read_txt(file_path: str) -> str:
-    return Path(file_path).read_text()
+T = TypeVar("T")
 
 
-def format_json_string(text: str) -> str:
+def extract_json_substring(text: str) -> str | None:
     decoder = json.JSONDecoder()
-    text = text.replace("\n", "")
-    length = len(text)
-    i = 0
-    while i < length:
-        ch = text[i]
-        if ch in "{[":
-            try:
-                _, end = decoder.raw_decode(text[i:])
-                return text[i : i + end]
-            except ValueError:
-                pass
-        i += 1
-
-    return text
+    for match in _JSON_START_RE.finditer(text):
+        start = match.start()
+        try:
+            _, end = decoder.raw_decode(text, idx=start)
+            return text[start:end]
+        except ValueError:
+            continue
+
+    return None
 
 
 def parse_json_or_py_string(
-    json_str: str, return_none_on_failure: bool = False
+    s: str, return_none_on_failure: bool = False
 ) -> dict[str, Any] | list[Any] | None:
+    s_fmt = re.sub(r"```[a-zA-Z0-9]*\n|```", "", s).strip()
     try:
-        json_response = ast.literal_eval(json_str)
+        return ast.literal_eval(s_fmt)
     except (ValueError, SyntaxError):
         try:
-            json_response = json.loads(json_str)
+            return json.loads(s_fmt)
         except json.JSONDecodeError as exc:
             if return_none_on_failure:
                 return None
             raise ValueError(
-                "Invalid JSON - Both ast.literal_eval and json.loads "
-                f"failed to parse the following response:\n{json_str}"
+                "Invalid JSON/Python string - Both ast.literal_eval and json.loads "
+                f"failed to parse the following response:\n{s}"
             ) from exc
 
-    return json_response
 
-
-def extract_json(
+def parse_json_or_py_substring(
     json_str: str, return_none_on_failure: bool = False
 ) -> dict[str, Any] | list[Any] | None:
-    return parse_json_or_py_string(format_json_string(json_str), return_none_on_failure)
+    return parse_json_or_py_string(
+        extract_json_substring(json_str) or "", return_none_on_failure
+    )
 
 
-def validate_obj_from_json_or_py_string(s: str, adapter: TypeAdapter[T]) -> T:
-    s_fmt = re.sub(r"```[a-zA-Z0-9]*\n|```", "", s).strip()
+def validate_obj_from_json_or_py_string(
+    s: str, adapter: TypeAdapter[T], from_substring: bool = False
+) -> T:
     try:
-        parsed = json.loads(s_fmt)
+        if from_substring:
+            parsed = parse_json_or_py_substring(s, return_none_on_failure=True)
+        else:
+            parsed = parse_json_or_py_string(s, return_none_on_failure=True)
+        if parsed is None:
+            parsed = s
         return adapter.validate_python(parsed)
-    except (json.JSONDecodeError, ValidationError):
-        try:
-            return adapter.validate_python(s_fmt)
-        except ValidationError as exc:
-            raise ValueError(
-                f"Invalid JSON or Python string:\n{s}\nExpected type: {adapter._type}",  # type: ignore[arg-type]
-            ) from exc
+    except (json.JSONDecodeError, ValidationError) as exc:
+        raise ValueError(
+            f"Invalid JSON or Python string:\n{s}\nExpected type: {adapter._type}",  # type: ignore[arg-type]
+        ) from exc
 
 
 def extract_xml_list(text: str) -> list[str]:
@@ -97,16 +89,26 @@ def extract_xml_list(text: str) -> list[str]:
     return chunks
 
 
-def make_conditional_parsed_output_type(
-    response_format: type, marker: str = "<DONE>"
+def build_marker_json_parser_type(
+    marker_to_model: Mapping[str, type],
 ) -> type:
-    class ParsedOutput:
-        """
-        * Accepts any **str**.
-        * If the string contains `marker`, it must contain a valid JSON for
-        `response_format` → we return that a response_format instance.
-        * Otherwise we leave the string untouched.
-        """
+    """
+    Return a Pydantic-compatible *type* that, when given a **str**, searches for
+    the first marker substring and validates the JSON that follows with the
+    corresponding Pydantic model.
+
+    If no marker is found, the raw string is returned unchanged.
+
+    Example:
+    -------
+    >>> Todo = build_marker_json_parser_type({'```json': MyModel})
+    >>> Todo.validate('```json {"a": 1}')
+    MyModel(a=1)
+
+    """
+
+    class MarkerParsedOutput:
+        """String → (Model | str) parser generated by build_marker_json_parser_type."""
 
         @classmethod
         def __get_pydantic_core_schema__(
@@ -114,40 +116,49 @@ def make_conditional_parsed_output_type(
             _source_type: Any,
             _handler: GetCoreSchemaHandler,
         ) -> core_schema.CoreSchema:
-            def validator(v: Any) -> Any:
-                if isinstance(v, str) and marker in v:
-                    v_json_str = format_json_string(v)
-                    response_format_adapter = TypeAdapter[Any](response_format)
+            def _validate(value: Any) -> Any:
+                if not isinstance(value, str):
+                    raise TypeError("MarkerParsedOutput expects a string")
 
-                    return response_format_adapter.validate_json(v_json_str)
+                for marker, model in marker_to_model.items():
+                    if marker in value:
+                        adapter = TypeAdapter[Any](model)
+                        return validate_obj_from_json_or_py_string(
+                            value, adapter=adapter, from_substring=True
+                        )
 
-                return v
+                return value
 
             return core_schema.no_info_after_validator_function(
-                validator, core_schema.any_schema()
+                _validate, core_schema.any_schema()
             )
 
         @classmethod
         def __get_pydantic_json_schema__(
-            cls, core_schema: core_schema.CoreSchema, handler: GetCoreSchemaHandler
+            cls,
+            schema: core_schema.CoreSchema,
+            handler: GetCoreSchemaHandler,
         ):
-            return handler(core_schema)
+            return handler(schema)
+
+    unique_suffix = "_".join(sorted(marker_to_model))[:40]
+    MarkerParsedOutput.__name__ = f"MarkerParsedOutput_{unique_suffix}"
 
-    return ParsedOutput
+    return MarkerParsedOutput
+
+
+def read_txt(file_path: str | Path, encoding: str = "utf-8") -> str:
+    return Path(file_path).read_text(encoding=encoding)
 
 
 def read_contents_from_file(
     file_path: str | Path,
     binary_mode: bool = False,
 ) -> str | bytes:
-    """Reads and returns contents of file"""
     try:
         if binary_mode:
-            with open(file_path, "rb") as file:
-                return file.read()
-        else:
-            with open(file_path) as file:
-                return file.read()
+            return Path(file_path).read_bytes()
+        return Path(file_path).read_text()
     except FileNotFoundError:
         logger.error(f"File {file_path} not found.")
         return ""
@@ -155,13 +166,9 @@ def read_contents_from_file(
 
 def get_prompt(prompt_text: str | None, prompt_path: str | Path | None) -> str | None:
     if prompt_text is None:
-        prompt = (
-            read_contents_from_file(prompt_path) if prompt_path is not None else None
-        )
-    else:
-        prompt = prompt_text
+        return read_contents_from_file(prompt_path) if prompt_path is not None else None  # type: ignore[arg-type]
 
-    return prompt  # type: ignore[assignment]
+    return prompt_text
 
 
 async def asyncio_gather_with_pbar(

grasp_agents/workflow/looped_agent.py

@@ -13,10 +13,10 @@ logger = getLogger(__name__)
 _EH_OutT = TypeVar("_EH_OutT", contravariant=True)  # noqa: PLC0105
 
 
-class WorkflowLoopExitHandler(Protocol[_EH_OutT, CtxT]):
+class ExitWorkflowLoopHandler(Protocol[_EH_OutT, CtxT]):
     def __call__(
         self,
-        output_message: AgentMessage[_EH_OutT, AgentState],
+        output_message: AgentMessage[_EH_OutT, Any],
         ctx: RunContextWrapper[CtxT] | None,
         **kwargs: Any,
     ) -> bool: ...
@@ -31,8 +31,8 @@ class LoopedWorkflowAgent(WorkflowAgent[InT, OutT, CtxT], Generic[InT, OutT, Ctx
     def __init__(
         self,
         agent_id: AgentID,
-        subagents: Sequence[CommunicatingAgent[Any, Any, AgentState, CtxT]],
-        exit_agent: CommunicatingAgent[Any, OutT, AgentState, CtxT],
+        subagents: Sequence[CommunicatingAgent[Any, Any, Any, CtxT]],
+        exit_agent: CommunicatingAgent[Any, OutT, Any, CtxT],
         message_pool: AgentMessagePool[CtxT] | None = None,
         recipient_ids: list[AgentID] | None = None,
         dynamic_routing: bool = False,
@@ -51,27 +51,27 @@ class LoopedWorkflowAgent(WorkflowAgent[InT, OutT, CtxT], Generic[InT, OutT, Ctx
 
         self._max_iterations = max_iterations
 
-        self._workflow_loop_exit_impl: WorkflowLoopExitHandler[OutT, CtxT] | None = None
+        self._exit_workflow_loop_impl: ExitWorkflowLoopHandler[OutT, CtxT] | None = None
 
     @property
     def max_iterations(self) -> int:
         return self._max_iterations
 
-    def workflow_loop_exit_handler(
-        self, func: WorkflowLoopExitHandler[OutT, CtxT]
-    ) -> WorkflowLoopExitHandler[OutT, CtxT]:
-        self._workflow_loop_exit_impl = func
+    def exit_workflow_loop_handler(
+        self, func: ExitWorkflowLoopHandler[OutT, CtxT]
+    ) -> ExitWorkflowLoopHandler[OutT, CtxT]:
+        self._exit_workflow_loop_impl = func
 
         return func
 
     def _exit_workflow_loop(
         self,
-        output_message: AgentMessage[OutT, AgentState],
+        output_message: AgentMessage[OutT, Any],
         ctx: RunContextWrapper[CtxT] | None,
         **kwargs: Any,
     ) -> bool:
-        if self._workflow_loop_exit_impl:
-            return self._workflow_loop_exit_impl(output_message, ctx=ctx, **kwargs)
+        if self._exit_workflow_loop_impl:
+            return self._exit_workflow_loop_impl(output_message, ctx=ctx, **kwargs)
 
         return False
 
@@ -80,15 +80,15 @@ class LoopedWorkflowAgent(WorkflowAgent[InT, OutT, CtxT], Generic[InT, OutT, Ctx
         self,
         inp_items: Any | None = None,
         *,
+        rcv_message: AgentMessage[InT, Any] | None = None,
         ctx: RunContextWrapper[CtxT] | None = None,
-        rcv_message: AgentMessage[InT, AgentState] | None = None,
         entry_point: bool = False,
         forbid_state_change: bool = False,
         **kwargs: Any,
     ) -> AgentMessage[OutT, AgentState]:
         agent_message = rcv_message
         num_iterations = 0
-        exit_message: AgentMessage[OutT, AgentState] | None = None
+        exit_message: AgentMessage[OutT, Any] | None = None
 
         while True:
             for subagent in self.subagents:

grasp_agents/workflow/sequential_agent.py

@@ -4,7 +4,7 @@ from typing import Any, ClassVar, Generic, cast, final
 from ..agent_message_pool import AgentMessage, AgentMessagePool
 from ..comm_agent import CommunicatingAgent
 from ..run_context import CtxT, RunContextWrapper
-from ..typing.io import AgentID, AgentState, InT, OutT
+from ..typing.io import AgentID, InT, OutT
 from .workflow_agent import WorkflowAgent
 
 
@@ -17,7 +17,7 @@ class SequentialWorkflowAgent(WorkflowAgent[InT, OutT, CtxT], Generic[InT, OutT,
     def __init__(
         self,
         agent_id: AgentID,
-        subagents: Sequence[CommunicatingAgent[Any, Any, AgentState, CtxT]],
+        subagents: Sequence[CommunicatingAgent[Any, Any, Any, CtxT]],
         message_pool: AgentMessagePool[CtxT] | None = None,
         recipient_ids: list[AgentID] | None = None,
         dynamic_routing: bool = False,
@@ -38,12 +38,12 @@ class SequentialWorkflowAgent(WorkflowAgent[InT, OutT, CtxT], Generic[InT, OutT,
         self,
         inp_items: Any | None = None,
         *,
+        rcv_message: AgentMessage[InT, Any] | None = None,
         ctx: RunContextWrapper[CtxT] | None = None,
-        rcv_message: AgentMessage[InT, AgentState] | None = None,
         entry_point: bool = False,
         forbid_state_change: bool = False,
         **kwargs: Any,
-    ) -> AgentMessage[OutT, AgentState]:
+    ) -> AgentMessage[OutT, Any]:
         agent_message = rcv_message
         for subagent in self.subagents:
             agent_message = await subagent.run(
@@ -57,4 +57,4 @@ class SequentialWorkflowAgent(WorkflowAgent[InT, OutT, CtxT], Generic[InT, OutT,
             inp_items = None
             entry_point = False
 
-        return cast("AgentMessage[OutT, AgentState]", agent_message)
+        return cast("AgentMessage[OutT, Any]", agent_message)

grasp_agents/workflow/workflow_agent.py

@@ -5,13 +5,11 @@ from typing import Any, ClassVar, Generic
 from ..agent_message_pool import AgentMessage, AgentMessagePool
 from ..comm_agent import CommunicatingAgent
 from ..run_context import CtxT, RunContextWrapper
-from ..typing.io import AgentID, AgentState, InT, OutT
+from ..typing.io import AgentID, InT, OutT
 
 
 class WorkflowAgent(
-    CommunicatingAgent[InT, OutT, AgentState, CtxT],
-    ABC,
-    Generic[InT, OutT, CtxT],
+    CommunicatingAgent[InT, OutT, Any, CtxT], ABC, Generic[InT, OutT, CtxT]
 ):
     _generic_arg_to_instance_attr_map: ClassVar[dict[int, str]] = {
         0: "_in_type",
@@ -21,9 +19,9 @@ class WorkflowAgent(
     def __init__(
         self,
         agent_id: AgentID,
-        subagents: Sequence[CommunicatingAgent[Any, Any, AgentState, CtxT]],
-        start_agent: CommunicatingAgent[InT, Any, AgentState, CtxT],
-        end_agent: CommunicatingAgent[Any, OutT, AgentState, CtxT],
+        subagents: Sequence[CommunicatingAgent[Any, Any, Any, CtxT]],
+        start_agent: CommunicatingAgent[InT, Any, Any, CtxT],
+        end_agent: CommunicatingAgent[Any, OutT, Any, CtxT],
         message_pool: AgentMessagePool[CtxT] | None = None,
         recipient_ids: list[AgentID] | None = None,
         dynamic_routing: bool = False,
@@ -53,11 +51,11 @@ class WorkflowAgent(
             )
 
     @property
-    def start_agent(self) -> CommunicatingAgent[InT, Any, AgentState, CtxT]:
+    def start_agent(self) -> CommunicatingAgent[InT, Any, Any, CtxT]:
         return self._start_agent
 
     @property
-    def end_agent(self) -> CommunicatingAgent[Any, OutT, AgentState, CtxT]:
+    def end_agent(self) -> CommunicatingAgent[Any, OutT, Any, CtxT]:
         return self._end_agent
 
     @abstractmethod
@@ -65,10 +63,10 @@ class WorkflowAgent(
         self,
         inp_items: Any | None = None,
         *,
+        rcv_message: AgentMessage[InT, Any] | None = None,
         ctx: RunContextWrapper[CtxT] | None = None,
-        rcv_message: AgentMessage[InT, AgentState] | None = None,
         entry_point: bool = False,
         forbid_state_change: bool = False,
         **generation_kwargs: Any,
-    ) -> AgentMessage[OutT, AgentState]:
+    ) -> AgentMessage[OutT, Any]:
         pass

{grasp_agents-0.2.0.dist-info → grasp_agents-0.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: grasp_agents
-Version: 0.2.0
+Version: 0.2.2
 Summary: Grasp Agents Library
 License-File: LICENSE.md
 Requires-Python: <4,>=3.11.4

{grasp_agents-0.2.0.dist-info → grasp_agents-0.2.2.dist-info}/RECORD

@@ -1,28 +1,29 @@
+grasp_agents/__init__.py,sha256=WPNUUFbucwli6oWIwxbckz0zpY4W2LnND0o7melYZOw,979
 grasp_agents/agent_message.py,sha256=eJV5n44t8EIE6M3jl48Ld7pmaW9dDhBX_FWm_u9yGWE,877
 grasp_agents/agent_message_pool.py,sha256=OKTXNEo9LAJTQJkzxmJ3TQgWw7WJKOzrKCJjeHpln6o,3158
 grasp_agents/base_agent.py,sha256=BOLYxS_cSisOR4qupUYIVn2FW15svit3jbNNfjw_cT8,1347
-grasp_agents/cloud_llm.py,sha256=X9o9x9TsX1zCBmzO-swEcTWhReQ8wHpFpFj3-kOT_-M,13116
+grasp_agents/cloud_llm.py,sha256=D3iWYb0F-6cG4rXgVoP4bWm2u2RtnEh_xG3MufFaFDo,13157
 grasp_agents/comm_agent.py,sha256=e2IsatGLxdDkSZpPxQm6s1ha6w0Z9XAzRU1L4qb9wNY,7280
 grasp_agents/costs_dict.yaml,sha256=EW6XxRXLZobMwQEEiUNYALbDzfbZFb2zEVCaTSAqYjw,2334
 grasp_agents/generics_utils.py,sha256=kw4Odte6Nvl4c9U7-mKPgXCavWZXo009zYDHAA0BR3g,6234
 grasp_agents/grasp_logging.py,sha256=H1GYhXdQvVkmauFDZ-KDwvVmPQHZUUm9sRqX_ObK2xI,1111
 grasp_agents/http_client.py,sha256=KZva2MjJjuI5ohUeU8RdTAImUnQYaqBrV2jDH8smbJw,738
 grasp_agents/llm.py,sha256=n67lXbB8spr_i3Xz0Plw7oeykfjQmVHHkSiveqBB5Lw,3150
-grasp_agents/llm_agent.py,sha256=V8aStNrrBFMEhqBpuq-YxpTPMPJAsvYBXzBV_uxg0qY,13468
-grasp_agents/llm_agent_state.py,sha256=Bt470miFHTFnxdIXUjd7jha6FWDf0hUuMI8n_G6cZI8,2439
+grasp_agents/llm_agent.py,sha256=Lx6L9ahe9WYnzKpCc-XaIyNw73U2YHtTb6OhFGUv9mU,14989
+grasp_agents/llm_agent_state.py,sha256=lLdYni2f3TA5zJLf_jqR5DSWqVI_zP2YfNrwEGqZnvg,2402
 grasp_agents/memory.py,sha256=X1YtVX8XxP5KnGPMW8BqjID8QK4hTG2obxoyhnnZ4pU,5575
 grasp_agents/printer.py,sha256=Jk6OJExio53gbKBod5Dd8Y3CWYrVb4K5q4UJ8i9cQvo,5024
-grasp_agents/prompt_builder.py,sha256=G1ZX0sCnA6_-rBi44ZtkiNU6h7Jpvu-5dTM4ok2ax70,8043
+grasp_agents/prompt_builder.py,sha256=wb7V8JXjD3IeD3l24HItUkvGmVE4e0PUzu8IT_9rgko,8208
 grasp_agents/run_context.py,sha256=M4w_HXl5aiz-18CDlfNCRNZm3m5UIQMrjKkhurFTtkY,2229
-grasp_agents/tool_orchestrator.py,sha256=BCzeLTJkXOFXjKTRs75fRs1vJVvavbTEXzvHFEvwCM4,6167
+grasp_agents/tool_orchestrator.py,sha256=--E-ue7Z8nK6NwqGbWeCQWfTjWIbPxEe5X54bjPe62M,6107
 grasp_agents/usage_tracker.py,sha256=5YuN6hpg6HASdg-hOylgWzhCiORmDMnZuQtbISfhm_4,3378
-grasp_agents/utils.py,sha256=NzMg11w7akRyMOYjS6hHTE2XZ7DKeuM5BD1SRfFFsNk,5350
-grasp_agents/openai/__init__.py,sha256=qN8HMAatSJKOsA6v-JwakMYguwkswCVHqrmK1gFy9wI,3096
+grasp_agents/utils.py,sha256=gKUtJ6__HB7yHBUPWY5tkdSAfgj3_R3--s2J5B5fBPE,5739
+grasp_agents/openai/__init__.py,sha256=P7oa4tdJ2JKJv16frRi1C09FnrMayuOYomu5l95uayE,3196
 grasp_agents/openai/completion_converters.py,sha256=lX9h1kaGAo5ttsl-4V7l4x8IpjxJaJJtyU2cKu3-EOc,1871
 grasp_agents/openai/content_converters.py,sha256=6GI0D7xJalzsiawAJOyCUzTJTo0NQdpv87YKmfN0LYQ,2631
 grasp_agents/openai/converters.py,sha256=DBXBxow9oRG6pc8inpZBLiuUqHzVfpscmHFpN9bAdvc,5276
 grasp_agents/openai/message_converters.py,sha256=KjF6FbXzwlWdM-1YT3cswUV-74sjiwOhLFPMY4sJ5Xk,4593
-grasp_agents/openai/openai_llm.py,sha256=dscGlVhH4v1yAw4NRPgJdww9toOoMRpIqA6HD4IGWOs,6132
+grasp_agents/openai/openai_llm.py,sha256=93dSQXed9yqMIVLKJoHp5rauin7xAc-8Aokf1vFJSho,6131
 grasp_agents/openai/tool_converters.py,sha256=KhWRETkjhjocISUo_HBZ8QfBiyTOoC5WurPNAR4BYxc,1027
 grasp_agents/rate_limiting/__init__.py,sha256=KRgtF_E7R3YfA2cpYcFcZ7wycV0pWVJ0xRQC7YhiIEQ,158
 grasp_agents/rate_limiting/rate_limiter_chunked.py,sha256=BPgkUXvhmZhTpZs2T6uujNFuxH_kYHiISuf6_-eNhUc,5544
@@ -30,16 +31,16 @@ grasp_agents/rate_limiting/types.py,sha256=PbnNhEAcYedQdIpPJWud8HUVcxa_xZS2RDZu4
 grasp_agents/rate_limiting/utils.py,sha256=oEDWDNHYMUdxOOG49PlAJochkZq8nnVBCo6JxPc1iSo,2007
 grasp_agents/typing/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 grasp_agents/typing/completion.py,sha256=_KDLx3Gtz7o-pEZrvAFgCZwDmkr2oQkxrL-2LSXHHsw,657
-grasp_agents/typing/content.py,sha256=13nLNZqZgtpo9sM0vCRQmZ4bQjjZqUSElMQOwjL7bO8,3651
+grasp_agents/typing/content.py,sha256=VdnHdW8PHDCtX_ffvcwQz-7ypPUQNSGqHa3txFE_72Y,3676
 grasp_agents/typing/converters.py,sha256=yORIljRsVoKz7oj38pHLD6luIelM1RcYL_PqG_D4nWM,3086
-grasp_agents/typing/io.py,sha256=aDT8tpZYc2R2jOa6QU0xO_HJYEBqCkeL1flHDugrsOg,541
-grasp_agents/typing/message.py,sha256=oCpqD_CV2Da-M-l-e5liFJSwK8267fxfcU68LIc7C1E,3801
-grasp_agents/typing/tool.py,sha256=l6TlWGpeUiJuXWUa0g1Xx7lw7jxZOpZ0bK63Ixt9h5A,2240
+grasp_agents/typing/io.py,sha256=uxSvbD05UK5nIhPfDvXIoGuU6xRMW4USZq_4IgBeGCY,609
+grasp_agents/typing/message.py,sha256=XgPjXeh47e2GG1AYslhxaNw1Ax6Ozatga_7X2SFFKMA,3826
+grasp_agents/typing/tool.py,sha256=e0pTMnRcpMpGNVQ8muE9wnh7LdIgh92AqXDo9hMDxf0,1960
 grasp_agents/workflow/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-grasp_agents/workflow/looped_agent.py,sha256=8NVy6dAwEs7f6JgYHZUI1h-N8SabpND4n-3rSy5mh70,3945
-grasp_agents/workflow/sequential_agent.py,sha256=Ral6Bvsl5-NdO-uKMGiWuz5EE9rNcYb1lXhY8CcQw4w,2054
-grasp_agents/workflow/workflow_agent.py,sha256=LadvEJTsV6YEGRb_eaYgu5r7k1aa8N-2FHXMYJpbBVU,2460
-grasp_agents-0.2.0.dist-info/METADATA,sha256=TfFjGFaXtrnwSbjy-Hr2m9TR0ryW4CZN75QJJlFZ3ds,6889
-grasp_agents-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-grasp_agents-0.2.0.dist-info/licenses/LICENSE.md,sha256=Kfeo0gdlLS6tLQiWwO9UWhjp9-f93a5kShSiBp2FG-c,1201
-grasp_agents-0.2.0.dist-info/RECORD,,
+grasp_agents/workflow/looped_agent.py,sha256=VU1Gst_qacU6TrJ0PcwHYOUgRkdR3NdiXm7KoD3U0vw,3903
+grasp_agents/workflow/sequential_agent.py,sha256=4aFLZDJk4A1_0I0mvISIqyO8Nlz5Q5rT7Ig5Zy80cHg,2014
+grasp_agents/workflow/workflow_agent.py,sha256=FzTil10WXzOIHzum-yo2mEETfjoY9RMXUycZhlLNqkw,2383
+grasp_agents-0.2.2.dist-info/METADATA,sha256=ejV2_4MaH9s2zh6HgVcHpae9HP9FzZo8eXZ8xRrEdPY,6889
+grasp_agents-0.2.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+grasp_agents-0.2.2.dist-info/licenses/LICENSE.md,sha256=-nNNdWqGB8gJ2O-peFQ2Irshv5tW5pHKyTcYkwvH7CE,1201
+grasp_agents-0.2.2.dist-info/RECORD,,

{grasp_agents-0.2.0.dist-info → grasp_agents-0.2.2.dist-info}/licenses/LICENSE.md

@@ -8,6 +8,6 @@ Package production dependencies are licensed under the following terms:
 | dotenv    | 0.9.9   | BSD-3-Clause license                              | https://github.com/pedroburon/dotenv    |
 | httpx     | 0.28.1  | BSD License                                       | https://github.com/encode/httpx         |
 | openai    | 1.77.0  | Apache Software License                           | https://github.com/openai/openai-python |
-| tenacity  | 9.1.2   | Apache Software License                           | https://github.com/jd/tenacity          |
+| tenacity  | 8.5.0   | Apache Software License                           | https://github.com/jd/tenacity          |
 | termcolor | 2.5.0   | MIT License                                       | https://github.com/termcolor/termcolor  |
 | tqdm      | 4.67.1  | MIT License; Mozilla Public License 2.0 (MPL 2.0) | https://tqdm.github.io                  |