ogx_open_client 1.0.3.dev0__py3-none-any.whl

ogx_open_client/lib/agents/event_synthesizer.py

@@ -0,0 +1,448 @@
+# Copyright (c) The OGX Contributors.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+"""Translate Responses API stream events into structured turn events.
+
+TurnEventSynthesizer keeps just enough state to expose turns and steps for
+agents. It consumes the raw Responses API stream and emits the higher-level
+events defined in ``turn_events.py`` without introducing an intermediate
+low-level event layer.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from logging import getLogger
+from typing import Any
+
+from .turn_events import (
+    AgentEvent,
+    InferenceStepResult,
+    StepCompleted,
+    StepProgress,
+    StepStarted,
+    TextDelta,
+    ToolCallDelta,
+    ToolCallIssuedDelta,
+    ToolExecutionStepResult,
+    TurnCompleted,
+    TurnFailed,
+    TurnStarted,
+)
+from .types import ToolCall
+
+logger = getLogger(__name__)
+
+
+@dataclass
+class _ToolCallState:
+    call_id: str
+    tool_name: str
+    tool_type: str
+    server_side: bool
+    arguments: str = ""
+
+    def update(self, *, delta: str | None = None, final: str | None = None) -> None:
+        if final is not None:
+            self.arguments = final or "{}"
+        elif delta:
+            self.arguments += delta
+
+    def as_tool_call(self) -> ToolCall:
+        payload = self.arguments or "{}"
+        return ToolCall(call_id=self.call_id, tool_name=self.tool_name, arguments=payload)
+
+
+class TurnEventSynthesizer:
+    """Produce turn/step events directly from Responses API streaming events."""
+
+    def __init__(self, session_id: str, turn_id: str):
+        self.session_id = session_id
+        self.turn_id = turn_id
+
+        self.step_counter = 0
+        self.current_step_id: str | None = None
+        self.current_step_type: str | None = None
+
+        self.current_response_id: str | None = None
+        self.text_parts: list[str] = []
+        self._function_call_ids: list[str] = []
+        self._tool_calls: dict[str, _ToolCallState] = {}
+
+        self.turn_started = False
+        self.all_response_ids: list[str] = []
+        self.last_response: Any | None = None
+
+    # ------------------------------------------------------------------ helpers
+
+    def _next_step_id(self) -> str:
+        step_id = f"{self.turn_id}_step_{self.step_counter}"
+        self.step_counter += 1
+        return step_id
+
+    def _maybe_emit_turn_started(self) -> Iterator[AgentEvent]:
+        if not self.turn_started:
+            self.turn_started = True
+            yield TurnStarted(turn_id=self.turn_id, session_id=self.session_id)
+
+    def _start_inference_step(
+        self, *, response_id: str | None = None, reset_tool_state: bool = False
+    ) -> Iterator[AgentEvent]:
+        if response_id:
+            self.current_response_id = response_id
+        if reset_tool_state:
+            self._tool_calls = {}
+        self.text_parts = []
+        self._function_call_ids = []
+        self.current_step_id = self._next_step_id()
+        self.current_step_type = "inference"
+        yield StepStarted(step_id=self.current_step_id, step_type="inference", turn_id=self.turn_id)
+
+    def _complete_inference_step(self, *, stop_reason: str, response_id: str | None = None) -> Iterator[AgentEvent]:
+        if self.current_step_type != "inference":
+            return
+        step_id = self.current_step_id or self._next_step_id()
+        resolved_response_id = response_id or self.current_response_id or ""
+        self.current_response_id = resolved_response_id
+
+        function_calls: list[ToolCall] = []
+        for call_id in self._function_call_ids:
+            state = self._tool_calls.get(call_id)
+            if state is None:
+                continue
+            function_calls.append(state.as_tool_call())
+
+        yield StepCompleted(
+            step_id=step_id,
+            step_type="inference",
+            turn_id=self.turn_id,
+            result=InferenceStepResult(
+                step_id=step_id,
+                response_id=resolved_response_id,
+                text_content="".join(self.text_parts),
+                function_calls=function_calls,
+                server_tool_executions=[],
+                stop_reason=stop_reason,
+            ),
+        )
+
+        for call_id in list(self._function_call_ids):
+            # Drop client-side call state once we hand it back to the agent.
+            self._tool_calls.pop(call_id, None)
+        self._function_call_ids = []
+        self.text_parts = []
+        self.current_step_id = None
+        self.current_step_type = None
+
+    def _start_tool_execution_step(self, call_state: _ToolCallState) -> Iterator[AgentEvent]:
+        self.current_step_id = self._next_step_id()
+        self.current_step_type = "tool_execution"
+        yield StepStarted(
+            step_id=self.current_step_id,
+            step_type="tool_execution",
+            turn_id=self.turn_id,
+            metadata={"server_side": True, "tool_type": call_state.tool_type, "tool_name": call_state.tool_name},
+        )
+        yield StepProgress(
+            step_id=self.current_step_id,
+            step_type="tool_execution",
+            turn_id=self.turn_id,
+            delta=ToolCallIssuedDelta(
+                call_id=call_state.call_id,
+                tool_type=call_state.tool_type,  # type: ignore[arg-type]
+                tool_name=call_state.tool_name,
+                arguments=call_state.arguments or "{}",
+            ),
+        )
+
+    def _complete_tool_execution_step(self, call_state: _ToolCallState) -> Iterator[AgentEvent]:
+        if self.current_step_type != "tool_execution":
+            return
+        step_id = self.current_step_id or self._next_step_id()
+        yield StepCompleted(
+            step_id=step_id,
+            step_type="tool_execution",
+            turn_id=self.turn_id,
+            result=ToolExecutionStepResult(
+                step_id=step_id,
+                tool_calls=[call_state.as_tool_call()],
+                tool_responses=[],
+            ),
+        )
+        self._tool_calls.pop(call_state.call_id, None)
+        self.current_step_id = None
+        self.current_step_type = None
+
+    @staticmethod
+    def _coerce_arguments(payload: Any) -> str | None:
+        if payload is None:
+            return None
+        if isinstance(payload, str):
+            return payload
+        try:
+            return json.dumps(payload)
+        except Exception:  # pragma: no cover - defensive
+            return str(payload)
+
+    def _register_tool_call(
+        self,
+        *,
+        call_id: str | None,
+        tool_name: str,
+        tool_type: str,
+        arguments: str | None,
+    ) -> _ToolCallState:
+        resolved_call_id = call_id or f"{tool_name}_{len(self._tool_calls)}"
+        state = _ToolCallState(
+            call_id=resolved_call_id,
+            tool_name=tool_name,
+            tool_type=tool_type,
+            server_side=tool_type != "function",
+        )
+        if arguments:
+            state.update(final=arguments)
+        self._tool_calls[resolved_call_id] = state
+        return state
+
+    def _classify_tool_type(self, tool_name: str) -> str:
+        server_side_tools = {
+            "file_search",
+            "file_search_call",
+            "knowledge_search",
+            "web_search",
+            "web_search_call",
+            "query_from_memory",
+            "mcp_call",
+            "mcp_list_tools",
+            "memory_retrieval",
+        }
+
+        if tool_name in server_side_tools:
+            if tool_name in {"file_search_call", "knowledge_search"}:
+                return "file_search"
+            if tool_name == "web_search_call":
+                return "web_search"
+            return tool_name
+
+        return "function"
+
+    # ------------------------------------------------------------------ handlers
+
+    def process_raw_stream(self, events: Iterable[Any]) -> Iterator[AgentEvent]:
+        current_response_id: str | None = None
+
+        for event in events:
+            yield from self._maybe_emit_turn_started()
+
+            response_id = getattr(event, "response_id", None)
+            if response_id is None and hasattr(event, "response"):
+                response = event.response
+                response_id = getattr(response, "id", None)
+            if response_id is not None:
+                current_response_id = response_id
+
+            event_type = getattr(event, "type", None)
+            if not event_type:
+                logger.debug("Unhandled stream event with no type: %r", event)
+                continue
+
+            if event_type == "response.in_progress":
+                response = getattr(event, "response", None)
+                response_id = getattr(response, "id", current_response_id)
+                if response_id is None:
+                    continue
+                if not self.all_response_ids or self.all_response_ids[-1] != response_id:
+                    self.all_response_ids.append(response_id)
+                yield from self._start_inference_step(response_id=response_id, reset_tool_state=True)
+
+            elif event_type == "response.output_text.delta":
+                if self.current_step_type != "inference":
+                    continue
+                text = getattr(event, "delta", "") or ""
+                if not text:
+                    continue
+                self.text_parts.append(text)
+                yield StepProgress(
+                    step_id=self.current_step_id or "",
+                    step_type="inference",
+                    turn_id=self.turn_id,
+                    delta=TextDelta(text=text),
+                )
+
+            elif event_type == "response.output_text.done":
+                # Text completions are tracked via the final StepCompleted event.
+                continue
+
+            elif event_type == "response.output_item.added":
+                yield from self._handle_output_item_added(getattr(event, "item", None))
+
+            elif event_type == "response.output_item.delta":
+                yield from self._handle_output_item_delta(getattr(event, "delta", None))
+
+            elif event_type == "response.output_item.done":
+                yield from self._handle_output_item_done(getattr(event, "item", None))
+
+            elif event_type == "response.completed":
+                response = getattr(event, "response", None)
+                if response is not None:
+                    self.last_response = response
+                stop_reason = "tool_calls" if self._function_call_ids else "end_of_turn"
+                yield from self._complete_inference_step(stop_reason=stop_reason, response_id=current_response_id)
+
+            elif event_type == "response.failed":
+                response = getattr(event, "response", None)
+                error_obj = getattr(response, "error", None)
+                error_message = getattr(error_obj, "message", None) if error_obj else None
+                yield TurnFailed(
+                    turn_id=self.turn_id,
+                    session_id=self.session_id,
+                    error_message=error_message or "Unknown error",
+                )
+
+            else:  # pragma: no cover - depends on streaming responses
+                # Allow unknown streaming events to pass silently; they are often ancillary metadata.
+                continue
+
+    def _handle_output_item_added(self, item: Any) -> Iterator[AgentEvent]:
+        if item is None:
+            return
+        item_type = getattr(item, "type", None)
+        if item_type is None:
+            return
+
+        if item_type == "message":
+            # Messages mirror text deltas, nothing extra to emit.
+            return
+
+        if item_type in {
+            "function_call",
+            "web_search",
+            "web_search_call",
+            "mcp_call",
+            "mcp_list_tools",
+            "file_search_call",
+        }:
+            call_id = getattr(item, "call_id", None) or getattr(item, "id", None)
+            tool_name = getattr(item, "name", None) or getattr(item, "type", "")
+            arguments = self._coerce_arguments(getattr(item, "arguments", None))
+            tool_type = self._classify_tool_type(tool_name if item_type == "function_call" else item_type)
+
+            state = self._register_tool_call(
+                call_id=call_id,
+                tool_name=tool_name,
+                tool_type=tool_type,
+                arguments=arguments,
+            )
+
+            if state.server_side:
+                yield from self._complete_inference_step(
+                    stop_reason="server_tool_call", response_id=self.current_response_id
+                )
+                yield from self._start_tool_execution_step(state)
+            else:
+                if state.call_id not in self._function_call_ids:
+                    self._function_call_ids.append(state.call_id)
+                yield StepProgress(
+                    step_id=self.current_step_id or "",
+                    step_type="inference",
+                    turn_id=self.turn_id,
+                    delta=ToolCallIssuedDelta(
+                        call_id=state.call_id,
+                        tool_type="function",
+                        tool_name=state.tool_name,
+                        arguments=state.arguments or "{}",
+                    ),
+                )
+
+    def _handle_output_item_delta(self, delta: Any) -> Iterator[AgentEvent]:
+        if delta is None:
+            return
+        delta_type = getattr(delta, "type", None)
+        if delta_type not in {
+            "function_call",
+            "web_search",
+            "web_search_call",
+            "mcp_call",
+            "mcp_list_tools",
+            "file_search_call",
+        }:
+            return
+
+        call_id = getattr(delta, "call_id", None) or getattr(delta, "id", None)
+        if call_id is None:
+            return
+
+        arguments_delta = getattr(delta, "arguments_delta", None)
+        if arguments_delta is None:
+            arguments_delta = getattr(delta, "arguments", None)
+        if arguments_delta is None and isinstance(delta, dict):
+            arguments_delta = delta.get("arguments_delta") or delta.get("arguments")
+        if arguments_delta is None:
+            return
+
+        state = self._tool_calls.get(call_id)
+        if state is None:
+            return
+
+        state.update(delta=arguments_delta)
+        step_type = "tool_execution" if state.server_side else "inference"
+        yield StepProgress(
+            step_id=self.current_step_id or "",
+            step_type=step_type,  # type: ignore[arg-type]
+            turn_id=self.turn_id,
+            delta=ToolCallDelta(call_id=state.call_id, arguments_delta=arguments_delta),
+        )
+
+    def _handle_output_item_done(self, item: Any) -> Iterator[AgentEvent]:
+        if item is None:
+            return
+
+        item_type = getattr(item, "type", None)
+        if item_type not in {
+            "function_call",
+            "web_search",
+            "web_search_call",
+            "mcp_call",
+            "mcp_list_tools",
+            "file_search_call",
+        }:
+            return
+
+        call_id = getattr(item, "call_id", None) or getattr(item, "id", None)
+        if call_id is None:
+            return
+
+        state = self._tool_calls.get(call_id)
+        if state is None:
+            return
+
+        arguments = self._coerce_arguments(getattr(item, "arguments", None))
+        if arguments:
+            state.update(final=arguments)
+
+        if state.server_side:
+            yield from self._complete_tool_execution_step(state)
+            # Start a fresh inference step so the model can continue reasoning.
+            yield from self._start_inference_step()
+        else:
+            if call_id not in self._function_call_ids:
+                self._function_call_ids.append(call_id)
+
+    # ------------------------------------------------------------------ turn end
+
+    def finish_turn(self) -> Iterator[AgentEvent]:
+        if not self.last_response:
+            raise RuntimeError("Cannot finish turn without a response")
+
+        yield TurnCompleted(
+            turn_id=self.turn_id,
+            session_id=self.session_id,
+            final_text=self.last_response.output_text,
+            response_ids=self.all_response_ids,
+            num_steps=self.step_counter,
+        )

ogx_open_client/lib/agents/react/__init__.py

@@ -0,0 +1,5 @@
+# Copyright (c) The OGX Contributors.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.

ogx_open_client/lib/agents/react/agent.py

@@ -0,0 +1,94 @@
+# Copyright (c) The OGX Contributors.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+import logging
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from ...._types import Headers
+from ..agent import Agent, AgentUtils
+from ..client_tool import ClientTool
+from ..tool_parser import ToolParser
+from .prompts import DEFAULT_REACT_AGENT_SYSTEM_PROMPT_TEMPLATE
+from .tool_parser import ReActToolParser
+
+logger = logging.getLogger(__name__)
+
+
+def _tool_definition_from_mapping(tool: Mapping[str, Any]) -> dict[str, Any]:
+    name = tool.get("name") or tool.get("identifier") or tool.get("tool_name") or tool.get("type") or "tool"
+    description = tool.get("description") or tool.get("summary") or ""
+    parameters = tool.get("parameters") or tool.get("input_schema") or {}
+    return {
+        "name": str(name),
+        "description": str(description),
+        "input_schema": parameters,
+    }
+
+
+def _collect_tool_definitions(
+    server_tools: tuple[Mapping[str, Any], ...],
+    client_tools: tuple[ClientTool, ...],
+) -> list[dict[str, Any]]:
+    tool_defs = [_tool_definition_from_mapping(tool) for tool in server_tools]
+    tool_defs.extend(
+        {
+            "name": tool.get_name(),
+            "description": tool.get_description(),
+            "input_schema": tool.get_input_schema(),
+        }
+        for tool in client_tools
+    )
+    return tool_defs
+
+
+def get_default_react_instructions(tool_defs: list[dict[str, Any]]) -> str:
+    tool_names = ", ".join([definition["name"] for definition in tool_defs])
+    tool_descriptions = "\n".join(
+        [
+            f"- {definition['name']}: {definition['description'] or definition['input_schema']}"
+            for definition in tool_defs
+        ]
+    )
+    instruction = DEFAULT_REACT_AGENT_SYSTEM_PROMPT_TEMPLATE.replace("<<tool_names>>", tool_names).replace(
+        "<<tool_descriptions>>", tool_descriptions
+    )
+    return instruction
+
+
+class ReActAgent(Agent):
+    def __init__(
+        self,
+        client: Any,
+        *,
+        model: str,
+        tools: list[dict[str, Any] | ClientTool | Callable[..., Any]] | None = None,
+        tool_parser: ToolParser | None = None,
+        instructions: str | None = None,
+        extra_headers: Headers | None = None,
+        json_response_format: bool = False,
+    ):
+        if json_response_format:
+            logger.warning("`json_response_format` is deprecated and will be removed in a future release.")
+
+        if tool_parser is None:
+            tool_parser = ReActToolParser()
+
+        tool_list = tools or []
+        client_tool_instances = AgentUtils.get_client_tools(tool_list)
+        server_tool_defs = tuple(tool for tool in tool_list if isinstance(tool, Mapping))
+
+        if instructions is None:
+            tool_definitions = _collect_tool_definitions(tuple(server_tool_defs), tuple(client_tool_instances))
+            instructions = get_default_react_instructions(tool_definitions)
+
+        super().__init__(
+            client=client,
+            model=model,
+            instructions=instructions,
+            tools=tool_list,
+            tool_parser=tool_parser,
+            extra_headers=extra_headers,
+        )

ogx_open_client/lib/agents/react/prompts.py

@@ -0,0 +1,151 @@
+# Copyright (c) The OGX Contributors.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+DEFAULT_REACT_AGENT_SYSTEM_PROMPT_TEMPLATE = """
+You are an expert assistant who can solve any task using tool calls. You will be given a task to solve as best you can.
+To do so, you have been given access to the following tools: <<tool_names>>
+
+You must always respond in the following JSON format:
+{
+    "thought": $THOUGHT_PROCESS,
+    "action": {
+        "tool_name": $TOOL_NAME,
+        "tool_params": $TOOL_PARAMS
+    },
+    "answer": $ANSWER
+}
+
+Specifically, this json should have a `thought` key, a `action` key and an `answer` key.
+
+The `action` key should specify the $TOOL_NAME the name of the tool to use and the `tool_params` key should specify the parameters key as input to the tool.
+
+Make sure to have the $TOOL_PARAMS as a list of dictionaries in the right format for the tool you are using, and do not put variable names as input if you can find the right values.
+
+You should always think about one action to take, and have the `thought` key contain your thought process about this action.
+If the tool responds, the tool will return an observation containing result of the action.
+... (this Thought/Action/Observation can repeat N times, you should take several steps when needed. The action key must only use a SINGLE tool at a time.)
+
+You can use the result of the previous action as input for the next action.
+The observation will always be the response from calling the tool: it can represent a file, like "image_1.jpg". You do not need to generate them, it will be provided to you.
+Then you can use it as input for the next action. You can do it for instance as follows:
+
+Observation: "image_1.jpg"
+{
+    "thought": "I need to transform the image that I received in the previous observation to make it green.",
+    "action": {
+        "tool_name": "image_transformer",
+        "tool_params": [{"name": "image"}, {"value": "image_1.jpg"}]
+    },
+    "answer": null
+}
+
+
+To provide the final answer to the task, use the `answer` key. It is the only way to complete the task, else you will be stuck on a loop. So your final output should look like this:
+Observation: "your observation"
+
+{
+    "thought": "you thought process",
+    "action": null,
+    "answer": "insert your final answer here"
+}
+
+Here are a few examples using notional tools:
+---
+Task: "Generate an image of the oldest person in this document."
+
+Your Response:
+{
+    "thought": "I will proceed step by step and use the following tools: `document_qa` to find the oldest person in the document, then `image_generator` to generate an image according to the answer.",
+    "action": {
+        "tool_name": "document_qa",
+        "tool_params": [{"name": "document"}, {"value": "document.pdf"}, {"name": "question"}, {"value": "Who is the oldest person mentioned?"}]
+    },
+    "answer": null
+}
+
+Your Observation: "The oldest person in the document is John Doe, a 55 year old lumberjack living in Newfoundland."
+
+Your Response:
+{
+    "thought": "I will now generate an image showcasing the oldest person.",
+    "action": {
+        "tool_name": "image_generator",
+        "tool_params": [{"name": "prompt"}, {"value": "A portrait of John Doe, a 55-year-old man living in Canada."}]
+    },
+    "answer": null
+}
+Your Observation: "image.png"
+
+{
+    "thought": "I will now return the generated image.",
+    "action": null,
+    "answer": "image.png"
+}
+
+---
+Task: "What is the result of the following operation: 5 + 3 + 1294.678?"
+
+Your Response:
+{
+    "thought": "I will use python code evaluator to compute the result of the operation and then return the final answer using the `final_answer` tool",
+    "action": {
+        "tool_name": "python_interpreter",
+        "tool_params": [{"name": "code"}, {"value": "5 + 3 + 1294.678"}]
+    },
+    "answer": null
+}
+Your Observation: 1302.678
+
+{
+    "thought": "Now that I know the result, I will now return it.",
+    "action": null,
+    "answer": 1302.678
+}
+
+---
+Task: "Which city has the highest population , Guangzhou or Shanghai?"
+
+Your Response:
+{
+    "thought": "I need to get the populations for both cities and compare them: I will use the tool `search` to get the population of both cities.",
+    "action": {
+        "tool_name": "search",
+        "tool_params": [{"name": "query"}, {"value": "Population Guangzhou"}]
+    },
+    "answer": null
+}
+Your Observation: ['Guangzhou has a population of 15 million inhabitants as of 2021.']
+
+Your Response:
+{
+    "thought": "Now let's get the population of Shanghai using the tool 'search'.",
+    "action": {
+        "tool_name": "search",
+        "tool_params": [{"name": "query"}, {"value": "Population Shanghai"}]
+    },
+    "answer": null
+}
+Your Observation: "26 million (2019)"
+
+Your Response:
+{
+    "thought": "Now I know that Shanghai has a larger population. Let's return the result.",
+    "action": null,
+    "answer": "Shanghai"
+}
+
+Above example were using notional tools that might not exist for you. You only have access to these tools:
+<<tool_descriptions>>
+
+Here are the rules you should always follow to solve your task:
+1. ALWAYS answer in the JSON format with keys "thought", "action", "answer", else you will fail.
+2. Always use the right arguments for the tools. Never use variable names in the 'tool_params' field, use the value instead.
+3. Call a tool only when needed: do not call the search agent if you do not need information, try to solve the task yourself.
+4. Never re-do a tool call that you previously did with the exact same parameters.
+5. Observations will be provided to you, no need to generate them
+
+Now Begin! If you solve the task correctly, you will receive a reward of $1,000,000.
+"""