openhands 0.0.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

openhands/sdk/tool/tool.py

@@ -1,142 +0,0 @@
-from typing import Any, Generic, TypeVar
-
-from litellm import ChatCompletionToolParam, ChatCompletionToolParamFunctionChunk
-from pydantic import BaseModel, Field
-
-from openhands.sdk.tool.schema import ActionBase, ObservationBase
-
-
-ActionT = TypeVar("ActionT", bound=ActionBase)
-ObservationT = TypeVar("ObservationT", bound=ObservationBase)
-
-
-class ToolAnnotations(BaseModel):
-    """Annotations to provide hints about the tool's behavior.
-
-    Based on Model Context Protocol (MCP) spec:
-    https://github.com/modelcontextprotocol/modelcontextprotocol/blob/caf3424488b10b4a7b1f8cb634244a450a1f4400/schema/2025-06-18/schema.ts#L838
-    """
-
-    title: str | None = Field(
-        default=None, description="A human-readable title for the tool."
-    )
-    readOnlyHint: bool = Field(
-        default=False,
-        description="If true, the tool does not modify its environment. Default: false",
-    )
-    destructiveHint: bool = Field(
-        default=True,
-        description="If true, the tool may perform destructive updates to its environment. If false, the tool performs only additive updates. (This property is meaningful only when `readOnlyHint == false`) Default: true",  # noqa: E501
-    )
-    idempotentHint: bool = Field(
-        default=False,
-        description="If true, calling the tool repeatedly with the same arguments will have no additional effect on the its environment. (This property is meaningful only when `readOnlyHint == false`) Default: false",  # noqa: E501
-    )
-    openWorldHint: bool = Field(
-        default=True,
-        description="If true, this tool may interact with an 'open world' of external entities. If false, the tool's domain of interaction is closed. For example, the world of a web search tool is open, whereas that of a memory tool is not. Default: true",  # noqa: E501
-    )
-
-
-class ToolExecutor(Generic[ActionT, ObservationT]):
-    """Executor function type for a Tool."""
-
-    def __call__(self, action: ActionT) -> ObservationT:
-        raise NotImplementedError
-
-
-class Tool(Generic[ActionT, ObservationT]):
-    """Tool that wraps an executor function with input/output validation and schema.
-
-    - Normalize input/output schemas (class or dict) into both model+schema.
-    - Validate inputs before execute.
-    - Coerce outputs only if an output model is defined; else return vanilla JSON.
-    - Export MCP tool description.
-    """
-
-    def __init__(
-        self,
-        *,
-        name: str,
-        description: str,
-        input_schema: type[ActionBase],
-        output_schema: type[ObservationBase] | None = None,
-        title: str | None = None,
-        annotations: ToolAnnotations | None = None,
-        _meta: dict[str, Any] | None = None,
-        executor: ToolExecutor | None = None,
-    ):
-        self.name = name
-        self.description = description
-        self.annotations = annotations
-        self._meta = _meta
-        self.title = title or name
-
-        # Schemas
-        self.action_type: type[ActionBase] = input_schema
-        self.input_schema: dict[str, Any] = input_schema.to_mcp_schema()
-        self.observation_type: type[ObservationBase] | None = output_schema
-        self.output_schema: dict[str, Any] | None = (
-            output_schema.to_mcp_schema() if output_schema else None
-        )
-
-        self.executor = executor
-
-    def set_executor(self, executor: ToolExecutor) -> "Tool":
-        """Set or replace the executor function."""
-        self.executor = executor
-        return self
-
-    def call(self, action: ActionT) -> ObservationBase:
-        """Validate input, execute, and coerce output.
-
-        We always return some ObservationBase subclass, but not always the
-        generic ObservationT.
-        """
-        if self.executor is None:
-            raise NotImplementedError(f"Tool '{self.name}' has no executor")
-
-        # Execute
-        result = self.executor(action)
-
-        # Coerce output only if we declared a model; else wrap in base ObservationBase
-        if self.observation_type:
-            if isinstance(result, self.observation_type):
-                return result
-            return self.observation_type.model_validate(result)
-        else:
-            # When no output schema is defined, wrap the result in ObservationBase
-            if isinstance(result, ObservationBase):
-                return result
-            elif isinstance(result, BaseModel):
-                return ObservationBase.model_validate(result.model_dump())
-            elif isinstance(result, dict):
-                return ObservationBase.model_validate(result)
-            raise TypeError(
-                "Output must be dict or BaseModel when no output schema is defined"
-            )
-
-    def to_mcp_tool(self) -> dict[str, Any]:
-        out = {
-            "name": self.name,
-            "description": self.description,
-            "inputSchema": self.input_schema,
-        }
-        if self.annotations:
-            out["annotations"] = self.annotations
-        if self._meta is not None:
-            out["_meta"] = self._meta
-        if self.output_schema:
-            out["outputSchema"] = self.output_schema
-        return out
-
-    def to_openai_tool(self) -> ChatCompletionToolParam:
-        """Convert an MCP tool to an OpenAI tool."""
-        return ChatCompletionToolParam(
-            type="function",
-            function=ChatCompletionToolParamFunctionChunk(
-                name=self.name,
-                description=self.description,
-                parameters=self.input_schema,
-            ),
-        )

openhands/sdk/utils/__init__.py

@@ -1,14 +0,0 @@
-"""Utility functions for the OpenHands SDK."""
-
-from .truncate import (
-    DEFAULT_TEXT_CONTENT_LIMIT,
-    DEFAULT_TRUNCATE_NOTICE,
-    maybe_truncate,
-)
-
-
-__all__ = [
-    "DEFAULT_TEXT_CONTENT_LIMIT",
-    "DEFAULT_TRUNCATE_NOTICE",
-    "maybe_truncate",
-]

openhands/sdk/utils/discriminated_union.py

@@ -1,210 +0,0 @@
-"""Utility for creating and managing discriminated unions of Pydantic models.
-
-Pydantic provides native support for disciriminated unions via the `Union` type and
-the `discriminator` argument to `Field`. However, this requires that all possible
-types in the union be known at the time the field is defined. This can be limiting
-in scenarios where new types may be defined later.
-
-To address this, we provide a `DiscriminatedUnionMixin` base class that models can
-inherit from to automatically register themselves as part of a discriminated union.
-We also provide a `DiscriminatedUnionType` type wrapper that can be used in Pydantic
-models to indicate that a field should be treated as a discriminated union of all
-subclasses of a given base class.
-
-Importantly, this approach allows us to _delay_ the resolution of the union types
-until validation time, meaning that new subclasses can be defined and registered
-at any time before validation occurs.
-
-Example usage:
-
-    from typing import Annotated
-    from pydantic import BaseModel
-
-    from openhands.sdk.utils.discriminated_union import (
-        DiscriminatedUnionMixin,
-        DiscriminatedUnionType
-    )
-
-    # The base class for the union is tagged with DiscriminatedUnionMixin
-    class Animal(BaseModel, DiscriminatedUnionMixin):
-        name: str
-
-    # We develop a special type to represent the discriminated union of all Animals.
-    # This acts just like Animal, but the annotation tells Pydantic to treat it as a
-    # discriminated union of all subclasses of Animal (defined so far or in the future).
-    AnyAnimal = Annotated[Animal, DiscriminatedUnionType[Animal]]
-
-    class Dog(Animal):
-        breed: str
-
-    class Cat(Animal):
-        color: str
-
-    class Zoo(BaseModel):
-        residents: list[AnyAnimal]
-
-    # Even animals defined after the Zoo class can be included without issue
-    class Mouse(Animal):
-        size: str
-
-    zoo = Zoo(residents=[
-        Dog(name="Fido", breed="Labrador"),
-        Cat(name="Whiskers", color="Tabby"),
-        Mouse(name="Jerry", size="Small")
-    ])
-
-    serialized_zoo = zoo.model_dump_json()
-    deserialized_zoo = Zoo.model_validate_json(serialized_zoo)
-
-    assert zoo == deserialized_zoo
-"""
-
-from __future__ import annotations
-
-from typing import Any, Generic, TypeVar, cast
-
-from pydantic import BaseModel, computed_field
-from pydantic_core import core_schema
-
-
-T = TypeVar("T", bound="DiscriminatedUnionMixin")
-
-
-class DiscriminatedUnionMixin(BaseModel):
-    """A Base class for members of tagged unions discriminated by the class name.
-
-    This class provides automatic subclass registration and discriminated union
-    functionality. Each subclass is automatically registered when defined and
-    can be used for polymorphic serialization/deserialization.
-
-    Child classes will automatically have a type field defined, which is used as a
-    discriminator for union types.
-    """
-
-    @computed_field  # type: ignore
-    @property
-    def kind(self) -> str:
-        """Property to create kind field from class name when serializing."""
-        return f"{self.__class__.__module__}.{self.__class__.__qualname__}"
-
-    @classmethod
-    def target_subclass(cls, kind: str) -> type[DiscriminatedUnionMixin] | None:
-        """Get the subclass corresponding to a given kind name."""
-        worklist = [cls]
-        while worklist:
-            current = worklist.pop()
-            if f"{current.__module__}.{current.__qualname__}" == kind:
-                return current
-            worklist.extend(current.__subclasses__())
-        return None
-
-    @classmethod
-    def model_validate(
-        cls: type[T],
-        obj: Any,
-        *,
-        strict=None,
-        from_attributes=None,
-        context=None,
-        **kwargs,
-    ) -> T:
-        """Custom model validation using registered subclasses for deserialization."""
-        # If we have a 'kind' field but no discriminated union handling,
-        # we still need to remove it to avoid extra field errors
-        if isinstance(obj, dict) and "kind" in obj:
-            kind = obj.get("kind")
-            assert isinstance(kind, str)
-            obj_without_kind = {k: v for k, v in obj.items() if k != "kind"}
-            if (target_class := cls.target_subclass(kind)) is not None:
-                return cast(
-                    T,
-                    target_class.model_validate(
-                        obj_without_kind,
-                        strict=strict,
-                        from_attributes=from_attributes,
-                        context=context,
-                        **kwargs,
-                    ),
-                )
-
-        # Fallback to default validation
-        return cast(
-            T,
-            super().model_validate(
-                obj,
-                strict=strict,
-                from_attributes=from_attributes,
-                context=context,
-                **kwargs,
-            ),
-        )
-
-    @classmethod
-    def model_validate_json(
-        cls: type[T],
-        json_data: str | bytes | bytearray,
-        *,
-        strict=None,
-        context=None,
-        **kwargs,
-    ) -> T:
-        """Custom JSON validation that uses our custom model_validate method."""
-        import json
-
-        # Parse JSON to dict first
-        if isinstance(json_data, bytes):
-            json_data = json_data.decode("utf-8")
-
-        obj = json.loads(json_data)
-
-        # Use our custom model_validate method
-        return cls.model_validate(
-            obj,
-            strict=strict,
-            context=context,
-            **kwargs,
-        )
-
-
-class DiscriminatedUnionType(Generic[T]):
-    """A type wrapper that enables discriminated union validation for Pydantic fields.
-
-    The wrapped type must be a subclass of `DiscriminatedUnionMixin`.
-    """
-
-    def __init__(self, cls: type[T]):
-        self.base_class = cls
-        self.__origin__ = cls
-        self.__args__ = ()
-
-    def __get_pydantic_core_schema__(self, source_type, handler):
-        """Define custom Pydantic core schema for this type.
-
-        This schema uses a custom validator function to handle discriminated union
-        deserialization based on the 'kind' field.
-        """
-
-        # Importantly, this validation function calls the base class model validation
-        # _at validation time_, meaning that even if new subclasses are registered after
-        # the fact they will still be recognized.
-        def validate(v):
-            if isinstance(v, self.base_class):
-                return v
-            if isinstance(v, dict) and "kind" in v:
-                return self.base_class.model_validate(v)
-            return self.base_class(**v)
-
-        return core_schema.no_info_plain_validator_function(validate)
-
-    def __repr__(self):
-        return f"DiscriminatedUnion[{self.base_class.__name__}]"
-
-    def __class_getitem__(cls, params):
-        """Support type-style subscript syntax like DiscriminatedUnionType[cls]."""
-        return cls(params)
-
-    def __instancecheck__(self, instance):
-        return isinstance(instance, self.base_class)
-
-    def __subclasscheck__(self, subclass):
-        return issubclass(subclass, self.base_class)

openhands/sdk/utils/json.py

@@ -1,48 +0,0 @@
-import json
-from datetime import datetime
-from typing import Any
-
-from litellm.types.utils import ModelResponse
-
-from openhands.sdk.llm.exceptions import LLMResponseError
-from openhands.sdk.llm.utils.metrics import Metrics
-
-
-class OpenHandsJSONEncoder(json.JSONEncoder):
-    """Custom JSON encoder that handles datetime and other OH objects"""
-
-    def default(self, o: object) -> Any:
-        if isinstance(o, datetime):
-            return o.isoformat()
-        if isinstance(o, Metrics):
-            return o.get()
-        if isinstance(o, ModelResponse):
-            return o.model_dump()
-        return super().default(o)
-
-
-# Create a single reusable encoder instance
-_json_encoder = OpenHandsJSONEncoder()
-
-
-def dumps(obj, **kwargs):
-    """Serialize an object to str format"""
-    if not kwargs:
-        return _json_encoder.encode(obj)
-
-    # Create a copy of the kwargs to avoid modifying the original
-    encoder_kwargs = kwargs.copy()
-
-    # If cls is specified, use it; otherwise use our custom encoder
-    if "cls" not in encoder_kwargs:
-        encoder_kwargs["cls"] = OpenHandsJSONEncoder
-
-    return json.dumps(obj, **encoder_kwargs)
-
-
-def loads(json_str, **kwargs):
-    """Create a JSON object from str"""
-    try:
-        return json.loads(json_str, **kwargs)
-    except json.JSONDecodeError:
-        raise LLMResponseError("No valid JSON object found in response.")

openhands/sdk/utils/truncate.py

@@ -1,44 +0,0 @@
-"""Utility functions for truncating text content."""
-
-# Default truncation limits
-DEFAULT_TEXT_CONTENT_LIMIT = 50_000
-
-# Default truncation notice
-DEFAULT_TRUNCATE_NOTICE = (
-    "<response clipped><NOTE>Due to the max output limit, only part of the full "
-    "response has been shown to you.</NOTE>"
-)
-
-
-def maybe_truncate(
-    content: str,
-    truncate_after: int | None = None,
-    truncate_notice: str = DEFAULT_TRUNCATE_NOTICE,
-) -> str:
-    """
-    Truncate the middle of content if it exceeds the specified length.
-
-    Keeps the head and tail of the content to preserve context at both ends.
-
-    Args:
-        content: The text content to potentially truncate
-        truncate_after: Maximum length before truncation. If None, no truncation occurs
-        truncate_notice: Notice to insert in the middle when content is truncated
-
-    Returns:
-        Original content if under limit, or truncated content with head and tail
-        preserved
-    """
-    if not truncate_after or len(content) <= truncate_after or truncate_after < 0:
-        return content
-
-    # Calculate how much space we have for actual content
-    available_chars = truncate_after - len(truncate_notice)
-    half = available_chars // 2
-
-    # Give extra character to head if odd number
-    head_chars = half + (available_chars % 2)
-    tail_chars = half
-
-    # Keep head and tail, insert notice in the middle
-    return content[:head_chars] + truncate_notice + content[-tail_chars:]

openhands/tools/__init__.py

@@ -1,44 +0,0 @@
-"""Runtime tools package."""
-
-from openhands.tools.execute_bash import (
-    BashExecutor,
-    BashTool,
-    ExecuteBashAction,
-    ExecuteBashObservation,
-    execute_bash_tool,
-)
-from openhands.tools.str_replace_editor import (
-    FileEditorExecutor,
-    FileEditorTool,
-    StrReplaceEditorAction,
-    StrReplaceEditorObservation,
-    str_replace_editor_tool,
-)
-from openhands.tools.task_tracker import (
-    TaskTrackerAction,
-    TaskTrackerExecutor,
-    TaskTrackerObservation,
-    TaskTrackerTool,
-    task_tracker_tool,
-)
-
-
-__all__ = [
-    "execute_bash_tool",
-    "ExecuteBashAction",
-    "ExecuteBashObservation",
-    "BashExecutor",
-    "BashTool",
-    "str_replace_editor_tool",
-    "StrReplaceEditorAction",
-    "StrReplaceEditorObservation",
-    "FileEditorExecutor",
-    "FileEditorTool",
-    "task_tracker_tool",
-    "TaskTrackerAction",
-    "TaskTrackerObservation",
-    "TaskTrackerExecutor",
-    "TaskTrackerTool",
-]
-
-__version__ = "1.0.0a0"

openhands/tools/execute_bash/__init__.py

@@ -1,30 +0,0 @@
-# Core tool interface
-from openhands.tools.execute_bash.definition import (
-    BashTool,
-    ExecuteBashAction,
-    ExecuteBashObservation,
-    execute_bash_tool,
-)
-from openhands.tools.execute_bash.impl import BashExecutor
-
-# Terminal session architecture - import from sessions package
-from openhands.tools.execute_bash.terminal import (
-    TerminalCommandStatus,
-    TerminalSession,
-    create_terminal_session,
-)
-
-
-__all__ = [
-    # === Core Tool Interface ===
-    "BashTool",
-    "execute_bash_tool",
-    "ExecuteBashAction",
-    "ExecuteBashObservation",
-    "BashExecutor",
-    # === Terminal Session Architecture ===
-    "TerminalSession",
-    "TerminalCommandStatus",
-    "TerminalSession",
-    "create_terminal_session",
-]

openhands/tools/execute_bash/constants.py

@@ -1,31 +0,0 @@
-import re
-
-
-CMD_OUTPUT_PS1_BEGIN = "\n###PS1JSON###\n"
-CMD_OUTPUT_PS1_END = "\n###PS1END###"
-CMD_OUTPUT_METADATA_PS1_REGEX = re.compile(
-    f"^{CMD_OUTPUT_PS1_BEGIN.strip()}(.*?){CMD_OUTPUT_PS1_END.strip()}",
-    re.DOTALL | re.MULTILINE,
-)
-
-# Default max size for command output content
-# to prevent too large observations from being saved in the stream
-# This matches the default max_message_chars in LLM class
-MAX_CMD_OUTPUT_SIZE: int = 30000
-
-
-# Common timeout message that can be used across different timeout scenarios
-TIMEOUT_MESSAGE_TEMPLATE = (
-    "You may wait longer to see additional output by sending empty command '', "
-    "send other commands to interact with the current process, send keys "
-    '("C-c", "C-z", "C-d") '
-    "to interrupt/kill the previous command before sending your new command, "
-    "or use the timeout parameter in execute_bash for future commands."
-)
-
-# How long to wait with no new output before considering it a no-change timeout
-NO_CHANGE_TIMEOUT_SECONDS = 30
-
-# How often to poll for new output in seconds
-POLL_INTERVAL = 0.5
-HISTORY_LIMIT = 10_000