Add Sphinx-compatible docstrings to core SDK classes (#1006)

Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: Xingyao Wang <xingyao@all-hands.dev>
Co-authored-by: Engel Nyst <engel.nyst@gmail.com>

Author: 4 people

openhands-sdk/openhands/sdk/agent/agent.py

@@ -47,6 +47,19 @@
 
 
 class Agent(AgentBase):
+    """Main agent implementation for OpenHands.
+
+    The Agent class provides the core functionality for running AI agents that can
+    interact with tools, process messages, and execute actions. It inherits from
+    AgentBase and implements the agent execution logic.
+
+    Example:
+        >>> from openhands.sdk import LLM, Agent, Tool
+        >>> llm = LLM(model="claude-sonnet-4-20250514", api_key=SecretStr("key"))
+        >>> tools = [Tool(name="BashTool"), Tool(name="FileEditorTool")]
+        >>> agent = Agent(llm=llm, tools=tools)
+    """
+
     @property
     def _add_security_risk_prediction(self) -> bool:
         return isinstance(self.security_analyzer, LLMSecurityAnalyzer)

openhands-sdk/openhands/sdk/agent/base.py

@@ -28,8 +28,11 @@
 
 
 class AgentBase(DiscriminatedUnionMixin, ABC):
-    """Abstract base class for agents.
+    """Abstract base class for OpenHands agents.
+
     Agents are stateless and should be fully defined by their configuration.
+    This base class provides the common interface and functionality that all
+    agent implementations must follow.
     """
 
     model_config = ConfigDict(

openhands-sdk/openhands/sdk/conversation/base.py

@@ -69,6 +69,13 @@ def agent(self) -> "AgentBase":
 
 
 class BaseConversation(ABC):
+    """Abstract base class for conversation implementations.
+
+    This class defines the interface that all conversation implementations must follow.
+    Conversations manage the interaction between users and agents, handling message
+    exchange, execution control, and state management.
+    """
+
     @property
     @abstractmethod
     def id(self) -> ConversationID: ...
@@ -82,13 +89,23 @@ def state(self) -> ConversationStateProtocol: ...
     def conversation_stats(self) -> ConversationStats: ...
 
     @abstractmethod
-    def send_message(self, message: str | Message) -> None: ...
+    def send_message(self, message: str | Message) -> None:
+        """Send a message to the agent."""
+        ...
 
     @abstractmethod
-    def run(self) -> None: ...
+    def run(self) -> None:
+        """Execute the agent to process messages and perform actions.
+
+        This method runs the agent until it finishes processing the current
+        message or reaches the maximum iteration limit.
+        """
+        ...
 
     @abstractmethod
-    def set_confirmation_policy(self, policy: ConfirmationPolicyBase) -> None: ...
+    def set_confirmation_policy(self, policy: ConfirmationPolicyBase) -> None:
+        """Set the confirmation policy for the conversation."""
+        ...
 
     @property
     def confirmation_policy_active(self) -> bool:

openhands-sdk/openhands/sdk/conversation/conversation.py

@@ -16,11 +16,23 @@
 
 
 class Conversation:
-    """Factory entrypoint that returns a LocalConversation or RemoteConversation.
+    """Factory class for creating conversation instances with OpenHands agents.
 
-    Usage:
-        - Conversation(agent=...) -> LocalConversation
-        - Conversation(agent=..., host="http://...") -> RemoteConversation
+    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

openhands-sdk/openhands/sdk/llm/llm.py

@@ -101,7 +101,23 @@
 
 
 class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
-    """Refactored LLM: simple `completion()`, centralized Telemetry, tiny helpers."""
+    """Language model interface for OpenHands agents.
+
+    The LLM class provides a unified interface for interacting with various
+    language models through the litellm library. It handles model configuration,
+    API authentication,
+    retry logic, and tool calling capabilities.
+
+    Example:
+        >>> from openhands.sdk import LLM
+        >>> from pydantic import SecretStr
+        >>> llm = LLM(
+        ...     model="claude-sonnet-4-20250514",
+        ...     api_key=SecretStr("your-api-key"),
+        ...     usage_id="my-agent"
+        ... )
+        >>> # Use with agent or conversation
+    """
 
     # =========================================================================
     # Config fields
@@ -388,6 +404,15 @@ def service_id(self, value: str) -> None:
 
     @property
     def metrics(self) -> Metrics:
+        """Get usage metrics for this LLM instance.
+
+        Returns:
+            Metrics object containing token usage, costs, and other statistics.
+
+        Example:
+            >>> cost = llm.metrics.accumulated_cost
+            >>> print(f"Total cost: ${cost}")
+        """
         assert self._metrics is not None, (
             "Metrics should be initialized after model validation"
         )
@@ -405,9 +430,22 @@ def completion(
         add_security_risk_prediction: bool = False,
         **kwargs,
     ) -> LLMResponse:
-        """Single entry point for LLM completion.
+        """Generate a completion from the language model.
+
+        This is the method for getting responses from the model via Completion API.
+        It handles message formatting, tool calling, and response processing.
+
+        Returns:
+            LLMResponse containing the model's response and metadata.
+
+        Raises:
+            ValueError: If streaming is requested (not supported).
 
-        Normalize → (maybe) mock tools → transport → postprocess.
+        Example:
+            >>> from openhands.sdk.llm import Message, TextContent
+            >>> messages = [Message(role="user", content=[TextContent(text="Hello")])]
+            >>> response = llm.completion(messages)
+            >>> print(response.content)
         """
         # Check if streaming is requested
         if kwargs.get("stream", False):

openhands-sdk/openhands/sdk/logger/logger.py

@@ -160,7 +160,24 @@ def setup_logging(
 
 
 def get_logger(name: str) -> logging.Logger:
-    """Return a logger for the given module name."""
+    """Get a logger instance for the specified module.
+
+    This function returns a configured logger that inherits from the root logger
+    setup. The logger supports both Rich formatting for human-readable output
+    and JSON formatting for machine processing, depending on environment configuration.
+
+    Args:
+        name: The name of the module, typically __name__.
+
+    Returns:
+        A configured Logger instance.
+
+    Example:
+        >>> from openhands.sdk.logger import get_logger
+        >>> logger = get_logger(__name__)
+        >>> logger.info("This is an info message")
+        >>> logger.error("This is an error message")
+    """
     logger = logging.getLogger(name)
     logger.propagate = True
     return logger

openhands-sdk/openhands/sdk/tool/tool.py

@@ -123,12 +123,26 @@ def __call__(
 
 
 class ToolBase[ActionT, ObservationT](DiscriminatedUnionMixin, ABC):
-    """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.
+    """Base class for tools that agents can use to perform actions.
+
+    Tools wrap executor functions with input/output validation and schema definition.
+    They provide a standardized interface for agents to interact with external systems,
+    APIs, or perform specific operations.
+
+    Features:
+    - Normalize input/output schemas (class or dict) into both model+schema
+    - Validate inputs before execution
+    - Coerce outputs only if an output model is defined; else return vanilla JSON
+    - Export MCP (Model Context Protocol) tool descriptions
+
+    Example:
+        >>> from openhands.sdk.tool import ToolDefinition
+        >>> tool = ToolDefinition(
+        ...     name="echo",
+        ...     description="Echo the input message",
+        ...     action_type=EchoAction,
+        ...     executor=echo_executor
+        ... )
     """
 
     model_config: ClassVar[ConfigDict] = ConfigDict(

openhands-sdk/openhands/sdk/workspace/base.py

@@ -14,13 +14,16 @@
 
 
 class BaseWorkspace(DiscriminatedUnionMixin, ABC):
-    """Abstract base mixin for workspace.
+    """Abstract base class for workspace implementations.
 
-    All workspace implementations support the context manager protocol,
-    allowing safe resource management:
+    Workspaces provide a sandboxed environment where agents can execute commands,
+    read/write files, and perform other operations. All workspace implementations
+    support the context manager protocol for safe resource management.
 
-        with workspace:
-            workspace.execute_command("echo 'hello'")
+    Example:
+        >>> with workspace:
+        ...     result = workspace.execute_command("echo 'hello'")
+        ...     content = workspace.read_file("example.txt")
     """
 
     working_dir: str = Field(

openhands-sdk/openhands/sdk/workspace/local.py

@@ -14,7 +14,18 @@
 
 
 class LocalWorkspace(BaseWorkspace):
-    """Mixin providing local workspace operations."""
+    """Local workspace implementation that operates on the host filesystem.
+
+    LocalWorkspace provides direct access to the local filesystem and command execution
+    environment. It's suitable for development and testing scenarios where the agent
+    should operate directly on the host system.
+
+    Example:
+        >>> workspace = LocalWorkspace(working_dir="/path/to/project")
+        >>> with workspace:
+        ...     result = workspace.execute_command("ls -la")
+        ...     content = workspace.read_file("README.md")
+    """
 
     def execute_command(
         self,

openhands-sdk/openhands/sdk/workspace/remote/base.py

@@ -12,7 +12,21 @@
 
 
 class RemoteWorkspace(RemoteWorkspaceMixin, BaseWorkspace):
-    """Remote Workspace Implementation."""
+    """Remote workspace implementation that connects to an OpenHands agent server.
+
+    RemoteWorkspace provides access to a sandboxed environment running on a remote
+    OpenHands agent server. This is the recommended approach for production deployments
+    as it provides better isolation and security.
+
+    Example:
+        >>> workspace = RemoteWorkspace(
+        ...     host="https://agent-server.example.com",
+        ...     working_dir="/workspace"
+        ... )
+        >>> with workspace:
+        ...     result = workspace.execute_command("ls -la")
+        ...     content = workspace.read_file("README.md")
+    """
 
     _client: httpx.Client | None = PrivateAttr(default=None)