feat(llm): add LLM profiles

.gitignore

@@ -203,3 +203,15 @@ cache
 /workspace/
 openapi.json
 .client/
+# Ignore local runtime and developer files
+.beads/*.db
+*.db
+.worktrees/
+*.code-workspace
+log.txt
+previous.md
+AGENTS.md
+CLAUDE.md
+docs/agent-sdk.workspace.code-workspace
+docs/llm-model-info-and-caps.md
+docs/llm-refactor.md

docs/llm_profiles.md

@@ -0,0 +1,42 @@
+LLM Profiles (design)
+
+Overview
+
+This document records the design decision for "LLM profiles" (named LLM configuration files) and how they map to the existing LLM model and persistence in the SDK.
+
+Key decisions
+
+- Reuse the existing LLM Pydantic model schema. A profile file is simply the JSON dump of an LLM instance (the same shape produced by LLM.model_dump(exclude_none=True) or LLM.load_from_json).
+- Storage location: ~/.openhands/llm-profiles/<profile_name>.json. The profile_name is the filename (no extension) used to refer to the profile.
+- Do not change ConversationState or Agent serialization format for now. Profiles are a convenience for creating LLM instances and registering them in the runtime LLMRegistry.
+- Secrets: do NOT store plaintext API keys in profile files by default. Prefer storing the env var name in the LLM.api_key (via LLM.load_from_env) or keep the API key in runtime SecretsManager. The ProfileManager.save_profile API will expose an include_secrets flag; default False.
+- LLM.service_id semantics: keep current behavior (a small set of runtime "usage" identifiers such as 'agent', 'condenser', 'title-gen', etc.). Do not use service_id as the profile name. We will evaluate a rename (service_id -> usage_id) in a separate task (see agent-sdk-23).
+
+ProfileManager API (summary)
+
+- list_profiles() -> list[str]
+- load_profile(name: str) -> LLM
+- save_profile(name: str, llm: LLM, include_secrets: bool = False) -> str (path)
+- register_all(registry: LLMRegistry) -> None
+
+Implementation notes
+
+- Use LLM.load_from_json(path) for loading and llm.model_dump(exclude_none=True) for saving.
+- Default directory: os.path.expanduser('~/.openhands/llm-profiles/')
+- When loading, do not inject secrets. The runtime should reconcile secrets via ConversationState/Agent resolve_diff_from_deserialized or via SecretsManager.
+- When saving, respect include_secrets flag; if False, ensure secret fields (api_key, aws_* keys) are omitted or masked.
+
+CLI
+
+- Use a single flag: --llm <profile_name> to select a profile for the agent LLM.
+- Also support an environment fallback: OPENHANDS_LLM_PROFILE.
+- Provide commands: `openhands llm list`, `openhands llm show <profile_name>` (redacts secrets).
+
+Migration
+
+- Migration from inline configs to profiles: provide a migration helper script to extract inline LLMs from ~/.openhands/agent_settings.json and conversation base_state.json into ~/.openhands/llm-profiles/<name>.json and update references (manual opt-in by user).
+
+Notes on service_id rename
+
+- There is an ongoing discussion about renaming `LLM.service_id` to a clearer name (e.g., `usage_id` or `token_tracking_id`) because `service_id` is overloaded. We will not rename immediately; agent-sdk-23 will investigate the migration and impact.
+

examples/llm-profiles/example.json

@@ -0,0 +1,11 @@
+{
+  "model": "gpt-4o-mini",
+  "base_url": "https://api.openai.com/v1",
+  "api_key": null,
+  "temperature": 0.0,
+  "max_output_tokens": 1024,
+  "service_id": "agent",
+  "metadata": {
+    "profile_description": "Example profile for local testing (no api_key stored)."
+  }
+}

openhands/sdk/conversation/impl/local_conversation.py

@@ -110,6 +110,20 @@ def _default_callback(e):
         for llm in list(self.agent.get_all_llms()):
             self.llm_registry.add(llm)
 
+        # Eagerly discover and register LLM profiles from disk so they are
+        # available through the registry (profiles are stored under
+        # ~/.openhands/llm-profiles/*.json). This keeps behavior backward
+        # compatible while making named profiles discoverable to the runtime.
+        try:
+            from openhands.sdk.llm.profile_manager import ProfileManager
+
+            ProfileManager().register_all(self.llm_registry)
+        except Exception:
+            # Do not fail conversation initialization if profile loading has problems
+            logger.debug(
+                "No LLM profiles registered or failed to load profiles", exc_info=True
+            )
+
         # Initialize secrets if provided
         if secrets:
             # Convert dict[str, str] to dict[str, SecretValue]

openhands/sdk/llm/llm.py

@@ -208,6 +208,10 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
             "Safety settings for models that support them (like Mistral AI and Gemini)"
         ),
     )
+    profile_id: str | None = Field(
+        default=None,
+        description="Optional profile id (filename under ~/.openhands/llm-profiles).",
+    )
     service_id: str = Field(
         default="default",
         description="Unique identifier for LLM. Typically used by LLM registry.",

openhands/sdk/llm/profile_manager.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+from openhands.sdk.llm.llm import LLM
+from openhands.sdk.llm.llm_registry import LLMRegistry
+
+
+logger = logging.getLogger(__name__)
+
+
+class ProfileManager:
+    """Manage LLM profile files on disk.
+
+    Profiles are stored as JSON files using the existing LLM schema, typically
+    at ~/.openhands/llm-profiles/<profile_name>.json.
+    """
+
+    def __init__(self, base_dir: str | Path | None = None):
+        if base_dir is None:
+            self.base_dir = Path.home() / ".openhands" / "llm-profiles"
+        else:
+            self.base_dir = Path(base_dir).expanduser()
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+
+    def list_profiles(self) -> list[str]:
+        return sorted([p.stem for p in self.base_dir.glob("*.json")])
+
+    def get_profile_path(self, name: str) -> Path:
+        return self.base_dir / f"{name}.json"
+
+    def load_profile(self, name: str) -> LLM:
+        p = self.get_profile_path(name)
+        if not p.exists():
+            raise FileNotFoundError(f"Profile not found: {name} -> {p}")
+        # Use LLM.load_from_json to leverage pydantic validation
+        llm = LLM.load_from_json(str(p))
+        # Ensure profile_id is present on loaded LLM
+        if getattr(llm, "profile_id", None) is None:
+            try:
+                llm = llm.model_copy(update={"profile_id": name})
+            except Exception:
+                # Old pydantic versions might not have model_copy; fallback
+                llm.profile_id = name  # type: ignore[attr-defined]
+        return llm
+
+    def save_profile(self, name: str, llm: LLM, include_secrets: bool = False) -> Path:
+        p = self.get_profile_path(name)
+        # Dump model to dict and ensure profile_id is set
+        data = llm.model_dump(exclude_none=True)
+        data["profile_id"] = name
+        # Remove secret fields unless explicitly requested
+        if not include_secrets:
+            for secret_field in (
+                "api_key",
+                "aws_access_key_id",
+                "aws_secret_access_key",
+            ):
+                if secret_field in data:
+                    data.pop(secret_field, None)
+        # Write to file
+        with open(p, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+        logger.info(f"Saved profile {name} -> {p}")
+        return p
+
+    def register_all(self, registry: LLMRegistry) -> None:
+        # Load and attempt to register all profiles. Skip duplicates.
+        for name in self.list_profiles():
+            try:
+                llm = self.load_profile(name)
+                try:
+                    registry.add(llm)
+                except Exception as e:
+                    logger.info(f"Skipping profile {name}: registry.add failed: {e}")
+            except Exception as e:
+                logger.warning(f"Failed to load profile {name}: {e}")

tests/sdk/llm/test_profile_manager.py

@@ -0,0 +1,70 @@
+import json
+
+from pydantic import SecretStr
+
+from openhands.sdk.llm.llm import LLM
+from openhands.sdk.llm.llm_registry import LLMRegistry
+from openhands.sdk.llm.profile_manager import ProfileManager
+
+
+def test_list_profiles_returns_sorted_names(tmp_path):
+    manager = ProfileManager(base_dir=tmp_path)
+    (tmp_path / "b.json").write_text("{}", encoding="utf-8")
+    (tmp_path / "a.json").write_text("{}", encoding="utf-8")
+
+    assert manager.list_profiles() == ["a", "b"]
+
+
+def test_save_profile_excludes_secret_fields(tmp_path):
+    manager = ProfileManager(base_dir=tmp_path)
+    llm = LLM(
+        model="gpt-4o-mini",
+        service_id="service",
+        api_key=SecretStr("secret"),
+        aws_access_key_id=SecretStr("id"),
+        aws_secret_access_key=SecretStr("value"),
+    )
+
+    path = manager.save_profile("sample", llm)
+    data = json.loads(path.read_text(encoding="utf-8"))
+
+    assert data["profile_id"] == "sample"
+    assert data["service_id"] == "service"
+    assert "api_key" not in data
+    assert "aws_access_key_id" not in data
+    assert "aws_secret_access_key" not in data
+
+
+def test_load_profile_assigns_profile_id_when_missing(tmp_path):
+    manager = ProfileManager(base_dir=tmp_path)
+    profile_path = tmp_path / "foo.json"
+    profile_path.write_text(
+        json.dumps({"model": "gpt-4o-mini", "service_id": "svc"}),
+        encoding="utf-8",
+    )
+
+    llm = manager.load_profile("foo")
+
+    assert llm.profile_id == "foo"
+    assert llm.service_id == "svc"
+
+
+def test_register_all_skips_invalid_and_duplicate_profiles(tmp_path):
+    manager = ProfileManager(base_dir=tmp_path)
+    registry = LLMRegistry()
+
+    llm = LLM(model="gpt-4o-mini", service_id="shared")
+    manager.save_profile("alpha", llm)
+
+    duplicate_data = llm.model_dump(exclude_none=True)
+    duplicate_data["profile_id"] = "beta"
+    (tmp_path / "beta.json").write_text(
+        json.dumps(duplicate_data),
+        encoding="utf-8",
+    )
+
+    (tmp_path / "gamma.json").write_text("{", encoding="utf-8")
+
+    manager.register_all(registry)
+
+    assert registry.list_services() == ["shared"]