core-runtime 3.0.0__tar.gz → 3.1.0__tar.gz

{core_runtime-3.0.0 → core_runtime-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-runtime
-Version: 3.0.0
+Version: 3.1.0
 Summary: CORE: executable constitutional governance for AI-assisted software development.
 License-Expression: MIT
 License-File: LICENSE
@@ -23,7 +23,7 @@ Requires-Dist: argon2-cffi (>=23.1,<24.0)
 Requires-Dist: asyncpg (>=0.31.0,<0.32.0)
 Requires-Dist: black (>=26.3.1,<27.0.0)
 Requires-Dist: click (>=8.5.0)
-Requires-Dist: cryptography (>=50.0.1,<51.0.0)
+Requires-Dist: cryptography (>=50.0.2,<51.0.0)
 Requires-Dist: dependency-injector (>=4.49.1,<5.0.0)
 Requires-Dist: email-validator (>=2.0,<3.0)
 Requires-Dist: fastapi (>=0.136.0,<0.137.0)
@@ -31,22 +31,22 @@ Requires-Dist: filelock (>=4.2.1,<5.0.0)
 Requires-Dist: httpx (>=0.28.0,<0.29.0)
 Requires-Dist: jsonschema (>=4.26.0,<5)
 Requires-Dist: mcp (>=2.3.0,<2.4.0)
-Requires-Dist: msgpack (>=1.2.3,<2.0.0)
-Requires-Dist: numpy (>=2.5.3,<3.0.0)
+Requires-Dist: msgpack (>=1.2.4,<2.0.0)
+Requires-Dist: numpy (>=2.5.4,<3.0.0)
 Requires-Dist: pathspec (>=1.1.0,<2.0.0)
-Requires-Dist: pydantic (>=2.13.5,<3.0)
-Requires-Dist: pydantic-settings (>=2.15.0,<3.0.0)
-Requires-Dist: python-dotenv (>=1.2.3,<2.0.0)
+Requires-Dist: pydantic (>=2.14.2,<3.0)
+Requires-Dist: pydantic-settings (>=2.16.2,<3.0.0)
+Requires-Dist: python-dotenv (>=1.2.4,<2.0.0)
 Requires-Dist: pyyaml (>=6.0.3,<7.0)
-Requires-Dist: qdrant-client (>=1.19.1,<2.0.0)
+Requires-Dist: qdrant-client (>=1.20.0,<2.0.0)
 Requires-Dist: radon (>=6.0.1,<7.0.0)
 Requires-Dist: redis (>=5.0,<6.0)
 Requires-Dist: rich (>=13,<16)
 Requires-Dist: scikit-learn (>=1.9.1,<2.0.0)
 Requires-Dist: setuptools (>=84.1.0)
-Requires-Dist: sqlalchemy[asyncio] (>=2.1.2,<3.0.0)
+Requires-Dist: sqlalchemy[asyncio] (>=2.1.6,<3.0.0)
 Requires-Dist: sqlparse (>=0.6.0,<0.7.0)
-Requires-Dist: typer (>=0.26.0,<0.28.0)
+Requires-Dist: typer (>=0.27.3,<0.28.0)
 Requires-Dist: uvicorn[standard] (>=0.38.0,<0.39.0)
 Project-URL: Documentation, https://dariusznewecki.github.io/CORE/
 Project-URL: Homepage, https://github.com/DariuszNewecki/CORE
@@ -58,10 +58,10 @@ Description-Content-Type: text/markdown
 > **Executable constitutional governance for AI-assisted software development.**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/DariuszNewecki/CORE/blob/main/LICENSE)
-[![Release](https://img.shields.io/badge/Release-v3.0.0-blue)](https://github.com/DariuszNewecki/CORE/releases)
+[![Release](https://img.shields.io/badge/Release-v3.1.0-blue)](https://github.com/DariuszNewecki/CORE/releases)
 [![Docs](https://img.shields.io/badge/Docs-online-green)](https://dariusznewecki.github.io/CORE/)
 
-**Current Release:** v3.0.0 — see [CHANGELOG.md](https://github.com/DariuszNewecki/CORE/blob/main/CHANGELOG.md).
+**Current Release:** v3.1.0 — see [CHANGELOG.md](https://github.com/DariuszNewecki/CORE/blob/main/CHANGELOG.md).
 
 ## What CORE is
 

{core_runtime-3.0.0 → core_runtime-3.1.0}/README.md

@@ -3,10 +3,10 @@
 > **Executable constitutional governance for AI-assisted software development.**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/DariuszNewecki/CORE/blob/main/LICENSE)
-[![Release](https://img.shields.io/badge/Release-v3.0.0-blue)](https://github.com/DariuszNewecki/CORE/releases)
+[![Release](https://img.shields.io/badge/Release-v3.1.0-blue)](https://github.com/DariuszNewecki/CORE/releases)
 [![Docs](https://img.shields.io/badge/Docs-online-green)](https://dariusznewecki.github.io/CORE/)
 
-**Current Release:** v3.0.0 — see [CHANGELOG.md](https://github.com/DariuszNewecki/CORE/blob/main/CHANGELOG.md).
+**Current Release:** v3.1.0 — see [CHANGELOG.md](https://github.com/DariuszNewecki/CORE/blob/main/CHANGELOG.md).
 
 ## What CORE is
 

{core_runtime-3.0.0 → core_runtime-3.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "core-runtime"
-version = "3.0.0"
+version = "3.1.0"
 description = "CORE: executable constitutional governance for AI-assisted software development."
 authors = [
     { name = "Dariusz Newecki", email = "d.newecki@gmail.com" },
@@ -41,19 +41,19 @@ dependencies = [
     "fastapi>=0.136.0,<0.137.0",
     "uvicorn[standard]>=0.38.0,<0.39.0",
     # Database (Async)
-    "sqlalchemy[asyncio]>=2.1.2,<3.0.0",
+    "sqlalchemy[asyncio]>=2.1.6,<3.0.0",
     "asyncpg>=0.31.0,<0.32.0",
     # Configuration & Validation
-    "pydantic>=2.13.5,<3.0",
-    "pydantic-settings>=2.15.0,<3.0.0",
-    "python-dotenv>=1.2.3,<2.0.0",
+    "pydantic>=2.14.2,<3.0",
+    "pydantic-settings>=2.16.2,<3.0.0",
+    "python-dotenv>=1.2.4,<2.0.0",
     # Security
-    "cryptography>=50.0.1,<51.0.0",
+    "cryptography>=50.0.2,<51.0.0",
     "PyJWT>=2.15.1,<3.0",
     "argon2-cffi>=23.1,<24.0",
     "email-validator>=2.0,<3.0",
     # CLI & UI
-    "typer>=0.26.0,<0.28.0",
+    "typer>=0.27.3,<0.28.0",
     "rich>=13,<16",
     # Data Processing
     "pyyaml>=6.0.3,<7.0",
@@ -64,12 +64,12 @@ dependencies = [
     "radon>=6.0.1,<7.0.0",
     "sqlparse>=0.6.0,<0.7.0",
     # Vector Database
-    "qdrant-client>=1.19.1,<2.0.0",
+    "qdrant-client>=1.20.0,<2.0.0",
     # Scientific Computing
-    "numpy>=2.5.3,<3.0.0",
+    "numpy>=2.5.4,<3.0.0",
     "scikit-learn>=1.9.1,<2.0.0",
     # Utilities
-    "msgpack>=1.2.3,<2.0.0",
+    "msgpack>=1.2.4,<2.0.0",
     "filelock>=4.2.1,<5.0.0",
     "pathspec>=1.1.0,<2.0.0",
     # Dependency Injection
@@ -109,18 +109,18 @@ packages = [
 # Testing
 pytest = "^9.0"
 pytest-asyncio = "^1.4"
-pytest-mock = "^3.16.0"
+pytest-mock = "^3.17.0"
 pytest-cov = "^7.1"
 pytest-dotenv = "^0.5.2"
 pytest-xdist = "^3.8.0"
 aiosqlite = "^0.22.1"
 
 # Code Quality
-pre-commit = "^4.6.2"
-mypy = "^2.3"
+pre-commit = "^4.7.0"
+mypy = "^2.4"
 types-PyYAML = "^6.0"
-types-jsonschema = "^4.0"
-ruff = "^0.16.9"
+types-jsonschema = "^4.26"
+ruff = "^0.17.3"
 
 # Documentation
 sphinx = "^9.1"
@@ -131,7 +131,7 @@ httpx = "^0.28.1"
 ipython = "^9.17"
 anyio = "^4.15.1"
 mkdocs = "^1.6.1"
-mkdocs-material = "^9.7.7"
+mkdocs-material = "^9.8.0"
 vulture = "^2.16"
 pip-audit = "^2.10.1"
 bandit = "^1.9.4"

{core_runtime-3.0.0 → core_runtime-3.1.0}/src/api/cli/llm_resources_client.py

@@ -33,3 +33,35 @@ class LlmResourcesClient:
             "/v1/llm-resources/author",
             json={"definition": definition, "write": write},
         )
+
+    # ID: 4b9e2d7a-8c3f-4a1e-b6d4-2e7a9c5f1b3d
+    async def setup(
+        self,
+        *,
+        api_url: str,
+        embedding_model: str,
+        chat_model: str,
+        locality: str = "local",
+        embedding_api_url: str = "",
+        embedding_locality: str = "",
+        write: bool = False,
+    ) -> dict:
+        """POST /v1/llm-resources/setup — the one-step model setup (#1374)."""
+        return await self._facade._request(
+            "POST",
+            "/v1/llm-resources/setup",
+            json={
+                "api_url": api_url,
+                "embedding_model": embedding_model,
+                "chat_model": chat_model,
+                "locality": locality,
+                "embedding_api_url": embedding_api_url,
+                "embedding_locality": embedding_locality,
+                "write": write,
+            },
+        )
+
+    # ID: 8f1c6a3e-2d9b-4e7a-a5c8-3b6e1d9f4a2c
+    async def check(self) -> dict:
+        """POST /v1/llm-resources/check — call both setup models once."""
+        return await self._facade._request("POST", "/v1/llm-resources/check")

{core_runtime-3.0.0 → core_runtime-3.1.0}/src/api/v1/inspect_routes.py

@@ -345,10 +345,10 @@ async def analysis_common_knowledge(
     ),
 )
 # ID: 0f4a6b2c-3d5e-4f7a-8b9c-0d1e2f3a4bf0
-async def analysis_command_tree(request: Request) -> dict:
+async def analysis_command_tree() -> dict:
     """Return the introspected CLI command hierarchy."""
-    core_context: CoreContext = request.app.state.core_context
-    return get_analysis_command_tree(core_context)
+    # The first call imports the whole CLI; keep it off the API event loop.
+    return await asyncio.to_thread(get_analysis_command_tree)
 
 
 @analysis_router.get(

{core_runtime-3.0.0 → core_runtime-3.1.0}/src/api/v1/llm_resource_routes.py

@@ -17,14 +17,19 @@ from __future__ import annotations
 
 from typing import Any
 
-from fastapi import APIRouter, Body, Request
+from fastapi import APIRouter, Body, Depends, Request
 from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import AsyncSession
 
-from api.dependencies import require_governor
+from api.dependencies import get_api_session, require_governor
 from api.v1.schemas import LlmResourceAuthoringResponse
 from shared.context import CoreContext
 from shared.logger import getLogger
-from will.governance.llm_resource_runner import run_author_llm_resource
+from will.governance.llm_resource_runner import (
+    run_author_llm_resource,
+    run_check_llm,
+    run_setup_llm,
+)
 
 
 logger = getLogger(__name__)
@@ -67,3 +72,52 @@ async def author_llm_resource(
         data=result.data,
         duration_sec=result.duration_sec,
     )
+
+
+# ID: 6e1b8d4a-3f7c-4a2e-b9d5-8c4a1f7e3b6d
+class SetupLlmRequest(BaseModel):
+    """Body for POST /llm-resources/setup (#1374)."""
+
+    api_url: str
+    embedding_model: str
+    chat_model: str
+    locality: str = "local"
+    embedding_api_url: str = ""
+    embedding_locality: str = ""
+    write: bool = False
+
+
+@router.post("/setup", response_model=LlmResourceAuthoringResponse)
+# ID: 2f8a5c1d-7b4e-4d9a-a3c6-5e1f9b7d2a4c
+async def setup_llm(
+    request: Request,
+    payload: SetupLlmRequest = Body(...),
+) -> LlmResourceAuthoringResponse:
+    """Create the system_config row and the two setup model rows."""
+    core_context: CoreContext = request.app.state.core_context
+    result = await run_setup_llm(
+        core_context,
+        write=payload.write,
+        api_url=payload.api_url,
+        embedding_model=payload.embedding_model,
+        chat_model=payload.chat_model,
+        locality=payload.locality,
+        embedding_api_url=payload.embedding_api_url,
+        embedding_locality=payload.embedding_locality,
+    )
+    return LlmResourceAuthoringResponse(
+        ok=result.ok, data=result.data, duration_sec=result.duration_sec
+    )
+
+
+@router.post("/check", response_model=LlmResourceAuthoringResponse)
+# ID: 7d3c9f2e-1a6b-4e8d-9b5f-4a2e8c6d1f3b
+async def check_llm(
+    request: Request, session: AsyncSession = Depends(get_api_session)
+) -> LlmResourceAuthoringResponse:
+    """Call the embedding model and the chat model once each; writes nothing."""
+    core_context: CoreContext = request.app.state.core_context
+    data = await run_check_llm(core_context, session)
+    return LlmResourceAuthoringResponse(
+        ok=bool(data.get("ok")), data=data, duration_sec=0.0
+    )

{core_runtime-3.0.0 → core_runtime-3.1.0}/src/body/atomic/__init__.py

@@ -18,6 +18,7 @@ from body.atomic import (
     file_ops,
     fix,
     llm_resource_authoring_actions,
+    llm_setup_actions,
     log_actions,
     metadata_ops,
     modularity_fix,
@@ -55,6 +56,7 @@ from body.atomic.fix import (
     action_format_code as action_fix_format,
 )
 from body.atomic.llm_resource_authoring_actions import action_author_llm_resource
+from body.atomic.llm_setup_actions import action_setup_llm
 from body.atomic.log_actions import (
     action_archive_log_partitions,
     action_maintain_log_partitions,
@@ -92,6 +94,7 @@ __all__ = [
     "action_refactor_apply_split",
     "action_registry",
     "action_run_gap_analysis",
+    "action_setup_llm",
     "action_sync_code_vectors",
     "action_sync_constitutional_vectors",
     "action_sync_database",

{core_runtime-3.0.0 → core_runtime-3.1.0}/src/body/atomic/cognitive_role_projection_actions.py

@@ -11,11 +11,11 @@ reconciliation (ADR-090 D1).
 
 write=False computes and returns the diff only. write=True applies it,
 UPDATE-ing required_capabilities for roles that exist (by name) in both
-YAML and DB and whose capability values are all canonical. This action
-never INSERTs or DELETEs a core.cognitive_roles row — a role name present
-in only one side is reported, never auto-corrected; changing the role
-*name* universe is a schema/CHECK-constraint migration concern (ADR-090
-D2), out of this action's boundary. A YAML capability value that is not
+YAML and DB and whose capability values are all canonical, and CREATING a
+role the YAML declares but the DB lacks (#894 seeding unit; this is how a
+fresh install gets its roles). It never DELETEs a core.cognitive_roles row:
+a role only the DB has is reported, never removed; the schema's role-name
+CHECK constraint stays the arbiter of names (ADR-090 D2). A YAML capability value that is not
 canonical per capability_taxonomy.yaml blocks that role's row from being
 written even under write=True (fail closed).
 

{core_runtime-3.0.0 → core_runtime-3.1.0}/src/body/atomic/external_run_seed_actions.py

@@ -15,8 +15,10 @@ Scope, exactly as ruled:
   validator ``author.llm_resource`` uses, ``core.role_resource_assignments``
   {role, resource, priority, is_active}, ``core.system_config``
   {operating_mode, llm_enabled};
-- create-only: a database that already carries any of these rows is not
-  the empty isolated database this action is for -- refuse;
+- create-only for resources and assignments: a database that already
+  carries any of these rows is not the empty isolated database this action
+  is for -- refuse. ``core.system_config`` is the singleton every database
+  has from install (#1390 G5), so the seed sets its two fields;
 - risk classification ``moderate`` (``.intent/enforcement/config/action_risk.yaml``);
   never listed in the safe-auto-approval envelope; ``write=False`` validates
   and reports without touching the database.
@@ -158,11 +160,6 @@ async def action_seed_external_run_resources(
                         select(func.count()).select_from(RoleResourceAssignment)
                     )
                 ).scalar_one(),
-                "system_config": (
-                    await session.execute(
-                        select(func.count()).select_from(SystemConfig)
-                    )
-                ).scalar_one(),
             }
             occupied = {k: v for k, v in counts.items() if v}
             if occupied:
@@ -172,6 +169,15 @@ async def action_seed_external_run_resources(
                     start,
                     occupied=occupied,
                 )
+            config = (
+                await session.execute(select(SystemConfig).limit(1))
+            ).scalar_one_or_none()
+            if config is None:
+                return _refuse(
+                    "core.system_config has no row; run "
+                    "`core-admin database migrate --write` first (#1390)",
+                    start,
+                )
             # Ruling E ordering: roles come from the copy's taxonomy via
             # project.cognitive_roles and must already exist -- an assignment
             # references core.cognitive_roles(role). Refuse clearly rather
@@ -238,12 +244,8 @@ async def action_seed_external_run_resources(
                         is_active=a["is_active"],
                     )
                 )
-            session.add(
-                SystemConfig(
-                    operating_mode=seed.system_config["operating_mode"],
-                    llm_enabled=seed.system_config["llm_enabled"],
-                )
-            )
+            config.operating_mode = seed.system_config["operating_mode"]
+            config.llm_enabled = seed.system_config["llm_enabled"]
             await session.flush()
             await session.commit()
             plan["dry_run"] = False

core_runtime-3.1.0/src/body/atomic/llm_setup_actions.py

@@ -0,0 +1,232 @@
+# src/body/atomic/llm_setup_actions.py
+"""
+setup.llm -- one step that gives a fresh install a working model (#1374).
+
+A fresh database has no ``core.system_config`` row and no
+``core.llm_resources`` rows, and nothing in the docs could create them: the
+``.env`` LLM settings were never read. This action writes exactly what a
+newcomer needs, in one transaction:
+
+- ``core.system_config``: created when absent (``llm_enabled`` true,
+  ``operating_mode`` ``local_only`` for local models, ``hybrid`` for remote
+  ones). An existing row is changed only when a remote model needs it to
+  leave ``local_only``, and then only to ``hybrid``.
+- ``core.llm_resources``: two rows through the same validator as
+  ``author.llm_resource`` -- ``setup_embedding`` (``embedding``) for the
+  Vectorizer role, and ``setup_chat`` with every other canonical capability,
+  so each role the prompts name (Coder, LocalCoder, Planner, Architect, ...)
+  finds a model.
+
+Roles are not written here: ``project.cognitive_roles`` creates them, and
+the CLI runs it first. Keys are not carried either; a remote model's key goes
+to the secret store under ``<env_prefix>.api_key``. ``write=False`` validates
+and reports without touching the database.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from sqlalchemy import select
+
+from body.atomic.registry import ActionCategory, register_action
+from body.infrastructure.repositories.llm_resource_repository import (
+    _MUTABLE_FIELDS,
+    validate_llm_resource_definition,
+)
+from shared.action_types import ActionImpact, ActionResult
+from shared.atomic_action import atomic_action
+from shared.context import CoreContext
+from shared.infrastructure.database.models import LlmResource, SystemConfig
+from shared.infrastructure.database.session_manager import get_session
+from shared.infrastructure.intent.capability_taxonomy import (
+    CapabilityTaxonomyError,
+    load_capability_taxonomy,
+)
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+ACTION_ID = "setup.llm"
+EMBEDDING_RESOURCE = "setup_embedding"
+CHAT_RESOURCE = "setup_chat"
+EMBEDDING_PREFIX = "setup_embedding"
+CHAT_PREFIX = "setup_chat"
+
+
+# ID: 3b7e1c9d-4f2a-4e8b-9c6d-1a5f7e3b9d2c
+def build_setup_definitions(
+    *,
+    api_url: str,
+    embedding_model: str,
+    chat_model: str,
+    locality: str,
+    canonical: frozenset[str],
+    embedding_api_url: str = "",
+    embedding_locality: str = "",
+) -> list[dict[str, Any]]:
+    """The two llm_resources rows a working install needs.
+
+    The embedding model may live on its own server (``embedding_api_url``,
+    ``embedding_locality``): a hosted chat model often has no 768-dimension
+    embedding model, so its embeddings stay local.
+    """
+    chat_capabilities = sorted(canonical - {"embedding"})
+    return [
+        {
+            "name": EMBEDDING_RESOURCE,
+            "env_prefix": EMBEDDING_PREFIX,
+            "provided_capabilities": ["embedding"],
+            "model_name": embedding_model,
+            "api_url": embedding_api_url or api_url,
+            "locality": embedding_locality or locality,
+            "is_available": True,
+        },
+        {
+            "name": CHAT_RESOURCE,
+            "env_prefix": CHAT_PREFIX,
+            "provided_capabilities": chat_capabilities,
+            "model_name": chat_model,
+            "api_url": api_url,
+            "locality": locality,
+            "is_available": True,
+        },
+    ]
+
+
+def _fail(start: float, error: str, **extra: Any) -> ActionResult:
+    return ActionResult(
+        action_id=ACTION_ID,
+        ok=False,
+        data={"error": error, **extra},
+        duration_sec=time.time() - start,
+    )
+
+
+@register_action(
+    action_id=ACTION_ID,
+    description="Give a fresh install a working embedding and chat model (#1374)",
+    category=ActionCategory.STATE,
+    policies=["rules/ai/capability_taxonomy_governance"],
+    requires_db=True,
+    remediates=[],
+)
+@atomic_action(
+    action_id=ACTION_ID,
+    intent="Create the system_config row and the two setup llm_resources rows",
+    impact=ActionImpact.WRITE_DATA,
+    policies=["atomic_actions"],
+)
+# ID: 8d2f6a1e-5c3b-4a9d-b7e4-2f8c1d6a3e5b
+async def action_setup_llm(
+    core_context: CoreContext,
+    write: bool = False,
+    api_url: str = "",
+    embedding_model: str = "",
+    chat_model: str = "",
+    locality: str = "local",
+    embedding_api_url: str = "",
+    embedding_locality: str = "",
+    **kwargs: Any,
+) -> ActionResult:
+    """Validate (write=False) or apply (write=True) the model setup."""
+    start = time.time()
+    if not (api_url and embedding_model and chat_model):
+        return _fail(start, "api_url, embedding_model and chat_model are required")
+    for value in (locality, embedding_locality or locality):
+        if value not in ("local", "remote"):
+            return _fail(start, f"locality must be local or remote, got {value!r}")
+
+    try:
+        canonical = frozenset(load_capability_taxonomy())
+    except CapabilityTaxonomyError as exc:
+        return _fail(start, str(exc), reason="capability_taxonomy_unreadable")
+
+    definitions = build_setup_definitions(
+        api_url=api_url,
+        embedding_model=embedding_model,
+        chat_model=chat_model,
+        locality=locality,
+        canonical=canonical,
+        embedding_api_url=embedding_api_url,
+        embedding_locality=embedding_locality,
+    )
+    violations = [
+        f"{d['name']}: {v}"
+        for d in definitions
+        for v in validate_llm_resource_definition(d, canonical)
+    ]
+    if violations:
+        return _fail(start, "invalid definition", violations=violations)
+
+    any_remote = any(d["locality"] == "remote" for d in definitions)
+    needed_mode = "hybrid" if any_remote else "local_only"
+    data: dict[str, Any] = {
+        "dry_run": not write,
+        "resources": [d["name"] for d in definitions],
+        # the rows whose key belongs in the secret store
+        "remote_env_prefixes": [
+            d["env_prefix"] for d in definitions if d["locality"] == "remote"
+        ],
+    }
+    try:
+        async with get_session() as session:
+            config = (
+                await session.execute(select(SystemConfig).limit(1))
+            ).scalar_one_or_none()
+            if config is None:
+                data["system_config"] = f"created ({needed_mode}, llm enabled)"
+                if write:
+                    session.add(
+                        SystemConfig(operating_mode=needed_mode, llm_enabled=True)
+                    )
+            elif any_remote and config.operating_mode == "local_only":
+                data["system_config"] = "operating_mode local_only -> hybrid"
+                if write:
+                    config.operating_mode = "hybrid"
+            else:
+                data["system_config"] = (
+                    f"kept ({config.operating_mode}, "
+                    f"llm {'enabled' if config.llm_enabled else 'disabled'})"
+                )
+                data["llm_enabled"] = bool(config.llm_enabled)
+
+            for definition in definitions:
+                existing = (
+                    await session.execute(
+                        select(LlmResource).where(
+                            LlmResource.name == definition["name"]
+                        )
+                    )
+                ).scalar_one_or_none()
+                if not write:
+                    continue
+                if existing is None:
+                    session.add(
+                        LlmResource(
+                            name=definition["name"],
+                            **{
+                                f: definition[f]
+                                for f in _MUTABLE_FIELDS
+                                if f in definition
+                            },
+                        )
+                    )
+                else:
+                    for field in _MUTABLE_FIELDS:
+                        if field in definition:
+                            setattr(existing, field, definition[field])
+            if write:
+                await session.commit()
+    except Exception as exc:
+        logger.exception("setup.llm failed")
+        return _fail(start, str(exc), error_type=type(exc).__name__)
+
+    return ActionResult(
+        action_id=ACTION_ID,
+        ok=True,
+        data=data,
+        duration_sec=time.time() - start,
+    )