Document new SDK public exports

sdk/api-reference/openhands.sdk.llm.mdx

@@ -4,6 +4,17 @@
 ---
 
 
+## Import shortcuts
+
+`TokenUsage` is part of the public LLM metrics surface and can be imported from either `openhands.sdk.llm` or the top-level `openhands.sdk` package.
+
+```python
+from openhands.sdk.llm import TokenUsage
+# or
+from openhands.sdk import TokenUsage
+```
+
+
 ### class CredentialStore
 
 Bases: `object`
@@ -40,7 +51,7 @@
 Get stored credentials for a vendor.
 
 * Parameters:
   `vendor` – The vendor/provider name (e.g., ‘openai’)
 * Returns:
   OAuthCredentials if found and valid, None otherwise
 
@@ -75,7 +86,7 @@
 
 #### Methods
 
 #### model_config = (configuration object)
 
 Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
 
@@ -90,7 +101,7 @@
 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.
 
@@ -159,7 +170,7 @@
 - `openrouter_site_url`: str
 - `output_cost_per_token`: float | None
 - `prompt_cache_retention`: str | None
 - `reasoning_effort`: Literal['low', 'medium', 'high', 'xhigh', 'none'] | None
 - `reasoning_summary`: Literal['auto', 'concise', 'detailed'] | None
 - `retry_listener`: SkipJsonSchema[Callable[[int, int, BaseException | None], None] | None]
 - `retry_max_wait`: int
@@ -191,15 +202,15 @@
   * `messages` – List of conversation messages
   * `tools` – Optional list of tools available to the model
   * `_return_metrics` – Whether to return usage metrics
   * `add_security_risk_prediction` – Add security_risk field to tool schemas
   * `on_token` – Optional callback for streaming tokens
    kwargs* – Additional arguments passed to the LLM API
 * Returns:
   LLMResponse containing the model’s response and metadata.
 
 #### NOTE
 Summary field is always added to tool schemas for transparency and
 explainability of agent actions.
 
 * Raises:
   `ValueError` – If streaming is requested (not supported).
@@ -212,11 +223,11 @@
 
 Prepare (instructions, input[]) for the OpenAI Responses API.
 
 - Skips prompt caching flags and string serializer concerns
 - Uses Message.to_responses_value to get either instructions (system)
   or input items (others)
 - Concatenates system instructions into a single instructions string
 - For subscription mode, system prompts are prepended to user content
 
 #### get_token_count()
 
@@ -230,9 +241,9 @@
 * Return type:
   boolean
 
 #### classmethod load_from_env()
 
 #### classmethod load_from_json()
 
 #### model_post_init()
 
@@ -248,9 +259,9 @@
 
 Reset metrics and telemetry to fresh instances.
 
 This is used by the LLMRegistry to ensure each registered LLM has
 independent metrics, preventing metrics from being shared between
 LLMs that were created via model_copy().
 
 When an LLM is copied (e.g., to create a condenser LLM from an agent LLM),
 Pydantic’s model_copy() does a shallow copy of private attributes by default,
@@ -262,7 +273,7 @@
 
 Alternative invocation path using OpenAI Responses API via LiteLLM.
 
 Maps Message[] -> (instructions, input[]) and returns LLMResponse.
 
 * Parameters:
   * `messages` – List of conversation messages
@@ -270,17 +281,17 @@
   * `include` – Optional list of fields to include in response
   * `store` – Whether to store the conversation
   * `_return_metrics` – Whether to return usage metrics
   * `add_security_risk_prediction` – Add security_risk field to tool schemas
   * `on_token` – Optional callback for streaming deltas
    kwargs* – Additional arguments passed to the API
 
 #### NOTE
 Summary field is always added to tool schemas for transparency and
 explainability of agent actions.
 
 #### restore_metrics()
 
 #### classmethod subscription_login()
 
 Authenticate with a subscription service and return an LLM instance.
 
@@ -290,7 +301,7 @@
 the OAuth login flow.
 
 Currently supported vendors:
 - “openai”: ChatGPT Plus/Pro subscription for Codex models
 
 Supported OpenAI models:
 - gpt-5.1-codex-max
@@ -299,7 +310,7 @@
 - gpt-5.2-codex
 
 * Parameters:
   * `vendor` – The vendor/provider. Currently only “openai” is supported.
   * `model` – The model to use. Must be supported by the vendor’s
     subscription service.
   * `force_login` – If True, always perform a fresh login even if valid
@@ -380,17 +391,17 @@
 * Raises:
   `TimeoutError` – If the lock cannot be acquired.
 
 ### class LLMRegistry
 
 Bases: `object`
 
 A minimal LLM registry for managing LLM instances by usage ID.
 
 This registry provides a simple way to manage multiple LLM instances,
 avoiding the need to recreate LLMs with the same configuration.
 
 The registry also ensures that each registered LLM has independent metrics,
 preventing metrics from being shared between LLMs that were created via
 model_copy(). This is important for scenarios like creating a condenser LLM
 from an agent LLM, where each should track its own usage independently.
 
@@ -435,7 +446,7 @@
 * Returns:
   The LLM instance.
 * Raises:
   `KeyError` – If usage_id is not found in the registry.
 
 #### list_usage_ids()
 
@@ -453,9 +464,9 @@
 Subscribe to registry events.
 
 * Parameters:
   `callback` – Function to call when LLMs are created or updated.
 
 ### class LLMResponse
 
 Bases: `BaseModel`
 
@@ -497,7 +508,7 @@
 * Type:
   [openhands.sdk.llm.utils.metrics.MetricsSnapshot](#class-metricssnapshot)
 
 #### raw_response
 
 The original LiteLLM response (ModelResponse or
 ResponsesAPIResponse) for internal use
@@ -526,21 +537,21 @@
 
 #### Methods
 
 #### classmethod from_llm_chat_message()
 
 Convert a LiteLLMMessage (Chat Completions) to our Message class.
 
 Provider-agnostic mapping for reasoning:
 - Prefer message.reasoning_content if present (LiteLLM normalized field)
 - Extract thinking_blocks from content array (Anthropic-specific)
 
 #### classmethod from_llm_responses_output()
 
 Convert OpenAI Responses API output items into a single assistant Message.
 
 Policy (non-stream):
 - Collect assistant text by concatenating output_text parts from message items
 - Normalize function_call items to MessageToolCall list
 
 #### to_chat_dict()
 
@@ -550,10 +561,10 @@
   * `cache_enabled` – Whether prompt caching is active.
   * `vision_enabled` – Whether vision/image processing is enabled.
   * `function_calling_enabled` – Whether native function calling is enabled.
   * `force_string_serializer` – Force string serializer instead of list format.
   * `send_reasoning_content` – Whether to include reasoning_content in output.
 
 Chooses the appropriate content serializer and then injects threading keys:
 - Assistant tool call turn: role == “assistant” and self.tool_calls
 - Tool result turn: role == “tool” and self.tool_call_id (with name)
 
@@ -563,12 +574,12 @@
 
 Produces a list of “input” items for the Responses API:
 - system: returns [], system content is expected in ‘instructions’
 - user: one ‘message’ item with content parts -> input_text / input_image
 (when vision enabled)
 - assistant: emits prior assistant content as input_text,
 and function_call items for tool_calls
 - tool: emits function_call_output items (one per TextContent)
 with matching call_id
 
 #### to_responses_value()
 
@@ -583,7 +594,7 @@
 Transport-agnostic tool call representation.
 
 One canonical id is used for linking across actions/observations and
 for Responses function_call_output call_id.
 
 
 #### Properties
@@ -598,27 +609,27 @@
 
 #### Methods
 
 #### classmethod from_chat_tool_call()
 
 Create a MessageToolCall from a Chat Completions tool call.
 
 #### classmethod from_responses_function_call()
 
 Create a MessageToolCall from a typed OpenAI Responses function_call item.
 
 Note: OpenAI Responses function_call.arguments is already a JSON string.
 
 #### model_config = (configuration object)
 
 Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
 
 #### to_chat_dict()
 
 Serialize to OpenAI Chat Completions tool_calls format.
 
 #### to_responses_dict()
 
 Serialize to OpenAI Responses ‘function_call’ input item format.
 
 #### add_cost()
 
@@ -661,11 +672,11 @@
 
 Merge ‘other’ metrics into this one.
 
 #### model_config = (configuration object)
 
 Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
 
 #### classmethod validate_accumulated_cost()
 
 ### class MetricsSnapshot
 
@@ -685,7 +696,7 @@
 
 #### Methods
 
 #### model_config = (configuration object)
 
 Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
 
@@ -710,7 +721,7 @@
 
 Check if the access token is expired.
 
 #### model_config = (configuration object)
 
 Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
 
@@ -795,7 +806,7 @@
 
 OpenAI Responses reasoning item (non-stream, subset we consume).
 
 Do not log or render encrypted_content.
 
 
 #### Properties
@@ -808,7 +819,7 @@
 
 #### Methods
 
 #### model_config = (configuration object)
 
 Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
 
@@ -829,7 +840,7 @@
 
 #### Methods
 
 #### model_config = (configuration object)
 
 Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
 
@@ -852,7 +863,7 @@
 inheriting from LLM, allowing routers to work with multiple underlying
 LLM models while presenting a unified LLM interface to consumers.
 Key features:
 - Works with multiple LLMs configured via llms_for_routing
 - Delegates all other operations/properties to the selected LLM
 - Provides routing interface through select_llm() method
 
@@ -876,13 +887,13 @@
   * `messages` – List of conversation messages
   * `tools` – Optional list of tools available to the model
   * `return_metrics` – Whether to return usage metrics
   * `add_security_risk_prediction` – Add security_risk field to tool schemas
   * `on_token` – Optional callback for streaming tokens
    kwargs* – Additional arguments passed to the LLM API
 
 #### NOTE
 Summary field is always added to tool schemas for transparency and
 explainability of agent actions.
 
 #### model_post_init()
 
@@ -894,25 +905,25 @@
   * `self` – The BaseModel instance.
   * `context` – The context.
 
 #### abstractmethod select_llm()
 
 Select which LLM to use based on messages and events.
 
 This method implements the core routing logic for the RouterLLM.
 Subclasses should analyze the provided messages to determine which
 LLM from llms_for_routing is most appropriate for handling the request.
 
 * Parameters:
   `messages` – List of messages in the conversation that can be used
   to inform the routing decision.
 * Returns:
   The key/name of the LLM to use from llms_for_routing dictionary.
 
 #### classmethod set_placeholder_model()
 
 Guarantee model exists before LLM base validation runs.
 
 #### classmethod validate_llms_not_empty()
 
 ### class TextContent
 
@@ -951,6 +962,6 @@
 
 #### Methods
 
 #### model_config = (configuration object)
 
 Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

sdk/api-reference/openhands.sdk.utils.mdx

@@ -6,6 +6,21 @@
 
 Utility functions for the OpenHands SDK.
 
+
+## Import shortcuts
+
+`page_iterator` is publicly exported from `openhands.sdk.utils` and from the top-level `openhands.sdk` package.
+
+```python
+from openhands.sdk.utils import page_iterator
+# or
+from openhands.sdk import page_iterator
+```
+
+### page_iterator()
+
+Iterate over items from paginated search results.
+
 ### deprecated()
 
 Return a decorator that deprecates a callable with explicit metadata.
@@ -60,15 +75,15 @@
 
 Return a copy of env with sanitized values.
 
 PyInstaller-based binaries rewrite `LD_LIBRARY_PATH` so their vendored
 libraries win. This function restores the original value so that subprocess
 will not use them.
 
 ### warn_deprecated()
 
 Emit a deprecation warning for dynamic access to a legacy feature.
 
 Prefer this helper when a decorator is not practical—e.g. attribute accessors,
 data migrations, or other runtime paths that must conditionally warn. Provide
 explicit version metadata so the SDK reports consistent messages and upgrades
 to `deprecation.UnsupportedWarning` after the removal threshold.

sdk/api-reference/openhands.sdk.workspace.mdx

@@ -4,13 +4,24 @@
 ---
 
 
+## Import shortcuts
+
+`AsyncRemoteWorkspace` is publicly exported from `openhands.sdk.workspace.remote`, `openhands.sdk.workspace`, and the top-level `openhands.sdk` package.
+
+```python
+from openhands.sdk.workspace import AsyncRemoteWorkspace
+# or
+from openhands.sdk import AsyncRemoteWorkspace
+```
+
+
 ### class BaseWorkspace
 
 Bases: `DiscriminatedUnionMixin`, `ABC`
 
 Abstract base class for workspace implementations.
 
 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.
 
@@ -29,7 +40,7 @@
 
 #### Methods
 
 #### abstractmethod execute_command()
 
 Execute a bash command on the system.
 
@@ -38,14 +49,14 @@
   * `cwd` – Working directory for the command (optional)
   * `timeout` – Timeout in seconds (defaults to 30.0)
 * Returns:
   Result containing stdout, stderr, exit_code, and other
   : metadata
 * Return type:
   [CommandResult](#class-commandresult)
 * Raises:
   `Exception` – If command execution fails
 
 #### abstractmethod file_download()
 
 Download a file from the system.
 
@@ -59,7 +70,7 @@
 * Raises:
   `Exception` – If file download fails
 
 #### abstractmethod file_upload()
 
 Upload a file to the system.
 
@@ -73,7 +84,7 @@
 * Raises:
   `Exception` – If file upload fails
 
 #### abstractmethod git_changes()
 
 Get the git changes for the repository at the path given.
 
@@ -86,7 +97,7 @@
 * Raises:
   `Exception` – If path is not a git repository or getting changes failed
 
 #### abstractmethod git_diff()
 
 Get the git diff for the file at the path given.
 
@@ -99,7 +110,7 @@
 * Raises:
   `Exception` – If path is not a git repository or getting diff failed
 
 #### model_config = (configuration object)
 
 Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
 
@@ -140,7 +151,7 @@
 
 #### Methods
 
 #### model_config = (configuration object)
 
 Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
 
@@ -161,7 +172,7 @@
 
 #### Methods
 
 #### model_config = (configuration object)
 
 Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
 
@@ -207,8 +218,8 @@
   * `cwd` – Working directory (optional)
   * `timeout` – Timeout in seconds
 * Returns:
   Result with stdout, stderr, exit_code, command, and
   : timeout_occurred
 * Return type:
   [CommandResult](#class-commandresult)
 
@@ -268,7 +279,7 @@
 * Raises:
   `Exception` – If path is not a git repository or getting diff failed
 
 #### model_config = (configuration object)
 
 Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
 
@@ -292,7 +303,7 @@
 
 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.
 
@@ -331,7 +342,7 @@
   * `cwd` – Working directory (optional)
   * `timeout` – Timeout in seconds
 * Returns:
   Result with stdout, stderr, exit_code, and other metadata
 * Return type:
   [CommandResult](#class-commandresult)
 
@@ -389,20 +400,20 @@
 * Raises:
   `Exception` – If path is not a git repository or getting diff failed
 
 #### model_config = (configuration object)
 
 Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
 
 #### model_post_init()
 
 Override this method to perform additional initialization after __init__ and model_construct.
 This is useful if you want to do some validation that requires the entire model to be initialized.
 
 #### reset_client()
 
 Reset the HTTP client to force re-initialization.
 
 This is useful when connection parameters (host, api_key) have changed
 and the client needs to be recreated with new values.
 
 ### class Workspace