openhands-sdk 1.7.3__py3-none-any.whl

openhands/sdk/io/cache.py

@@ -0,0 +1,85 @@
+from typing import Any
+
+from cachetools import LRUCache
+
+from openhands.sdk.logger import get_logger
+
+
+logger = get_logger(__name__)
+
+
+class MemoryLRUCache(LRUCache):
+    """LRU cache with both entry count and memory size limits.
+
+    This cache enforces two limits:
+    1. Maximum number of entries (maxsize)
+    2. Maximum memory usage in bytes (max_memory)
+
+    When either limit is exceeded, the least recently used items are evicted.
+
+    Note: Memory tracking is based on string length for simplicity and accuracy.
+    For non-string values, sys.getsizeof is used as a rough approximation.
+    """
+
+    def __init__(self, max_memory: int, max_size: int, *args, **kwargs):
+        # Ensure minimum maxsize of 1 to avoid LRUCache issues
+        maxsize = max(1, max_size)
+        super().__init__(maxsize=maxsize, *args, **kwargs)
+        self.max_memory = max_memory
+        self.current_memory = 0
+
+    def _get_size(self, value: Any) -> int:
+        """Calculate size of value for memory tracking.
+
+        For strings (the common case in FileStore), we use len() which gives
+        accurate character count. For other types, we use sys.getsizeof() as
+        a rough approximation.
+        """
+        if isinstance(value, str):
+            # For strings, len() gives character count which is what we care about
+            # This is much more accurate than sys.getsizeof for our use case
+            return len(value)
+        elif isinstance(value, bytes):
+            return len(value)
+        else:
+            # For other types, fall back to sys.getsizeof
+            # This is mainly for edge cases and won't be accurate for nested
+            # structures, but it's better than nothing
+            try:
+                import sys
+
+                return sys.getsizeof(value)
+            except Exception:
+                return 0
+
+    def __setitem__(self, key: Any, value: Any) -> None:
+        new_size = self._get_size(value)
+
+        # Don't cache items that are larger than max_memory
+        # This prevents cache thrashing where one huge item evicts everything
+        if new_size > self.max_memory:
+            logger.debug(
+                f"Item too large for cache ({new_size} bytes > "
+                f"{self.max_memory} bytes), skipping cache"
+            )
+            return
+
+        # Update memory accounting if key exists
+        if key in self:
+            old_value = self[key]
+            self.current_memory -= self._get_size(old_value)
+
+        self.current_memory += new_size
+
+        # Evict items until we're under memory limit
+        while self.current_memory > self.max_memory and len(self) > 0:
+            self.popitem()
+
+        super().__setitem__(key, value)
+
+    def __delitem__(self, key: Any) -> None:
+        if key in self:
+            old_value = self[key]
+            self.current_memory -= self._get_size(old_value)
+
+        super().__delitem__(key)

openhands/sdk/io/local.py

@@ -0,0 +1,119 @@
+import os
+import shutil
+
+from openhands.sdk.io.cache import MemoryLRUCache
+from openhands.sdk.logger import get_logger
+from openhands.sdk.observability.laminar import observe
+
+from .base import FileStore
+
+
+logger = get_logger(__name__)
+
+
+class LocalFileStore(FileStore):
+    root: str
+    cache: MemoryLRUCache
+
+    def __init__(
+        self,
+        root: str,
+        cache_limit_size: int = 500,
+        cache_memory_size: int = 20 * 1024 * 1024,
+    ) -> None:
+        """Initialize a LocalFileStore with caching.
+
+        Args:
+            root: Root directory for file storage.
+            cache_limit_size: Maximum number of cached entries (default: 500).
+            cache_memory_size: Maximum cache memory in bytes (default: 20MB).
+
+        Note:
+            The cache assumes exclusive access to files. External modifications
+            to files will not be detected and may result in stale cache reads.
+        """
+        if root.startswith("~"):
+            root = os.path.expanduser(root)
+        root = os.path.abspath(os.path.normpath(root))
+        self.root = root
+        os.makedirs(self.root, exist_ok=True)
+        self.cache = MemoryLRUCache(cache_memory_size, cache_limit_size)
+
+    def get_full_path(self, path: str) -> str:
+        # strip leading slash to keep relative under root
+        if path.startswith("/"):
+            path = path[1:]
+        # normalize path separators to handle both Unix (/) and Windows (\) styles
+        normalized_path = path.replace("\\", "/")
+        full = os.path.abspath(
+            os.path.normpath(os.path.join(self.root, normalized_path))
+        )
+        # ensure sandboxing
+        if os.path.commonpath([self.root, full]) != self.root:
+            raise ValueError(f"path escapes filestore root: {path}")
+
+        return full
+
+    @observe(name="LocalFileStore.write", span_type="TOOL")
+    def write(self, path: str, contents: str | bytes) -> None:
+        full_path = self.get_full_path(path)
+        os.makedirs(os.path.dirname(full_path), exist_ok=True)
+        if isinstance(contents, str):
+            with open(full_path, "w", encoding="utf-8") as f:
+                f.write(contents)
+            self.cache[full_path] = contents
+        else:
+            with open(full_path, "wb") as f:
+                f.write(contents)
+            # Don't cache binary content - LocalFileStore is meant for JSON data
+            # If binary data is written and then read, it will error on read
+
+    def read(self, path: str) -> str:
+        full_path = self.get_full_path(path)
+
+        if full_path in self.cache:
+            return self.cache[full_path]
+
+        if not os.path.exists(full_path):
+            raise FileNotFoundError(path)
+
+        with open(full_path, encoding="utf-8") as f:
+            result = f.read()
+
+        self.cache[full_path] = result
+        return result
+
+    @observe(name="LocalFileStore.list", span_type="TOOL")
+    def list(self, path: str) -> list[str]:
+        full_path = self.get_full_path(path)
+        if not os.path.exists(full_path):
+            return []
+
+        # If path is a file, return the file itself (S3-consistent behavior)
+        if os.path.isfile(full_path):
+            return [path]
+
+        # Otherwise it's a directory, return its contents
+        files = [os.path.join(path, f) for f in os.listdir(full_path)]
+        files = [f + "/" if os.path.isdir(self.get_full_path(f)) else f for f in files]
+        return files
+
+    @observe(name="LocalFileStore.delete", span_type="TOOL")
+    def delete(self, path: str) -> None:
+        try:
+            full_path = self.get_full_path(path)
+            if not os.path.exists(full_path):
+                logger.debug(f"Local path does not exist: {full_path}")
+                return
+
+            if os.path.isfile(full_path):
+                os.remove(full_path)
+                del self.cache[full_path]
+                logger.debug(f"Removed local file: {full_path}")
+            elif os.path.isdir(full_path):
+                shutil.rmtree(full_path)
+                self.cache.clear()
+                logger.debug(f"Removed local directory: {full_path}")
+
+        except Exception as e:
+            logger.error(f"Error clearing local file store: {str(e)}")

openhands/sdk/io/memory.py

@@ -0,0 +1,54 @@
+import os
+
+from openhands.sdk.io.base import FileStore
+from openhands.sdk.logger import get_logger
+
+
+logger = get_logger(__name__)
+
+
+class InMemoryFileStore(FileStore):
+    files: dict[str, str]
+
+    def __init__(self, files: dict[str, str] | None = None) -> None:
+        self.files = {}
+        if files is not None:
+            self.files = files
+
+    def write(self, path: str, contents: str | bytes) -> None:
+        if isinstance(contents, bytes):
+            contents = contents.decode("utf-8")
+        self.files[path] = contents
+
+    def read(self, path: str) -> str:
+        if path not in self.files:
+            raise FileNotFoundError(path)
+        return self.files[path]
+
+    def list(self, path: str) -> list[str]:
+        files = []
+        for file in self.files:
+            if not file.startswith(path):
+                continue
+            suffix = file.removeprefix(path)
+            parts = suffix.split("/")
+            if parts[0] == "":
+                parts.pop(0)
+            if len(parts) == 1:
+                files.append(file)
+            else:
+                dir_path = os.path.join(path, parts[0])
+                if not dir_path.endswith("/"):
+                    dir_path += "/"
+                if dir_path not in files:
+                    files.append(dir_path)
+        return files
+
+    def delete(self, path: str) -> None:
+        try:
+            keys_to_delete = [key for key in self.files.keys() if key.startswith(path)]
+            for key in keys_to_delete:
+                del self.files[key]
+            logger.debug(f"Cleared in-memory file store: {path}")
+        except Exception as e:
+            logger.error(f"Error clearing in-memory file store: {str(e)}")

openhands/sdk/llm/__init__.py

@@ -0,0 +1,45 @@
+from openhands.sdk.llm.llm import LLM
+from openhands.sdk.llm.llm_registry import LLMRegistry, RegistryEvent
+from openhands.sdk.llm.llm_response import LLMResponse
+from openhands.sdk.llm.message import (
+    ImageContent,
+    Message,
+    MessageToolCall,
+    ReasoningItemModel,
+    RedactedThinkingBlock,
+    TextContent,
+    ThinkingBlock,
+    content_to_str,
+)
+from openhands.sdk.llm.router import RouterLLM
+from openhands.sdk.llm.streaming import LLMStreamChunk, TokenCallbackType
+from openhands.sdk.llm.utils.metrics import Metrics, MetricsSnapshot
+from openhands.sdk.llm.utils.unverified_models import (
+    UNVERIFIED_MODELS_EXCLUDING_BEDROCK,
+    get_unverified_models,
+)
+from openhands.sdk.llm.utils.verified_models import VERIFIED_MODELS
+
+
+__all__ = [
+    "LLMResponse",
+    "LLM",
+    "LLMRegistry",
+    "RouterLLM",
+    "RegistryEvent",
+    "Message",
+    "MessageToolCall",
+    "TextContent",
+    "ImageContent",
+    "ThinkingBlock",
+    "RedactedThinkingBlock",
+    "ReasoningItemModel",
+    "content_to_str",
+    "LLMStreamChunk",
+    "TokenCallbackType",
+    "Metrics",
+    "MetricsSnapshot",
+    "VERIFIED_MODELS",
+    "UNVERIFIED_MODELS_EXCLUDING_BEDROCK",
+    "get_unverified_models",
+]

openhands/sdk/llm/exceptions/__init__.py

@@ -0,0 +1,45 @@
+from .classifier import is_context_window_exceeded, looks_like_auth_error
+from .mapping import map_provider_exception
+from .types import (
+    FunctionCallConversionError,
+    FunctionCallNotExistsError,
+    FunctionCallValidationError,
+    LLMAuthenticationError,
+    LLMBadRequestError,
+    LLMContextWindowExceedError,
+    LLMError,
+    LLMMalformedActionError,
+    LLMNoActionError,
+    LLMNoResponseError,
+    LLMRateLimitError,
+    LLMResponseError,
+    LLMServiceUnavailableError,
+    LLMTimeoutError,
+    OperationCancelled,
+    UserCancelledError,
+)
+
+
+__all__ = [
+    # Types
+    "LLMError",
+    "LLMMalformedActionError",
+    "LLMNoActionError",
+    "LLMResponseError",
+    "FunctionCallConversionError",
+    "FunctionCallValidationError",
+    "FunctionCallNotExistsError",
+    "LLMNoResponseError",
+    "LLMContextWindowExceedError",
+    "LLMAuthenticationError",
+    "LLMRateLimitError",
+    "LLMTimeoutError",
+    "LLMServiceUnavailableError",
+    "LLMBadRequestError",
+    "UserCancelledError",
+    "OperationCancelled",
+    # Helpers
+    "is_context_window_exceeded",
+    "looks_like_auth_error",
+    "map_provider_exception",
+]

openhands/sdk/llm/exceptions/classifier.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from litellm.exceptions import BadRequestError, ContextWindowExceededError, OpenAIError
+
+from .types import LLMContextWindowExceedError
+
+
+# Minimal, provider-agnostic context-window detection
+LONG_PROMPT_PATTERNS: list[str] = [
+    "contextwindowexceedederror",
+    "prompt is too long",
+    "input length and `max_tokens` exceed context limit",
+    "please reduce the length of",
+    "the request exceeds the available context size",
+    "context length exceeded",
+    "input exceeds the context window",
+]
+
+
+def is_context_window_exceeded(exception: Exception) -> bool:
+    if isinstance(exception, (ContextWindowExceededError, LLMContextWindowExceedError)):
+        return True
+
+    if not isinstance(exception, (BadRequestError, OpenAIError)):
+        return False
+
+    s = str(exception).lower()
+    return any(p in s for p in LONG_PROMPT_PATTERNS)
+
+
+AUTH_PATTERNS: list[str] = [
+    "invalid api key",
+    "unauthorized",
+    "missing api key",
+    "invalid authentication",
+    "access denied",
+]
+
+
+def looks_like_auth_error(exception: Exception) -> bool:
+    if not isinstance(exception, (BadRequestError, OpenAIError)):
+        return False
+    s = str(exception).lower()
+    if any(p in s for p in AUTH_PATTERNS):
+        return True
+    # Some providers include explicit status codes in message text
+    for code in ("status 401", "status 403"):
+        if code in s:
+            return True
+    return False

openhands/sdk/llm/exceptions/mapping.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from litellm.exceptions import (
+    APIConnectionError,
+    BadRequestError,
+    InternalServerError,
+    RateLimitError,
+    ServiceUnavailableError,
+    Timeout as LiteLLMTimeout,
+)
+
+from .classifier import is_context_window_exceeded, looks_like_auth_error
+from .types import (
+    LLMAuthenticationError,
+    LLMBadRequestError,
+    LLMContextWindowExceedError,
+    LLMRateLimitError,
+    LLMServiceUnavailableError,
+    LLMTimeoutError,
+)
+
+
+def map_provider_exception(exception: Exception) -> Exception:
+    """
+    Map provider/LiteLLM exceptions to SDK-typed exceptions.
+
+    Returns original exception if no mapping applies.
+    """
+    # Context window exceeded first (highest priority)
+    if is_context_window_exceeded(exception):
+        return LLMContextWindowExceedError(str(exception))
+
+    # Auth-like errors often appear as BadRequest/OpenAIError with specific text
+    if looks_like_auth_error(exception):
+        return LLMAuthenticationError(str(exception))
+
+    if isinstance(exception, RateLimitError):
+        return LLMRateLimitError(str(exception))
+
+    if isinstance(exception, LiteLLMTimeout):
+        return LLMTimeoutError(str(exception))
+
+    # Connectivity and service-side availability issues → service unavailable
+    if isinstance(
+        exception, (APIConnectionError, ServiceUnavailableError, InternalServerError)
+    ):
+        return LLMServiceUnavailableError(str(exception))
+
+    # Generic client-side 4xx errors
+    if isinstance(exception, BadRequestError):
+        return LLMBadRequestError(str(exception))
+
+    # Unknown: let caller re-raise original
+    return exception

openhands/sdk/llm/exceptions/types.py

@@ -0,0 +1,101 @@
+class LLMError(Exception):
+    message: str
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+    def __str__(self) -> str:
+        return self.message
+
+
+# General response parsing/validation errors
+class LLMMalformedActionError(LLMError):
+    def __init__(self, message: str = "Malformed response") -> None:
+        super().__init__(message)
+
+
+class LLMNoActionError(LLMError):
+    def __init__(self, message: str = "Agent must return an action") -> None:
+        super().__init__(message)
+
+
+class LLMResponseError(LLMError):
+    def __init__(
+        self, message: str = "Failed to retrieve action from LLM response"
+    ) -> None:
+        super().__init__(message)
+
+
+# Function-calling conversion/validation
+class FunctionCallConversionError(LLMError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class FunctionCallValidationError(LLMError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class FunctionCallNotExistsError(LLMError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+# Provider/transport related
+class LLMNoResponseError(LLMError):
+    def __init__(
+        self,
+        message: str = (
+            "LLM did not return a response. This is only seen in Gemini models so far."
+        ),
+    ) -> None:
+        super().__init__(message)
+
+
+class LLMContextWindowExceedError(LLMError):
+    def __init__(
+        self,
+        message: str = (
+            "Conversation history longer than LLM context window limit. "
+            "Consider enabling a condenser or shortening inputs."
+        ),
+    ) -> None:
+        super().__init__(message)
+
+
+class LLMAuthenticationError(LLMError):
+    def __init__(self, message: str = "Invalid or missing API credentials") -> None:
+        super().__init__(message)
+
+
+class LLMRateLimitError(LLMError):
+    def __init__(self, message: str = "Rate limit exceeded") -> None:
+        super().__init__(message)
+
+
+class LLMTimeoutError(LLMError):
+    def __init__(self, message: str = "LLM request timed out") -> None:
+        super().__init__(message)
+
+
+class LLMServiceUnavailableError(LLMError):
+    def __init__(self, message: str = "LLM service unavailable") -> None:
+        super().__init__(message)
+
+
+class LLMBadRequestError(LLMError):
+    def __init__(self, message: str = "Bad request to LLM provider") -> None:
+        super().__init__(message)
+
+
+# Other
+class UserCancelledError(Exception):
+    def __init__(self, message: str = "User cancelled the request") -> None:
+        super().__init__(message)
+
+
+class OperationCancelled(Exception):
+    def __init__(self, message: str = "Operation was cancelled") -> None:
+        super().__init__(message)