grasp_agents 0.2.3__tar.gz → 0.2.5__tar.gz

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: grasp_agents
-Version: 0.2.3
+Version: 0.2.5
 Summary: Grasp Agents Library
 License-File: LICENSE.md
 Requires-Python: <4,>=3.11.4
@@ -168,9 +168,8 @@ Problem = str
 teacher = LLMAgent[Any, Problem, None](
     agent_id="teacher",
     llm=OpenAILLM(
-        model_name="gpt-4.1",
-        api_provider="openai",
-        llm_settings=OpenAILLMSettings(temperature=0.1),
+        model_name="openai:gpt-4.1",
+        llm_settings=OpenAILLMSettings(temperature=0.1)
     ),
     tools=[AskStudentTool()],
     max_turns=20,

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/README.md

@@ -152,9 +152,8 @@ Problem = str
 teacher = LLMAgent[Any, Problem, None](
     agent_id="teacher",
     llm=OpenAILLM(
-        model_name="gpt-4.1",
-        api_provider="openai",
-        llm_settings=OpenAILLMSettings(temperature=0.1),
+        model_name="openai:gpt-4.1",
+        llm_settings=OpenAILLMSettings(temperature=0.1)
     ),
     tools=[AskStudentTool()],
     max_turns=20,

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "grasp_agents"
-version = "0.2.3"
+version = "0.2.5"
 description = "Grasp Agents Library"
 readme = "README.md"
 requires-python = ">=3.11.4,<4"

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/src/grasp_agents/base_agent.py

@@ -37,7 +37,7 @@ class BaseAgent(AutoInstanceAttributesMixin, ABC, Generic[OutT, StateT, CtxT]):
     @abstractmethod
     async def run(
         self,
-        inp_items: Any,
+        chat_inputs: Any | None = None,
         *,
         ctx: RunContextWrapper[CtxT] | None = None,
         **kwargs: Any,

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/src/grasp_agents/cloud_llm.py

@@ -106,7 +106,6 @@ class CloudLLM(LLM[SettingsT, ConvertT], Generic[SettingsT, ConvertT]):
         tools: list[BaseTool[BaseModel, Any, Any]] | None = None,
         response_format: type | None = None,
         # Connection settings
-        api_provider: APIProvider = "openai",
         async_http_client_params: (
             dict[str, Any] | AsyncHTTPClientParams | None
         ) = None,
@@ -134,7 +133,16 @@ class CloudLLM(LLM[SettingsT, ConvertT], Generic[SettingsT, ConvertT]):
         )
 
         self._model_name = model_name
+
+        api_provider = model_name.split(":", 1)[0]
+        api_model_name = model_name.split(":", 1)[-1]
+        if api_provider not in PROVIDERS:
+            raise ValueError(
+                f"API provider '{api_provider}' is not supported. "
+                f"Supported providers are: {', '.join(PROVIDERS.keys())}"
+            )
         self._api_provider: APIProvider = api_provider
+        self._api_model_name: str = api_model_name
 
         self._struct_output_support: bool = any(
             fnmatch.fnmatch(self._model_name, pat)
@@ -284,7 +292,7 @@ class CloudLLM(LLM[SettingsT, ConvertT], Generic[SettingsT, ConvertT]):
                 and not message.tool_calls
             ):
                 validate_obj_from_json_or_py_string(
-                    message.content,
+                    message.content or "",
                     adapter=self._response_format_pyd,
                     from_substring=True,
                 )

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/src/grasp_agents/comm_agent.py

@@ -51,7 +51,7 @@ class CommunicatingAgent(
         self._in_type: type[InT]
         super().__init__(agent_id=agent_id, **kwargs)
 
-        self._rcv_args_type_adapter: TypeAdapter[InT] = TypeAdapter(self._in_type)
+        self._in_args_type_adapter: TypeAdapter[InT] = TypeAdapter(self._in_type)
         self.recipient_ids = recipient_ids or []
 
         self._message_pool = message_pool or AgentMessagePool()
@@ -99,10 +99,10 @@ class CommunicatingAgent(
     @abstractmethod
     async def run(
         self,
-        inp_items: Any | None = None,
+        chat_inputs: Any | None = None,
         *,
         ctx: RunContextWrapper[CtxT] | None = None,
-        rcv_message: AgentMessage[InT, AgentState] | None = None,
+        in_message: AgentMessage[InT, AgentState] | None = None,
         entry_point: bool = False,
         forbid_state_change: bool = False,
         **kwargs: Any,
@@ -113,7 +113,7 @@ class CommunicatingAgent(
         self, ctx: RunContextWrapper[CtxT] | None = None, **run_kwargs: Any
     ) -> None:
         output_message = await self.run(
-            ctx=ctx, rcv_message=None, entry_point=True, **run_kwargs
+            ctx=ctx, in_message=None, entry_point=True, **run_kwargs
         )
         await self.post_message(output_message)
 
@@ -140,8 +140,8 @@ class CommunicatingAgent(
         ctx: RunContextWrapper[CtxT] | None = None,
         **run_kwargs: Any,
     ) -> None:
-        rcv_message = cast("AgentMessage[InT, AgentState]", message)
-        out_message = await self.run(ctx=ctx, rcv_message=rcv_message, **run_kwargs)
+        in_message = cast("AgentMessage[InT, AgentState]", message)
+        out_message = await self.run(ctx=ctx, in_message=in_message, **run_kwargs)
 
         if self._exit_condition(output_message=out_message, ctx=ctx):
             await self._message_pool.stop_all()
@@ -199,14 +199,14 @@ class CommunicatingAgent(
                 inp: InT,
                 ctx: RunContextWrapper[CtxT] | None = None,
             ) -> OutT:
-                rcv_args = in_type.model_validate(inp)
-                rcv_message = AgentMessage[in_type, AgentState](
-                    payloads=[rcv_args],
+                in_args = in_type.model_validate(inp)
+                in_message = AgentMessage[in_type, AgentState](
+                    payloads=[in_args],
                     sender_id="<tool_user>",
                     recipient_ids=[agent_instance.agent_id],
                 )
                 agent_result = await agent_instance.run(
-                    rcv_message=rcv_message,
+                    in_message=in_message,
                     entry_point=False,
                     forbid_state_change=True,
                     ctx=ctx,

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/src/grasp_agents/llm_agent.py

@@ -52,7 +52,7 @@ class ParseOutputHandler(Protocol[InT, OutT, CtxT]):
         self,
         conversation: Conversation,
         *,
-        rcv_args: InT | None,
+        in_args: InT | None,
         batch_idx: int,
         ctx: RunContextWrapper[CtxT] | None,
     ) -> OutT: ...
@@ -74,8 +74,8 @@ class LLMAgent(
         # LLM
         llm: LLM[LLMSettings, Converters],
         # Input prompt template (combines user and received arguments)
-        inp_prompt: LLMPrompt | None = None,
-        inp_prompt_path: str | Path | None = None,
+        in_prompt: LLMPrompt | None = None,
+        in_prompt_path: str | Path | None = None,
         # System prompt template
         sys_prompt: LLMPrompt | None = None,
         sys_prompt_path: str | Path | None = None,
@@ -119,13 +119,13 @@ class LLMAgent(
 
         # Prompt builder
         sys_prompt = get_prompt(prompt_text=sys_prompt, prompt_path=sys_prompt_path)
-        inp_prompt = get_prompt(prompt_text=inp_prompt, prompt_path=inp_prompt_path)
+        in_prompt = get_prompt(prompt_text=in_prompt, prompt_path=in_prompt_path)
         self._prompt_builder: PromptBuilder[InT, CtxT] = PromptBuilder[
             self.in_type, CtxT
         ](
             agent_id=self._agent_id,
             sys_prompt=sys_prompt,
-            inp_prompt=inp_prompt,
+            in_prompt=in_prompt,
             sys_args_schema=sys_args_schema,
             usr_args_schema=usr_args_schema,
         )
@@ -159,14 +159,14 @@ class LLMAgent(
         return self._prompt_builder.sys_prompt
 
     @property
-    def inp_prompt(self) -> LLMPrompt | None:
-        return self._prompt_builder.inp_prompt
+    def in_prompt(self) -> LLMPrompt | None:
+        return self._prompt_builder.in_prompt
 
     def _parse_output(
         self,
         conversation: Conversation,
         *,
-        rcv_args: InT | None = None,
+        in_args: InT | None = None,
         batch_idx: int = 0,
         ctx: RunContextWrapper[CtxT] | None = None,
     ) -> OutT:
@@ -180,25 +180,48 @@ class LLMAgent(
 
             return self._parse_output_impl(
                 conversation=conversation,
-                rcv_args=rcv_args,
+                in_args=in_args,
                 batch_idx=batch_idx,
                 ctx=ctx,
             )
 
         return validate_obj_from_json_or_py_string(
-            str(conversation[-1].content),
+            str(conversation[-1].content or ""),
             adapter=self._out_type_adapter,
             from_substring=True,
         )
 
+    @staticmethod
+    def _validate_run_inputs(
+        chat_inputs: LLMPrompt | Sequence[str | ImageData] | None = None,
+        in_args: InT | Sequence[InT] | None = None,
+        in_message: AgentMessage[InT, AgentState] | None = None,
+        entry_point: bool = False,
+    ) -> None:
+        multiple_inputs_err_message = (
+            "Only one of chat_inputs, in_args, or in_message must be provided."
+        )
+        if chat_inputs is not None and in_args is not None:
+            raise ValueError(multiple_inputs_err_message)
+        if chat_inputs is not None and in_message is not None:
+            raise ValueError(multiple_inputs_err_message)
+        if in_args is not None and in_message is not None:
+            raise ValueError(multiple_inputs_err_message)
+
+        if entry_point and in_message is not None:
+            raise ValueError(
+                "Entry point agent cannot receive messages from other agents."
+            )
+
     @final
     async def run(
         self,
-        inp_items: LLMPrompt | list[str | ImageData] | None = None,
+        chat_inputs: LLMPrompt | Sequence[str | ImageData] | None = None,
         *,
-        ctx: RunContextWrapper[CtxT] | None = None,
-        rcv_message: AgentMessage[InT, AgentState] | None = None,
+        in_message: AgentMessage[InT, AgentState] | None = None,
+        in_args: InT | Sequence[InT] | None = None,
         entry_point: bool = False,
+        ctx: RunContextWrapper[CtxT] | None = None,
         forbid_state_change: bool = False,
         **gen_kwargs: Any,  # noqa: ARG002
     ) -> AgentMessage[OutT, LLMAgentState]:
@@ -211,16 +234,12 @@ class LLMAgent(
                 sys_args = run_args.sys
                 usr_args = run_args.usr
 
-        if entry_point:
-            assert rcv_message is None, (
-                "Entry point run should not have a received message"
-            )
-        if inp_items:
-            assert rcv_message is None, (
-                "There must be no received message with user inputs"
-            )
-
-        cur_state = self.state.model_copy(deep=True)
+        self._validate_run_inputs(
+            chat_inputs=chat_inputs,
+            in_args=in_args,
+            in_message=in_message,
+            entry_point=entry_point,
+        )
 
         # 1. Make system prompt (can be None)
         formatted_sys_prompt = self._prompt_builder.make_sys_prompt(
@@ -229,12 +248,13 @@ class LLMAgent(
 
         # 2. Set agent state
 
-        rcv_state = rcv_message.sender_state if rcv_message else None
+        cur_state = self.state.model_copy(deep=True)
+        in_state = in_message.sender_state if in_message else None
         prev_mh_len = len(cur_state.message_history)
 
-        state = LLMAgentState.from_cur_and_rcv_states(
+        state = LLMAgentState.from_cur_and_in_states(
             cur_state=cur_state,
-            rcv_state=rcv_state,
+            in_state=in_state,
             sys_prompt=formatted_sys_prompt,
             strategy=self.set_state_strategy,
             set_agent_state_impl=self._set_agent_state_impl,
@@ -244,10 +264,16 @@ class LLMAgent(
         self._print_sys_msg(state=state, prev_mh_len=prev_mh_len, ctx=ctx)
 
         # 3. Make and add user messages (can be empty)
+        _in_args_batch: Sequence[InT] | None = None
+        if in_message is not None:
+            _in_args_batch = in_message.payloads
+        elif in_args is not None:
+            _in_args_batch = in_args if isinstance(in_args, Sequence) else [in_args]  # type: ignore[assignment]
+
         user_message_batch = self._prompt_builder.make_user_messages(
-            inp_items=inp_items,
+            chat_inputs=chat_inputs,
             usr_args=usr_args,
-            rcv_args_batch=rcv_message.payloads if rcv_message else None,
+            in_args_batch=_in_args_batch,
             entry_point=entry_point,
             ctx=ctx,
         )
@@ -257,7 +283,7 @@ class LLMAgent(
 
         if not self.tools:
             # 4. Generate messages without tools
-            await self._tool_orchestrator.generate_once(agent_state=state, ctx=ctx)
+            await self._tool_orchestrator.generate_once(state=state, ctx=ctx)
         else:
             # 4. Run tool call loop (new messages are added to the message
             #    history inside the loop)
@@ -265,14 +291,14 @@ class LLMAgent(
 
         # 5. Parse outputs
         batch_size = state.message_history.batch_size
-        rcv_args_batch = rcv_message.payloads if rcv_message else batch_size * [None]
+        in_args_batch = in_message.payloads if in_message else batch_size * [None]
         val_output_batch = [
             self._out_type_adapter.validate_python(
-                self._parse_output(conversation=conv, rcv_args=rcv_args, ctx=ctx)
+                self._parse_output(conversation=conv, in_args=in_args, ctx=ctx)
             )
-            for conv, rcv_args in zip(
+            for conv, in_args in zip(
                 state.message_history.batched_conversations,
-                rcv_args_batch,
+                in_args_batch,
                 strict=False,
             )
         ]
@@ -285,12 +311,12 @@ class LLMAgent(
             interaction_record = InteractionRecord(
                 source_id=self.agent_id,
                 recipient_ids=recipient_ids,
-                inp_items=inp_items,
+                chat_inputs=chat_inputs,
                 sys_prompt=self.sys_prompt,
-                inp_prompt=self.inp_prompt,
+                in_prompt=self.in_prompt,
                 sys_args=sys_args,
                 usr_args=usr_args,
-                rcv_args=(rcv_message.payloads if rcv_message is not None else None),
+                in_args=(in_message.payloads if in_message is not None else None),
                 outputs=val_output_batch,
                 state=state,
             )
@@ -343,10 +369,10 @@ class LLMAgent(
 
         return func
 
-    def format_inp_args_handler(
+    def format_in_args_handler(
         self, func: FormatInputArgsHandler[InT, CtxT]
     ) -> FormatInputArgsHandler[InT, CtxT]:
-        self._prompt_builder.format_inp_args_impl = func
+        self._prompt_builder.format_in_args_impl = func
 
         return func
 
@@ -385,8 +411,8 @@ class LLMAgent(
         if cur_cls._format_sys_args is not base_cls._format_sys_args:  # noqa: SLF001
             self._prompt_builder.format_sys_args_impl = self._format_sys_args
 
-        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._format_in_args is not base_cls._format_in_args:  # noqa: SLF001
+            self._prompt_builder.format_in_args_impl = self._format_in_args
 
         if cur_cls._set_agent_state is not base_cls._set_agent_state:  # noqa: SLF001
             self._set_agent_state_impl = self._set_agent_state
@@ -412,23 +438,23 @@ class LLMAgent(
             "if it's intended to be used as the system arguments formatter."
         )
 
-    def _format_inp_args(
+    def _format_in_args(
         self,
         *,
         usr_args: LLMPromptArgs,
-        rcv_args: InT,
+        in_args: InT,
         batch_idx: int = 0,
         ctx: RunContextWrapper[CtxT] | None = None,
     ) -> LLMFormattedArgs:
         raise NotImplementedError(
-            "LLMAgent._format_inp_args must be overridden by a subclass"
+            "LLMAgent._format_in_args must be overridden by a subclass"
         )
 
     def _set_agent_state(
         self,
         cur_state: LLMAgentState,
         *,
-        rcv_state: AgentState | None,
+        in_state: AgentState | None,
         sys_prompt: LLMPrompt | None,
         ctx: RunContextWrapper[Any] | None,
     ) -> LLMAgentState:

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/src/grasp_agents/llm_agent_state.py

@@ -15,7 +15,7 @@ class SetAgentState(Protocol):
         self,
         cur_state: "LLMAgentState",
         *,
-        rcv_state: AgentState | None,
+        in_state: AgentState | None,
         sys_prompt: LLMPrompt | None,
         ctx: RunContextWrapper[Any] | None,
     ) -> "LLMAgentState": ...
@@ -29,11 +29,11 @@ class LLMAgentState(AgentState):
         return self.message_history.batch_size
 
     @classmethod
-    def from_cur_and_rcv_states(
+    def from_cur_and_in_states(
         cls,
         cur_state: "LLMAgentState",
         *,
-        rcv_state: Optional["AgentState"] = None,
+        in_state: Optional["AgentState"] = None,
         sys_prompt: LLMPrompt | None = None,
         strategy: SetAgentStateStrategy = "from_sender",
         set_agent_state_impl: SetAgentState | None = None,
@@ -50,13 +50,13 @@ class LLMAgentState(AgentState):
             upd_mh.reset(sys_prompt)
 
         elif strategy == "from_sender":
-            rcv_mh = (
-                rcv_state.message_history
-                if rcv_state and isinstance(rcv_state, "LLMAgentState")
+            in_mh = (
+                in_state.message_history
+                if in_state and isinstance(in_state, "LLMAgentState")
                 else None
             )
-            if rcv_mh:
-                upd_mh = deepcopy(rcv_mh)
+            if in_mh:
+                in_mh = deepcopy(in_mh)
             else:
                 upd_mh.reset(sys_prompt)
 
@@ -66,7 +66,7 @@ class LLMAgentState(AgentState):
             )
             return set_agent_state_impl(
                 cur_state=cur_state,
-                rcv_state=rcv_state,
+                in_state=in_state,
                 sys_prompt=sys_prompt,
                 ctx=ctx,
             )

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/src/grasp_agents/openai/completion_converters.py

@@ -14,17 +14,22 @@ def from_api_completion(
 ) -> Completion:
     choices: list[CompletionChoice] = []
     if api_completion.choices is None:  # type: ignore
-        # Choices can sometimes be None for some providers using the OpenAI API
+        # Some providers return None for the choices when there is an error
         # TODO: add custom error types
         raise RuntimeError(
             f"Completion API error: {getattr(api_completion, 'error', None)}"
         )
     for api_choice in api_completion.choices:
         # TODO: currently no way to assign individual message usages when len(choices) > 1
+        finish_reason = api_choice.finish_reason
+        # Some providers return None for the message when finish_reason is other than "stop"
+        if api_choice.message is None:  # type: ignore
+            raise RuntimeError(
+                f"API returned None for message with finish_reason: {finish_reason}"
+            )
         message = from_api_assistant_message(
             api_choice.message, api_completion.usage, model_id=model_id
         )
-        finish_reason = api_choice.finish_reason
         choices.append(CompletionChoice(message=message, finish_reason=finish_reason))
 
     return Completion(choices=choices, model_id=model_id)

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/src/grasp_agents/openai/message_converters.py

@@ -51,11 +51,6 @@ def from_api_assistant_message(
     api_usage: ChatCompletionUsage | None = None,
     model_id: str | None = None,
 ) -> AssistantMessage:
-    content = api_message.content or ""
-    assert isinstance(content, str), (
-        "Only string content is currently supported in assistant messages"
-    )
-
     usage = None
     if api_usage is not None:
         reasoning_tokens = None
@@ -88,7 +83,7 @@ def from_api_assistant_message(
         ]
 
     return AssistantMessage(
-        content=content,
+        content=api_message.content,
         usage=usage,
         tool_calls=tool_calls,
         refusal=api_message.refusal,
@@ -113,12 +108,22 @@ def to_api_assistant_message(
             for tool_call in message.tool_calls
         ]
 
-    return ChatCompletionAssistantMessageParam(
+    api_message = ChatCompletionAssistantMessageParam(
         role="assistant",
         content=message.content,
-        tool_calls=api_tool_calls,  # type: ignore
+        tool_calls=api_tool_calls or [],
         refusal=message.refusal,
     )
+    if message.content is None and not api_tool_calls:
+        # Some API providers return None in the generated content without errors,
+        # even though None in the input content is not accepted.
+        api_message["content"] = "<empty>"
+    if api_tool_calls is None:
+        api_message.pop("tool_calls")
+    if message.refusal is None:
+        api_message.pop("refusal")
+
+    return api_message
 
 
 def from_api_system_message(

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/src/grasp_agents/openai/openai_llm.py

@@ -7,7 +7,7 @@ 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 ..cloud_llm import CloudLLM, CloudLLMSettings
 from ..http_client import AsyncHTTPClientParams
 from ..rate_limiting.rate_limiter_chunked import RateLimiterC
 from ..typing.message import AssistantMessage, Conversation
@@ -69,7 +69,6 @@ class OpenAILLM(CloudLLM[OpenAILLMSettings, OpenAIConverters]):
         tools: list[BaseTool[BaseModel, Any, Any]] | None = None,
         response_format: type | None = None,
         # Connection settings
-        api_provider: APIProvider = "openai",
         async_http_client_params: (
             dict[str, Any] | AsyncHTTPClientParams | None
         ) = None,
@@ -92,7 +91,6 @@ class OpenAILLM(CloudLLM[OpenAILLMSettings, OpenAIConverters]):
             converters=OpenAIConverters(),
             tools=tools,
             response_format=response_format,
-            api_provider=api_provider,
             async_http_client_params=async_http_client_params,
             rate_limiter=rate_limiter,
             rate_limiter_rpm=rate_limiter_rpm,
@@ -125,7 +123,7 @@ class OpenAILLM(CloudLLM[OpenAILLMSettings, OpenAIConverters]):
         tool_choice = api_tool_choice or NOT_GIVEN
 
         return await self._client.chat.completions.create(
-            model=self._model_name,
+            model=self._api_model_name,
             messages=api_messages,
             tools=tools,
             tool_choice=tool_choice,
@@ -146,7 +144,7 @@ class OpenAILLM(CloudLLM[OpenAILLMSettings, OpenAIConverters]):
         response_format = api_response_format or NOT_GIVEN
 
         return await self._client.beta.chat.completions.parse(
-            model=self._model_name,
+            model=self._api_model_name,
             messages=api_messages,
             tools=tools,
             tool_choice=tool_choice,
@@ -167,7 +165,7 @@ class OpenAILLM(CloudLLM[OpenAILLMSettings, OpenAIConverters]):
         tool_choice = api_tool_choice or NOT_GIVEN
 
         return await self._client.chat.completions.create(
-            model=self._model_name,
+            model=self._api_model_name,
             messages=api_messages,
             tools=tools,
             tool_choice=tool_choice,

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/src/grasp_agents/openai/tool_converters.py

@@ -15,15 +15,16 @@ from . import (
 def to_api_tool(
     tool: BaseTool[BaseModel, Any, Any],
 ) -> ChatCompletionToolParam:
-    return ChatCompletionToolParam(
-        type="function",
-        function=ChatCompletionFunctionDefinition(
-            name=tool.name,
-            description=tool.description,
-            parameters=tool.in_schema.model_json_schema(),
-            strict=tool.strict,
-        ),
+    function = ChatCompletionFunctionDefinition(
+        name=tool.name,
+        description=tool.description,
+        parameters=tool.in_schema.model_json_schema(),
+        strict=tool.strict,
     )
+    if tool.strict is None:
+        function.pop("strict")
+
+    return ChatCompletionToolParam(type="function", function=function)
 
 
 def to_api_tool_choice(

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/src/grasp_agents/printer.py

@@ -88,7 +88,7 @@ class Printer:
 
         role = message.role
         usage = message.usage if isinstance(message, AssistantMessage) else None
-        content_str = self.content_to_str(message.content, message.role)
+        content_str = self.content_to_str(message.content or "", message.role)
 
         if self.color_by == "agent_id":
             color = self.get_agent_color(agent_id)

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/src/grasp_agents/prompt_builder.py

@@ -35,7 +35,7 @@ class FormatInputArgsHandler(Protocol[InT, CtxT]):
         self,
         *,
         usr_args: LLMPromptArgs,
-        rcv_args: InT,
+        in_args: InT,
         batch_idx: int,
         ctx: RunContextWrapper[CtxT] | None,
     ) -> LLMFormattedArgs: ...
@@ -48,7 +48,7 @@ class PromptBuilder(AutoInstanceAttributesMixin, Generic[InT, CtxT]):
         self,
         agent_id: str,
         sys_prompt: LLMPrompt | None,
-        inp_prompt: LLMPrompt | None,
+        in_prompt: LLMPrompt | None,
         sys_args_schema: type[LLMPromptArgs],
         usr_args_schema: type[LLMPromptArgs],
     ):
@@ -57,13 +57,13 @@ class PromptBuilder(AutoInstanceAttributesMixin, Generic[InT, CtxT]):
 
         self._agent_id = agent_id
         self.sys_prompt = sys_prompt
-        self.inp_prompt = inp_prompt
+        self.in_prompt = in_prompt
         self.sys_args_schema = sys_args_schema
         self.usr_args_schema = usr_args_schema
         self.format_sys_args_impl: FormatSystemArgsHandler[CtxT] | None = None
-        self.format_inp_args_impl: FormatInputArgsHandler[InT, CtxT] | None = None
+        self.format_in_args_impl: FormatInputArgsHandler[InT, CtxT] | None = None
 
-        self._rcv_args_type_adapter: TypeAdapter[InT] = TypeAdapter(self._in_type)
+        self._in_args_type_adapter: TypeAdapter[InT] = TypeAdapter(self._in_type)
 
     def _format_sys_args(
         self,
@@ -75,31 +75,31 @@ class PromptBuilder(AutoInstanceAttributesMixin, Generic[InT, CtxT]):
 
         return sys_args.model_dump(exclude_unset=True)
 
-    def _format_inp_args(
+    def _format_in_args(
         self,
         *,
         usr_args: LLMPromptArgs,
-        rcv_args: InT,
+        in_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, batch_idx=batch_idx, ctx=ctx
+        if self.format_in_args_impl:
+            return self.format_in_args_impl(
+                usr_args=usr_args, in_args=in_args, batch_idx=batch_idx, ctx=ctx
             )
 
-        if not isinstance(rcv_args, BaseModel) and rcv_args is not None:
+        if not isinstance(in_args, BaseModel) and in_args is not None:
             raise TypeError(
                 "Cannot apply default formatting to non-BaseModel received arguments."
             )
 
         usr_args_ = usr_args
-        rcv_args_ = DummySchema() if rcv_args is None else rcv_args
+        in_args_ = DummySchema() if in_args is None else in_args
 
         usr_args_dump = usr_args_.model_dump(exclude_unset=True)
-        rcv_args_dump = rcv_args_.model_dump(exclude={"selected_recipient_ids"})
+        in_args_dump = in_args_.model_dump(exclude={"selected_recipient_ids"})
 
-        return usr_args_dump | rcv_args_dump
+        return usr_args_dump | in_args_dump
 
     def make_sys_prompt(
         self,
@@ -118,17 +118,17 @@ class PromptBuilder(AutoInstanceAttributesMixin, Generic[InT, CtxT]):
         return [UserMessage.from_text(text, model_id=self._agent_id)]
 
     def _usr_messages_from_content_parts(
-        self, content_parts: list[str | ImageData]
-    ) -> list[UserMessage]:
+        self, content_parts: Sequence[str | ImageData]
+    ) -> Sequence[UserMessage]:
         return [UserMessage.from_content_parts(content_parts, model_id=self._agent_id)]
 
-    def _usr_messages_from_rcv_args(
-        self, rcv_args_batch: Sequence[InT]
-    ) -> list[UserMessage]:
+    def _usr_messages_from_in_args(
+        self, in_args_batch: Sequence[InT]
+    ) -> Sequence[UserMessage]:
         return [
             UserMessage.from_text(
-                self._rcv_args_type_adapter.dump_json(
-                    rcv,
+                self._in_args_type_adapter.dump_json(
+                    inp,
                     exclude_unset=True,
                     indent=2,
                     exclude={"selected_recipient_ids"},
@@ -136,96 +136,102 @@ class PromptBuilder(AutoInstanceAttributesMixin, Generic[InT, CtxT]):
                 ).decode("utf-8"),
                 model_id=self._agent_id,
             )
-            for rcv in rcv_args_batch
+            for inp in in_args_batch
         ]
 
     def _usr_messages_from_prompt_template(
         self,
-        inp_prompt: LLMPrompt,
+        in_prompt: LLMPrompt,
         usr_args: UserRunArgs | None = None,
-        rcv_args_batch: Sequence[InT] | None = None,
+        in_args_batch: Sequence[InT] | None = None,
         ctx: RunContextWrapper[CtxT] | None = None,
     ) -> Sequence[UserMessage]:
-        usr_args_batch_, rcv_args_batch_ = self._make_batched(usr_args, rcv_args_batch)
+        usr_args_batch_, in_args_batch_ = self._make_batched(usr_args, in_args_batch)
 
         val_usr_args_batch_ = [
             self.usr_args_schema.model_validate(u) for u in usr_args_batch_
         ]
-        val_rcv_args_batch_ = [
-            self._rcv_args_type_adapter.validate_python(rcv) for rcv in rcv_args_batch_
+        val_in_args_batch_ = [
+            self._in_args_type_adapter.validate_python(inp) for inp in in_args_batch_
         ]
 
-        formatted_inp_args_batch = [
-            self._format_inp_args(
-                usr_args=val_usr_args, rcv_args=val_rcv_args, batch_idx=i, ctx=ctx
+        formatted_in_args_batch = [
+            self._format_in_args(
+                usr_args=val_usr_args, in_args=val_in_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)
+            for i, (val_usr_args, val_in_args) in enumerate(
+                zip(val_usr_args_batch_, val_in_args_batch_, strict=False)
             )
         ]
 
         return [
             UserMessage.from_formatted_prompt(
-                prompt_template=inp_prompt, prompt_args=inp_args
+                prompt_template=in_prompt, prompt_args=in_args
             )
-            for inp_args in formatted_inp_args_batch
+            for in_args in formatted_in_args_batch
         ]
 
     def make_user_messages(
         self,
-        inp_items: LLMPrompt | list[str | ImageData] | None = None,
+        chat_inputs: LLMPrompt | Sequence[str | ImageData] | None = None,
         usr_args: UserRunArgs | None = None,
-        rcv_args_batch: Sequence[InT] | None = None,
+        in_args_batch: Sequence[InT] | None = None,
         entry_point: bool = False,
         ctx: RunContextWrapper[CtxT] | None = None,
     ) -> Sequence[UserMessage]:
         # 1) Direct user input (e.g. chat input)
-        if inp_items is not None or entry_point:
+        if chat_inputs is not None or entry_point:
             """
-            * If user inputs are provided, use them instead of the predefined
+            * If chat inputs are provided, use them instead of the predefined
                 input prompt template
             * In a multi-agent system, the predefined input prompt is used to
                 construct agent inputs using the combination of received
                 and user arguments.
                 However, the first agent run (entry point) has no received
-                messages, so we use the user inputs directly, if provided.
+                messages, so we use the chat inputs directly, if provided.
             """
-            if isinstance(inp_items, LLMPrompt):
-                return self._usr_messages_from_text(inp_items)
-            if isinstance(inp_items, list) and inp_items:
-                return self._usr_messages_from_content_parts(inp_items)
-            return []
+            if isinstance(chat_inputs, LLMPrompt):
+                return self._usr_messages_from_text(chat_inputs)
+
+            if isinstance(chat_inputs, Sequence) and chat_inputs:
+                return self._usr_messages_from_content_parts(chat_inputs)
 
         # 2) No input prompt template + received args → raw JSON messages
-        if self.inp_prompt is None and rcv_args_batch:
-            return self._usr_messages_from_rcv_args(rcv_args_batch)
+        if self.in_prompt is None and in_args_batch:
+            return self._usr_messages_from_in_args(in_args_batch)
 
         # 3) Input prompt template + any args → batch & format
-        if self.inp_prompt is not None:
+        if self.in_prompt is not None:
+            if in_args_batch and not isinstance(in_args_batch[0], BaseModel):
+                raise TypeError(
+                    "Cannot use the input prompt template with "
+                    "non-BaseModel received arguments."
+                )
             return self._usr_messages_from_prompt_template(
-                inp_prompt=self.inp_prompt,
+                in_prompt=self.in_prompt,
                 usr_args=usr_args,
-                rcv_args_batch=rcv_args_batch,
+                in_args_batch=in_args_batch,
                 ctx=ctx,
             )
+
         return []
 
     def _make_batched(
         self,
         usr_args: UserRunArgs | None = None,
-        rcv_args_batch: Sequence[InT] | None = None,
+        in_args_batch: Sequence[InT] | None = None,
     ) -> tuple[Sequence[LLMPromptArgs | DummySchema], Sequence[InT | DummySchema]]:
         usr_args_batch_ = (
             usr_args if isinstance(usr_args, list) else [usr_args or DummySchema()]
         )
-        rcv_args_batch_ = rcv_args_batch or [DummySchema()]
+        in_args_batch_ = in_args_batch or [DummySchema()]
 
         # Broadcast singleton → match lengths
-        if len(usr_args_batch_) == 1 and len(rcv_args_batch_) > 1:
-            usr_args_batch_ = [deepcopy(usr_args_batch_[0]) for _ in rcv_args_batch_]
-        if len(rcv_args_batch_) == 1 and len(usr_args_batch_) > 1:
-            rcv_args_batch_ = [deepcopy(rcv_args_batch_[0]) for _ in usr_args_batch_]
-        if len(usr_args_batch_) != len(rcv_args_batch_):
+        if len(usr_args_batch_) == 1 and len(in_args_batch_) > 1:
+            usr_args_batch_ = [deepcopy(usr_args_batch_[0]) for _ in in_args_batch_]
+        if len(in_args_batch_) == 1 and len(usr_args_batch_) > 1:
+            in_args_batch_ = [deepcopy(in_args_batch_[0]) for _ in usr_args_batch_]
+        if len(usr_args_batch_) != len(in_args_batch_):
             raise ValueError("User args and received args must have the same length")
 
-        return usr_args_batch_, rcv_args_batch_
+        return usr_args_batch_, in_args_batch_

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/src/grasp_agents/run_context.py

@@ -32,12 +32,12 @@ class InteractionRecord(BaseModel, Generic[InT, OutT, StateT]):
     source_id: str
     recipient_ids: Sequence[AgentID]
     state: StateT
-    inp_items: LLMPrompt | list[str | ImageData] | None = None
+    chat_inputs: LLMPrompt | Sequence[str | ImageData] | None = None
     sys_prompt: LLMPrompt | None = None
-    inp_prompt: LLMPrompt | None = None
+    in_prompt: LLMPrompt | None = None
     sys_args: SystemRunArgs | None = None
     usr_args: UserRunArgs | None = None
-    rcv_args: Sequence[InT] | None = None
+    in_args: Sequence[InT] | None = None
     outputs: Sequence[OutT]
 
     model_config = ConfigDict(extra="forbid", frozen=True)

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/src/grasp_agents/tool_orchestrator.py

@@ -103,11 +103,11 @@ class ToolOrchestrator(Generic[CtxT]):
 
     async def generate_once(
         self,
-        agent_state: LLMAgentState,
+        state: LLMAgentState,
         tool_choice: ToolChoice | None = None,
         ctx: RunContextWrapper[CtxT] | None = None,
     ) -> Sequence[AssistantMessage]:
-        message_history = agent_state.message_history
+        message_history = state.message_history
         message_batch = await self.llm.generate_message_batch(
             message_history, tool_choice=tool_choice
         )

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/src/grasp_agents/typing/message.py

@@ -61,7 +61,7 @@ class MessageBase(BaseModel):
 
 class AssistantMessage(MessageBase):
     role: Literal[Role.ASSISTANT] = Role.ASSISTANT
-    content: str
+    content: str | None
     usage: Usage | None = None
     tool_calls: Sequence[ToolCall] | None = None
     refusal: str | None = None

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/src/grasp_agents/usage_tracker.py

@@ -19,6 +19,7 @@ CostsDict: TypeAlias = dict[str, ModelCostsDict]
 
 
 class UsageTracker(BaseModel):
+    # TODO: specify different costs per provider:model, not just per model
     source_id: str
     costs_dict_path: str | Path = COSTS_DICT_PATH
     costs_dict: CostsDict | None = None
@@ -60,7 +61,7 @@ class UsageTracker(BaseModel):
         self, messages: Sequence[Message], model_name: str | None = None
     ) -> None:
         if model_name is not None and self.costs_dict is not None:
-            model_costs_dict = self.costs_dict.get(model_name)
+            model_costs_dict = self.costs_dict.get(model_name.split(":", 1)[-1])
         else:
             model_costs_dict = None
 

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/src/grasp_agents/workflow/looped_agent.py

@@ -67,7 +67,8 @@ class LoopedWorkflowAgent(WorkflowAgent[InT, OutT, CtxT], Generic[InT, OutT, Ctx
     def _exit_workflow_loop(
         self,
         output_message: AgentMessage[OutT, Any],
-        ctx: RunContextWrapper[CtxT] | None,
+        *,
+        ctx: RunContextWrapper[CtxT] | None = None,
         **kwargs: Any,
     ) -> bool:
         if self._exit_workflow_loop_impl:
@@ -78,23 +79,25 @@ class LoopedWorkflowAgent(WorkflowAgent[InT, OutT, CtxT], Generic[InT, OutT, Ctx
     @final
     async def run(
         self,
-        inp_items: Any | None = None,
+        chat_inputs: Any | None = None,
         *,
-        rcv_message: AgentMessage[InT, Any] | None = None,
+        in_args: InT | Sequence[InT] | None = None,
+        in_message: AgentMessage[InT, Any] | None = None,
         ctx: RunContextWrapper[CtxT] | None = None,
         entry_point: bool = False,
         forbid_state_change: bool = False,
         **kwargs: Any,
     ) -> AgentMessage[OutT, AgentState]:
-        agent_message = rcv_message
+        agent_message = in_message
         num_iterations = 0
         exit_message: AgentMessage[OutT, Any] | None = None
 
         while True:
             for subagent in self.subagents:
                 agent_message = await subagent.run(
-                    inp_items=inp_items,
-                    rcv_message=agent_message,
+                    chat_inputs=chat_inputs,
+                    in_args=in_args,
+                    in_message=agent_message,
                     entry_point=entry_point,
                     forbid_state_change=forbid_state_change,
                     ctx=ctx,
@@ -112,5 +115,6 @@ class LoopedWorkflowAgent(WorkflowAgent[InT, OutT, CtxT], Generic[InT, OutT, Ctx
                         )
                         return exit_message
 
-                inp_items = None
+                chat_inputs = None
+                in_args = None
                 entry_point = False

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/src/grasp_agents/workflow/sequential_agent.py

@@ -36,25 +36,28 @@ class SequentialWorkflowAgent(WorkflowAgent[InT, OutT, CtxT], Generic[InT, OutT,
     @final
     async def run(
         self,
-        inp_items: Any | None = None,
+        chat_inputs: Any | None = None,
         *,
-        rcv_message: AgentMessage[InT, Any] | None = None,
+        in_args: InT | Sequence[InT] | None = None,
+        in_message: AgentMessage[InT, Any] | None = None,
         ctx: RunContextWrapper[CtxT] | None = None,
         entry_point: bool = False,
         forbid_state_change: bool = False,
         **kwargs: Any,
     ) -> AgentMessage[OutT, Any]:
-        agent_message = rcv_message
+        agent_message = in_message
         for subagent in self.subagents:
             agent_message = await subagent.run(
-                inp_items=inp_items,
-                rcv_message=agent_message,
+                chat_inputs=chat_inputs,
+                in_args=in_args,
+                in_message=agent_message,
                 entry_point=entry_point,
                 forbid_state_change=forbid_state_change,
                 ctx=ctx,
                 **kwargs,
             )
-            inp_items = None
+            chat_inputs = None
+            in_args = None
             entry_point = False
 
         return cast("AgentMessage[OutT, Any]", agent_message)

{grasp_agents-0.2.3 → grasp_agents-0.2.5}/src/grasp_agents/workflow/workflow_agent.py

@@ -61,9 +61,10 @@ class WorkflowAgent(
     @abstractmethod
     async def run(
         self,
-        inp_items: Any | None = None,
+        chat_inputs: Any | None = None,
         *,
-        rcv_message: AgentMessage[InT, Any] | None = None,
+        in_args: InT | Sequence[InT] | None = None,
+        in_message: AgentMessage[InT, Any] | None = None,
         ctx: RunContextWrapper[CtxT] | None = None,
         entry_point: bool = False,
         forbid_state_change: bool = False,