Add minimal config & port over the LLM class (#12)

Author: xingyaoww

openhands/core/config/__init__.py

@@ -0,0 +1,4 @@
+from .openhands_config import OpenHandsConfig
+from .llm_config import LLMConfig
+
+__all__ = ["OpenHandsConfig", "LLMConfig"]

openhands/core/config/llm_config.py

@@ -0,0 +1,132 @@
+import os
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr
+
+
+from openhands.core.logger import get_logger, ENV_LOG_DIR
+
+logger = get_logger(__name__)
+
+
+class LLMConfig(BaseModel):
+    """Configuration for the LLM model.
+
+    Attributes:
+        model: The model to use.
+        api_key: The API key to use.
+        base_url: The base URL for the API. This is necessary for local LLMs.
+        api_version: The version of the API.
+        aws_access_key_id: The AWS access key ID.
+        aws_secret_access_key: The AWS secret access key.
+        aws_region_name: The AWS region name.
+        num_retries: The number of retries to attempt.
+        retry_multiplier: The multiplier for the exponential backoff.
+        retry_min_wait: The minimum time to wait between retries, in seconds. This is exponential backoff minimum. For models with very low limits, this can be set to 15-20.
+        retry_max_wait: The maximum time to wait between retries, in seconds. This is exponential backoff maximum.
+        timeout: The timeout for the API.
+        max_message_chars: The approximate max number of characters in the content of an event included in the prompt to the LLM. Larger observations are truncated.
+        temperature: The temperature for the API.
+        top_p: The top p for the API.
+        top_k: The top k for the API.
+        custom_llm_provider: The custom LLM provider to use. This is undocumented in openhands, and normally not used. It is documented on the litellm side.
+        max_input_tokens: The maximum number of input tokens. Note that this is currently unused, and the value at runtime is actually the total tokens in OpenAI (e.g. 128,000 tokens for GPT-4).
+        max_output_tokens: The maximum number of output tokens. This is sent to the LLM.
+        input_cost_per_token: The cost per input token. This will available in logs for the user to check.
+        output_cost_per_token: The cost per output token. This will available in logs for the user to check.
+        ollama_base_url: The base URL for the OLLAMA API.
+        drop_params: Drop any unmapped (unsupported) params without causing an exception.
+        modify_params: Modify params allows litellm to do transformations like adding a default message, when a message is empty.
+        disable_vision: If model is vision capable, this option allows to disable image processing (useful for cost reduction).
+        caching_prompt: Use the prompt caching feature if provided by the LLM and supported by the provider.
+        log_completions: Whether to log LLM completions to the state.
+        log_completions_folder: The folder to log LLM completions to. Required if log_completions is True.
+        custom_tokenizer: A custom tokenizer to use for token counting.
+        native_tool_calling: Whether to use native tool calling if supported by the model. Can be True, False, or not set.
+        reasoning_effort: The effort to put into reasoning. This is a string that can be one of 'low', 'medium', 'high', or 'none'. Can apply to all reasoning models.
+        seed: The seed to use for the LLM.
+        safety_settings: Safety settings for models that support them (like Mistral AI and Gemini).
+    """
+
+    model: str = Field(default="claude-sonnet-4-20250514")
+    api_key: SecretStr | None = Field(default=None)
+    base_url: str | None = Field(default=None)
+    api_version: str | None = Field(default=None)
+    aws_access_key_id: SecretStr | None = Field(default=None)
+    aws_secret_access_key: SecretStr | None = Field(default=None)
+    aws_region_name: str | None = Field(default=None)
+    openrouter_site_url: str = Field(default="https://docs.all-hands.dev/")
+    openrouter_app_name: str = Field(default="OpenHands")
+    # total wait time: 8 + 16 + 32 + 64 = 120 seconds
+    num_retries: int = Field(default=5)
+    retry_multiplier: float = Field(default=8)
+    retry_min_wait: int = Field(default=8)
+    retry_max_wait: int = Field(default=64)
+    timeout: int | None = Field(default=None)
+    max_message_chars: int = Field(
+        default=30_000
+    )  # maximum number of characters in an observation's content when sent to the llm
+    temperature: float = Field(default=0.0)
+    top_p: float = Field(default=1.0)
+    top_k: float | None = Field(default=None)
+    custom_llm_provider: str | None = Field(default=None)
+    max_input_tokens: int | None = Field(default=None)
+    max_output_tokens: int | None = Field(default=None)
+    input_cost_per_token: float | None = Field(default=None)
+    output_cost_per_token: float | None = Field(default=None)
+    ollama_base_url: str | None = Field(default=None)
+    # This setting can be sent in each call to litellm
+    drop_params: bool = Field(default=True)
+    # Note: this setting is actually global, unlike drop_params
+    modify_params: bool = Field(default=True)
+    disable_vision: bool | None = Field(default=None)
+    disable_stop_word: bool | None = Field(default=False)
+    caching_prompt: bool = Field(default=True)
+    log_completions: bool = Field(default=False)
+    log_completions_folder: str = Field(
+        default=os.path.join(ENV_LOG_DIR, "completions")
+    )
+    custom_tokenizer: str | None = Field(default=None)
+    native_tool_calling: bool | None = Field(default=None)
+    reasoning_effort: str | None = Field(default=None)
+    seed: int | None = Field(default=None)
+    safety_settings: list[dict[str, str]] | None = Field(
+        default=None,
+        description="Safety settings for models that support them (like Mistral AI and Gemini)",
+    )
+
+    model_config = ConfigDict(extra="forbid")
+
+    def model_post_init(self, __context: Any) -> None:
+        """Post-initialization hook to assign OpenRouter-related variables to environment variables.
+
+        This ensures that these values are accessible to litellm at runtime.
+        """
+        super().model_post_init(__context)
+
+        # Assign OpenRouter-specific variables to environment variables
+        if self.openrouter_site_url:
+            os.environ["OR_SITE_URL"] = self.openrouter_site_url
+        if self.openrouter_app_name:
+            os.environ["OR_APP_NAME"] = self.openrouter_app_name
+
+        # Set reasoning_effort to 'high' by default for non-Gemini models
+        # Gemini models use optimized thinking budget when reasoning_effort is None
+        if self.reasoning_effort is None and "gemini-2.5-pro" not in self.model:
+            self.reasoning_effort = "high"
+
+        # Set an API version by default for Azure models
+        # Required for newer models.
+        # Azure issue: https://github.com/All-Hands-AI/OpenHands/issues/7755
+        if self.model.startswith("azure") and self.api_version is None:
+            self.api_version = "2024-12-01-preview"
+
+        # Set AWS credentials as environment variables for LiteLLM Bedrock
+        if self.aws_access_key_id:
+            os.environ["AWS_ACCESS_KEY_ID"] = self.aws_access_key_id.get_secret_value()
+        if self.aws_secret_access_key:
+            os.environ["AWS_SECRET_ACCESS_KEY"] = (
+                self.aws_secret_access_key.get_secret_value()
+            )
+        if self.aws_region_name:
+            os.environ["AWS_REGION_NAME"] = self.aws_region_name

openhands/core/config/openhands_config.py

@@ -0,0 +1,29 @@
+from pydantic import BaseModel, ConfigDict, Field
+
+from openhands.core.config.llm_config import LLMConfig
+
+from openhands.core.logger import get_logger
+
+logger = get_logger(__name__)
+
+OH_DEFAULT_AGENT = "CodeActAgent"
+OH_MAX_ITERATIONS = 500
+
+
+class OpenHandsConfig(BaseModel):
+    """Configuration for the app."""
+
+    llm: LLMConfig = Field(default_factory=LLMConfig)
+    secondary_llm: LLMConfig | None = Field(
+        default=None,
+        description="Secondary LLM config, used for tasks like summarization or verification.",
+    )
+    workspace_base: str | None = Field(
+        default="./workspace",
+        description="Path to launch the agent workspace from. Relative paths are relative to the current working directory.",
+    )
+    max_iterations: int = Field(
+        default=OH_MAX_ITERATIONS,
+        description="Maximum number of iterations the agent can perform.",
+    )
+    model_config = ConfigDict(extra="forbid")

openhands/core/llm/__init__.py

@@ -0,0 +1,3 @@
+from .llm import LLM
+
+__all__ = ["LLM"]

openhands/core/llm/exceptions.py

@@ -0,0 +1,103 @@
+class LLMError(Exception):
+    """Base class for all LLM-related exceptions."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+    def __str__(self) -> str:
+        return self.message
+
+
+class LLMMalformedActionError(LLMError):
+    """Exception raised when the LLM response is malformed or does not conform to the expected format."""
+
+    def __init__(self, message: str = "Malformed response") -> None:
+        super().__init__(message)
+
+
+class LLMNoActionError(LLMError):
+    """Exception raised when the LLM response does not include an action."""
+
+    def __init__(self, message: str = "Agent must return an action") -> None:
+        super().__init__(message)
+
+
+class LLMResponseError(LLMError):
+    """Exception raised when the LLM response does not include an action or the action is not of the expected type."""
+
+    def __init__(
+        self, message: str = "Failed to retrieve action from LLM response"
+    ) -> None:
+        super().__init__(message)
+
+
+class LLMNoResponseError(LLMError):
+    """Exception raised when the LLM does not return a response, typically seen in Gemini models.
+
+    This exception should be retried
+    Typically, after retry with a non-zero temperature, the LLM will return a response
+    """
+
+    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 turning on enable_history_truncation config to avoid this error",
+    ) -> None:
+        super().__init__(message)
+
+
+# ============================================
+# LLM function calling Exceptions
+# ============================================
+
+
+class FunctionCallConversionError(LLMError):
+    """Exception raised when FunctionCallingConverter failed to convert a non-function call message to a function call message.
+
+    This typically happens when there's a malformed message (e.g., missing <function=...> tags). But not due to LLM output.
+    """
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class FunctionCallValidationError(LLMError):
+    """Exception raised when FunctionCallingConverter failed to validate a function call message.
+
+    This typically happens when the LLM outputs unrecognized function call / parameter names / values.
+    """
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class FunctionCallNotExistsError(LLMError):
+    """Exception raised when an LLM call a tool that is not registered."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+# ============================================
+# Other Exceptions
+# ============================================
+
+
+class UserCancelledError(Exception):
+    def __init__(self, message: str = "User cancelled the request") -> None:
+        super().__init__(message)
+
+
+class OperationCancelled(Exception):
+    """Exception raised when an operation is cancelled (e.g. by a keyboard interrupt)."""
+
+    def __init__(self, message: str = "Operation was cancelled") -> None:
+        super().__init__(message)