grasp_agents 0.2.3__tar.gz → 0.2.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: grasp_agents
-Version: 0.2.3
+Version: 0.2.4
 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.4}/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.4}/pyproject.toml

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

{grasp_agents-0.2.3 → grasp_agents-0.2.4}/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.4}/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.4}/src/grasp_agents/comm_agent.py

@@ -99,7 +99,7 @@ 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,

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

@@ -186,19 +186,42 @@ class LLMAgent(
             )
 
         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,
+        rcv_args: InT | Sequence[InT] | None = None,
+        rcv_message: AgentMessage[InT, AgentState] | None = None,
+        entry_point: bool = False,
+    ) -> None:
+        multiple_inputs_err_message = (
+            "Only one of chat_inputs, rcv_args, or rcv_message must be provided."
+        )
+        if chat_inputs is not None and rcv_args is not None:
+            raise ValueError(multiple_inputs_err_message)
+        if chat_inputs is not None and rcv_message is not None:
+            raise ValueError(multiple_inputs_err_message)
+        if rcv_args is not None and rcv_message is not None:
+            raise ValueError(multiple_inputs_err_message)
+
+        if entry_point and rcv_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,
+        rcv_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,
+            rcv_args=rcv_args,
+            rcv_message=rcv_message,
+            entry_point=entry_point,
+        )
 
         # 1. Make system prompt (can be None)
         formatted_sys_prompt = self._prompt_builder.make_sys_prompt(
@@ -229,6 +248,7 @@ class LLMAgent(
 
         # 2. Set agent state
 
+        cur_state = self.state.model_copy(deep=True)
         rcv_state = rcv_message.sender_state if rcv_message else None
         prev_mh_len = len(cur_state.message_history)
 
@@ -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)
+        _rcv_args_batch: Sequence[InT] | None = None
+        if rcv_message is not None:
+            _rcv_args_batch = rcv_message.payloads
+        elif rcv_args is not None:
+            _rcv_args_batch = rcv_args if isinstance(rcv_args, Sequence) else [rcv_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,
+            rcv_args_batch=_rcv_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)
@@ -285,7 +311,7 @@ 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,
                 sys_args=sys_args,

{grasp_agents-0.2.3 → grasp_agents-0.2.4}/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.4}/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.4}/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.4}/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.4}/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.4}/src/grasp_agents/prompt_builder.py

@@ -118,13 +118,13 @@ 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]:
+    ) -> Sequence[UserMessage]:
         return [
             UserMessage.from_text(
                 self._rcv_args_type_adapter.dump_json(
@@ -173,28 +173,28 @@ class PromptBuilder(AutoInstanceAttributesMixin, Generic[InT, CtxT]):
 
     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,
         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:
@@ -208,6 +208,7 @@ class PromptBuilder(AutoInstanceAttributesMixin, Generic[InT, CtxT]):
                 rcv_args_batch=rcv_args_batch,
                 ctx=ctx,
             )
+
         return []
 
     def _make_batched(

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

@@ -32,7 +32,7 @@ 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
     sys_args: SystemRunArgs | None = None

{grasp_agents-0.2.3 → grasp_agents-0.2.4}/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.4}/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.4}/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.4}/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,8 +79,9 @@ 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_args: InT | Sequence[InT] | None = None,
         rcv_message: AgentMessage[InT, Any] | None = None,
         ctx: RunContextWrapper[CtxT] | None = None,
         entry_point: bool = False,
@@ -93,7 +95,8 @@ class LoopedWorkflowAgent(WorkflowAgent[InT, OutT, CtxT], Generic[InT, OutT, Ctx
         while True:
             for subagent in self.subagents:
                 agent_message = await subagent.run(
-                    inp_items=inp_items,
+                    chat_inputs=chat_inputs,
+                    rcv_args=rcv_args,
                     rcv_message=agent_message,
                     entry_point=entry_point,
                     forbid_state_change=forbid_state_change,
@@ -112,5 +115,6 @@ class LoopedWorkflowAgent(WorkflowAgent[InT, OutT, CtxT], Generic[InT, OutT, Ctx
                         )
                         return exit_message
 
-                inp_items = None
+                chat_inputs = None
+                rcv_args = None
                 entry_point = False

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

@@ -36,8 +36,9 @@ 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_args: InT | Sequence[InT] | None = None,
         rcv_message: AgentMessage[InT, Any] | None = None,
         ctx: RunContextWrapper[CtxT] | None = None,
         entry_point: bool = False,
@@ -47,14 +48,16 @@ class SequentialWorkflowAgent(WorkflowAgent[InT, OutT, CtxT], Generic[InT, OutT,
         agent_message = rcv_message
         for subagent in self.subagents:
             agent_message = await subagent.run(
-                inp_items=inp_items,
+                chat_inputs=chat_inputs,
+                rcv_args=rcv_args,
                 rcv_message=agent_message,
                 entry_point=entry_point,
                 forbid_state_change=forbid_state_change,
                 ctx=ctx,
                 **kwargs,
             )
-            inp_items = None
+            chat_inputs = None
+            rcv_args = None
             entry_point = False
 
         return cast("AgentMessage[OutT, Any]", agent_message)

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

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