android-midscene-automation 0.2.4 → 1.1.1

package/artemis-main/artemis/config/constants.py

@@ -0,0 +1,151 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Centralized constants, environment variable names, and type definitions for ARTEMIS."""
+
+from typing import Literal
+
+# ==============================================================================
+# Environment Variable Keys
+# ==============================================================================
+
+# Application & Workspace Paths
+ENV_ARTEMIS_APP_DIR = "ARTEMIS_APP_DIR"
+ENV_ANTIGRAVITY_APP_DIR = "ANTIGRAVITY_APP_DIR"
+ENV_ARTEMIS_USE_USER_DIR = "ARTEMIS_USE_USER_DIR"
+ENV_ARTEMIS_TRACES_DIR = "ARTEMIS_TRACES_DIR"
+ENV_DATA_ENGINE_DB_PATH = "DATA_ENGINE_DB_PATH"
+
+# Cloud Brain & Distributed Execution
+ENV_ARTEMIS_CLOUD_MODE = "ARTEMIS_CLOUD_MODE"
+ENV_ARTEMIS_CLOUD_SESSION_ID = "ARTEMIS_CLOUD_SESSION_ID"
+ENV_ARTEMIS_CLOUD_GATEWAY_URL = "ARTEMIS_CLOUD_GATEWAY_URL"
+ENV_ARTEMIS_TENANT_ID = "ARTEMIS_TENANT_ID"
+ENV_ARTEMIS_TENANT_TOKEN = "ARTEMIS_TENANT_TOKEN"
+ENV_ARTEMIS_EDGE_PORT = "ARTEMIS_EDGE_PORT"
+
+# Runtime State & IPC
+ENV_ARTEMIS_IPC_PORT = "ARTEMIS_IPC_PORT"
+ENV_ANTIGRAVITY_LS_ADDRESS = "ANTIGRAVITY_LS_ADDRESS"
+ENV_ARTEMIS_MCP_SERVER = "ARTEMIS_MCP_SERVER"
+
+# Device & ADB
+ENV_ADB_DEVICE_SERIAL = "ADB_DEVICE_SERIAL"
+ENV_ARTEMIS_DEVICE_ID = "ARTEMIS_DEVICE_ID"
+ENV_ADB_HOST = "ADB_HOST"
+ENV_ADB_PORT = "ADB_PORT"
+ENV_ADB_SERVER_SOCKET = "ADB_SERVER_SOCKET"
+# UI hierarchy backend: "auto" (helper, UIAutomator2 fallback), "helper", "uiautomator"
+ENV_ARTEMIS_HIERARCHY_BACKEND = "ARTEMIS_HIERARCHY_BACKEND"
+# "true" (default) lets a task install / upgrade the Accessibility Helper APK on a
+# device it holds; "false" only attaches to a helper someone installed by hand.
+ENV_ARTEMIS_HELPER_AUTO_INSTALL = "ARTEMIS_HELPER_AUTO_INSTALL"
+
+# LLM & Vision OCR API Keys
+ENV_GOOGLE_API_KEY = "GOOGLE_API_KEY"
+ENV_GEMINI_API_KEY = "GEMINI_API_KEY"
+ENV_GCP_API_KEY = "GCP_API_KEY"
+ENV_OCR_API_KEY = "OCR_API_KEY"
+ENV_VISION_API_KEY = "VISION_API_KEY"
+ENV_API_KEY = "API_KEY"
+ENV_OPENAI_API_KEY = "OPENAI_API_KEY"
+ENV_OPENAI_BASE_URL = "OPENAI_BASE_URL"
+ENV_ANTHROPIC_API_KEY = "ANTHROPIC_API_KEY"
+ENV_OPEN_ROUTER_API_KEY = "OPEN_ROUTER_API_KEY"
+ENV_XAI_API_KEY = "XAI_API_KEY"
+
+# Explorer & Agent Defaults
+ENV_ARTEMIS_EXPLORER_VERSION = "ARTEMIS_EXPLORER_VERSION"
+ENV_ARTEMIS_DEFAULT_PROFILE = "ARTEMIS_DEFAULT_PROFILE"
+ENV_ARTEMIS_DEFAULT_MODEL = "ARTEMIS_DEFAULT_MODEL"
+ENV_ARTEMIS_USE_FILE_API = "ARTEMIS_USE_FILE_API"
+
+# Debugging & Output Paths
+ENV_KEEP_VIDEOS = "KEEP_VIDEOS"
+ENV_ARTEMIS_DEBUG = "ARTEMIS_DEBUG"
+ENV_EVENTS_OUTPUT_PATH = "EVENTS_OUTPUT_PATH"
+ENV_RESULTS_OUTPUT_PATH = "RESULTS_OUTPUT_PATH"
+
+
+# ==============================================================================
+# Configuration Filenames
+# ==============================================================================
+
+ARTEMIS_CONFIG_FILENAME = "artemis.jsonc"
+LLM_CONFIG_FILENAME = "llm-config.json"
+LLM_CONFIG_OVERRIDE_FILENAME = "llm-config.override.jsonc"
+AGENT_CONFIG_FILENAME = "agent_config.json"
+DATA_ENGINE_DB_FILENAME = "data_engine.db"
+IPC_PORT_FILENAME = ".artemis_ipc_port"
+LS_ADDRESS_FILENAME = ".jetski_ls_address"
+SERVER_INFO_FILENAME = ".artemis_server.json"
+PAUSE_FILENAME = ".artemis_paused"
+REPLAY_DIRNAME = "replay"
+TEST_DATA_DIRNAME = "data"
+TEST_OUTPUTS_DIRNAME = "outputs"
+IMAGES_DIRNAME = "images"
+DOTENV_FILENAME = ".env"
+
+
+# ==============================================================================
+# Default Values & Network Ports
+# ==============================================================================
+
+DEFAULT_ADB_HOST = "127.0.0.1"
+DEFAULT_ADB_PORT = 5037
+DEFAULT_GATEWAY_PORT = 8000
+DEFAULT_EDGE_MONITOR_PORT = 8000
+DEFAULT_ACTION_TIMEOUT = 30.0
+DEFAULT_STREAM_PING_INTERVAL = 15.0
+
+DEFAULT_PROFILE = "pro"
+DEFAULT_MODEL = "gemini-2.5-flash"
+DEFAULT_EXPLORER_VERSION: Literal["flash", "pro", "ultra"] = "flash"
+
+
+# ==============================================================================
+# Literals and Type Aliases
+# ==============================================================================
+
+LLMProvider = Literal[
+    "openai", "google", "openrouter", "xai", "vertexai", "anthropic", "ollama", "vllm", "custom"
+]
+ExplorerVersion = Literal["flash", "pro", "ultra"]
+
+LLMUtilsNode = Literal[
+    "outputter",
+    "hopper",
+    "video_analyzer",
+    "object_detector",
+]
+
+AgentNode = Literal[
+    "planner",
+    "summarizer",
+    "operator",
+    "operator_summarizer",
+    "log_reader_sub_agent",
+    "log_analyzer",
+    "diagnoser",
+    "checker",
+    "planner_avatar",
+    "history_analyzer_expert",
+    "diagnoser_expert",
+    "explorer",
+    "history_analyzer",
+    "validator_pixel_safety_net",
+    "planner_validation",
+    "validator",
+    "output_analyzer",
+]

package/artemis-main/artemis/config/core/__init__.py

@@ -0,0 +1,24 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Artemis unified configuration core."""
+
+from artemis.config.core.engine import CascadingConfigEngine, config_engine
+from artemis.config.core.interpolator import interpolate_config_value
+
+__all__ = [
+    "CascadingConfigEngine",
+    "config_engine",
+    "interpolate_config_value",
+]

package/artemis-main/artemis/config/core/engine.py

@@ -0,0 +1,118 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Multi-source Cascading Configuration Engine."""
+
+import json
+from pathlib import Path
+import re
+from typing import Any
+
+from dotenv import load_dotenv
+
+from artemis.config.core.interpolator import interpolate_config_value
+from artemis.platform import platform
+from third_party.mobile_use.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def _strip_json_comments(text: str) -> str:
+    """Strip // and /* */ comments from JSONC text while preserving string literals."""
+    pattern = r'//.*?$|/\*.*?\*/|\'(?:\\.|[^\\\'])*\'|"(?:\\.|[^\\"])*"'
+
+    def replacer(match: re.Match) -> str:
+        s = match.group(0)
+        if s.startswith("/"):
+            return ""
+        return s
+
+    return re.sub(pattern, replacer, text, flags=re.DOTALL | re.MULTILINE)
+
+
+def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Recursively deep merge two dictionaries."""
+    merged = base.copy()
+    for key, value in override.items():
+        if key in merged and isinstance(merged[key], dict) and isinstance(value, dict):
+            merged[key] = _deep_merge(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
+class CascadingConfigEngine:
+    """Manages 5-tier configuration hierarchy with automatic cascade and interpolation."""
+
+    def __init__(self, workspace_root: Path | None = None):
+        self.workspace_root = workspace_root or Path.cwd()
+        self._load_environment_files()
+
+    def _load_environment_files(self) -> None:
+        """Load .env files from global config dir and workspace root."""
+        # 1. Global user .env
+        global_env = platform.paths.config_dir / ".env"
+        if global_env.exists():
+            load_dotenv(dotenv_path=global_env, override=False, encoding="utf-8")
+
+        # 2. Legacy ~/.artemis/.env fallback
+        legacy_env = platform.paths.data_dir / ".env"
+        if legacy_env.exists() and legacy_env != global_env:
+            load_dotenv(dotenv_path=legacy_env, override=False, encoding="utf-8")
+
+        # 3. Workspace .env
+        ws_env = self.workspace_root / ".env"
+        if ws_env.exists():
+            load_dotenv(dotenv_path=ws_env, override=True, encoding="utf-8")
+
+    def load_raw_config(
+        self,
+        cli_overrides: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Load and merge all config layers into a unified dictionary."""
+        config: dict[str, Any] = {}
+
+        # Tier 1: Global user configuration ($CONFIG_DIR/artemis.jsonc)
+        global_config_path = platform.paths.config_dir / "artemis.jsonc"
+        if global_config_path.exists():
+            try:
+                raw_text = global_config_path.read_text(encoding="utf-8")
+                cleaned = _strip_json_comments(raw_text)
+                config = _deep_merge(config, json.loads(cleaned))
+            except Exception as e:
+                logger.warning(f"Failed to load global config {global_config_path}: {e}")
+
+        # Tier 2: Workspace project configuration (config/artemis.jsonc)
+        ws_config_path = self.workspace_root / "config" / "artemis.jsonc"
+        if not ws_config_path.exists():
+            ws_config_path = self.workspace_root / "artemis.jsonc"
+
+        if ws_config_path.exists():
+            try:
+                raw_text = ws_config_path.read_text(encoding="utf-8")
+                cleaned = _strip_json_comments(raw_text)
+                config = _deep_merge(config, json.loads(cleaned))
+            except Exception as e:
+                logger.warning(f"Failed to load workspace config {ws_config_path}: {e}")
+
+        # Tier 3: CLI overrides
+        if cli_overrides:
+            config = _deep_merge(config, cli_overrides)
+
+        # Apply variable interpolation across merged dictionary
+        interpolated = interpolate_config_value(config, workspace_root=self.workspace_root)
+        return interpolated
+
+
+config_engine = CascadingConfigEngine()

package/artemis-main/artemis/config/core/interpolator.py

@@ -0,0 +1,78 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Dynamic configuration variable interpolation engine (${env:VAR}, ${path:NAME})."""
+
+import os
+from pathlib import Path
+import re
+from typing import Any
+
+from artemis.platform import platform
+
+_VAR_PATTERN = re.compile(r"\$\{([^}]+)\}")
+
+
+def _resolve_variable(expr: str, workspace_root: Path | None = None) -> str:
+    """Resolve a single ${namespace:key:-default} expression."""
+    expr = expr.strip()
+    namespace, _, rest = expr.partition(":")
+    if not rest:
+        # Defaults to environment variable lookup
+        return os.getenv(namespace, f"${{{expr}}}")
+
+    key, _, default = rest.partition(":-")
+
+    if namespace == "env":
+        return os.getenv(key, default)
+    elif namespace == "path":
+        paths = platform.paths
+        if key == "config_dir":
+            return str(paths.config_dir)
+        elif key == "data_dir":
+            return str(paths.data_dir)
+        elif key == "cache_dir":
+            return str(paths.cache_dir)
+        elif key == "logs_dir":
+            return str(paths.logs_dir)
+        elif key == "temp_dir":
+            return str(paths.temp_dir())
+        elif key == "workspace_root" or key == "root_dir":
+            return str(workspace_root or Path.cwd())
+        return default or f"${{{expr}}}"
+    elif namespace == "platform":
+        if key == "os_type":
+            return platform.os_type.value
+        elif key == "path_sep":
+            return platform.process.path_separator
+        return default or f"${{{expr}}}"
+
+    return os.getenv(expr, default or f"${{{expr}}}")
+
+
+def interpolate_config_value(val: Any, workspace_root: Path | None = None) -> Any:
+    """Recursively interpolate strings, lists, and dicts containing ${...} variables."""
+    if isinstance(val, str):
+        if "${" not in val:
+            return val
+
+        def replacer(match: re.Match) -> str:
+            return _resolve_variable(match.group(1), workspace_root)
+
+        return _VAR_PATTERN.sub(replacer, val)
+    elif isinstance(val, dict):
+        return {k: interpolate_config_value(v, workspace_root) for k, v in val.items()}
+    elif isinstance(val, list):
+        return [interpolate_config_value(item, workspace_root) for item in val]
+    return val

package/artemis-main/artemis/config/llm.py

@@ -0,0 +1,267 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""LLM provider, model hierarchy, fallback chaining, and configuration loaders."""
+
+from pathlib import Path
+from typing import Any
+
+
+from artemis.config.constants import (
+    LLM_CONFIG_FILENAME,
+    AgentNode,
+)
+from artemis.config.paths import ROOT_DIR, get_config_path
+from artemis.utils.cython_compat import CyFunctionDetector
+from third_party.mobile_use.config import llm as base_llm_config
+from third_party.mobile_use.config.llm import (
+    LLM,
+    AgentNodeWithFallback,
+    LLMConfigBase,
+    LLMConfigUtils,
+    LLMUtilsNodeWithFallback,
+    LLMWithFallback,
+    validate_vertex_ai_credentials,
+)
+from third_party.mobile_use.utils.file import load_jsonc
+from third_party.mobile_use.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+__all__ = [
+    "LLM",
+    "AgentNodeWithFallback",
+    "LLMUtilsNodeWithFallback",
+    "CyFunctionDetector",
+    "LLMConfig",
+    "LLMConfigUtils",
+    "LLMWithFallback",
+    "deep_merge_llm_config",
+    "get_default_llm_config",
+    "initialize_llm_config",
+    "lightweight_judge_default",
+    "load_llm_config_override",
+    "parse_llm_config",
+    "validate_vertex_ai_credentials",
+]
+
+
+def lightweight_judge_default() -> "LLMWithFallback":
+    """Factory default for the lightweight judge nodes (pixel safety net and
+    planner validation): a flash-lite model at temperature 0."""
+    return LLMWithFallback(
+        provider="google",
+        model="gemini-3.5-flash-lite",
+        temperature=0.0,
+        fallback=LLM(
+            provider="google",
+            model="gemini-3.1-flash-lite",
+            temperature=0.0,
+        ),
+    )
+
+
+class LLMConfig(LLMConfigBase):
+    """Comprehensive LLM configuration mapping every node to primary/fallback models."""
+
+    summarizer: LLMWithFallback
+    operator: LLMWithFallback
+    operator_summarizer: LLMWithFallback
+    log_reader_sub_agent: LLMWithFallback
+    log_analyzer: LLMWithFallback
+    diagnoser: LLMWithFallback
+    checker: LLMWithFallback
+    planner_avatar: LLMWithFallback
+    history_analyzer_expert: LLMWithFallback
+    diagnoser_expert: LLMWithFallback
+    explorer: LLMWithFallback
+    history_analyzer: LLMWithFallback | None = None
+    validator_pixel_safety_net: LLMWithFallback | None = None
+    planner_validation: LLMWithFallback | None = None
+    output_analyzer: LLMWithFallback | None = None
+
+    def validate_providers(self) -> None:
+        """Validate credentials across all configured agent nodes."""
+        super().validate_providers()
+        self.summarizer.validate_provider("Summarizer")
+        self.operator.validate_provider("Operator")
+        self.operator_summarizer.validate_provider("OperatorSummarizer")
+        self.log_reader_sub_agent.validate_provider("LogReaderSubAgent")
+        self.log_analyzer.validate_provider("LogAnalyzer")
+        self.diagnoser.validate_provider("Diagnoser")
+        self.checker.validate_provider("Checker")
+        self.planner_avatar.validate_provider("PlannerAvatar")
+        self.history_analyzer_expert.validate_provider("HistoryAnalyzerExpert")
+        self.diagnoser_expert.validate_provider("DiagnoserExpert")
+        self.explorer.validate_provider("Explorer")
+        if self.history_analyzer:
+            self.history_analyzer.validate_provider("HistoryAnalyzer")
+        if self.validator_pixel_safety_net:
+            self.validator_pixel_safety_net.validate_provider("ValidatorPixelSafetyNet")
+        if self.planner_validation:
+            self.planner_validation.validate_provider("PlannerValidation")
+        if self.output_analyzer:
+            self.output_analyzer.validate_provider("OutputAnalyzer")
+
+    def get_agent(self, item: AgentNode) -> LLMWithFallback:
+        """Retrieve model configuration for a specific agent node with sensible defaults."""
+        val = getattr(self, item)
+        if val is None:
+            if item == "history_analyzer":
+                return self.operator
+            elif item in ("validator_pixel_safety_net", "planner_validation"):
+                # A non-Google installation must not require a hidden Gemini key.
+                if self.operator.provider != "google":
+                    return self.operator
+                # Both are cheap, high-frequency judges: the pixel safety net
+                # runs before actions, the planner validator after every
+                # milestone edit. They share one lightweight default.
+                return lightweight_judge_default()
+            elif item == "output_analyzer":
+                return self.log_analyzer
+        return val
+
+
+def _expand_default_into_nodes(config_dict: dict) -> dict:
+    """Expand unified config format with 'default' and 'nodes' into full LLMConfig schema."""
+    if "planner" in config_dict and "utils" in config_dict:
+        return config_dict
+
+    default_model_cfg = config_dict.get(
+        "default",
+        {
+            "provider": "google",
+            "model": "gemini-3.8-flash",
+            "fallback": {
+                "provider": "google",
+                "model": "gemini-3.7-flash",
+            },
+        },
+    )
+
+    nodes_override = config_dict.get("nodes", {})
+
+    all_agent_nodes = [
+        "planner",
+        "summarizer",
+        "operator",
+        "operator_summarizer",
+        "log_reader_sub_agent",
+        "log_analyzer",
+        "diagnoser",
+        "checker",
+        "planner_avatar",
+        "history_analyzer_expert",
+        "diagnoser_expert",
+        "explorer",
+    ]
+    for node in ("history_analyzer", "validator_pixel_safety_net", "planner_validation", "output_analyzer"):
+        if node in nodes_override or (
+            node in {"validator_pixel_safety_net", "planner_validation"}
+            and default_model_cfg.get("provider") != "google"
+        ):
+            all_agent_nodes.append(node)
+
+    all_utils_nodes = [
+        "outputter",
+        "hopper",
+        "video_analyzer",
+        "object_detector",
+    ]
+
+    result: dict[str, Any] = {}
+    for node in all_agent_nodes:
+        node_cfg = dict(default_model_cfg)
+        if node in nodes_override:
+            for k, v in nodes_override[node].items():
+                if isinstance(v, dict) and isinstance(node_cfg.get(k), dict):
+                    node_cfg[k] = {**node_cfg[k], **v}
+                else:
+                    node_cfg[k] = v
+        result[node] = node_cfg
+
+    utils_dict: dict[str, Any] = {}
+    for util in all_utils_nodes:
+        util_cfg = dict(default_model_cfg)
+        if util in nodes_override:
+            for k, v in nodes_override[util].items():
+                if isinstance(v, dict) and isinstance(util_cfg.get(k), dict):
+                    util_cfg[k] = {**util_cfg[k], **v}
+                else:
+                    util_cfg[k] = v
+        utils_dict[util] = util_cfg
+    result["utils"] = utils_dict
+
+    return result
+
+
+def parse_llm_config() -> LLMConfig:
+    """Parse and instantiate LLMConfig from artemis.jsonc or llm-config.json."""
+    config_path = None
+    for candidate in ("artemis.jsonc", "artemis.json", LLM_CONFIG_FILENAME):
+        try:
+            config_path = get_config_path(candidate)
+            break
+        except FileNotFoundError:
+            continue
+
+    if not config_path:
+        config_path = get_config_path(LLM_CONFIG_FILENAME, ROOT_DIR / LLM_CONFIG_FILENAME)
+
+    try:
+        with open(config_path, encoding="utf-8") as f:
+            config_dict = load_jsonc(f)
+            expanded_dict = _expand_default_into_nodes(config_dict)
+            return LLMConfig.model_validate(expanded_dict)
+    except Exception as e:
+        logger.error(f"Failed to load or parse llm config: {config_path}. Error: {e}")
+        raise
+
+
+def initialize_llm_config() -> LLMConfig:
+    """Parse and validate credentials for LLMConfig."""
+    return base_llm_config.initialize_llm_config(parse_llm_config)
+
+
+def get_default_llm_config() -> LLMConfig:
+    """Returns default LLMConfig parsed from standard configuration file."""
+    return parse_llm_config()
+
+
+def deep_merge_llm_config(base: LLMConfig, overrides: dict) -> LLMConfig:
+    """Recursively merge dictionary overrides into an existing LLMConfig object."""
+    base_dict = base.model_dump()
+
+    def merge(d1: dict, d2: dict) -> None:
+        for k, v in d2.items():
+            if k in d1 and isinstance(d1[k], dict) and isinstance(v, dict):
+                merge(d1[k], v)
+            else:
+                d1[k] = v
+
+    merge(base_dict, overrides)
+    return LLMConfig.model_validate(base_dict)
+
+
+def load_llm_config_override(path: Path | str) -> LLMConfig:
+    """Load custom LLM configuration JSON/JSONC overrides on top of default configuration."""
+    resolved_path = Path(path)
+    if not resolved_path.exists():
+        try:
+            resolved_path = get_config_path(str(path))
+        except OSError:
+            pass
+    return base_llm_config.load_llm_config_override(
+        resolved_path, get_default_llm_config, deep_merge_llm_config
+    )