openhands-sdk 1.7.0__py3-none-any.whl

openhands/sdk/conversation/conversation.py

@@ -0,0 +1,146 @@
+from collections.abc import Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING, Self, overload
+
+from openhands.sdk.agent.base import AgentBase
+from openhands.sdk.conversation.base import BaseConversation
+from openhands.sdk.conversation.types import (
+    ConversationCallbackType,
+    ConversationID,
+    ConversationTokenCallbackType,
+    StuckDetectionThresholds,
+)
+from openhands.sdk.conversation.visualizer import (
+    ConversationVisualizerBase,
+    DefaultConversationVisualizer,
+)
+from openhands.sdk.logger import get_logger
+from openhands.sdk.secret import SecretValue
+from openhands.sdk.workspace import LocalWorkspace, RemoteWorkspace
+
+
+if TYPE_CHECKING:
+    from openhands.sdk.conversation.impl.local_conversation import LocalConversation
+    from openhands.sdk.conversation.impl.remote_conversation import RemoteConversation
+
+logger = get_logger(__name__)
+
+
+class Conversation:
+    """Factory class for creating conversation instances with OpenHands agents.
+
+    This factory automatically creates either a LocalConversation or RemoteConversation
+    based on the workspace type provided. LocalConversation runs the agent locally,
+    while RemoteConversation connects to a remote agent server.
+
+    Returns:
+        LocalConversation if workspace is local, RemoteConversation if workspace
+        is remote.
+
+    Example:
+        >>> from openhands.sdk import LLM, Agent, Conversation
+        >>> llm = LLM(model="claude-sonnet-4-20250514", api_key=SecretStr("key"))
+        >>> agent = Agent(llm=llm, tools=[])
+        >>> conversation = Conversation(agent=agent, workspace="./workspace")
+        >>> conversation.send_message("Hello!")
+        >>> conversation.run()
+    """
+
+    @overload
+    def __new__(
+        cls: type[Self],
+        agent: AgentBase,
+        *,
+        workspace: str | Path | LocalWorkspace = "workspace/project",
+        persistence_dir: str | Path | None = None,
+        conversation_id: ConversationID | None = None,
+        callbacks: list[ConversationCallbackType] | None = None,
+        token_callbacks: list[ConversationTokenCallbackType] | None = None,
+        max_iteration_per_run: int = 500,
+        stuck_detection: bool = True,
+        stuck_detection_thresholds: (
+            StuckDetectionThresholds | Mapping[str, int] | None
+        ) = None,
+        visualizer: (
+            type[ConversationVisualizerBase] | ConversationVisualizerBase | None
+        ) = DefaultConversationVisualizer,
+        secrets: dict[str, SecretValue] | dict[str, str] | None = None,
+    ) -> "LocalConversation": ...
+
+    @overload
+    def __new__(
+        cls: type[Self],
+        agent: AgentBase,
+        *,
+        workspace: RemoteWorkspace,
+        conversation_id: ConversationID | None = None,
+        callbacks: list[ConversationCallbackType] | None = None,
+        token_callbacks: list[ConversationTokenCallbackType] | None = None,
+        max_iteration_per_run: int = 500,
+        stuck_detection: bool = True,
+        stuck_detection_thresholds: (
+            StuckDetectionThresholds | Mapping[str, int] | None
+        ) = None,
+        visualizer: (
+            type[ConversationVisualizerBase] | ConversationVisualizerBase | None
+        ) = DefaultConversationVisualizer,
+        secrets: dict[str, SecretValue] | dict[str, str] | None = None,
+    ) -> "RemoteConversation": ...
+
+    def __new__(
+        cls: type[Self],
+        agent: AgentBase,
+        *,
+        workspace: str | Path | LocalWorkspace | RemoteWorkspace = "workspace/project",
+        persistence_dir: str | Path | None = None,
+        conversation_id: ConversationID | None = None,
+        callbacks: list[ConversationCallbackType] | None = None,
+        token_callbacks: list[ConversationTokenCallbackType] | None = None,
+        max_iteration_per_run: int = 500,
+        stuck_detection: bool = True,
+        stuck_detection_thresholds: (
+            StuckDetectionThresholds | Mapping[str, int] | None
+        ) = None,
+        visualizer: (
+            type[ConversationVisualizerBase] | ConversationVisualizerBase | None
+        ) = DefaultConversationVisualizer,
+        secrets: dict[str, SecretValue] | dict[str, str] | None = None,
+    ) -> BaseConversation:
+        from openhands.sdk.conversation.impl.local_conversation import LocalConversation
+        from openhands.sdk.conversation.impl.remote_conversation import (
+            RemoteConversation,
+        )
+
+        if isinstance(workspace, RemoteWorkspace):
+            # For RemoteConversation, persistence_dir should not be used
+            # Only check if it was explicitly set to something other than the default
+            if persistence_dir is not None:
+                raise ValueError(
+                    "persistence_dir should not be set when using RemoteConversation"
+                )
+            return RemoteConversation(
+                agent=agent,
+                conversation_id=conversation_id,
+                callbacks=callbacks,
+                token_callbacks=token_callbacks,
+                max_iteration_per_run=max_iteration_per_run,
+                stuck_detection=stuck_detection,
+                stuck_detection_thresholds=stuck_detection_thresholds,
+                visualizer=visualizer,
+                workspace=workspace,
+                secrets=secrets,
+            )
+
+        return LocalConversation(
+            agent=agent,
+            conversation_id=conversation_id,
+            callbacks=callbacks,
+            token_callbacks=token_callbacks,
+            max_iteration_per_run=max_iteration_per_run,
+            stuck_detection=stuck_detection,
+            stuck_detection_thresholds=stuck_detection_thresholds,
+            visualizer=visualizer,
+            workspace=workspace,
+            persistence_dir=persistence_dir,
+            secrets=secrets,
+        )

openhands/sdk/conversation/conversation_stats.py

@@ -0,0 +1,85 @@
+from typing import Any
+
+from pydantic import BaseModel, Field, PrivateAttr, model_serializer
+
+from openhands.sdk.llm.llm_registry import RegistryEvent
+from openhands.sdk.llm.utils.metrics import Metrics
+from openhands.sdk.logger import get_logger
+
+
+logger = get_logger(__name__)
+
+
+class ConversationStats(BaseModel):
+    """Track per-LLM usage metrics observed during conversations."""
+
+    usage_to_metrics: dict[str, Metrics] = Field(
+        default_factory=dict,
+        description="Active usage metrics tracked by the registry.",
+    )
+
+    _restored_usage_ids: set[str] = PrivateAttr(default_factory=set)
+
+    @model_serializer(mode="wrap")
+    def _serialize_with_context(self, serializer: Any, info: Any) -> dict[str, Any]:
+        """Serialize metrics based on context.
+
+        By default, preserves full metrics history including costs,
+        response_latencies, and token_usages lists for persistence.
+
+        When context={'use_snapshot': True} is passed, converts Metrics to
+        MetricsSnapshot format to minimize payload size for network transmission.
+
+        Args:
+            serializer: Pydantic's default serializer
+            info: Serialization info containing context
+
+        Returns:
+            Dictionary with metrics serialized based on context
+        """
+        # Get the default serialization
+        data = serializer(self)
+
+        # Check if we should use snapshot serialization
+        context = info.context if info else None
+        use_snapshot = context.get("use_snapshot", False) if context else False
+
+        if use_snapshot and "usage_to_metrics" in data:
+            # Replace each Metrics with its snapshot
+            usage_to_snapshots = {}
+            for usage_id, metrics in self.usage_to_metrics.items():
+                snapshot = metrics.get_snapshot()
+                usage_to_snapshots[usage_id] = snapshot.model_dump()
+
+            data["usage_to_metrics"] = usage_to_snapshots
+
+        return data
+
+    def get_combined_metrics(self) -> Metrics:
+        total_metrics = Metrics()
+        for metrics in self.usage_to_metrics.values():
+            total_metrics.merge(metrics)
+        return total_metrics
+
+    def get_metrics_for_usage(self, usage_id: str) -> Metrics:
+        if usage_id not in self.usage_to_metrics:
+            raise Exception(f"LLM usage does not exist {usage_id}")
+
+        return self.usage_to_metrics[usage_id]
+
+    def register_llm(self, event: RegistryEvent):
+        # Listen for LLM creations and track their metrics
+        llm = event.llm
+        usage_id = llm.usage_id
+
+        # Usage costs exist but have not been restored yet
+        if (
+            usage_id in self.usage_to_metrics
+            and usage_id not in self._restored_usage_ids
+        ):
+            llm.restore_metrics(self.usage_to_metrics[usage_id])
+            self._restored_usage_ids.add(usage_id)
+
+        # Usage is new, track its metrics
+        if usage_id not in self.usage_to_metrics and llm.metrics:
+            self.usage_to_metrics[usage_id] = llm.metrics

openhands/sdk/conversation/event_store.py

@@ -0,0 +1,157 @@
+# state.py
+import operator
+from collections.abc import Iterator
+from typing import SupportsIndex, overload
+
+from openhands.sdk.conversation.events_list_base import EventsListBase
+from openhands.sdk.conversation.persistence_const import (
+    EVENT_FILE_PATTERN,
+    EVENT_NAME_RE,
+    EVENTS_DIR,
+)
+from openhands.sdk.event import Event, EventID
+from openhands.sdk.io import FileStore
+from openhands.sdk.logger import get_logger
+
+
+logger = get_logger(__name__)
+
+
+class EventLog(EventsListBase):
+    _fs: FileStore
+    _dir: str
+    _length: int
+
+    def __init__(self, fs: FileStore, dir_path: str = EVENTS_DIR) -> None:
+        self._fs = fs
+        self._dir = dir_path
+        self._id_to_idx: dict[EventID, int] = {}
+        self._idx_to_id: dict[int, EventID] = {}
+        self._length = self._scan_and_build_index()
+
+    def get_index(self, event_id: EventID) -> int:
+        """Return the integer index for a given event_id."""
+        try:
+            return self._id_to_idx[event_id]
+        except KeyError:
+            raise KeyError(f"Unknown event_id: {event_id}")
+
+    def get_id(self, idx: int) -> EventID:
+        """Return the event_id for a given index."""
+        if idx < 0:
+            idx += self._length
+        if idx < 0 or idx >= self._length:
+            raise IndexError("Event index out of range")
+        return self._idx_to_id[idx]
+
+    @overload
+    def __getitem__(self, idx: int) -> Event: ...
+
+    @overload
+    def __getitem__(self, idx: slice) -> list[Event]: ...
+
+    def __getitem__(self, idx: SupportsIndex | slice) -> Event | list[Event]:
+        if isinstance(idx, slice):
+            start, stop, step = idx.indices(self._length)
+            return [self._get_single_item(i) for i in range(start, stop, step)]
+        # idx is int-like (SupportsIndex)
+        return self._get_single_item(idx)
+
+    def _get_single_item(self, idx: SupportsIndex) -> Event:
+        i = operator.index(idx)
+        if i < 0:
+            i += self._length
+        if i < 0 or i >= self._length:
+            raise IndexError("Event index out of range")
+        txt = self._fs.read(self._path(i))
+        if not txt:
+            raise FileNotFoundError(f"Missing event file: {self._path(i)}")
+        return Event.model_validate_json(txt)
+
+    def __iter__(self) -> Iterator[Event]:
+        for i in range(self._length):
+            txt = self._fs.read(self._path(i))
+            if not txt:
+                continue
+            evt = Event.model_validate_json(txt)
+            evt_id = evt.id
+            # only backfill mapping if missing
+            if i not in self._idx_to_id:
+                self._idx_to_id[i] = evt_id
+                self._id_to_idx.setdefault(evt_id, i)
+            yield evt
+
+    def append(self, event: Event) -> None:
+        evt_id = event.id
+        # Check for duplicate ID
+        if evt_id in self._id_to_idx:
+            existing_idx = self._id_to_idx[evt_id]
+            raise ValueError(
+                f"Event with ID '{evt_id}' already exists at index {existing_idx}"
+            )
+
+        path = self._path(self._length, event_id=evt_id)
+        self._fs.write(path, event.model_dump_json(exclude_none=True))
+        self._idx_to_id[self._length] = evt_id
+        self._id_to_idx[evt_id] = self._length
+        self._length += 1
+
+    def __len__(self) -> int:
+        return self._length
+
+    def _path(self, idx: int, *, event_id: EventID | None = None) -> str:
+        return f"{self._dir}/{
+            EVENT_FILE_PATTERN.format(
+                idx=idx, event_id=event_id or self._idx_to_id[idx]
+            )
+        }"
+
+    def _scan_and_build_index(self) -> int:
+        try:
+            paths = self._fs.list(self._dir)
+        except Exception:
+            self._id_to_idx.clear()
+            self._idx_to_id.clear()
+            return 0
+
+        by_idx: dict[int, EventID] = {}
+        for p in paths:
+            name = p.rsplit("/", 1)[-1]
+            m = EVENT_NAME_RE.match(name)
+            if m:
+                idx = int(m.group("idx"))
+                evt_id = m.group("event_id")
+                by_idx[idx] = evt_id
+            else:
+                logger.warning(f"Unrecognized event file name: {name}")
+
+        if not by_idx:
+            self._id_to_idx.clear()
+            self._idx_to_id.clear()
+            return 0
+
+        n = 0
+        while True:
+            if n not in by_idx:
+                if any(i > n for i in by_idx.keys()):
+                    logger.warning(
+                        "Event index gap detected: "
+                        f"expect next index {n} but got {sorted(by_idx.keys())}"
+                    )
+                break
+            n += 1
+
+        self._id_to_idx.clear()
+        self._idx_to_id.clear()
+        for i in range(n):
+            evt_id = by_idx[i]
+            self._idx_to_id[i] = evt_id
+            if evt_id in self._id_to_idx:
+                logger.warning(
+                    f"Duplicate event ID '{evt_id}' found during scan. "
+                    f"Keeping first occurrence at index {self._id_to_idx[evt_id]}, "
+                    f"ignoring duplicate at index {i}"
+                )
+            else:
+                self._id_to_idx[evt_id] = i
+        return n

openhands/sdk/conversation/events_list_base.py

@@ -0,0 +1,17 @@
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+
+from openhands.sdk.event import Event
+
+
+class EventsListBase(Sequence[Event], ABC):
+    """Abstract base class for event lists that can be appended to.
+
+    This provides a common interface for both local EventLog and remote
+    RemoteEventsList implementations, avoiding circular imports in protocols.
+    """
+
+    @abstractmethod
+    def append(self, event: Event) -> None:
+        """Add a new event to the list."""
+        ...

openhands/sdk/conversation/exceptions.py

@@ -0,0 +1,50 @@
+from openhands.sdk.conversation.types import ConversationID
+
+
+ISSUE_URL = "https://github.com/OpenHands/software-agent-sdk/issues/new"
+
+
+class ConversationRunError(RuntimeError):
+    """Raised when a conversation run fails.
+
+    Carries the conversation_id and persistence_dir to make resuming/debugging
+    easier while preserving the original exception via exception chaining.
+    """
+
+    conversation_id: ConversationID
+    persistence_dir: str | None
+    original_exception: BaseException
+
+    def __init__(
+        self,
+        conversation_id: ConversationID,
+        original_exception: BaseException,
+        persistence_dir: str | None = None,
+        message: str | None = None,
+    ) -> None:
+        self.conversation_id = conversation_id
+        self.persistence_dir = persistence_dir
+        self.original_exception = original_exception
+        default_msg = self._build_error_message(
+            conversation_id, original_exception, persistence_dir
+        )
+        super().__init__(message or default_msg)
+
+    @staticmethod
+    def _build_error_message(
+        conversation_id: ConversationID,
+        original_exception: BaseException,
+        persistence_dir: str | None,
+    ) -> str:
+        """Build a detailed error message with debugging information."""
+        lines = [
+            f"Conversation run failed for id={conversation_id}: {original_exception}",
+        ]
+
+        if persistence_dir:
+            lines.append(f"\nConversation logs are stored at: {persistence_dir}")
+            lines.append("\nTo help debug this issue, please file a bug report at:")
+            lines.append(f"  {ISSUE_URL}")
+            lines.append("and attach the conversation logs from the directory above.")
+
+        return "\n".join(lines)

openhands/sdk/conversation/fifo_lock.py

@@ -0,0 +1,133 @@
+"""
+FIFO Lock implementation that guarantees first-in-first-out access ordering.
+
+This provides fair lock access where threads acquire the lock in the exact order
+they requested it, preventing starvation that can occur with standard RLock.
+"""
+
+import threading
+import time
+from collections import deque
+from typing import Any, Self
+
+
+class FIFOLock:
+    """
+    A reentrant lock that guarantees FIFO (first-in-first-out) access ordering.
+
+    Unlike Python's standard RLock, this lock ensures that threads acquire
+    the lock in the exact order they requested it, providing fairness and
+    preventing lock starvation.
+
+    Features:
+    - Reentrant: Same thread can acquire multiple times
+    - FIFO ordering: Threads get lock in request order
+    - Context manager support: Use with 'with' statement
+    - Thread-safe: Safe for concurrent access
+    """
+
+    _mutex: threading.Lock
+    _count: int
+
+    def __init__(self) -> None:
+        self._mutex = threading.Lock()  # Protects internal state
+        self._waiters: deque[threading.Condition] = (
+            deque()
+        )  # FIFO queue of waiting threads
+        self._owner: int | None = None  # Current lock owner thread ID
+        self._count = 0  # Reentrancy counter
+
+    def acquire(self, blocking: bool = True, timeout: float = -1) -> bool:
+        """
+        Acquire the lock.
+
+        Args:
+            blocking: If True, block until lock is acquired. If False, return
+                     immediately.
+            timeout: Maximum time to wait for lock (ignored if blocking=False).
+                    -1 means wait indefinitely.
+
+        Returns:
+            True if lock was acquired, False otherwise.
+        """
+        ident = threading.get_ident()
+        start = time.monotonic()
+
+        with self._mutex:
+            # Reentrant case
+            if self._owner == ident:
+                self._count += 1
+                return True
+
+            if self._owner is None and not self._waiters:
+                self._owner = ident
+                self._count = 1
+                return True
+
+            if not blocking:
+                # Give up immediately
+                return False
+
+            # Add to wait queue
+            me = threading.Condition(self._mutex)
+            self._waiters.append(me)
+
+            while True:
+                # If I'm at the front of the queue and nobody owns it → acquire
+                if self._waiters[0] is me and self._owner is None:
+                    self._waiters.popleft()
+                    self._owner = ident
+                    self._count = 1
+                    return True
+
+                if timeout >= 0:
+                    remaining = timeout - (time.monotonic() - start)
+                    if remaining <= 0:
+                        self._waiters.remove(me)
+                        return False
+                    me.wait(remaining)
+                else:
+                    me.wait()
+
+    def release(self) -> None:
+        """
+        Release the lock.
+
+        Raises:
+            RuntimeError: If the current thread doesn't own the lock.
+        """
+        ident = threading.get_ident()
+        with self._mutex:
+            if self._owner != ident:
+                raise RuntimeError("Cannot release lock not owned by current thread")
+            assert self._count >= 1, (
+                "When releasing the resource, the count must be >= 1"
+            )
+            self._count -= 1
+            if self._count == 0:
+                self._owner = None
+                if self._waiters:
+                    self._waiters[0].notify()
+
+    def __enter__(self: Self) -> Self:
+        """Context manager entry."""
+        self.acquire()
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit."""
+        self.release()
+
+    def locked(self) -> bool:
+        """
+        Return True if the lock is currently held by any thread.
+        """
+        with self._mutex:
+            return self._owner is not None
+
+    def owned(self) -> bool:
+        """
+        Return True if the lock is currently held by the calling thread.
+        """
+        with self._mutex:
+            return self._owner == threading.get_ident()

openhands/sdk/conversation/impl/__init__.py

@@ -0,0 +1,5 @@
+from openhands.sdk.conversation.impl.local_conversation import LocalConversation
+from openhands.sdk.conversation.impl.remote_conversation import RemoteConversation
+
+
+__all__ = ["LocalConversation", "RemoteConversation"]