ogx_open_client 1.0.3.dev0__py3-none-any.whl

ogx_client/lib/agents/react/tool_parser.py

@@ -0,0 +1,59 @@
+# 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 json
+import uuid
+
+from pydantic import BaseModel, ValidationError
+
+from ..tool_parser import ToolParser
+from ..types import CompletionMessage, ToolCall
+
+
+class Param(BaseModel):
+    name: str
+    value: str | int | float | bool
+
+
+class Action(BaseModel):
+    tool_name: str
+    tool_params: list[Param]
+
+
+class ReActOutput(BaseModel):
+    thought: str
+    action: Action | None
+    answer: str | None
+
+
+class ReActToolParser(ToolParser):
+    def get_tool_calls(self, output_message: CompletionMessage) -> list[ToolCall]:
+        tool_calls = []
+        response_text = str(output_message.content)
+        try:
+            react_output = ReActOutput.model_validate_json(response_text)
+        except ValidationError as e:
+            print(f"Error parsing action: {e}")
+            return tool_calls
+
+        if react_output.answer:
+            return tool_calls
+
+        if react_output.action:
+            tool_name = react_output.action.tool_name
+            tool_params = react_output.action.tool_params
+            params = {param.name: param.value for param in tool_params}
+            if tool_name and tool_params:
+                call_id = str(uuid.uuid4())
+                tool_calls = [
+                    ToolCall(
+                        call_id=call_id,
+                        tool_name=tool_name,
+                        arguments=json.dumps(params),
+                    )
+                ]
+
+        return tool_calls

ogx_client/lib/agents/tool_parser.py

@@ -0,0 +1,42 @@
+# 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.
+
+from abc import abstractmethod
+
+from .types import CompletionMessage, ToolCall
+
+
+class ToolParser:
+    """
+    Abstract base class for parsing agent responses into tool calls. Implement this class to customize how
+    agent outputs are processed and transformed into executable tool calls.
+
+    To use this class:
+    1. Create a subclass of ToolParser
+    2. Implement the `get_tool_calls` method
+    3. Pass your parser instance to the Agent's constructor
+
+    Example:
+        class MyCustomParser(ToolParser):
+            def get_tool_calls(self, output_message: CompletionMessage) -> list[ToolCall]:
+                # Add your custom parsing logic here
+                return extracted_tool_calls
+
+    Methods:
+        get_tool_calls(output_message: CompletionMessage) -> list[ToolCall]:
+            Abstract method that must be implemented by subclasses to process
+            the agent's response and extract tool calls.
+
+            Args:
+                output_message (CompletionMessage): The response message from agent turn
+
+            Returns:
+                list[ToolCall] | None: A list of parsed tool calls, or None if no tools should be called
+    """
+
+    @abstractmethod
+    def get_tool_calls(self, output_message: CompletionMessage) -> list[ToolCall]:
+        raise NotImplementedError

ogx_client/lib/agents/turn_events.py

@@ -0,0 +1,268 @@
+# 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.
+
+"""High-level turn and step events for agent interactions.
+
+This module defines the semantic event model that wraps the lower-level
+responses API stream events. It provides a turn/step conceptual model that
+makes agent interactions easier to understand and work with.
+
+Key concepts:
+- Turn: A complete interaction loop that may span multiple responses
+- Step: A distinct phase within a turn (inference or tool_execution)
+- Delta: Incremental updates during step execution
+- Result: Complete output when a step finishes
+"""
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from .types import ToolCall
+
+__all__ = [
+    "TurnStarted",
+    "TurnCompleted",
+    "TurnFailed",
+    "StepStarted",
+    "StepProgress",
+    "StepCompleted",
+    "TextDelta",
+    "ToolCallIssuedDelta",
+    "ToolCallDelta",
+    "ToolCallCompletedDelta",
+    "StepDelta",
+    "InferenceStepResult",
+    "ToolExecutionStepResult",
+    "StepResult",
+    "AgentEvent",
+    "AgentStreamChunk",
+]
+
+
+# ============= Turn-Level Events =============
+
+
+@dataclass
+class TurnStarted:
+    """Emitted when agent begins processing user input.
+
+    This marks the beginning of a complete interaction cycle that may
+    involve multiple inference steps and tool executions.
+    """
+
+    turn_id: str
+    session_id: str
+    event_type: Literal["turn_started"] = "turn_started"
+
+
+@dataclass
+class TurnCompleted:
+    """Emitted when agent finishes with final answer.
+
+    This marks the end of a turn when the model has produced a final
+    response without any pending client-side tool calls.
+    """
+
+    turn_id: str
+    session_id: str
+    final_text: str
+    response_ids: list[str]  # All response IDs involved in this turn
+    num_steps: int
+    event_type: Literal["turn_completed"] = "turn_completed"
+
+
+@dataclass
+class TurnFailed:
+    """Emitted if turn processing fails.
+
+    This indicates an unrecoverable error during turn processing.
+    """
+
+    turn_id: str
+    session_id: str
+    error_message: str
+    event_type: Literal["turn_failed"] = "turn_failed"
+
+
+# ============= Step-Level Events =============
+
+
+@dataclass
+class StepStarted:
+    """Emitted when a distinct work phase begins.
+
+    Steps represent distinct phases of work within a turn:
+    - inference: Model thinking/generation (deciding what to do)
+    - tool_execution: Tool execution (server-side or client-side)
+    """
+
+    step_id: str
+    step_type: Literal["inference", "tool_execution"]
+    turn_id: str
+    event_type: Literal["step_started"] = "step_started"
+    metadata: dict[str, Any] | None = None  # e.g., {"server_side": True/False, "tool_type": "file_search"}
+
+
+# ============= Progress Delta Types =============
+
+
+@dataclass
+class TextDelta:
+    """Incremental text during inference.
+
+    Emitted as the model generates text token by token.
+    """
+
+    text: str
+    delta_type: Literal["text"] = "text"
+
+
+@dataclass
+class ToolCallIssuedDelta:
+    """Model initiates a tool call (client or server-side).
+
+    This is emitted when the model decides to call a tool. The tool_type
+    field indicates whether this is:
+    - "function": Client-side tool requiring client execution
+    - Other types: Server-side tools executed within the response
+    """
+
+    call_id: str
+    tool_type: Literal["function", "file_search", "web_search", "mcp_call", "mcp_list_tools", "memory_retrieval"]
+    tool_name: str
+    arguments: str  # JSON string
+    delta_type: Literal["tool_call_issued"] = "tool_call_issued"
+
+
+@dataclass
+class ToolCallDelta:
+    """Incremental tool call arguments (streaming).
+
+    Emitted as the model streams tool call arguments. The arguments
+    are accumulated over multiple deltas to form the complete JSON.
+    """
+
+    call_id: str
+    arguments_delta: str
+    delta_type: Literal["tool_call_delta"] = "tool_call_delta"
+
+
+@dataclass
+class ToolCallCompletedDelta:
+    """Server-side tool execution completed.
+
+    Emitted when a server-side tool (file_search, web_search, etc.)
+    finishes execution. The result field contains the tool output.
+
+    Note: Client-side function tools do NOT emit this event; instead
+    they trigger a separate tool_execution step.
+    """
+
+    call_id: str
+    tool_type: Literal["file_search", "web_search", "mcp_call", "mcp_list_tools", "memory_retrieval"]
+    tool_name: str
+    result: Any  # Tool execution result from server
+    delta_type: Literal["tool_call_completed"] = "tool_call_completed"
+
+
+# Union of all delta types
+StepDelta = TextDelta | ToolCallIssuedDelta | ToolCallDelta | ToolCallCompletedDelta
+
+
+@dataclass
+class StepProgress:
+    """Emitted during step execution with streaming updates.
+
+    Progress events provide real-time updates as a step executes,
+    including text deltas and tool call information.
+    """
+
+    step_id: str
+    step_type: Literal["inference", "tool_execution"]
+    turn_id: str
+    delta: StepDelta
+    event_type: Literal["step_progress"] = "step_progress"
+
+
+# ============= Step Result Types =============
+
+
+@dataclass
+class InferenceStepResult:
+    """Complete inference step output.
+
+    This contains the final accumulated state after an inference step
+    completes. It separates client-side function calls (which need
+    client execution) from server-side tool executions (which are
+    included for logging/reference only).
+    """
+
+    step_id: str
+    response_id: str
+    text_content: str
+    function_calls: list[ToolCall]  # Client-side function calls that need execution
+    server_tool_executions: list[dict[str, Any]]  # Server-side tool calls (for reference/logging)
+    stop_reason: str
+
+
+@dataclass
+class ToolExecutionStepResult:
+    """Complete tool execution step output (client-side only).
+
+    This contains the results of executing client-side function tools.
+    These results will be fed back to the model in the next inference step.
+    """
+
+    step_id: str
+    tool_calls: list[ToolCall]  # Function calls executed
+    tool_responses: list[dict[str, Any]]  # Normalized responses
+
+
+# Union of all result types
+StepResult = InferenceStepResult | ToolExecutionStepResult
+
+
+@dataclass
+class StepCompleted:
+    """Emitted when a step finishes.
+
+    This provides the complete result of the step execution, including
+    all accumulated data and final state.
+    """
+
+    step_id: str
+    step_type: Literal["inference", "tool_execution"]
+    turn_id: str
+    result: StepResult
+    event_type: Literal["step_completed"] = "step_completed"
+
+
+# ============= Unified Event Type =============
+
+
+# Union of all event types
+AgentEvent = TurnStarted | StepStarted | StepProgress | StepCompleted | TurnCompleted | TurnFailed
+
+
+@dataclass
+class AgentStreamChunk:
+    """What the agent yields to users.
+
+    This is the top-level container for streaming events. Each chunk
+    contains a high-level event (turn or step) and optionally the
+    final response payload when the turn completes.
+
+    Usage:
+        for chunk in agent.create_turn(messages, session_id, stream=True):
+            if isinstance(chunk.event, StepProgress):
+                if isinstance(chunk.event.delta, TextDelta):
+                    print(chunk.event.delta.text, end="")
+            elif isinstance(chunk.event, TurnCompleted):
+                print(f"\\nDone! Response: {chunk.response}")
+    """
+
+    event: AgentEvent
+    response: Any | None = None  # Only set on TurnCompleted

ogx_client/lib/agents/types.py

@@ -0,0 +1,63 @@
+# 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.
+
+"""Lightweight agent-facing types that avoid ogx SDK dependencies."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol, TypedDict
+
+
+@dataclass
+class ToolCall:
+    """Minimal representation of an issued tool call."""
+
+    call_id: str
+    tool_name: str
+    arguments: str
+
+
+@dataclass
+class ToolResponse:
+    """Payload returned from executing a client-side tool."""
+
+    call_id: str
+    tool_name: str
+    content: Any
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class CompletionMessage:
+    """Synthetic completion message mirroring the OpenAI Responses schema."""
+
+    role: str
+    content: Any
+    tool_calls: list[ToolCall]
+    stop_reason: str
+
+
+Message = CompletionMessage
+
+
+class ToolDefinition(TypedDict, total=False):
+    """Definition object passed to the Responses API when registering tools."""
+
+    type: str
+    name: str
+    description: str
+    parameters: dict[str, Any]
+
+
+class FunctionTool(Protocol):
+    """Protocol describing the minimal surface area we expect from tools."""
+
+    def get_name(self) -> str: ...
+
+    def get_description(self) -> str: ...
+
+    def get_input_schema(self) -> dict[str, Any]: ...

ogx_client/lib/cli/__init__.py

@@ -0,0 +1,12 @@
+# 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.
+
+# Ignore tqdm experimental warning
+import warnings
+
+from tqdm import TqdmExperimentalWarning
+
+warnings.filterwarnings("ignore", category=TqdmExperimentalWarning)

ogx_client/lib/cli/common/__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_client/lib/cli/common/utils.py

@@ -0,0 +1,54 @@
+# 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.
+from functools import wraps
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+
+def create_bar_chart(data, labels, title=""):
+    """Create a bar chart using Rich Table."""
+
+    console = Console()
+    table = Table(title=title)
+    table.add_column("Score")
+    table.add_column("Count")
+
+    max_value = max(data)
+    total_count = sum(data)
+
+    # Define a list of colors to cycle through
+    colors = ["green", "blue", "red", "yellow", "magenta", "cyan"]
+
+    for i, (label, value) in enumerate(zip(labels, data, strict=False)):
+        bar_length = int((value / max_value) * 20)  # Adjust bar length as needed
+        bar = "█" * bar_length + " " * (20 - bar_length)
+        color = colors[i % len(colors)]
+        table.add_row(label, f"[{color}]{bar}[/] {value}/{total_count}")
+
+    console.print(table)
+
+
+def handle_client_errors(operation_name):
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            try:
+                return func(*args, **kwargs)
+            except Exception as e:
+                console = Console()
+                console.print(
+                    Panel.fit(
+                        f"[bold red]Failed to {operation_name}[/bold red]\n\n"
+                        f"[yellow]Error Type:[/yellow] {e.__class__.__name__}\n"
+                        f"[yellow]Details:[/yellow] {str(e)}"
+                    )
+                )
+
+        return wrapper
+
+    return decorator

ogx_client/lib/cli/configure.py

@@ -0,0 +1,68 @@
+# 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 os
+from urllib.parse import urlparse
+
+import click
+import yaml
+from prompt_toolkit import prompt
+from prompt_toolkit.validation import Validator
+
+from .constants import OGX_CLIENT_CONFIG_DIR, get_config_file_path
+
+
+def get_config():
+    config_file = get_config_file_path()
+    if config_file.exists():
+        with open(config_file) as f:
+            return yaml.safe_load(f)
+    return None
+
+
+@click.command()
+@click.help_option("-h", "--help")
+@click.option("--endpoint", type=str, help="OGX distribution endpoint", default="")
+@click.option("--api-key", type=str, help="OGX distribution API key", default="")
+def configure(endpoint: str | None, api_key: str | None):
+    """Configure OGX Client CLI."""
+    os.makedirs(OGX_CLIENT_CONFIG_DIR, exist_ok=True)
+    config_path = get_config_file_path()
+
+    if endpoint != "":
+        final_endpoint = endpoint
+    else:
+        final_endpoint = prompt(
+            "> Enter the endpoint of the OGX distribution server: ",
+            validator=Validator.from_callable(
+                lambda x: len(x) > 0 and (parsed := urlparse(x)).scheme and parsed.netloc,
+                error_message="Endpoint cannot be empty and must be a valid URL, please enter a valid endpoint",
+            ),
+        )
+
+    if api_key != "":
+        final_api_key = api_key
+    else:
+        final_api_key = prompt(
+            "> Enter the API key (leave empty if no key is needed): ",
+        )
+
+    # Prepare config dict before writing it
+    config_dict = {
+        "endpoint": final_endpoint,
+    }
+    if final_api_key != "":
+        config_dict["api_key"] = final_api_key
+
+    with open(config_path, "w") as f:
+        f.write(
+            yaml.dump(
+                config_dict,
+                sort_keys=True,
+            )
+        )
+
+    print(f"Done! You can now use the OGX Client CLI with endpoint {final_endpoint}")

ogx_client/lib/cli/constants.py

@@ -0,0 +1,14 @@
+# 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 os
+from pathlib import Path
+
+OGX_CLIENT_CONFIG_DIR = Path(os.path.expanduser("~/.ogx/client"))
+
+
+def get_config_file_path():
+    return OGX_CLIENT_CONFIG_DIR / "config.yaml"

ogx_client/lib/cli/datasets/__init__.py

@@ -0,0 +1,9 @@
+# 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.
+
+from .datasets import datasets
+
+__all__ = ["datasets"]

ogx_client/lib/cli/datasets/datasets.py

@@ -0,0 +1,22 @@
+# 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 click
+
+from .list import list_datasets
+from .register import register
+from .unregister import unregister
+
+
+@click.group()
+@click.help_option("-h", "--help")
+def datasets():
+    """Manage datasets."""
+
+
+# Register subcommands
+datasets.add_command(list_datasets)
+datasets.add_command(register)
+datasets.add_command(unregister)

ogx_client/lib/cli/datasets/list.py

@@ -0,0 +1,32 @@
+# 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 click
+from rich.console import Console
+from rich.table import Table
+
+from ..common.utils import handle_client_errors
+
+
+@click.command("list")
+@click.help_option("-h", "--help")
+@click.pass_context
+@handle_client_errors("list datasets")
+def list_datasets(ctx):
+    """Show available datasets on distribution endpoint"""
+    client = ctx.obj["client"]
+    console = Console()
+    headers = ["identifier", "provider_id", "metadata", "type", "purpose"]
+
+    datasets_list_response = client.datasets.list()
+    if datasets_list_response:
+        table = Table()
+        for header in headers:
+            table.add_column(header)
+
+        for item in datasets_list_response:
+            table.add_row(*[str(getattr(item, header)) for header in headers])
+        console.print(table)