AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.
feat(backend/copilot): local-LLM AutoPilot for the no-API-key install (#12993)
Nicholas Tindled41848939af1
diff --git a/autogpt_platform/backend/.env.default b/autogpt_platform/backend/.env.defaultindex 0eefdb2c48..eae42c4ab1 100644--- a/autogpt_platform/backend/.env.default+++ b/autogpt_platform/backend/.env.default@@ -75,6 +75,20 @@ V0_API_KEY=OPEN_ROUTER_API_KEY=NVIDIA_API_KEY=+# AutoPilot — self-hosted LLM (Ollama et al.)+# Set CHAT_USE_LOCAL=true to route AutoPilot through an OpenAI-compatible+# endpoint instead of OpenRouter / Anthropic. CHAT_BASE_URL must point at+# the local server (e.g. http://host.docker.internal:11434/v1 for Ollama+# running on the Docker host) and CHAT_API_KEY can be any non-empty string+# — Ollama doesn't validate it. The CHAT_*_MODEL fields must be set to+# bare model names served by the local backend (e.g. llama3.2:3b);+# OpenRouter-style provider/model slugs do not resolve. Extended-thinking+# mode is automatically downgraded to fast under this transport because+# the Claude Agent SDK CLI requires Anthropic's wire protocol.+CHAT_API_KEY=+CHAT_BASE_URL=+CHAT_USE_LOCAL=false+# Graphiti Temporal Knowledge Graph Memory# Rollout controlled by LaunchDarkly flag "graphiti-memory"# LLM key falls back to CHAT_API_KEY (AutoPilot), then OPEN_ROUTER_API_KEY.diff --git a/autogpt_platform/backend/backend/api/features/search/embeddings.py b/autogpt_platform/backend/backend/api/features/search/embeddings.pyindex c50882a4f5..0b6742ec65 100644--- a/autogpt_platform/backend/backend/api/features/search/embeddings.py+++ b/autogpt_platform/backend/backend/api/features/search/embeddings.py@@ -24,11 +24,18 @@ from backend.api.features.search.content_handlers import CONTENT_HANDLERSfrom backend.data.db import execute_raw_with_schema, query_raw_with_schemafrom backend.util.clients import get_openai_clientfrom backend.util.json import dumps+from backend.util.settings import Settingslogger = logging.getLogger(__name__)-# OpenAI embedding model configuration-EMBEDDING_MODEL = "text-embedding-3-small"+_settings = Settings()++# Embedding model — overridable via STORE_EMBEDDING_MODEL so deployments+# with a compatible backend (vLLM, LiteLLM proxy, Ollama with an+# embedding model pulled, Azure OpenAI, ...) can swap models without a+# code change. Default keeps the historical OpenAI+# ``text-embedding-3-small`` so existing pgvector columns still match.+EMBEDDING_MODEL = _settings.config.store_embedding_model# Embedding dimension for the model above# text-embedding-3-small: 1536, text-embedding-3-large: 3072EMBEDDING_DIM = 1536@@ -83,8 +90,16 @@ def build_searchable_text(# Cached at module load: ``encoding_for_model`` loads a tokenizer file# from disk on every call (~10–20 ms). At backfill scale we run this on-# every row, so amortising it module-level is a meaningful win.-_ENCODER = encoding_for_model(EMBEDDING_MODEL)+# every row, so amortising it module-level is a meaningful win. Falls+# back to ``cl100k_base`` (the OpenAI ada/embedding-3 tokenizer) when+# the configured model name is unknown to tiktoken — e.g. Ollama tags+# like ``nomic-embed-text``.+try:+ _ENCODER = encoding_for_model(EMBEDDING_MODEL)+except KeyError:+ from tiktoken import get_encoding++ _ENCODER = get_encoding("cl100k_base")async def generate_embedding(text: str) -> list[float]:@@ -95,7 +110,21 @@ async def generate_embedding(text: str) -> list[float]:"""client = get_openai_client()if not client:- raise RuntimeError("openai_internal_api_key not set, cannot generate embedding")+ # ``get_openai_client`` already honors ``CHAT_USE_LOCAL`` first, so+ # reaching None here means *no* embedding backend is configured at+ # all. Hybrid search wraps this in try/except and degrades to+ # lexical-only — the raise is still useful so direct callers+ # (uploads, reindex jobs) get a clear "wire something up" signal+ # instead of a silent ``None`` cascade.+ raise RuntimeError(+ "No embedding-capable LLM client configured. Set ONE of: "+ "OPENAI_INTERNAL_API_KEY, OPEN_ROUTER_API_KEY, or "+ "CHAT_USE_LOCAL=true with a CHAT_BASE_URL that exposes "+ "/v1/embeddings (vLLM / LiteLLM proxy / Azure OpenAI / "+ "Ollama with an embedding model pulled). Override the model "+ "via STORE_EMBEDDING_MODEL (must emit 1536-dim vectors to "+ "match the pgvector column)."+ )# Truncate text to token limit using tiktoken# Character-based truncation is insufficient because token ratios vary by content typediff --git a/autogpt_platform/backend/backend/api/features/search/embeddings_test.py b/autogpt_platform/backend/backend/api/features/search/embeddings_test.pyindex 6a7acb19a0..3a71683e7f 100644--- a/autogpt_platform/backend/backend/api/features/search/embeddings_test.py+++ b/autogpt_platform/backend/backend/api/features/search/embeddings_test.py@@ -78,7 +78,9 @@ async def test_generate_embedding_no_api_key():) as mock_get_client:mock_get_client.return_value = None- with pytest.raises(RuntimeError, match="openai_internal_api_key not set"):+ with pytest.raises(+ RuntimeError, match="No embedding-capable LLM client configured"+ ):await embeddings.generate_embedding("test text")diff --git a/autogpt_platform/backend/backend/copilot/baseline/service.py b/autogpt_platform/backend/backend/copilot/baseline/service.pyindex 7103d47753..fac253fd3c 100644--- a/autogpt_platform/backend/backend/copilot/baseline/service.py+++ b/autogpt_platform/backend/backend/copilot/baseline/service.py@@ -22,6 +22,7 @@ from typing import TYPE_CHECKING, Any, castimport orjsonfrom langfuse import propagate_attributes+from openai import APIConnectionErrorfrom openai.types import CompletionUsagefrom openai.types.chat import ChatCompletionMessageParam, ChatCompletionToolParamfrom opentelemetry import trace as otel_trace@@ -42,6 +43,10 @@ from backend.copilot.builder_context import (from backend.copilot.config import CopilotLlmModel, CopilotModefrom backend.copilot.context import get_workspace_manager, set_execution_contextfrom backend.copilot.graphiti.config import is_enabled_for_user+from backend.copilot.local_context_probe import (+ compaction_target_for_window,+ probe_local_context_window,+)from backend.copilot.model import (ChatMessage,ChatSession,@@ -784,16 +789,33 @@ async def _baseline_llm_caller(final_messages = messagesextra_headers = Nonetyped_messages = cast(list[ChatCompletionMessageParam], final_messages)- # OR-only: Anthropic's compat endpoint 400s on usage.include + reasoning; use native thinking param in direct mode.- if config.openrouter_active:- extra_body: dict[str, Any] = dict(_OPENROUTER_INCLUDE_USAGE_COST)+ # The wire format must match the endpoint ``main_client_credentials``+ # actually dialed — ``baseline_provider`` is the shared truth for both+ # (local → openrouter_active → anthropic). Keying on+ # ``transport.name == "openrouter"`` would send direct-Anthropic shape+ # to an OpenRouter endpoint in subscription mode with OR creds present,+ # where ``transport.name`` is ``"subscription"`` but the baseline client+ # still routes to OpenRouter.+ baseline_provider = config.baseline_provider+ is_openrouter_transport = baseline_provider == "openrouter"+ extra_body: dict[str, Any] = {}+ if baseline_provider == "local":+ # Local backends govern their own context window at launch (e.g.+ # OLLAMA_CONTEXT_LENGTH); AutoPilot reads it back at runtime for+ # compaction (see local_context_probe). Send no extra_body — skip+ # the OpenRouter ``usage.include`` extension and reasoning params,+ # which stricter local backends reject outright.+ pass+ elif is_openrouter_transport:+ # OR-only: Anthropic's compat endpoint 400s on usage.include + reasoning.+ extra_body.update(dict(_OPENROUTER_INCLUDE_USAGE_COST))reasoning_param = reasoning_extra_body(state.model, config.claude_agent_max_thinking_tokens)if reasoning_param:extra_body.update(reasoning_param)else:- extra_body = {}+ # Direct mode (non-OR, non-local): use native Anthropic thinking param.thinking_param = anthropic_thinking_extra_body(state.model, config.claude_agent_max_thinking_tokens)@@ -806,10 +828,10 @@ async def _baseline_llm_caller("extra_body": extra_body,}# OR-only: Anthropic's compat endpoint 400s on stream_options; OR embeds cost via it.- if config.openrouter_active:+ if is_openrouter_transport:create_kwargs["stream_options"] = {"include_usage": True}# Direct: Anthropic requires max_tokens > budget_tokens explicitly; OR injects a default.- if not config.openrouter_active and "thinking" in extra_body:+ if not is_openrouter_transport and "thinking" in extra_body:model_max = get_max_output_tokens(state.model)budget = min(config.claude_agent_max_thinking_tokens, model_max - 1)extra_body["thinking"]["budget_tokens"] = budget@@ -837,7 +859,16 @@ async def _baseline_llm_caller(_extract_cache_creation_tokens(ptd))cost = _extract_usage_cost(chunk.usage)- direct_mode = not config.openrouter_active+ # Rate-card recovery covers direct-Anthropic mode —+ # Anthropic's OpenAI-compat endpoint doesn't emit OR's+ # ``usage.cost`` extension, so the rate card is what+ # produces a cost number on that path. Local+ # (Ollama/vLLM) transports also lack ``usage.cost`` but+ # ``compute_anthropic_cost_usd`` returns None for any+ # non-Anthropic slug, so the recovery is a no-op for+ # local — skip it explicitly so the intent is clear and+ # we don't burn a rate-card lookup per usage chunk.+ direct_mode = baseline_provider == "anthropic"if cost is None and direct_mode:# Direct mode: no usage.cost field (OR extension); compute from rate card.ptd = chunk.usage.prompt_tokens_details@@ -1234,9 +1265,19 @@ async def _compress_session_messages(msg_dict["tool_call_id"] = msg.tool_call_idmessages_dict.append(msg_dict)+ # Under the local transport the model slug isn't in the cloud model+ # registry, so compress_context()'s default target would fall back to+ # ~120k and never fire before the (much smaller) local window overflows.+ # Probe the backend for its real window and target compaction at it.+ target_tokens: int | None = None+ if config.effective_transport == "local" and config.base_url:+ window = await probe_local_context_window(config.base_url, model)+ target_tokens = compaction_target_for_window(window)+try:result = await compress_context(messages=messages_dict,+ target_tokens=target_tokens,model=model,client=_get_main_client(),)@@ -1244,6 +1285,7 @@ async def _compress_session_messages(logger.warning("[Baseline] Context compression with LLM failed: %s", e)result = await compress_context(messages=messages_dict,+ target_tokens=target_tokens,model=model,client=None,)@@ -1269,6 +1311,22 @@ async def _compress_session_messages(return messages+def _humanize_baseline_error(e: Exception) -> str:+ """Map a raw streaming exception to a user-facing message.++ A connection error under the local transport almost always means the+ operator's LLM backend (Ollama/vLLM/…) isn't running — say so, instead of+ surfacing a bare "Connection error.".+ """+ if isinstance(e, APIConnectionError) and config.effective_transport == "local":+ return (+ f"Can't reach the local LLM backend at {config.base_url}. Make sure "+ "your model server is running — for Ollama, start it with "+ "`ollama serve` (or check CHAT_BASE_URL)."+ )+ return str(e) or type(e).__name__++def should_upload_transcript(user_id: str | None, upload_safe: bool) -> bool:"""Return ``True`` when the caller should upload the final transcript.@@ -2240,7 +2298,7 @@ async def stream_chat_completion_baseline(state.assistant_text += fallback_textexcept Exception as e:_stream_error = True- error_msg = str(e) or type(e).__name__+ error_msg = _humanize_baseline_error(e)logger.error("[Baseline] Streaming error: %s", error_msg, exc_info=True)# Drain any queued tail events (reasoning/text close + finish step)# that ``_baseline_llm_caller``'s finally block pushed before the@@ -2327,9 +2385,17 @@ async def stream_chat_completion_baseline(state.turn_prompt_tokens,state.turn_completion_tokens,)- # Safety net: recover cost from rate card if usage chunk was dropped (truncated SSE).- # OR mode skips recovery — OR's markup differs from raw Anthropic pricing.- if state.cost_usd is None and not config.openrouter_active:+ # Safety net: recover cost from rate card if usage chunk was dropped+ # (truncated SSE). OR mode skips recovery — OR's markup differs from+ # raw Anthropic pricing. Local Ollama/vLLM never emit ``usage.cost``+ # *and* have no rate card to recover from (``compute_anthropic_cost_usd``+ # returns None for any non-Anthropic slug), so cost stays None for+ # the whole turn — fine, since local deployments are self-hosted and+ # ``persist_and_record_usage`` no-ops the cost-credit charge when+ # ``cost_usd`` is None. Skip the rate-card call explicitly under+ # local transport so the intent is clear.+ baseline_provider = config.baseline_provider+ if state.cost_usd is None and baseline_provider == "anthropic":recovered = compute_anthropic_cost_usd(model=active_model,prompt_tokens=state.turn_prompt_tokens,@@ -2358,7 +2424,11 @@ async def stream_chat_completion_baseline(log_prefix="[Baseline]",cost_usd=state.cost_usd,model=active_model,- provider="open_router" if config.openrouter_active else "anthropic",+ provider=(+ "open_router"+ if baseline_provider == "openrouter"+ else config.transport.cost_log_provider+ ),)# Persist structured tool-call history (assistant + tool messages)diff --git a/autogpt_platform/backend/backend/copilot/config.py b/autogpt_platform/backend/backend/copilot/config.pyindex f3dabbac8c..4283d51f18 100644--- a/autogpt_platform/backend/backend/copilot/config.py+++ b/autogpt_platform/backend/backend/copilot/config.py@@ -1,15 +1,24 @@"""Configuration management for chat system."""+import loggingimport osfrom typing import Literalfrom urllib.parse import urlparse-from pydantic import AliasChoices, Field, field_validator, model_validator+from pydantic import (+ AliasChoices,+ BaseModel,+ ConfigDict,+ Field,+ field_validator,+ model_validator,+)from pydantic_settings import BaseSettings-from backend.blocks.llm import LlmModelfrom backend.util.clients import OPENROUTER_BASE_URL+logger = logging.getLogger(__name__)+def _host_matches(base_url: str | None, suffix: str) -> bool:"""True when ``base_url``'s parsed hostname equals or ends with@@ -32,6 +41,104 @@ def _host_matches(base_url: str | None, suffix: str) -> bool:# directly to api.anthropic.com instead of going through OpenRouter.ANTHROPIC_OPENAI_COMPAT_BASE_URL = "https://api.anthropic.com/v1/"+# Default values for the cloud-routed auxiliary models. The local transport+# auto-overrides them when left at default — see ``_apply_local_aux_models``+# below. Kept as module constants so the validator and the field defaults+# can't drift.+_DEFAULT_TITLE_MODEL = "anthropic/claude-haiku-4-5"+_DEFAULT_SIMULATION_MODEL = "google/gemini-2.5-flash-lite"+# Default for ``fast_advanced_model`` — kept in sync with the field default+# below. ``_apply_local_aux_models`` reads this to detect "operator left it+# at the cloud default" so it can rewrite to ``fast_standard_model`` under+# local transport (otherwise an "advanced" tier request 404s against+# Ollama's OpenAI shim — no ``anthropic/`` slugs there).+_DEFAULT_FAST_ADVANCED_MODEL = "anthropic/claude-opus-4.7"++TransportName = Literal["subscription", "openrouter", "direct_anthropic", "local"]+++class TransportProfile(BaseModel):+ """Per-transport behaviour table.++ Each row collapses what *was* a scattered set of ``if config.use_X``+ checks (model-vendor validation, SDK availability, api_key fallback+ chain, auxiliary-model derivation) into named capabilities the+ config can read once. Adding a new transport (vLLM, llama.cpp,+ LocalAI, …) becomes "add a row to ``_TRANSPORT_PROFILES``" instead+ of "find every transport branch and extend the if/else."++ Read at call sites via ``ChatConfig.transport`` — never instantiate+ directly. Frozen so the ``_TRANSPORT_PROFILES`` constants table is+ immutable at runtime.+ """++ model_config = ConfigDict(frozen=True)++ name: TransportName+ # Whether the Claude Agent SDK CLI can be invoked under this transport.+ # The CLI speaks Anthropic's wire protocol, so only Anthropic-compatible+ # transports qualify. ``local`` (Ollama et al.) → False, downgraded to+ # baseline at request time.+ supports_sdk: bool+ # If set, the SDK model slug must come from this provider — otherwise+ # ``_validate_sdk_model_vendor_compatibility`` raises at config load.+ # ``None`` means "no vendor constraint" (OpenRouter accepts any slug;+ # subscription resolves to None and bypasses the check; local skips+ # the SDK entirely).+ sdk_model_vendor_constraint: str | None+ # Env vars consulted in order when ``CHAT_API_KEY`` is unset. Empty+ # tuple = no fallback — the transport requires CHAT_API_KEY explicitly+ # (local) or doesn't use api_key at all (subscription).+ api_key_fallback_envs: tuple[str, ...]+ # When True, ``title_model`` / ``simulation_model`` left at their cloud+ # defaults are overridden to ``fast_standard_model`` so operators don't+ # have to set every CHAT_*_MODEL slug. Cloud transports leave them+ # alone — operators can mix providers per field if they want.+ inherit_fast_model_for_aux: bool+ # Free-form provider string persisted to ``PlatformCostLog.provider`` for+ # rows attributable to this transport. Kept on the profile so the+ # baseline path, the simulator, the activity-status generator, and any+ # future cost-emitting call site share a single source of truth — a+ # ``provider="open_router"`` row from a local Ollama turn would+ # falsely show up as OR spend on the admin dashboard.+ cost_log_provider: str+++_TRANSPORT_PROFILES: dict[TransportName, TransportProfile] = {+ "subscription": TransportProfile(+ name="subscription",+ supports_sdk=True,+ sdk_model_vendor_constraint=None,+ api_key_fallback_envs=(),+ inherit_fast_model_for_aux=False,+ cost_log_provider="anthropic",+ ),+ "openrouter": TransportProfile(+ name="openrouter",+ supports_sdk=True,+ sdk_model_vendor_constraint=None,+ api_key_fallback_envs=("OPEN_ROUTER_API_KEY", "OPENAI_API_KEY"),+ inherit_fast_model_for_aux=False,+ cost_log_provider="open_router",+ ),+ "direct_anthropic": TransportProfile(+ name="direct_anthropic",+ supports_sdk=True,+ sdk_model_vendor_constraint="anthropic",+ api_key_fallback_envs=("OPEN_ROUTER_API_KEY", "OPENAI_API_KEY"),+ inherit_fast_model_for_aux=False,+ cost_log_provider="anthropic",+ ),+ "local": TransportProfile(+ name="local",+ supports_sdk=False,+ sdk_model_vendor_constraint=None,+ api_key_fallback_envs=(),+ inherit_fast_model_for_aux=True,+ cost_log_provider="ollama",+ ),+}+# Per-request routing mode for a single chat turn.# - 'fast': route to the baseline OpenAI-compatible path with the cheaper model.# - 'extended_thinking': route to the Claude Agent SDK path with the default@@ -77,10 +184,12 @@ class ChatConfig(BaseSettings):"(see ``copilot/model_router.py``); this value is the fallback.",)fast_advanced_model: str = Field(- default="anthropic/claude-opus-4.7",+ default=_DEFAULT_FAST_ADVANCED_MODEL,validation_alias=AliasChoices("CHAT_FAST_ADVANCED_MODEL"),description="Baseline path, 'advanced' tier. LD override: "- "``copilot-model-routing[fast][advanced]``.",+ "``copilot-model-routing[fast][advanced]``. Auto-overridden to "+ "match ``fast_standard_model`` under ``use_local`` when left at "+ "the cloud default — see ``_apply_local_aux_models``.",)thinking_standard_model: str = Field(default="anthropic/claude-sonnet-4-6",@@ -101,17 +210,19 @@ class ChatConfig(BaseSettings):"override: ``copilot-model-routing[thinking][advanced]``.",)title_model: str = Field(- default="anthropic/claude-haiku-4-5",+ default=_DEFAULT_TITLE_MODEL,description="Model to use for generating session titles (should be ""fast/cheap). Default is Anthropic Haiku so direct-Anthropic ""deployments (``CHAT_USE_OPENROUTER=false``) can route the title ""call through the same client without 404-ing on a non-Anthropic ""vendor prefix. OpenRouter deployments can override to a cheaper ""non-Anthropic alternative (e.g. ``CHAT_TITLE_MODEL=openai/gpt-4o-mini``) "- "via env without code changes.",+ "via env without code changes. Auto-overridden to match "+ "``fast_standard_model`` under ``use_local`` when left at the cloud "+ "default — see ``_apply_local_aux_models``.",)simulation_model: str = Field(- default=LlmModel.GEMINI_2_5_FLASH_LITE.value,+ default=_DEFAULT_SIMULATION_MODEL,description="Model for dry-run block simulation. Constraints: ""(1) the LLM-simulation path calls OpenRouter's OpenAI-compat ""endpoint with ``response_format=json_object`` and "@@ -121,7 +232,9 @@ class ChatConfig(BaseSettings):"a Claude default would hit ``api.anthropic.com`` with the ""platform OR key and 401, while Gemini has provider=open_router ""and routes correctly. Flash-Lite satisfies both and keeps "- "platform OR cost low.",+ "platform OR cost low. Auto-overridden to match "+ "``fast_standard_model`` under ``use_local`` when left at the "+ "cloud default — see ``_apply_local_aux_models``.",)api_key: str | None = Field(default=None, description="OpenAI API key")base_url: str | None = Field(@@ -436,6 +549,35 @@ class ChatConfig(BaseSettings):default=False,description="For personal/dev use: use Claude Code CLI subscription auth instead of API keys. Requires `claude login` on the host. Only works with SDK mode.",)+ local_request_timeout_s: float = Field(+ default=1800.0,+ ge=60.0,+ description="HTTP request timeout (seconds) for the OpenAI-compatible "+ "client when ``use_local`` is True. The OpenAI Python client defaults "+ "to 600 s — tighter than what an 8 B model running on a CPU-only host "+ "needs for a single AutoPilot turn (system prompt ≈ 8 k tokens; the "+ "tool-call loop multiplies that across iterations). Set to the longest "+ "single-call wait an operator is willing to tolerate before bailing. "+ "30 minutes accommodates CPU-only setups; drop it to ≤120 s if you "+ "have a GPU and want fast-fail on hangs. Ignored under cloud "+ "transports — those keep the OpenAI client default.",+ )+ use_local: bool = Field(+ default=False,+ description="Route chat through a self-hosted, OpenAI-compatible LLM "+ "endpoint (typically Ollama at ``http://host:11434/v1``). When True: "+ "(a) ``effective_transport`` is ``'local'`` regardless of OpenRouter "+ "or subscription credentials; (b) ``thinking_available`` is False — "+ "the Claude Agent SDK CLI speaks Anthropic's wire protocol and cannot "+ "route to Ollama, so requests with ``mode='extended_thinking'`` are "+ "downgraded to ``'fast'`` with a logged warning; (c) the "+ "``CHAT_*_MODEL`` fields should be set to bare names served by the "+ "local backend (e.g. ``llama3.2:3b``) — OpenRouter-style "+ "``provider/model`` slugs are passed through verbatim and will not "+ "resolve. ``CHAT_BASE_URL`` and ``CHAT_API_KEY`` must still be set "+ "(api_key can be any non-empty string for Ollama). Override via "+ "``CHAT_USE_LOCAL``.",+ )test_mode: bool = Field(default=False,description="Use dummy service instead of real LLM calls. "@@ -491,33 +633,85 @@ class ChatConfig(BaseSettings):return bool(self.api_key and base and base.startswith("http"))@property- def effective_transport(- self,- ) -> Literal["subscription", "openrouter", "direct_anthropic"]:- """The transport the SDK CLI subprocess actually uses for this turn.+ def effective_transport(self) -> TransportName:+ """The transport the chat path actually uses for this turn.Detection order:- 1. ``subscription`` — when ``use_claude_code_subscription`` is True- the CLI uses OAuth from the keychain or- ``CLAUDE_CODE_OAUTH_TOKEN`` and ignores ``CHAT_BASE_URL`` /- ``CHAT_API_KEY`` entirely (see ``build_sdk_env`` mode 1).- 2. ``openrouter`` — when ``openrouter_active`` (use_openrouter ++ 1. ``local`` — ``use_local`` is True. Wins over every other mode+ because operators opting into ``CHAT_USE_LOCAL`` have explicitly+ chosen self-hosted; we don't silently route to OpenRouter just+ because credentials happen to be in the env.+ 2. ``subscription`` — ``use_claude_code_subscription`` is True;+ the CLI uses OAuth from the keychain or ``CLAUDE_CODE_OAUTH_TOKEN``+ and ignores ``CHAT_BASE_URL`` / ``CHAT_API_KEY`` entirely+ (``build_sdk_env`` mode 1).+ 3. ``openrouter`` — ``openrouter_active`` (use_openrouter +api_key + a valid base_url).- 3. ``direct_anthropic`` — fallback (CLI talks to api.anthropic.com- with ``ANTHROPIC_API_KEY`` from parent env).+ 4. ``direct_anthropic`` — fallback (CLI talks to api.anthropic.com+ with ``ANTHROPIC_API_KEY`` from the parent env).- Use this when the question is "which model-name format will the- CLI accept?" — the OpenRouter slug ``anthropic/claude-opus-4.7``- works through the proxy but is rejected by the subscription /- direct-Anthropic transports.+ For per-transport *behaviour* (vendor constraints, SDK availability,+ api_key fallback chain, …) read ``self.transport`` instead of+ branching on this string at every call site."""+ if self.use_local:+ return "local"if self.use_claude_code_subscription:return "subscription"if self.openrouter_active:return "openrouter"return "direct_anthropic"+ @property+ def transport(self) -> TransportProfile:+ """The active transport's behaviour descriptor.++ Single source of truth for "what does this transport allow / require"+ — replaces the scattered ``if config.use_X`` checks that used to+ live in the validators, the SDK env builder, the request-path mode+ resolver, and the api_key fallback. See ``TransportProfile`` and+ ``_TRANSPORT_PROFILES``.+ """+ return _TRANSPORT_PROFILES[self.effective_transport]++ @property+ def thinking_available(self) -> bool:+ """Backwards-compatible alias for ``self.transport.supports_sdk``.++ Existing call sites in ``executor.processor`` consume this as a+ named kwarg; keeping the property avoids a churning rename across+ the request path.+ """+ return self.transport.supports_sdk++ @property+ def baseline_provider(self) -> Literal["local", "openrouter", "anthropic"]:+ """Endpoint + wire dialect the baseline OpenAI-compat client speaks.++ The single source of truth that ``main_client_credentials`` (which+ picks the endpoint) and the baseline request-shaping / cost path+ (wire format + cost attribution) both read, so the dialect can never+ disagree with the endpoint the client actually dialed. Resolved+ ``local → openrouter_active → anthropic`` — the same ladder as+ ``main_client_credentials``.++ Deliberately *not* ``effective_transport`` / ``transport.name``: in+ subscription mode the CLI authenticates via OAuth, which can't drive+ an OpenAI-compat client, so the baseline falls back to+ OR-if-available-else-direct. Keying the dialect on+ ``transport.name == "openrouter"`` (which is ``"subscription"`` here)+ while ``main_client_credentials`` still routes to OpenRouter (gated on+ ``openrouter_active``) would send direct-Anthropic shape to an+ OpenRouter endpoint. ``local`` is checked first because its default+ ``api_key="ollama"`` also satisfies the shape-only ``openrouter_active``.+ """+ if self.transport.name == "local":+ return "local"+ if self.openrouter_active:+ return "openrouter"+ return "anthropic"+@propertydef main_client_credentials(self) -> tuple[str | None, str | None]:"""``(api_key, base_url)`` for the main OpenAI-compatible client.@@ -530,12 +724,15 @@ class ChatConfig(BaseSettings):- **OpenRouter active**: returns ``(api_key, base_url)`` — theexisting OR creds.+ - **Local transport**: returns ``(api_key, base_url)`` — the+ operator-supplied self-hosted endpoint creds; bypasses the+ OpenRouter / Anthropic fallback that doesn't apply here.- **Otherwise** (direct mode or OR misconfigured): returns``(direct_anthropic_api_key, ANTHROPIC_OPENAI_COMPAT_BASE_URL)``so the baseline OpenAI-compat client talks straight toapi.anthropic.com."""- if self.openrouter_active:+ if self.baseline_provider in ("local", "openrouter"):return self.api_key, self.base_urlreturn self.direct_anthropic_api_key, ANTHROPIC_OPENAI_COMPAT_BASE_URL@@ -556,7 +753,8 @@ class ChatConfig(BaseSettings):deployment this routes aux through Anthropic (the title modelmust be Anthropic too — boot validator catches mismatches);in a single-key OpenRouter deployment it routes through OR- with the existing OR key.+ with the existing OR key; in a single-key local deployment+ it routes aux through the same self-hosted endpoint.2. **At least one aux env var set** — use the resolved auxvalues, falling back to the raw ``api_key`` / ``base_url``for whichever wasn't set. This is the explicit-split flow.@@ -587,8 +785,15 @@ class ChatConfig(BaseSettings):"""Cost-log ``provider`` label tracking the aux client's actualtransport.- Three buckets:+ Four buckets:+ - ``"ollama"`` (or whatever the local transport's+ ``cost_log_provider`` is) — local transport. Aux falls back to+ main creds under local, so the host-match heuristics below+ would otherwise mis-label the Ollama URL as ``"openai"`` and+ split the admin dashboard's per-provider rollup between+ ``"openai"`` (titles) and ``"ollama"`` (turns) for the same+ deployment.- ``"open_router"`` — base URL points at OpenRouter.- ``"anthropic"`` — base URL points at api.anthropic.com. Asingle-key direct-Anthropic deployment falls into this case@@ -597,6 +802,8 @@ class ChatConfig(BaseSettings):- ``"openai"`` — anything else (custom OAI-compat endpoint,plain api.openai.com, ...)."""+ if self.transport.name == "local":+ return self.transport.cost_log_provider_, base_url = self.aux_client_credentialsif not base_url:return "openai"@@ -639,20 +846,18 @@ class ChatConfig(BaseSettings):@field_validator("api_key", mode="before")@classmethoddef get_api_key(cls, v):- """Get API key from environment if not provided."""+ """Pick up ``CHAT_API_KEY`` from env if the field is unset.++ The transport-specific cross-key fallback (e.g. ``OPEN_ROUTER_API_KEY``,+ ``OPENAI_API_KEY``) runs in the model_validator so it can consult+ the resolved transport via ``self.transport.api_key_fallback_envs``+ — see ``_apply_transport_api_key_fallback``. Note: ``ANTHROPIC_API_KEY``+ is intentionally *never* in any fallback chain, because the SDK CLI+ reads it directly from the parent env — pairing it with an OpenRouter+ base_url at the chat layer would cause auth failures.+ """if not v:- # Try to get from environment variables- # First check for CHAT_API_KEY (Pydantic prefix)v = os.getenv("CHAT_API_KEY")- if not v:- # Fall back to OPEN_ROUTER_API_KEY- v = os.getenv("OPEN_ROUTER_API_KEY")- if not v:- # Fall back to OPENAI_API_KEY- v = os.getenv("OPENAI_API_KEY")- # Note: ANTHROPIC_API_KEY is intentionally NOT included here.- # The SDK CLI picks it up from the env directly. Including it- # would pair it with the OpenRouter base_url, causing auth failures.return v@field_validator("base_url", mode="before")@@ -748,45 +953,208 @@ class ChatConfig(BaseSettings):)return v+ @model_validator(mode="after")+ def _validate_local_transport_requirements(self) -> "ChatConfig":+ """Fail fast at config load when ``use_local`` lacks an explicit+ endpoint or auth token.++ Without this guard, ``CHAT_USE_LOCAL=true`` silently inherits the+ ``OPENROUTER_BASE_URL`` default from the ``base_url`` field+ validator and AutoPilot routes local-intended traffic at+ OpenRouter — usually with the operator's `OPENAI_API_KEY` as the+ bearer (since the api_key fallback chain ran in OpenRouter's+ order before the model_validator phase). The user gets an opaque+ 401 on the first turn instead of a clear "you turned on local+ but didn't tell me where" error at boot.++ Runs before ``_apply_transport_api_key_fallback`` (model_validators+ execute in definition order under pydantic 2) so we see+ ``api_key`` exactly as the operator set it (or didn't), not after+ a fallback has masked the omission.+ """+ if self.transport.name != "local":+ return self+ if not self.base_url or self.base_url.rstrip("/") == OPENROUTER_BASE_URL.rstrip(+ "/"+ ):+ raise ValueError(+ "CHAT_USE_LOCAL=true requires an explicit CHAT_BASE_URL "+ "(an OpenAI-compatible /v1 endpoint, e.g. "+ "http://host.docker.internal:11434/v1 for Ollama). "+ "The OpenRouter default isn't valid here — see "+ "docs/platform/copilot-local-llm.md."+ )+ if not self.api_key:+ raise ValueError(+ "CHAT_USE_LOCAL=true requires an explicit CHAT_API_KEY. "+ "Ollama doesn't validate it — any non-empty placeholder "+ "(e.g. 'ollama') is fine. See "+ "docs/platform/copilot-local-llm.md."+ )+ return self++ @model_validator(mode="after")+ def _apply_transport_api_key_fallback(self) -> "ChatConfig":+ """Fill ``api_key`` from the active transport's env fallback chain.++ Field validators see env vars before the model exists, so the+ per-transport policy ("openrouter falls back to OPEN_ROUTER_API_KEY,+ local does not fall back at all") cannot live in+ ``get_api_key``. Running it here keeps a single source of truth+ — ``self.transport.api_key_fallback_envs`` — and prevents the+ biggest local-transport footgun: a stray ``OPENAI_API_KEY`` set+ for graphiti / embedders silently overriding ``CHAT_API_KEY=ollama``.+ """+ if self.api_key:+ return self+ for env_name in self.transport.api_key_fallback_envs:+ if v := os.getenv(env_name):+ # Pydantic doesn't re-trigger field validators on object_setattr+ # — that's fine, we already have the value we want.+ object.__setattr__(self, "api_key", v)+ break+ return self++ @model_validator(mode="after")+ def _apply_local_aux_models(self) -> "ChatConfig":+ """Inherit ``fast_standard_model`` for the auxiliary model fields+ when the transport asks for it.++ The cloud defaults are ``openai/gpt-4o-mini`` / ``google/gemini-...``+ / ``anthropic/claude-opus-4.7`` — fine on OpenRouter, instant 404+ on a local backend (no provider slugs there). Operators on the+ local transport otherwise have to repeat the same Ollama slug+ across half a dozen ``CHAT_*_MODEL`` envs. Only fires when the+ field is still at the cloud default — explicit overrides win.++ Covers ``title_model`` + ``simulation_model`` (aux call sites)+ AND ``fast_advanced_model`` (the "advanced" baseline tier);+ without the advanced derivation, a user clicking the advanced+ toggle in the UI sends ``anthropic/claude-opus-4.7`` to Ollama+ and gets a model-not-found 404. The boot-time vendor validator+ is skipped under local transport so this misconfig wouldn't+ surface until the first advanced-tier turn.++ Overrides fire when the field still carries the cloud default+ OR carries a known cloud-vendor prefix (``openai/``,+ ``anthropic/``, ``google/``, ``meta-llama/``, ``mistralai/``,+ ``deepseek/``, ``qwen/``, ``x-ai/``, ``cohere/``). The+ cloud-vendor check catches operators who pinned a non-default+ cloud slug (e.g. ``CHAT_FAST_ADVANCED_MODEL=anthropic/claude-opus-4.6``)+ before switching to local — without it, the request-time 404+ would only surface on first use and+ ``_validate_sdk_model_vendor_compatibility`` is explicitly+ skipped under ``use_local=True`` so nothing catches it at boot.++ Custom registry paths (``myregistry.io/llama3.1``,+ ``huggingface.co/microsoft/phi-3``) are NOT touched — those are+ legitimate Ollama / OAI-compat model references. Bare slugs+ without a slash (``llama3.1:8b-instruct-q4_K_M``) are also+ treated as deliberate local-side overrides and left alone.++ For any slash-containing slug that does NOT match a known cloud+ vendor, we log a single startup WARNING so an operator who+ intentionally chose a non-default path sees a clear breadcrumb+ if the model later 404s at request time, rather than scratching+ their head about config-load behavior.+ """+ if not self.transport.inherit_fast_model_for_aux:+ return self++ # Vendor prefixes that exist in the OpenRouter catalog (i.e.+ # accepted by the cloud transports and rejected by Ollama's+ # OpenAI shim). Kept as an explicit set rather than detecting+ # any '/' so a custom registry path ('myregistry.io/foo') used+ # as a model name doesn't get silently rewritten.+ _CLOUD_VENDOR_PREFIXES = (+ "openai/",+ "anthropic/",+ "google/",+ "meta-llama/",+ "mistralai/",+ "deepseek/",+ "qwen/",+ "x-ai/",+ "cohere/",+ )++ def _is_cloud_default(value: str, default: str) -> bool:+ return value == default or value.startswith(_CLOUD_VENDOR_PREFIXES)++ for field_name, default in (+ ("title_model", _DEFAULT_TITLE_MODEL),+ ("simulation_model", _DEFAULT_SIMULATION_MODEL),+ ("fast_advanced_model", _DEFAULT_FAST_ADVANCED_MODEL),+ ):+ current = getattr(self, field_name)+ if _is_cloud_default(current, default):+ object.__setattr__(self, field_name, self.fast_standard_model)+ elif "/" in current:+ logger.warning(+ "Local transport: %s=%r contains '/' but no known cloud "+ "vendor prefix; passing through unchanged. If Ollama "+ "404s on this slug, override CHAT_%s_MODEL with a bare "+ "Ollama tag (e.g. %s).",+ field_name,+ current,+ field_name.upper().replace("_MODEL", ""),+ self.fast_standard_model,+ )+ return self+@model_validator(mode="after")def _validate_sdk_model_vendor_compatibility(self) -> "ChatConfig":"""Fail at config load when an SDK model slug is incompatible with- explicit direct-Anthropic mode.+ the operator's *explicit* opt-out from OpenRouter.The SDK path's ``_normalize_model_name`` raises ``ValueError`` whena non-Anthropic vendor slug (e.g. ``moonshotai/kimi-k2.6``) is pairedwith direct-Anthropic mode — but that fires inside the request loop,so a misconfigured deployment would surface a 500 to every user- instead of failing visibly at boot.-- Only the **explicit** opt-out (``use_openrouter=False``) is checked- here, not the credential-missing path. Build environments and+ instead of failing visibly at boot. Catching it at config load+ makes the misconfig obvious.++ Gated on **explicit operator intent flags**, NOT on the resolved+ ``effective_transport``. The credential-missing case (default+ ``use_openrouter=True`` but no ``api_key`` in env) makes+ ``effective_transport`` fall through to ``direct_anthropic`` —+ which would falsely trip a vendor-constraint check on configs+ that are merely "not yet wired up". Build environments andOpenAPI-schema export jobs construct ``ChatConfig()`` without any- OpenRouter credentials in the env — that's not a misconfiguration,- it's "config loads ok, but no SDK turn will succeed until creds are- wired". The runtime guard in ``_normalize_model_name`` still+ OpenRouter credentials in the env; that's not a misconfiguration,+ it's "config loads ok, but no SDK turn will succeed until creds+ are wired". The runtime guard in ``_normalize_model_name`` stillcatches the credential-missing path on the first SDK turn.+ Skipped when:+ - ``use_local=True`` — SDK never invoked under local transport.+ - ``use_claude_code_subscription=True`` — subscription resolves+ the static config to ``None`` (CLI default) and bypasses+ ``_normalize_model_name``. An LD-served override under+ subscription does flow through; the runtime guard handles it.+ - ``use_openrouter=True`` — operator hasn't opted out; the+ credential-missing case is OK at boot.++ Empty fallback strings are also skipped (no fallback configured).+Covers every model field that flows through``normalize_model_for_transport``: SDK tiers(``thinking_standard_model``, ``thinking_advanced_model``),baseline tiers (``fast_standard_model``,``fast_advanced_model``), and the SDK fallback(``claude_agent_fallback_model`` via ``_resolve_fallback_model``).-- Skipped when ``use_claude_code_subscription=True`` because the- subscription path normally resolves the static config to ``None``- (CLI default). An LD-served override under subscription does- flow through ``_normalize_model_name``; the runtime guard first- falls back to the tier default, and only avoids a request error- when that default is itself valid (otherwise the original LD- ValueError is re-raised — see ``_resolve_sdk_model_for_request``).- Empty fallback strings are also skipped (no fallback configured)."""+ if self.use_local:+ return selfif self.use_claude_code_subscription:return selfif self.use_openrouter:return self+ # Explicit direct-Anthropic mode — read the constraint from the+ # profile so the value is single-sourced (still ``"anthropic"``).+ constraint = _TRANSPORT_PROFILES["direct_anthropic"].sdk_model_vendor_constraint+ if constraint is None:+ return selffor field_name in ("thinking_standard_model","thinking_advanced_model",@@ -798,16 +1166,16 @@ class ChatConfig(BaseSettings):if not value:continueif "/" in value:- if value.split("/", 1)[0] != "anthropic":+ if value.split("/", 1)[0] != constraint:raise ValueError(f"Direct-Anthropic mode (use_openrouter=False) "- f"requires an Anthropic model for {field_name}, got "- f"{value!r}. Set CHAT_THINKING_STANDARD_MODEL / "+ f"requires a {constraint}/* model for {field_name}, "+ f"got {value!r}. Set CHAT_THINKING_STANDARD_MODEL / "f"CHAT_THINKING_ADVANCED_MODEL / "f"CHAT_FAST_STANDARD_MODEL / "f"CHAT_FAST_ADVANCED_MODEL / "f"CHAT_CLAUDE_AGENT_FALLBACK_MODEL to an "- f"``anthropic/*`` or ``claude-*`` slug, or set "+ f"``{constraint}/*`` or ``claude-*`` slug, or set "f"CHAT_USE_OPENROUTER=true.")elif not value.startswith("claude-"):@@ -817,8 +1185,8 @@ class ChatConfig(BaseSettings):# request time (``normalize_model_for_transport`` raises).raise ValueError(f"Direct-Anthropic mode (use_openrouter=False) "- f"requires an Anthropic model slug for {field_name}, "- f"got {value!r}. Use an ``anthropic/*`` or "+ f"requires an {constraint} model slug for {field_name}, "+ f"got {value!r}. Use an ``{constraint}/*`` or "f"``claude-*`` slug, or set CHAT_USE_OPENROUTER=true.")return self@@ -848,11 +1216,21 @@ class ChatConfig(BaseSettings):``(None, api.anthropic.com)`` from main, 401-ing every call.Skipped when the resolved aux transport is OpenRouter — OR can- serve any vendor prefix. Also skipped on a fully-empty config- (no main creds + no aux creds + no subscription) so build /- OpenAPI-schema-export environments that construct- ``ChatConfig()`` without env vars don't fail.+ serve any vendor prefix. Also skipped under local transport —+ aux routes to the same self-hosted backend, never Anthropic.+ Also skipped on a fully-empty config (no main creds + no aux+ creds + no subscription) so build / OpenAPI-schema-export+ environments that construct ``ChatConfig()`` without env vars+ don't fail."""+ # Local transport routes aux through the same self-hosted+ # endpoint as main (Ollama, vLLM, …); the Anthropic-only title+ # constraint doesn't apply. ``_apply_local_aux_models`` already+ # rewrote ``title_model`` to ``fast_standard_model`` (typically+ # a bare local slug like ``llama3.1:8b``) — the title check+ # below would otherwise reject every local config.+ if self.transport.name == "local":+ return self# Empty-config escape hatch: build / openapi-export / pytest-# collection environments construct ``ChatConfig()`` without any# creds. In that shape ``main_client_credentials`` returnsdiff --git a/autogpt_platform/backend/backend/copilot/config_test.py b/autogpt_platform/backend/backend/copilot/config_test.pyindex a293af6dbf..627642afcc 100644--- a/autogpt_platform/backend/backend/copilot/config_test.py+++ b/autogpt_platform/backend/backend/copilot/config_test.py@@ -2,6 +2,8 @@import pytest+from backend.util.clients import OPENROUTER_BASE_URL+from .config import ChatConfig, _host_matches# Env vars that the ChatConfig validators read — must be cleared so they don't@@ -16,6 +18,7 @@ _ENV_VARS_TO_CLEAR = ("CHAT_USE_OPENROUTER","CHAT_USE_CLAUDE_AGENT_SDK","CHAT_USE_CLAUDE_CODE_SUBSCRIPTION",+ "CHAT_USE_LOCAL","CHAT_API_KEY","OPEN_ROUTER_API_KEY","OPENAI_API_KEY",@@ -217,7 +220,9 @@ class TestSdkModelVendorCompatibility:def test_direct_anthropic_with_kimi_override_raises(self):"""A non-Anthropic SDK model must fail at config load when thedeployment has no OpenRouter credentials."""- with pytest.raises(Exception, match="requires an Anthropic model"):+ with pytest.raises(+ Exception, match=r"Direct-Anthropic mode.*anthropic/\* model"+ ):ChatConfig(use_openrouter=False,api_key=None,@@ -299,6 +304,40 @@ class TestSdkModelVendorCompatibility:claude_agent_fallback_model="moonshotai/kimi-k2.6",)+ def test_credentialless_default_construct_does_not_raise(self):+ """Build environments and OpenAPI-schema export jobs construct+ ``ChatConfig()`` with no API keys in the env; the SDK vendor+ validator must NOT trip on that case. Regression guard against+ the descriptor-refactor where the validator started reading+ ``self.transport.sdk_model_vendor_constraint`` (which falls+ through to ``direct_anthropic`` when openrouter creds are+ missing) instead of the explicit ``use_openrouter`` flag.++ The contract: as long as the operator hasn't *explicitly* set+ ``use_openrouter=False``, the validator skips — no boot-time+ error for "haven't wired up creds yet"."""+ # Simulates a fresh build env: default flags, no creds. No+ # ``thinking_*_model`` overrides so the field defaults+ # (``anthropic/...``) wouldn't trip the check anyway, but the+ # important assertion is that construction succeeds at all.+ cfg = ChatConfig(api_key=None, base_url=None)+ assert cfg.use_openrouter is True+ assert cfg.api_key is None++ def test_credentialless_default_with_non_anthropic_override_does_not_raise(+ self,+ ):+ """Same as above but with an explicit non-anthropic SDK model+ slug. Still must construct cleanly because the operator has not+ opted out of OpenRouter — the runtime guard catches the actual+ mismatch on the first SDK turn."""+ cfg = ChatConfig(+ api_key=None,+ base_url=None,+ thinking_standard_model="moonshotai/kimi-k2.6",+ )+ assert cfg.thinking_standard_model == "moonshotai/kimi-k2.6"+def test_fast_standard_model_also_validated(self):"""Baseline (fast) tier slugs flow through the same``normalize_model_for_transport``, so the validator must catch@@ -374,6 +413,319 @@ class TestSdkModelVendorCompatibility:assert cfg.claude_agent_fallback_model == ""+class TestTransportProfile:+ """The ``transport`` property is the single source of truth for+ per-transport behaviour — every other check (SDK gate, vendor+ constraint, api_key fallback, aux-model derivation) reads it+ instead of branching on ``use_X`` flags directly. These tests+ pin the descriptor table so a hidden change to either the+ profile contents or the ``effective_transport`` selection+ surfaces immediately."""++ def test_local_profile_shape(self):+ cfg = ChatConfig(use_local=True, api_key="ollama", base_url="http://h:11434/v1")+ p = cfg.transport+ assert p.name == "local"+ assert p.supports_sdk is False+ assert p.sdk_model_vendor_constraint is None+ assert p.api_key_fallback_envs == ()+ assert p.inherit_fast_model_for_aux is True+ assert p.cost_log_provider == "ollama"++ def test_openrouter_profile_shape(self):+ cfg = ChatConfig(+ use_openrouter=True,+ api_key="or-key",+ base_url="https://openrouter.ai/api/v1",+ )+ p = cfg.transport+ assert p.name == "openrouter"+ assert p.supports_sdk is True+ assert p.sdk_model_vendor_constraint is None+ assert "OPEN_ROUTER_API_KEY" in p.api_key_fallback_envs+ assert "OPENAI_API_KEY" in p.api_key_fallback_envs+ assert p.inherit_fast_model_for_aux is False+ assert p.cost_log_provider == "open_router"++ def test_subscription_profile_shape(self):+ cfg = _make_direct_safe_config(use_claude_code_subscription=True)+ p = cfg.transport+ assert p.name == "subscription"+ assert p.supports_sdk is True+ assert p.sdk_model_vendor_constraint is None+ assert p.api_key_fallback_envs == ()+ assert p.inherit_fast_model_for_aux is False+ assert p.cost_log_provider == "anthropic"++ def test_direct_anthropic_profile_shape(self):+ cfg = _make_direct_safe_config(+ use_openrouter=False, api_key=None, base_url=None+ )+ p = cfg.transport+ assert p.name == "direct_anthropic"+ assert p.supports_sdk is True+ assert p.sdk_model_vendor_constraint == "anthropic"+ assert p.cost_log_provider == "anthropic"++ def test_thinking_available_alias_matches_profile(self):+ """``thinking_available`` is a backwards-compat alias used by+ ``executor.processor.resolve_use_sdk_for_mode`` — must stay in+ sync with ``transport.supports_sdk``."""+ for kwargs in (+ dict(use_local=True, api_key="ollama", base_url="http://h:11434/v1"),+ dict(use_claude_code_subscription=True),+ dict(+ use_openrouter=True,+ api_key="or-key",+ base_url="https://openrouter.ai/api/v1",+ ),+ ):+ cfg = _make_direct_safe_config(**kwargs)+ assert cfg.thinking_available == cfg.transport.supports_sdk+++class TestApiKeyFallback:+ """The fallback chain (``OPEN_ROUTER_API_KEY`` → ``OPENAI_API_KEY``)+ fires from a model_validator that reads+ ``self.transport.api_key_fallback_envs`` — so each transport gets+ its own policy without scattered env checks."""++ def test_local_does_not_fall_back_to_openai_key(+ self, monkeypatch: pytest.MonkeyPatch+ ):+ """Critical safety check: a stray ``OPENAI_API_KEY`` (set by users+ for graphiti / embedders) must not silently bind to AutoPilot's+ local Ollama endpoint as the bearer token. The fallback chain+ for local is empty by design — and the+ ``_validate_local_transport_requirements`` guard surfaces the+ missing ``CHAT_API_KEY`` as an explicit boot-time error rather+ than letting the leaked OpenAI key be quietly accepted."""+ monkeypatch.setenv("OPENAI_API_KEY", "sk-leaked-from-graphiti")+ with pytest.raises(Exception, match=r"CHAT_API_KEY"):+ ChatConfig(use_local=True, base_url="http://h:11434/v1")++ def test_openrouter_falls_back_to_open_router_api_key(+ self, monkeypatch: pytest.MonkeyPatch+ ):+ monkeypatch.setenv("OPEN_ROUTER_API_KEY", "or-fallback")+ cfg = ChatConfig(use_openrouter=True, base_url="https://openrouter.ai/api/v1")+ assert cfg.api_key == "or-fallback"++ def test_explicit_api_key_wins_over_env_fallback(+ self, monkeypatch: pytest.MonkeyPatch+ ):+ monkeypatch.setenv("OPENAI_API_KEY", "sk-from-env")+ cfg = ChatConfig(+ use_openrouter=True,+ api_key="explicit",+ base_url="https://openrouter.ai/api/v1",+ )+ assert cfg.api_key == "explicit"+++class TestLocalAuxModels:+ """``title_model`` / ``simulation_model`` cloud defaults instant-404+ on a local backend; under the local transport they inherit the+ operator's ``fast_standard_model`` so the local install needs only+ one model slug instead of three."""++ def test_local_inherits_fast_model(self):+ cfg = ChatConfig(+ use_local=True,+ api_key="ollama",+ base_url="http://h:11434/v1",+ fast_standard_model="llama3.1:8b-instruct-q4_K_M",+ )+ assert cfg.title_model == "llama3.1:8b-instruct-q4_K_M"+ assert cfg.simulation_model == "llama3.1:8b-instruct-q4_K_M"+ # ``fast_advanced_model`` must inherit too — without it, the+ # "advanced" tier button in the UI sends the cloud opus slug to+ # Ollama and 404s. Boot-time vendor validator is skipped under+ # local transport so the misconfig wouldn't surface until the+ # first advanced-tier turn.+ assert cfg.fast_advanced_model == "llama3.1:8b-instruct-q4_K_M"++ def test_explicit_aux_model_wins(self):+ """Operators who genuinely want a different aux model (e.g.+ a tiny ``qwen3:0.6b`` for titles) must still be able to override."""+ cfg = ChatConfig(+ use_local=True,+ api_key="ollama",+ base_url="http://h:11434/v1",+ fast_standard_model="llama3.1:8b-instruct-q4_K_M",+ title_model="qwen3:0.6b",+ simulation_model="qwen3:4b",+ fast_advanced_model="llama3.1:70b",+ )+ assert cfg.title_model == "qwen3:0.6b"+ assert cfg.simulation_model == "qwen3:4b"+ assert cfg.fast_advanced_model == "llama3.1:70b"++ def test_non_default_cloud_slug_rewritten_under_local(self):+ """Any ``provider/slug`` value is rewritten to ``fast_standard_model``+ under local transport — not just the exact cloud default. Operators+ who pinned a cloud slug (e.g. ``anthropic/claude-opus-4.6``) before+ adding ``CHAT_USE_LOCAL=true`` would otherwise hit a 404 on the+ first advanced-tier turn (``_validate_sdk_model_vendor_compatibility``+ is skipped under local so nothing catches it at boot)."""+ cfg = ChatConfig(+ use_local=True,+ api_key="ollama",+ base_url="http://h:11434/v1",+ fast_standard_model="llama3.1:8b-instruct-q4_K_M",+ title_model="openai/gpt-4o-mini",+ simulation_model="google/gemini-2.5-flash",+ fast_advanced_model="anthropic/claude-opus-4.6",+ )+ assert cfg.title_model == "llama3.1:8b-instruct-q4_K_M"+ assert cfg.simulation_model == "llama3.1:8b-instruct-q4_K_M"+ assert cfg.fast_advanced_model == "llama3.1:8b-instruct-q4_K_M"++ def test_cloud_transport_does_not_inherit(self):+ """Cloud transports leave the per-field cloud defaults alone — an+ operator might genuinely want gpt-4o-mini for titles even though+ their primary model is anthropic/claude-sonnet-4-6."""+ cfg = ChatConfig(+ use_openrouter=True,+ api_key="or-key",+ base_url="https://openrouter.ai/api/v1",+ )+ assert cfg.title_model == "anthropic/claude-haiku-4-5"+ assert cfg.simulation_model == "google/gemini-2.5-flash-lite"+ assert cfg.fast_advanced_model == "anthropic/claude-opus-4.7"+++class TestLocalRequirementsValidator:+ """``_validate_local_transport_requirements`` rejects the silent+ misconfig where ``CHAT_USE_LOCAL=true`` was set but the operator+ forgot to provide either an endpoint or an api key. Without it the+ base_url field validator silently fills the OpenRouter default and+ AutoPilot's first turn 401s — much worse UX than a startup error+ pointing at the missing env var."""++ def test_explicit_base_url_and_api_key_succeeds(self):+ cfg = ChatConfig(use_local=True, api_key="ollama", base_url="http://h:11434/v1")+ assert cfg.transport.name == "local"++ def test_missing_base_url_raises(self):+ """No CHAT_BASE_URL → base_url field defaults to OpenRouter — the+ validator should catch it and refuse to boot."""+ with pytest.raises(Exception, match=r"CHAT_BASE_URL"):+ ChatConfig(use_local=True, api_key="ollama")++ def test_explicit_openrouter_base_url_under_local_raises(self):+ """Even if the operator copy-pasted the OpenRouter URL into+ CHAT_BASE_URL by mistake, the validator catches it — local+ transport against the OpenRouter endpoint is never intentional."""+ with pytest.raises(Exception, match=r"CHAT_BASE_URL"):+ ChatConfig(use_local=True, api_key="ollama", base_url=OPENROUTER_BASE_URL)++ def test_missing_api_key_raises(self):+ with pytest.raises(Exception, match=r"CHAT_API_KEY"):+ ChatConfig(use_local=True, base_url="http://h:11434/v1")++ def test_cloud_transport_unaffected(self):+ """Validator must not fire for non-local transports — they have+ their own (existing) credential handling and base_url defaults."""+ cfg = ChatConfig(+ use_openrouter=True,+ api_key="or-key",+ base_url="https://openrouter.ai/api/v1",+ )+ assert cfg.transport.name == "openrouter"+++class TestLocalTransport:+ """``use_local=True`` exposes a 4th ``effective_transport`` value+ (``'local'``) for self-hosted OpenAI-compatible endpoints (Ollama et al.).++ Local transport is mutually exclusive with the SDK path because the+ Claude Agent SDK CLI speaks Anthropic's wire protocol and Ollama+ doesn't implement it. ``thinking_available`` reports this so the+ request layer can downgrade gracefully (see+ ``executor.processor.resolve_use_sdk_for_mode``)."""++ def test_local_transport_overrides_subscription(self):+ """An operator opting into local self-hosting must not have their+ choice silently bypassed by an inherited subscription token."""+ cfg = ChatConfig(+ use_local=True,+ use_claude_code_subscription=True,+ api_key="ollama",+ base_url="http://host.docker.internal:11434/v1",+ )+ assert cfg.effective_transport == "local"++ def test_local_transport_overrides_openrouter(self):+ """Same defense for OpenRouter credentials that happen to be in+ the env (CI inheritance, dev workstation, etc.). Note we use a+ non-OpenRouter ``base_url`` here because ``use_local=True`` with+ the OpenRouter URL is rejected by+ ``_validate_local_transport_requirements`` — that combo is+ almost always a typo, and the validator surfaces it at boot+ rather than silently routing to OpenRouter."""+ cfg = ChatConfig(+ use_local=True,+ use_openrouter=True,+ api_key="or-key",+ base_url="http://h:11434/v1",+ )+ assert cfg.effective_transport == "local"++ def test_thinking_available_false_under_local(self):+ cfg = ChatConfig(+ use_local=True,+ api_key="ollama",+ base_url="http://localhost:11434/v1",+ )+ assert cfg.thinking_available is False++ def test_thinking_available_true_otherwise(self):+ """Every non-local transport can serve SDK turns — the Claude+ Agent CLI works against subscription, OpenRouter, or direct+ Anthropic auth."""+ for kwargs in (+ dict(use_claude_code_subscription=True),+ dict(+ use_openrouter=True,+ api_key="or-key",+ base_url="https://openrouter.ai/api/v1",+ ),+ dict(use_openrouter=False, api_key=None, base_url=None),+ ):+ cfg = _make_direct_safe_config(**kwargs)+ assert cfg.thinking_available is True++ def test_local_skips_sdk_vendor_validator(self):+ """Operators on local transport must not be forced to set+ anthropic/* placeholders for SDK fields they will never use."""+ cfg = ChatConfig(+ use_local=True,+ use_openrouter=False,+ api_key="ollama",+ base_url="http://localhost:11434/v1",+ thinking_standard_model="llama3.2:3b",+ thinking_advanced_model="llama3.1:8b",+ claude_agent_fallback_model="phi3:mini",+ )+ assert cfg.thinking_standard_model == "llama3.2:3b"++ def test_default_use_local_is_false(self):+ """Default deployments stay on the existing transports."""+ cfg = ChatConfig()+ assert cfg.use_local is False+ assert cfg.effective_transport != "local"+ assert cfg.thinking_available is True++ def test_env_var_picked_up(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("CHAT_USE_LOCAL", "true")+ monkeypatch.setenv("CHAT_API_KEY", "ollama")+ monkeypatch.setenv("CHAT_BASE_URL", "http://ollama:11434/v1")+ cfg = ChatConfig()+ assert cfg.use_local is True+ assert cfg.effective_transport == "local"++class TestRenderReasoningInUi:"""``render_reasoning_in_ui`` gates reasoning wire events globally."""@@ -409,6 +761,64 @@ class TestStreamReplayCount:ChatConfig(stream_replay_count=0)+class TestBaselineProvider:+ """``baseline_provider`` keeps the baseline wire format and cost attribution+ aligned with the endpoint ``main_client_credentials`` actually dials."""++ def test_subscription_with_openrouter_creds_resolves_to_openrouter(self):+ """Subscription + OR creds present routes the baseline OpenAI-compat+ client to OpenRouter (the CLI's OAuth can't drive it), so the wire+ format must be OpenRouter too. Regression for keying the dialect on+ ``transport.name == "openrouter"`` — ``"subscription"`` here — which+ sent direct-Anthropic shape to the OR endpoint."""+ cfg = ChatConfig(+ use_claude_code_subscription=True,+ use_openrouter=True,+ api_key="or-key",+ base_url="https://openrouter.ai/api/v1",+ )+ # The endpoint and the dialect must agree.+ assert cfg.effective_transport == "subscription"+ assert cfg.main_client_credentials == (+ "or-key",+ "https://openrouter.ai/api/v1",+ )+ assert cfg.baseline_provider == "openrouter"++ def test_subscription_without_openrouter_resolves_to_anthropic(self):+ cfg = _make_direct_safe_config(use_claude_code_subscription=True)+ assert cfg.baseline_provider == "anthropic"++ def test_local_creds_do_not_leak_to_openrouter(self):+ """A local install whose default ``api_key="ollama"`` satisfies the+ shape-only ``openrouter_active`` must still resolve to ``local`` so OR+ request shape never leaks into local turns."""+ cfg = ChatConfig(+ use_local=True,+ use_openrouter=True,+ api_key="ollama",+ base_url="http://h:11434/v1",+ )+ assert cfg.baseline_provider == "local"++ def test_openrouter_transport_resolves_to_openrouter(self):+ cfg = ChatConfig(+ use_openrouter=True,+ api_key="or-key",+ base_url="https://openrouter.ai/api/v1",+ )+ assert cfg.baseline_provider == "openrouter"++ def test_direct_mode_resolves_to_anthropic(self):+ cfg = _make_direct_safe_config(+ use_openrouter=False,+ direct_anthropic_api_key="anthropic-key",+ api_key=None,+ base_url=None,+ )+ assert cfg.baseline_provider == "anthropic"++class TestMainClientCredentials:"""``main_client_credentials`` picks the right (api_key, base_url) per transport."""@@ -568,6 +978,23 @@ class TestAuxProviderLabel:)assert cfg.aux_provider_label == "openai"+ def test_local_transport_returns_ollama(self):+ """Under local transport, aux falls back to main creds (the Ollama+ URL). Without the explicit ``transport.name == 'local'`` short-circuit+ the host-match cascade lands on the ``"openai"`` fallback, splitting+ the admin dashboard's per-provider cost rollup between ``"openai"``+ (title rows via this label) and ``"ollama"`` (turn rows via+ ``transport.cost_log_provider``) for the same local-transport+ deployment."""+ cfg = ChatConfig(+ use_local=True,+ api_key="ollama",+ base_url="http://localhost:11434/v1",+ fast_standard_model="llama3.1:8b-instruct-q4_K_M",+ )+ assert cfg.aux_provider_label == "ollama"+ assert cfg.aux_provider_label == cfg.transport.cost_log_provider+class TestAuxClientForDirectMainValidator:"""``_validate_aux_client_for_direct_main`` fails fast at boot whendiff --git a/autogpt_platform/backend/backend/copilot/executor/processor.py b/autogpt_platform/backend/backend/copilot/executor/processor.pyindex fc126847df..68ae65b111 100644--- a/autogpt_platform/backend/backend/copilot/executor/processor.py+++ b/autogpt_platform/backend/backend/copilot/executor/processor.py@@ -149,6 +149,7 @@ async def resolve_use_sdk_for_mode(*,use_claude_code_subscription: bool,config_default: bool,+ thinking_available: bool = True,) -> bool:"""Pick the SDK vs baseline path for a single turn.@@ -156,7 +157,21 @@ async def resolve_use_sdk_for_mode(``CHAT_MODE_OPTION`` gate has been applied upstream). Otherwisefalls back to the Claude Code subscription override, then the``COPILOT_SDK`` LaunchDarkly flag, then the config default.++ ``thinking_available`` is the kill-switch for deployments where the+ SDK transport simply cannot run (today: ``CHAT_USE_LOCAL=true`` —+ Ollama doesn't speak Anthropic's wire protocol). When False the+ baseline path is forced regardless of mode / flags / subscription;+ an explicit ``mode='extended_thinking'`` request is logged at WARNING+ so misconfigured deployments are visible without 500s."""+ if not thinking_available:+ if mode == "extended_thinking":+ logger.warning(+ "Downgrading mode=extended_thinking to fast: SDK is "+ "unavailable under the current transport (CHAT_USE_LOCAL=true)"+ )+ return Falseif mode == "fast":return Falseif mode == "extended_thinking":@@ -501,6 +516,7 @@ class CoPilotProcessor:entry.user_id,use_claude_code_subscription=config.use_claude_code_subscription,config_default=config.use_claude_agent_sdk,+ thinking_available=config.thinking_available,)stream_fn = (sdk_service.stream_chat_completion_sdkdiff --git a/autogpt_platform/backend/backend/copilot/executor/processor_test.py b/autogpt_platform/backend/backend/copilot/executor/processor_test.pyindex 66b74f26a4..609999f85f 100644--- a/autogpt_platform/backend/backend/copilot/executor/processor_test.py+++ b/autogpt_platform/backend/backend/copilot/executor/processor_test.py@@ -134,6 +134,50 @@ class TestResolveUseSdkForMode:is False)+ @pytest.mark.asyncio+ async def test_thinking_unavailable_forces_baseline(self, caplog):+ """When the SDK transport can't run (use_local=true), every mode+ routes to baseline — including an explicit extended_thinking+ request, which is logged at WARNING for visibility."""+ caplog.set_level(logging.WARNING, logger="backend.copilot.executor.processor")+ with patch(+ "backend.copilot.executor.processor.is_feature_enabled",+ new=AsyncMock(return_value=True),+ ):+ for mode in ("fast", "extended_thinking", None):+ assert (+ await resolve_use_sdk_for_mode(+ mode,+ "user-1",+ use_claude_code_subscription=True,+ config_default=True,+ thinking_available=False,+ )+ is False+ )+ warnings = [r for r in caplog.records if r.levelname == "WARNING"]+ assert len(warnings) == 1+ assert "extended_thinking" in warnings[0].message++ @pytest.mark.asyncio+ async def test_thinking_available_default_preserves_legacy_behaviour(self):+ """The new ``thinking_available`` kwarg defaults to True, so+ existing call sites (and existing tests in this class) continue+ to work without explicit opt-in."""+ with patch(+ "backend.copilot.executor.processor.is_feature_enabled",+ new=AsyncMock(return_value=False),+ ):+ assert (+ await resolve_use_sdk_for_mode(+ "extended_thinking",+ "user-1",+ use_claude_code_subscription=False,+ config_default=False,+ )+ is True+ )+class TestResolveEffectiveMode:"""Tests for the CHAT_MODE_OPTION server-side gate."""diff --git a/autogpt_platform/backend/backend/copilot/local_context_probe.py b/autogpt_platform/backend/backend/copilot/local_context_probe.pynew file mode 100644index 0000000000..15aef47164--- /dev/null+++ b/autogpt_platform/backend/backend/copilot/local_context_probe.py@@ -0,0 +1,206 @@+"""Auto-detect the context window of a local OpenAI-compatible LLM backend.++The local transport (``CHAT_USE_LOCAL=true``) talks to an operator-run backend+(Ollama, vLLM, LM Studio, llama.cpp server, …). That backend's *loaded* context+window — not any AutoGPT-side config — is the real ceiling AutoPilot must compact+its conversation under. Rather than carry a second config value that has to be+kept in lockstep with the server (and silently drifts), we read the window back+from the backend at runtime.++Probe order (first hit wins; every probe is best-effort, all errors swallowed):++ Ollama GET {root}/api/ps models[].context_length+ llama.cpp GET {root}/props default_generation_settings.n_ctx+ vLLM GET {base}/models data[].max_model_len+ LM Studio GET {root}/api/v0/models data[].max_context_length++Backends that expose nothing standard (LiteLLM proxy, Jan, text-generation-webui)+fall back to ``LOCAL_CONTEXT_FALLBACK`` (32768) — conservative: AutoPilot compacts+as if the window were 32k, retaining less history rather than overflowing.++``{root}`` is the base URL minus a trailing ``/v1``. The Ollama probe only returns+a value while a model is loaded; that's fine because the window is needed for+*compaction*, which only matters after a few turns — by which point an earlier+turn has already loaded the model.+"""++import logging+import time++import httpx++logger = logging.getLogger(__name__)++# ``compaction_target_for_window`` reserves this much of the window for the+# static per-turn floor (system prompt + ~43 tool schemas ≈ 19k measured) plus+# ~5k headroom for content a turn appends *after* the turn-start compaction+# check (tool results, the new user message) — without it a chunky tool result+# can push one turn past a small window before the next compaction fires.+# ``compress_context`` applies its own ~2k response reserve on top. The+# conversation-history budget is therefore ``window - _FLOOR_RESERVE``.+_FLOOR_RESERVE = 24_000+_TARGET_FLOOR = 4_096++# Used when no backend reports a window. Matches the installer's default+# ``OLLAMA_CONTEXT_LENGTH`` so the common Ollama path is correct even when the+# model is briefly unloaded and ``/api/ps`` is empty.+LOCAL_CONTEXT_FALLBACK = 32_768++# Below this, the ~19k floor leaves almost no room for conversation — the+# operator's backend window is misconfigured for AutoPilot.+_MINIMUM_SAFE_WINDOW = 24_576++_PROBE_TIMEOUT_S = 2.0+_CACHE_TTL_S = 300.0++# Both keyed by (base_url, model): vLLM / LM Studio expose a *per-model* window,+# so caching by base_url alone would serve one model's window for another.+# ``_last_window`` never expires and is reused when a probe can't determine the+# window (e.g. the model isn't loaded yet) — a far better fallback than the+# optimistic constant.+_CacheKey = tuple[str, str]+_probe_cache: dict[_CacheKey, tuple[int, float]] = {}+_last_window: dict[_CacheKey, int] = {}+++def compaction_target_for_window(window: int) -> int:+ """Token budget for conversation history given the backend's ``window``.++ Floored at ``_TARGET_FLOOR`` so the value is never zero/negative on a+ pathologically small window (a separate WARNING is logged by the probe).+ """+ return max(_TARGET_FLOOR, window - _FLOOR_RESERVE)+++def _cache_get(key: _CacheKey) -> int | None:+ entry = _probe_cache.get(key)+ if entry is None:+ return None+ window, fetched_at = entry+ if time.monotonic() - fetched_at > _CACHE_TTL_S:+ del _probe_cache[key]+ return None+ return window+++def _server_root(base_url: str) -> str:+ """Strip a trailing ``/v1`` (or ``/v1/``) from the OpenAI-compat base URL."""+ url = base_url.rstrip("/")+ if url.endswith("/v1"):+ url = url[:-3]+ return url.rstrip("/")+++async def probe_local_context_window(base_url: str, model: str) -> int:+ """Return the loaded context window (tokens) for ``model`` at ``base_url``.++ Cached per ``(base_url, model)`` for 5 minutes so it never fires on every+ turn. When a probe can't determine the window (e.g. the model isn't loaded+ yet), reuses the last successfully-detected window for that endpoint+model+ if known — a far better estimate than the optimistic constant — and does+ NOT cache the miss, so the next turn re-probes once a model is loaded. Logs+ a WARNING when a detected window is below ``_MINIMUM_SAFE_WINDOW``.+ """+ key = (base_url, model)+ cached = _cache_get(key)+ if cached is not None:+ return cached++ detected = await _detect_window(base_url, model)+ if detected is None:+ return _last_window.get(key, LOCAL_CONTEXT_FALLBACK)++ _last_window[key] = detected+ if detected < _MINIMUM_SAFE_WINDOW:+ logger.warning(+ "[LocalProbe] Backend at %s reports a %d-token context window — below "+ "the %d-token minimum AutoPilot needs (its system prompt + tools use "+ "~19k alone, leaving only ~%d for conversation). Raise the backend's "+ "context length (e.g. OLLAMA_CONTEXT_LENGTH=%d) to avoid truncation.",+ base_url,+ detected,+ _MINIMUM_SAFE_WINDOW,+ max(0, detected - _FLOOR_RESERVE),+ _MINIMUM_SAFE_WINDOW,+ )+ _probe_cache[key] = (detected, time.monotonic())+ return detected+++async def _detect_window(base_url: str, model: str) -> int | None:+ root = _server_root(base_url)+ base = base_url.rstrip("/")+ model_base = model.split(":")[0]++ async with httpx.AsyncClient(timeout=_PROBE_TIMEOUT_S) as client:+ # 1. Ollama — GET {root}/api/ps -> models[].context_length.+ # The window is a server-wide setting (OLLAMA_CONTEXT_LENGTH), so any+ # loaded model reflects it; prefer a name match, else the first model.+ try:+ resp = await client.get(f"{root}/api/ps")+ if resp.status_code == 200:+ models = resp.json().get("models") or []+ match = next(+ (+ m+ for m in models+ if str(m.get("name", "")).startswith(model_base)+ ),+ models[0] if models else None,+ )+ if match:+ ctx = match.get("context_length")+ if isinstance(ctx, int) and ctx > 0:+ logger.debug(+ "[LocalProbe] Ollama /api/ps context_length=%d", ctx+ )+ return ctx+ except Exception as exc:+ logger.debug("[LocalProbe] /api/ps probe failed: %s", exc)++ # 2. llama.cpp server — GET {root}/props -> default_generation_settings.n_ctx+ try:+ resp = await client.get(f"{root}/props")+ if resp.status_code == 200:+ n_ctx = (resp.json().get("default_generation_settings") or {}).get(+ "n_ctx"+ )+ if isinstance(n_ctx, int) and n_ctx > 0:+ logger.debug("[LocalProbe] llama.cpp /props n_ctx=%d", n_ctx)+ return n_ctx+ except Exception as exc:+ logger.debug("[LocalProbe] /props probe failed: %s", exc)++ # 3. vLLM — GET {base}/models -> data[].max_model_len+ try:+ resp = await client.get(f"{base}/models")+ if resp.status_code == 200:+ for m in resp.json().get("data") or []:+ if model in (m.get("id"), m.get("name")):+ ctx = m.get("max_model_len")+ if isinstance(ctx, int) and ctx > 0:+ logger.debug("[LocalProbe] vLLM max_model_len=%d", ctx)+ return ctx+ except Exception as exc:+ logger.debug("[LocalProbe] /models probe failed: %s", exc)++ # 4. LM Studio — GET {root}/api/v0/models -> data[].max_context_length+ try:+ resp = await client.get(f"{root}/api/v0/models")+ if resp.status_code == 200:+ for m in resp.json().get("data") or []:+ if model in (m.get("id"), m.get("name")):+ ctx = m.get("max_context_length")+ if isinstance(ctx, int) and ctx > 0:+ logger.debug(+ "[LocalProbe] LM Studio max_context_length=%d", ctx+ )+ return ctx+ except Exception as exc:+ logger.debug("[LocalProbe] /api/v0/models probe failed: %s", exc)++ logger.debug(+ "[LocalProbe] No backend window detected at %s; caller will fall back",+ base_url,+ )+ return Nonediff --git a/autogpt_platform/backend/backend/copilot/local_context_probe_test.py b/autogpt_platform/backend/backend/copilot/local_context_probe_test.pynew file mode 100644index 0000000000..622f6344fd--- /dev/null+++ b/autogpt_platform/backend/backend/copilot/local_context_probe_test.py@@ -0,0 +1,301 @@+"""Tests for backend/copilot/local_context_probe.py.++Covers the core compaction-target regression (no more 120k default for local+models) plus all four probe strategies and the fallback/cache paths. All probes+are mocked — no network.+"""++import logging+import time+from unittest.mock import AsyncMock, MagicMock, patch++import pytest++from backend.copilot.local_context_probe import (+ _MINIMUM_SAFE_WINDOW,+ LOCAL_CONTEXT_FALLBACK,+ _last_window,+ _probe_cache,+ _server_root,+ compaction_target_for_window,+ probe_local_context_window,+)+++def _resp(status: int, body: dict) -> MagicMock:+ r = MagicMock()+ r.status_code = status+ r.json.return_value = body+ return r+++def _mock_client(responses) -> MagicMock:+ """An httpx.AsyncClient mock whose GETs yield *responses* in order.++ *responses* may be a list (one per GET) or a single Exception raised on+ every GET.+ """+ client = AsyncMock()+ client.__aenter__ = AsyncMock(return_value=client)+ client.__aexit__ = AsyncMock(return_value=False)+ client.get = AsyncMock(side_effect=responses)+ return client+++class TestCompactionTargetForWindow:+ def test_32k_window_is_not_the_broken_120k_default(self):+ # The whole point: a 32k local window must yield ~9k, not 120_000.+ assert compaction_target_for_window(32_768) == 8_768++ def test_64k_window(self):+ assert compaction_target_for_window(65_536) == 41_536++ def test_tiny_window_clamps_to_floor(self):+ assert compaction_target_for_window(4_096) == 4_096+ assert compaction_target_for_window(1_000) == 4_096++ def test_fallback_constant_yields_sane_target(self):+ assert compaction_target_for_window(LOCAL_CONTEXT_FALLBACK) == 8_768+++class TestServerRoot:+ def test_strips_v1(self):+ assert _server_root("http://host:11434/v1") == "http://host:11434"++ def test_strips_v1_trailing_slash(self):+ assert _server_root("http://host:11434/v1/") == "http://host:11434"++ def test_no_v1(self):+ assert _server_root("http://host:11434") == "http://host:11434"++ def test_https(self):+ assert (+ _server_root("https://ollama.example.com/v1")+ == "https://ollama.example.com"+ )+++class TestProbeStrategies:+ def setup_method(self):+ _probe_cache.clear()+ _last_window.clear()++ @pytest.mark.asyncio+ async def test_ollama_api_ps_fixes_compaction_bug(self):+ client = _mock_client(+ [+ _resp(+ 200,+ {+ "models": [+ {+ "name": "llama3.1:8b-instruct-q4_K_M",+ "context_length": 32_768,+ }+ ]+ },+ )+ ]+ )+ with patch(+ "backend.copilot.local_context_probe.httpx.AsyncClient", return_value=client+ ):+ window = await probe_local_context_window(+ "http://localhost:11434/v1", "llama3.1:8b-instruct-q4_K_M"+ )+ assert window == 32_768+ assert compaction_target_for_window(window) == 8_768++ @pytest.mark.asyncio+ async def test_ollama_falls_back_to_first_loaded_model_window(self):+ # Name doesn't match, but a model is loaded — window is server-wide.+ client = _mock_client(+ [_resp(200, {"models": [{"name": "other:7b", "context_length": 16_384}]})]+ )+ with patch(+ "backend.copilot.local_context_probe.httpx.AsyncClient", return_value=client+ ):+ window = await probe_local_context_window(+ "http://localhost:11434/v1", "mymodel:8b"+ )+ assert window == 16_384++ @pytest.mark.asyncio+ async def test_empty_ollama_falls_through_to_vllm(self):+ client = _mock_client(+ [+ _resp(200, {"models": []}), # /api/ps: nothing loaded+ _resp(404, {}), # /props: not llama.cpp+ _resp(+ 200, {"data": [{"id": "llama3.1:8b", "max_model_len": 32_768}]}+ ), # vLLM+ ]+ )+ with patch(+ "backend.copilot.local_context_probe.httpx.AsyncClient", return_value=client+ ):+ window = await probe_local_context_window(+ "http://localhost:11434/v1", "llama3.1:8b"+ )+ assert window == 32_768++ @pytest.mark.asyncio+ async def test_llamacpp_props(self):+ client = _mock_client(+ [+ _resp(404, {}), # /api/ps+ _resp(200, {"default_generation_settings": {"n_ctx": 8192}}), # /props+ ]+ )+ with patch(+ "backend.copilot.local_context_probe.httpx.AsyncClient", return_value=client+ ):+ window = await probe_local_context_window(+ "http://localhost:8080/v1", "llama-3-8b.gguf"+ )+ assert window == 8192++ @pytest.mark.asyncio+ async def test_lmstudio_api_v0(self):+ client = _mock_client(+ [+ _resp(404, {}), # /api/ps+ _resp(404, {}), # /props+ _resp(200, {"data": []}), # /v1/models: no max_model_len+ _resp(+ 200, {"data": [{"id": "llama-3-8b", "max_context_length": 32_768}]}+ ), # LM Studio+ ]+ )+ with patch(+ "backend.copilot.local_context_probe.httpx.AsyncClient", return_value=client+ ):+ window = await probe_local_context_window(+ "http://localhost:1234/v1", "llama-3-8b"+ )+ assert window == 32_768+++class TestFallbackAndWarnings:+ def setup_method(self):+ _probe_cache.clear()+ _last_window.clear()++ @pytest.mark.asyncio+ async def test_all_probes_fail_returns_fallback(self):+ client = _mock_client(OSError("connection refused"))+ with patch(+ "backend.copilot.local_context_probe.httpx.AsyncClient", return_value=client+ ):+ window = await probe_local_context_window(+ "http://localhost:11434/v1", "llama3.1:8b"+ )+ assert window == LOCAL_CONTEXT_FALLBACK+ assert compaction_target_for_window(window) > 0++ @pytest.mark.asyncio+ async def test_window_below_minimum_logs_warning(self, caplog):+ client = _mock_client(+ [_resp(200, {"models": [{"name": "tiny", "context_length": 8192}]})]+ )+ with (+ patch(+ "backend.copilot.local_context_probe.httpx.AsyncClient",+ return_value=client,+ ),+ caplog.at_level(+ logging.WARNING, logger="backend.copilot.local_context_probe"+ ),+ ):+ window = await probe_local_context_window(+ "http://localhost:11434/v1", "tiny"+ )+ assert window == 8192+ assert window < _MINIMUM_SAFE_WINDOW+ assert any("OLLAMA_CONTEXT_LENGTH" in r.message for r in caplog.records)++ @pytest.mark.asyncio+ async def test_probe_miss_reuses_last_known_window(self):+ """After a successful read, a later miss (model unloaded) reuses the+ last detected window — not the optimistic 32k constant."""+ client = _mock_client(+ [+ _resp(200, {"models": [{"name": "m", "context_length": 8192}]}),+ _resp(200, {"models": []}), # 2nd probe: model unloaded+ _resp(404, {}),+ _resp(404, {}),+ _resp(404, {}),+ ]+ )+ with patch(+ "backend.copilot.local_context_probe.httpx.AsyncClient", return_value=client+ ):+ w1 = await probe_local_context_window("http://h:11434/v1", "m")+ _probe_cache[("http://h:11434/v1", "m")] = (+ w1,+ time.monotonic() - 400,+ ) # force-expire so the next call re-probes+ w2 = await probe_local_context_window("http://h:11434/v1", "m")+ assert w1 == 8192+ assert w2 == 8192 # reused, not LOCAL_CONTEXT_FALLBACK+ assert w2 != LOCAL_CONTEXT_FALLBACK+++class TestCaching:+ def setup_method(self):+ _probe_cache.clear()+ _last_window.clear()++ @pytest.mark.asyncio+ async def test_cache_hit_skips_probe(self):+ client = _mock_client(+ [_resp(200, {"models": [{"name": "m", "context_length": 32_768}]})]+ )+ with patch(+ "backend.copilot.local_context_probe.httpx.AsyncClient", return_value=client+ ) as cls:+ w1 = await probe_local_context_window("http://localhost:11434/v1", "m")+ w2 = await probe_local_context_window("http://localhost:11434/v1", "m")+ assert w1 == w2 == 32_768+ assert cls.call_count == 1 # AsyncClient instantiated only once++ @pytest.mark.asyncio+ async def test_cache_expires_after_ttl(self):+ client = _mock_client(+ [+ _resp(200, {"models": [{"name": "m", "context_length": 32_768}]}),+ _resp(200, {"models": [{"name": "m", "context_length": 65_536}]}),+ ]+ )+ with patch(+ "backend.copilot.local_context_probe.httpx.AsyncClient", return_value=client+ ) as cls:+ w1 = await probe_local_context_window("http://h:11434/v1", "m")+ _probe_cache[("http://h:11434/v1", "m")] = (+ w1,+ time.monotonic() - 400,+ ) # force-expire+ w2 = await probe_local_context_window("http://h:11434/v1", "m")+ assert w1 == 32_768+ assert w2 == 65_536+ assert cls.call_count == 2++ @pytest.mark.asyncio+ async def test_cache_keyed_by_base_url_and_model(self):+ """Two models on the same endpoint don't share a cached window —+ vLLM / LM Studio expose a per-model window."""+ loaded = {+ "models": [+ {"name": "modelA", "context_length": 32_768},+ {"name": "modelB", "context_length": 16_384},+ ]+ }+ client = _mock_client([_resp(200, loaded), _resp(200, loaded)])+ with patch(+ "backend.copilot.local_context_probe.httpx.AsyncClient", return_value=client+ ) as cls:+ wa = await probe_local_context_window("http://h:11434/v1", "modelA")+ wb = await probe_local_context_window("http://h:11434/v1", "modelB")+ assert wa == 32_768+ assert wb == 16_384 # not modelA's cached 32_768+ assert cls.call_count == 2 # second model re-probed, not served from cachediff --git a/autogpt_platform/backend/backend/copilot/model_normalize.py b/autogpt_platform/backend/backend/copilot/model_normalize.pyindex 169d53a5e0..03710e84ca 100644--- a/autogpt_platform/backend/backend/copilot/model_normalize.py+++ b/autogpt_platform/backend/backend/copilot/model_normalize.py@@ -19,13 +19,17 @@ def normalize_model_for_transport(raw_model: str, cfg: ChatConfig | None = None)"""Normalize a model name for the **actual** SDK CLI / OpenAI-compattransport.- Three transports (see ``ChatConfig.effective_transport``):+ Four transports (see ``ChatConfig.effective_transport``):1. **OpenRouter** — return the prefixed ``vendor/model`` slugunchanged (``anthropic/claude-opus-4-6``,``moonshotai/kimi-k2-6``, ...). Stripping the prefix would breakrouting for non-Anthropic vendors.- 2. **Subscription / Direct Anthropic** — strip the OpenRouter+ 2. **Local** (Ollama, vLLM, LM Studio, ...) — return the operator's+ slug unchanged (``llama3.1:8b-instruct-q4_K_M``,+ ``qwen3:0.6b``, ...). Self-hosted backends use their own+ naming and the Anthropic-prefix rewrite would 404 every call.+ 3. **Subscription / Direct Anthropic** — strip the OpenRouter``anthropic/`` prefix and convert dots to hyphens(``claude-opus-4.6`` → ``claude-opus-4-6``). The CLI subprocess(subscription mode) and the Anthropic Messages / OpenAI-compat@@ -43,7 +47,10 @@ def normalize_model_for_transport(raw_model: str, cfg: ChatConfig | None = None)cache that goes stale when tests mutate env vars."""config = cfg if cfg is not None else ChatConfig()- if config.effective_transport == "openrouter":+ # OpenRouter accepts ``vendor/model`` for any vendor; the local+ # transport (Ollama, vLLM, …) speaks raw operator-chosen slugs and+ # must never have them rewritten — both pass through unchanged.+ if config.effective_transport in ("openrouter", "local"):return raw_modelmodel = raw_modelif "/" in model:diff --git a/autogpt_platform/backend/backend/copilot/model_normalize_test.py b/autogpt_platform/backend/backend/copilot/model_normalize_test.pyindex a6bc6d56e4..ec229f4aca 100644--- a/autogpt_platform/backend/backend/copilot/model_normalize_test.py+++ b/autogpt_platform/backend/backend/copilot/model_normalize_test.py@@ -86,3 +86,19 @@ class TestNormalizeModelForTransport:)with pytest.raises(ValueError, match="Anthropic model slug"):normalize_model_for_transport("gpt-4o-mini", cfg)++ def test_local_transport_passes_bare_slug_unchanged(self):+ # Local backends (Ollama, vLLM, …) use operator-chosen slugs+ # like ``llama3.1:8b-instruct-q4_K_M`` that don't fit the+ # ``vendor/model`` convention and must not be rewritten — the+ # Anthropic-prefix rule applies only to cloud transports.+ cfg = ChatConfig(+ use_local=True,+ api_key="ollama",+ base_url="http://ollama:11434/v1",+ fast_standard_model="llama3.1:8b-instruct-q4_K_M",+ )+ assert (+ normalize_model_for_transport("llama3.1:8b-instruct-q4_K_M", cfg)+ == "llama3.1:8b-instruct-q4_K_M"+ )diff --git a/autogpt_platform/backend/backend/copilot/sdk/env.py b/autogpt_platform/backend/backend/copilot/sdk/env.pyindex cf77dab224..8aa7fa6359 100644--- a/autogpt_platform/backend/backend/copilot/sdk/env.py+++ b/autogpt_platform/backend/backend/copilot/sdk/env.py@@ -48,6 +48,19 @@ def build_sdk_env(vars (currently: ``CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`` is skipped forMoonshot since the cache-cost rationale doesn't apply there)."""+ # Transports that don't run the SDK at all (currently: ``local`` —+ # Ollama et al. don't implement Anthropic's wire protocol) must not+ # reach this builder. The processor downgrades extended_thinking →+ # fast for those transports, so an entry here indicates a bug+ # upstream. Fail loudly rather than constructing a doomed env.+ if not config.transport.supports_sdk:+ raise RuntimeError(+ f"build_sdk_env() called under transport "+ f"{config.transport.name!r}, which doesn't support the SDK. "+ "The request should have been downgraded to the baseline "+ "path — see executor.processor.resolve_use_sdk_for_mode."+ )+# --- Mode 1: Claude Code subscription auth ---if config.use_claude_code_subscription:validate_subscription()diff --git a/autogpt_platform/backend/backend/copilot/sdk/env_test.py b/autogpt_platform/backend/backend/copilot/sdk/env_test.pyindex b4070e76ae..209937d9d8 100644--- a/autogpt_platform/backend/backend/copilot/sdk/env_test.py+++ b/autogpt_platform/backend/backend/copilot/sdk/env_test.py@@ -475,3 +475,30 @@ class TestAutocompactPctOverrideConfigurable:result = build_sdk_env(model=None)assert result.get("CLAUDE_AUTOCOMPACT_PCT_OVERRIDE") == "50"+++# ---------------------------------------------------------------------------+# Defensive guard — local transport must never reach the SDK env builder+# ---------------------------------------------------------------------------+++class TestBuildSdkEnvLocalTransportGuard:+ """``use_local=True`` is incompatible with the SDK CLI's Anthropic+ wire protocol, so reaching ``build_sdk_env`` under that transport+ indicates an upstream routing bug (the request layer should have+ downgraded to baseline). The builder fails loudly rather than+ constructing a doomed subprocess env."""++ def test_local_transport_raises(self):+ cfg = _make_config(+ use_local=True,+ api_key="ollama",+ base_url="http://host.docker.internal:11434/v1",+ )+ with patch("backend.copilot.sdk.env.config", cfg):+ from backend.copilot.sdk.env import build_sdk_env++ with pytest.raises(+ RuntimeError, match=r"transport 'local'.*doesn't support the SDK"+ ):+ build_sdk_env()diff --git a/autogpt_platform/backend/backend/copilot/service.py b/autogpt_platform/backend/backend/copilot/service.pyindex c7c66d262c..2be390d12a 100644--- a/autogpt_platform/backend/backend/copilot/service.py+++ b/autogpt_platform/backend/backend/copilot/service.py@@ -81,7 +81,15 @@ def _get_main_client() -> LangfuseAsyncOpenAI:global _main_clientif _main_client is None:api_key, base_url = config.main_client_credentials- _main_client = LangfuseAsyncOpenAI(api_key=api_key, base_url=base_url)+ kwargs: dict = {"api_key": api_key, "base_url": base_url}+ # Local-LLM backends (Ollama et al.) on CPU-only hosts can take+ # many minutes for a single turn against AutoPilot's heavy system+ # prompt. The OpenAI client default (600 s) is too short for that+ # case — extend it under the local transport. Cloud transports+ # keep the SDK default so genuine hangs still surface promptly.+ if config.transport.name == "local":+ kwargs["timeout"] = config.local_request_timeout_s+ _main_client = LangfuseAsyncOpenAI(**kwargs)return _main_client@@ -97,7 +105,14 @@ def _get_aux_client() -> LangfuseAsyncOpenAI:global _aux_clientif _aux_client is None:api_key, base_url = config.aux_client_credentials- _aux_client = LangfuseAsyncOpenAI(api_key=api_key, base_url=base_url)+ kwargs: dict = {"api_key": api_key, "base_url": base_url}+ # Local transport routes aux through the same self-hosted backend+ # (Ollama et al.) when ``CHAT_AUX_*`` are unset — extend the+ # client timeout to match ``_get_main_client`` so title generation+ # on a CPU-only host doesn't surface as an opaque 600 s timeout.+ if config.transport.name == "local":+ kwargs["timeout"] = config.local_request_timeout_s+ _aux_client = LangfuseAsyncOpenAI(**kwargs)return _aux_clientdiff --git a/autogpt_platform/backend/backend/data/tally.py b/autogpt_platform/backend/backend/data/tally.pyindex 2fdf090d42..bd90166761 100644--- a/autogpt_platform/backend/backend/data/tally.py+++ b/autogpt_platform/backend/backend/data/tally.py@@ -6,6 +6,8 @@ import loggingfrom datetime import datetime, timezonefrom typing import Optional+from openai.types.chat import ChatCompletionUserMessageParam+from backend.data.redis_client import get_redis_asyncfrom backend.data.understanding import (BusinessUnderstandingInput,@@ -38,6 +40,12 @@ _MAX_PAGES = 100# LLM extraction timeout (seconds)_LLM_TIMEOUT = 30+# Cloud-transport model for ``extract_business_understanding``. Frozen at the+# historical pick so existing OpenRouter / direct-Anthropic deployments don't+# see a silent model swap (and cost change) when the local-transport plumbing+# rolls out — local transport routes through ``chat_cfg.title_model`` instead.+_EXTRACTION_MODEL_CLOUD = "openai/gpt-4o-mini"+SUGGESTION_THEMES = ["Learn", "Create", "Automate", "Organize"]PROMPTS_PER_THEME = 5@@ -351,27 +359,67 @@ async def extract_business_understanding("""Use an LLM to extract structured business understanding from form text.Raises on timeout or unparseable response so the caller can handle it.+ Routes through ``get_openai_client(prefer_openrouter=True)`` so a+ self-hosted ``CHAT_USE_LOCAL=true`` deployment hits the operator's+ Ollama / vLLM / LiteLLM endpoint instead of unauthenticated OpenRouter+ (the previous direct ``AsyncOpenAI(api_key=settings.secrets.open_router_api_key,+ base_url=OPENROUTER_BASE_URL)`` returned a 401 on the very first signup+ of any no-API-key install).++ Model picks ``ChatConfig.title_model`` only under the local transport so+ the auto-derivation from ``fast_standard_model`` flows through here too —+ one less env to remember for self-hosted operators. Cloud transports+ (OpenRouter / direct-Anthropic) keep the historical ``openai/gpt-4o-mini``+ pick so existing deployments don't see a silent model swap (different+ pricing, different output shape). Reuses the module-level ``ChatConfig``+ singleton from ``copilot.sdk.env`` to avoid a fresh ``.env``-parse on+ every Tally submission."""+ from backend.copilot.sdk.env import config as chat_cfg+client = get_openai_client(prefer_openrouter=True)if client is None:raise RuntimeError(- "open_router_api_key not set, cannot extract business understanding"+ "Tally extraction needs an LLM client but none is configured. "+ "Set OPEN_ROUTER_API_KEY (cloud) or CHAT_USE_LOCAL=true with "+ "CHAT_BASE_URL + CHAT_API_KEY (local). See "+ "docs/platform/copilot-local-llm.md.")+ model = (+ chat_cfg.title_model+ if chat_cfg.transport.name == "local"+ else _EXTRACTION_MODEL_CLOUD+ )++ # ``_LLM_TIMEOUT`` was sized for OpenRouter latency. Local CPU-only+ # Ollama can take 30–120+ seconds for even a small JSON extraction+ # (`qwen3:0.6b` on a 4-core VM is typical of the no-API-key install+ # target), so the fixed cloud timeout fires before the model finishes+ # and every Tally submission raises ``TimeoutError`` under local+ # transport. Track the operator's already-tuned+ # ``local_request_timeout_s`` instead — the same knob that gates the+ # AsyncOpenAI client timeout, so the two stay aligned.+ timeout_s = (+ chat_cfg.local_request_timeout_s+ if chat_cfg.transport.name == "local"+ else _LLM_TIMEOUT+ )+ messages: list[ChatCompletionUserMessageParam] = [+ {+ "role": "user",+ "content": f"{_EXTRACTION_PROMPT}{formatted_text}{_EXTRACTION_SUFFIX}",+ }+ ]try:response = await asyncio.wait_for(client.chat.completions.create(- model="openai/gpt-4o-mini",- messages=[- {- "role": "user",- "content": f"{_EXTRACTION_PROMPT}{formatted_text}{_EXTRACTION_SUFFIX}",- }- ],+ model=model,+ messages=messages,response_format={"type": "json_object"},temperature=0.0,),- timeout=_LLM_TIMEOUT,+ timeout=timeout_s,)except asyncio.TimeoutError:logger.warning("Tally: LLM extraction timed out")@@ -431,8 +479,21 @@ async def populate_understanding_from_tally(user_id: str, email: str) -> None:if not settings.secrets.tally_api_key or not settings.secrets.tally_form_id:logger.debug("Tally: Tally config incomplete, skipping")return- if not settings.secrets.open_router_api_key:- logger.debug("Tally: no OpenRouter API key configured, skipping")+ # Tally extraction needs an LLM. ``extract_business_understanding``+ # routes through ``get_openai_client(prefer_openrouter=True)``,+ # which returns the local-transport client when+ # ``CHAT_USE_LOCAL=true`` (no OpenRouter key required) and the+ # OpenRouter / direct-Anthropic client otherwise. The guard only+ # bails when no LLM client is available at all — gating on+ # ``open_router_api_key`` alone would silently skip Tally for+ # every local install even though the local client is wired up.+ from backend.copilot.sdk.env import config as chat_cfg++ if (+ chat_cfg.transport.name != "local"+ and not settings.secrets.open_router_api_key+ ):+ logger.debug("Tally: no LLM client configured, skipping")return# Look up submission by emaildiff --git a/autogpt_platform/backend/backend/data/tally_test.py b/autogpt_platform/backend/backend/data/tally_test.pyindex 9bdeb16b0c..15ffcf3537 100644--- a/autogpt_platform/backend/backend/data/tally_test.py+++ b/autogpt_platform/backend/backend/data/tally_test.py@@ -522,12 +522,14 @@ async def test_extract_business_understanding_timeout():@pytest.mark.asyncioasync def test_extract_business_understanding_missing_openrouter_key():- """When OpenRouter is not configured, raise a clear RuntimeError."""+ """When no LLM client is configured, raise a clear RuntimeError pointing+ operators at both the cloud (``OPEN_ROUTER_API_KEY``) and local+ (``CHAT_USE_LOCAL=true``) escape hatches."""with (patch("backend.data.tally.get_openai_client", return_value=None) as mock_get_client,- pytest.raises(RuntimeError, match="open_router_api_key not set"),+ pytest.raises(RuntimeError, match=r"OPEN_ROUTER_API_KEY.*CHAT_USE_LOCAL"),):await extract_business_understanding("Q: Name?\nA: Alice")mock_get_client.assert_called_once_with(prefer_openrouter=True)diff --git a/autogpt_platform/backend/backend/executor/activity_status_generator.py b/autogpt_platform/backend/backend/executor/activity_status_generator.pyindex 1c2d6f3531..e7bf88e738 100644--- a/autogpt_platform/backend/backend/executor/activity_status_generator.py+++ b/autogpt_platform/backend/backend/executor/activity_status_generator.py@@ -20,7 +20,7 @@ from backend.data.execution import ExecutionStatus, NodeExecutionResultfrom backend.data.model import GraphExecutionStatsfrom backend.data.platform_cost import PlatformCostEntry, usd_to_microdollarsfrom backend.executor.cost_tracking import schedule_platform_cost_log-from backend.util.clients import get_openai_client+from backend.util.clients import get_openai_client, openrouter_helper_cost_providerfrom backend.util.feature_flag import Flag, is_feature_enabledfrom backend.util.truncate import truncate@@ -38,6 +38,13 @@ _OPENROUTER_INCLUDE_USAGE_COST: dict[str, Any] = {"usage": {"include": True}}_MAX_JSON_RETRIES = 3_MAX_OUTPUT_TOKENS = 150+# Sentinel for ``generate_activity_status_for_execution.model_name``. The+# parameter defaults to this for cloud routing. Under the local transport+# we only override to ``ChatConfig.title_model`` when the caller didn't+# supply an explicit value — same pattern ``ChatConfig._apply_local_aux_models``+# uses for ``title_model`` / ``simulation_model``.+_DEFAULT_MODEL_NAME = "gpt-4o-mini"+# Default system prompt template for activity status generationDEFAULT_SYSTEM_PROMPT = """You are an AI assistant analyzing what an agent execution accomplished and whether it worked correctly.@@ -198,7 +205,7 @@ async def generate_activity_status_for_execution(db_client: "DatabaseManagerAsyncClient",user_id: str,execution_status: ExecutionStatus | None = None,- model_name: str = "gpt-4o-mini",+ model_name: str = _DEFAULT_MODEL_NAME,skip_feature_flag: bool = False,system_prompt: str = DEFAULT_SYSTEM_PROMPT,user_prompt: str = DEFAULT_USER_PROMPT,@@ -249,15 +256,22 @@ async def generate_activity_status_for_execution("correctness_score": execution_stats.correctness_score,}- # Acquire an OpenRouter-backed OpenAI client. Activity-status generation is- # only meaningful when we can record real USD cost in PlatformCostLog;- # without OpenRouter the upstream platform cost would be tokens-only, so- # we skip rather than fall back to direct-OpenAI which produces no- # provider_cost. Same gating pattern as backend/executor/simulator.py.+ # Acquire an OpenRouter-backed (or local-transport) OpenAI client.+ # Activity-status generation under OpenRouter is only meaningful when we+ # can record real USD cost in PlatformCostLog; without OpenRouter the+ # upstream platform cost would be tokens-only, so we skip rather than+ # fall back to direct-OpenAI which produces no provider_cost. Under+ # ``CHAT_USE_LOCAL=true`` the helper instead returns a client pointed at+ # the operator's Ollama / vLLM / LiteLLM endpoint and we generate the+ # status off the local model — there's no provider_cost field on+ # local-stack usage chunks but the status itself is still useful.+ # ``None`` means neither path is configured, in which case skip.+ # Same gating pattern as backend/executor/simulator.py.client = get_openai_client(prefer_openrouter=True)if client is None:logger.debug(- "OpenRouter API key not configured, skipping activity status generation"+ "No LLM client configured (OpenRouter or local) — "+ "skipping activity status generation")return None@@ -312,10 +326,50 @@ async def generate_activity_status_for_execution(f"Sending prompt to LLM for graph execution {graph_exec_id}: {json.dumps(messages, indent=2)}")- # Model values arriving without a provider prefix (e.g. "gpt-4o-mini")- # need to be remapped to OpenRouter's namespaced form. Already-prefixed- # values (e.g. "openai/gpt-4o-mini", "anthropic/claude-...") pass through.- or_model = model_name if "/" in model_name else f"openai/{model_name}"+ # Under the local OpenAI-compat transport (CHAT_USE_LOCAL=true) the+ # client is pointed at Ollama / vLLM / LiteLLM, not OpenRouter:+ #+ # - The hardcoded ``gpt-4o-mini`` default is meaningless against a+ # local server, and the ``openai/`` prefix coercion would mangle+ # bare Ollama tags (``qwen3:0.6b`` → ``openai/qwen3:0.6b``) into+ # 404s. Use ``ChatConfig.title_model`` instead — it auto-derives+ # from the operator's chosen ``fast_standard_model`` under+ # ``use_local`` and is already shaped for the local backend.+ # - ``extra_body={"usage": {"include": True}}`` is OpenRouter's+ # piggybacked-cost extension; local backends don't implement it+ # and may reject the request body. Local sends an empty+ # ``extra_body`` instead — the backend's own launched context+ # window (e.g. OLLAMA_CONTEXT_LENGTH) governs, read back at+ # runtime by ``local_context_probe`` for compaction.+ #+ # Same gating pattern as ``backend/copilot/baseline/service.py`` and+ # ``backend/executor/simulator.py`` — keep the three in sync.+ from backend.copilot.sdk.env import config as chat_cfg++ is_local_transport = chat_cfg.transport.name == "local"+ if is_local_transport:+ # Only auto-override to ``chat_cfg.title_model`` when the caller+ # left ``model_name`` at its cloud-routing default. An explicit+ # caller-supplied value (e.g. an admin reroute or a test) wins+ # — we mustn't silently discard it. Same pattern+ # ``ChatConfig._apply_local_aux_models`` uses for the field defaults.+ or_model = (+ chat_cfg.title_model+ if model_name == _DEFAULT_MODEL_NAME+ else model_name+ )+ extra_body: dict[str, Any] = {}+ else:+ # Model values arriving without a provider prefix (e.g. "gpt-4o-mini")+ # need to be remapped to OpenRouter's namespaced form. Already-prefixed+ # values (e.g. "openai/gpt-4o-mini", "anthropic/claude-...") pass through.+ or_model = model_name if "/" in model_name else f"openai/{model_name}"+ # Shallow-copy the module-level constant rather than sharing+ # the reference. The OpenAI SDK treats ``extra_body`` as opaque+ # pass-through, but if any intermediate layer ever mutates it+ # the shared constant would leak across coroutines. Mirrors the+ # defensive ``dict(...)`` ``baseline/service.py`` already uses.+ extra_body = dict(_OPENROUTER_INCLUDE_USAGE_COST)# Track the most recent attempt's usage so we can persist cost even# when every retry fails — the API calls were billed regardless of@@ -330,7 +384,7 @@ async def generate_activity_status_for_execution(messages=messages,max_tokens=_MAX_OUTPUT_TOKENS,response_format={"type": "json_object"},- extra_body=_OPENROUTER_INCLUDE_USAGE_COST,+ extra_body=extra_body,)last_usage = response.usageif not response.choices:@@ -374,6 +428,11 @@ async def generate_activity_status_for_execution(graph_exec_id=graph_exec_id,graph_id=graph_id,model_name=or_model,+ # This helper routes through ``get_openai_client(prefer_openrouter=True)``,+ # so a non-local call physically hits OpenRouter regardless of the chat+ # transport identity — label it accordingly (not ``cost_log_provider``,+ # which would mislabel subscription / direct_anthropic as ``anthropic``).+ provider=openrouter_helper_cost_provider(),db_client=db_client,)@@ -431,6 +490,7 @@ def _persist_activity_status_cost(graph_exec_id: str,graph_id: str,model_name: str,+ provider: str,db_client: "DatabaseManagerAsyncClient",) -> None:"""Schedule a PlatformCostLog entry for the activity-status LLM call.@@ -468,7 +528,7 @@ def _persist_activity_status_cost(graph_exec_id=graph_exec_id,graph_id=graph_id,block_name="activity_status_generator",- provider="open_router",+ provider=provider,cost_microdollars=cost_microdollars,input_tokens=input_tokens or None,output_tokens=output_tokens or None,diff --git a/autogpt_platform/backend/backend/executor/activity_status_generator_test.py b/autogpt_platform/backend/backend/executor/activity_status_generator_test.pyindex 182938624c..52c0240d5d 100644--- a/autogpt_platform/backend/backend/executor/activity_status_generator_test.py+++ b/autogpt_platform/backend/backend/executor/activity_status_generator_test.py@@ -563,6 +563,10 @@ class TestGenerateActivityStatusForExecution:assert entry.graph_exec_id == "test_exec"assert entry.graph_id == "test_graph"assert entry.block_name == "activity_status_generator"+ # Routes through ``get_openai_client(prefer_openrouter=True)``, which+ # only hits OpenRouter (or None) under non-local transport — so the+ # cost row is always ``open_router`` here, never the chat transport's+ # identity. See ``clients_test.TestOpenrouterHelperCostProvider``.assert entry.provider == "open_router"assert entry.model == "openai/gpt-4o-mini"assert entry.tracking_type == "cost_usd"diff --git a/autogpt_platform/backend/backend/executor/simulator.py b/autogpt_platform/backend/backend/executor/simulator.pyindex c93956ada7..12e5856d6b 100644--- a/autogpt_platform/backend/backend/executor/simulator.py+++ b/autogpt_platform/backend/backend/executor/simulator.py@@ -42,7 +42,7 @@ from backend.blocks.io import AgentInputBlock, AgentOutputBlockfrom backend.blocks.llm import LlmModelfrom backend.blocks.orchestrator import ExecutionMode, OrchestratorBlockfrom backend.copilot.token_tracking import persist_and_record_usage-from backend.util.clients import get_openai_client+from backend.util.clients import get_openai_client, openrouter_helper_cost_providerlogger = logging.getLogger(__name__)@@ -82,9 +82,13 @@ _OPENROUTER_INCLUDE_USAGE_COST: dict[str, Any] = {"usage": {"include": True}}def _simulator_model() -> str:try:- from backend.copilot.config import ChatConfig # noqa: PLC0415+ # Reuse the module-level ChatConfig singleton from copilot.sdk.env+ # rather than constructing a fresh one — the validator chain runs+ # at import time, so a per-call ``ChatConfig()`` re-reads ``.env``+ # and re-runs every model_validator on every dry-run turn.+ from backend.copilot.sdk.env import config as chat_cfg # noqa: PLC0415- return ChatConfig().simulation_model or _DEFAULT_SIMULATOR_MODEL+ return chat_cfg.simulation_model or _DEFAULT_SIMULATOR_MODELexcept Exception:return _DEFAULT_SIMULATOR_MODEL@@ -154,10 +158,34 @@ async def _call_llm_for_simulation(client = get_openai_client(prefer_openrouter=True)if client is None:raise RuntimeError(- "[SIMULATOR ERROR — NOT A BLOCK FAILURE] No LLM client available "- "(missing OpenAI/OpenRouter API key)."+ "[SIMULATOR ERROR — NOT A BLOCK FAILURE] No LLM client available. "+ "Set OPEN_ROUTER_API_KEY (cloud) or CHAT_USE_LOCAL=true with "+ "CHAT_BASE_URL + CHAT_API_KEY (local). See "+ "docs/platform/copilot-local-llm.md.")+ # ``_OPENROUTER_INCLUDE_USAGE_COST`` is OpenRouter-specific+ # (``{"usage": {"include": True}}``). Cloud OpenAI ignores unknown+ # body keys; stricter local OpenAI-compat backends (LiteLLM proxy+ # with strict mode, some vLLM configs) reject them. Mirror the+ # ``baseline/service.py`` policy: only send when actually routing+ # through OpenRouter.+ #+ # Local backends govern their own context window at launch (e.g.+ # OLLAMA_CONTEXT_LENGTH), so we send no per-request num_ctx hint —+ # Ollama's OpenAI shim ignores ``options.num_ctx`` anyway.+ from backend.copilot.sdk.env import config as chat_cfg++ if chat_cfg.transport.name == "local":+ extra_body: dict[str, Any] = {}+ else:+ # Shallow-copy the constant rather than sharing the reference — see+ # the matching pattern in ``baseline/service.py`` and+ # ``activity_status_generator.py``. Defends against intermediate+ # layers ever mutating ``extra_body`` and corrupting the shared+ # module-level dict for every future call.+ extra_body = dict(_OPENROUTER_INCLUDE_USAGE_COST)+model = _simulator_model()last_error: Exception | None = Nonefor attempt in range(_MAX_JSON_RETRIES):@@ -170,7 +198,7 @@ async def _call_llm_for_simulation({"role": "system", "content": system_prompt},{"role": "user", "content": user_prompt},],- extra_body=_OPENROUTER_INCLUDE_USAGE_COST,+ extra_body=extra_body,)if not response.choices:raise ValueError("LLM returned empty choices array")@@ -193,7 +221,16 @@ async def _call_llm_for_simulation("simulate(%s): attempt=%d usage unavailable", label, attempt + 1)- await _track_simulator_cost(usage=usage, user_id=user_id, model=model)+ await _track_simulator_cost(+ usage=usage,+ user_id=user_id,+ model=model,+ # Routes through ``get_openai_client(prefer_openrouter=True)``, so a+ # non-local call physically hits OpenRouter regardless of the chat+ # transport identity — label it accordingly (not ``cost_log_provider``,+ # which would mislabel subscription / direct_anthropic as ``anthropic``).+ provider=openrouter_helper_cost_provider(),+ )return parsedexcept (json.JSONDecodeError, ValueError) as e:@@ -256,6 +293,7 @@ async def _track_simulator_cost(usage: CompletionUsage | None,user_id: str | None,model: str,+ provider: str,) -> None:"""Record platform cost for a single simulator LLM call.@@ -277,7 +315,7 @@ async def _track_simulator_cost(log_prefix="[simulator]",cost_usd=cost_usd,model=model,- provider="open_router",+ provider=provider,)except Exception as exc:logger.warning("[simulator] usage tracking failed: %s", exc)diff --git a/autogpt_platform/backend/backend/executor/simulator_test.py b/autogpt_platform/backend/backend/executor/simulator_test.pyindex 8e50f671c0..6b5c3db251 100644--- a/autogpt_platform/backend/backend/executor/simulator_test.py+++ b/autogpt_platform/backend/backend/executor/simulator_test.py@@ -807,6 +807,11 @@ class TestSimulatorCostTracking:assert create_kwargs["extra_body"] == {"usage": {"include": True}}track_kwargs = mock_track.await_args.kwargs+ # The simulator routes through ``get_openai_client(prefer_openrouter=True)``,+ # which only ever hits OpenRouter (or None) under non-local transport — so+ # the cost row is always ``open_router`` here, never the chat transport's+ # identity. See ``clients_test.TestOpenrouterHelperCostProvider`` for the+ # per-transport matrix (incl. the subscription / direct_anthropic regression).assert track_kwargs["provider"] == "open_router"assert track_kwargs["model"] == _DEFAULT_SIMULATOR_MODELassert track_kwargs["user_id"] == "user-42"@@ -846,6 +851,7 @@ class TestSimulatorCostTracking:track_kwargs = mock_track.await_args.kwargsassert track_kwargs["cost_usd"] is Noneassert track_kwargs["user_id"] == "user-7"+ # Non-local prefer_openrouter route → always logged as ``open_router``.assert track_kwargs["provider"] == "open_router"@pytest.mark.asynciodiff --git a/autogpt_platform/backend/backend/util/architecture_test.py b/autogpt_platform/backend/backend/util/architecture_test.pyindex b3cf457911..42dc5c0e42 100644--- a/autogpt_platform/backend/backend/util/architecture_test.py+++ b/autogpt_platform/backend/backend/util/architecture_test.py@@ -45,6 +45,12 @@ _KNOWN_OFFENDERS = frozenset({"util/clients.py get_async_supabase","util/clients.py get_openai_client",+ # Inner helper extracted from ``get_openai_client`` so the local-+ # transport branch shares one cached client across both+ # ``prefer_openrouter`` arms (no semantic change vs the parent+ # offender — same loop-binding caveat applies, will be migrated+ # together when ``get_openai_client`` is moved to ``per_loop_cached``).+ "util/clients.py _get_local_openai_client",})diff --git a/autogpt_platform/backend/backend/util/clients.py b/autogpt_platform/backend/backend/util/clients.pyindex a1dc1f966e..0df62fc33f 100644--- a/autogpt_platform/backend/backend/util/clients.py+++ b/autogpt_platform/backend/backend/util/clients.py@@ -182,20 +182,73 @@ async def get_async_supabase() -> "AClient":# ============ OpenAI Client ============ #+@cached(ttl_seconds=3600)+def _get_local_openai_client() -> "AsyncOpenAI":+ """Build the local-transport OpenAI client.++ Factored out so both ``prefer_openrouter`` arms of ``get_openai_client``+ share a single cached instance under ``CHAT_USE_LOCAL=true`` — the cache+ keys on its own arglist (which is empty), not on the caller's+ ``prefer_openrouter`` kwarg, so we don't end up with two equivalent+ ``AsyncOpenAI`` instances pointed at the same endpoint.+ """+ from openai import AsyncOpenAI++ # Reuse the module-level ``ChatConfig`` singleton from+ # ``copilot.sdk.env`` rather than constructing a fresh one — that+ # config object already exists for the SDK env builder, runs the full+ # validator chain once at import time, and avoids the ``.env``-reread+ # cost on every cache miss here. Lazy-imported because+ # ``backend.copilot.config`` imports ``OPENROUTER_BASE_URL`` from this+ # module — a top-level import would create a cycle.+ from backend.copilot.sdk.env import config as chat_cfg++ return AsyncOpenAI(+ api_key=chat_cfg.api_key,+ base_url=chat_cfg.base_url,+ timeout=chat_cfg.local_request_timeout_s,+ )++@cached(ttl_seconds=3600)def get_openai_client(*, prefer_openrouter: bool = False) -> "AsyncOpenAI | None":"""Get a process-cached async OpenAI client.- By default prefers openai_internal_api_key (direct OpenAI) and falls back- to open_router_api_key via OpenRouter.-- When ``prefer_openrouter=True``, returns an OpenRouter client or None —- does **not** fall back to direct OpenAI (which can't route non-OpenAI- models like ``google/gemini-2.5-flash``).+ Resolution order:++ 1. **Local transport** (``CHAT_USE_LOCAL=true``) wins unconditionally.+ Operators who opted into self-hosted shouldn't have platform helpers+ (dry-run simulator, prompt compression, marketplace embeddings, …)+ silently route to the cloud just because legacy cloud-key fallbacks+ happen to be present. Returns a client pointed at the same+ OpenAI-compatible endpoint AutoPilot uses, with the same generous+ request timeout — those helpers fire under the same hardware+ constraints (CPU-only Ollama is slow). ``prefer_openrouter`` is+ intentionally ignored here: the local client is the only sane+ routing target regardless of the caller's preference.+ 2. ``prefer_openrouter=True`` → returns an OpenRouter client or None.+ Does **not** fall back to direct OpenAI (which can't route non-OpenAI+ models like ``google/gemini-2.5-flash``).+ 3. Default → prefers ``openai_internal_api_key`` (direct OpenAI), falls+ back to ``open_router_api_key`` via OpenRouter.++ Returns ``None`` only when none of the above resolve — callers must+ handle that branch (see e.g. ``executor/simulator._run_simulation_llm``).+ Note that under ``CHAT_USE_LOCAL=true`` this never returns ``None``,+ so callers that previously used a ``None`` return as a "skip cloud-only+ feature" sentinel will instead exercise the local path — that is the+ intended behaviour for this PR."""from openai import AsyncOpenAI+ # Local transport takes precedence so a stray ``OPENAI_API_KEY`` set+ # for some other reason can't override an explicit ``CHAT_USE_LOCAL=true``.+ from backend.copilot.sdk.env import config as chat_cfg++ if chat_cfg.transport.name == "local":+ return _get_local_openai_client()+openai_key = settings.secrets.openai_internal_api_keyopenrouter_key = settings.secrets.open_router_api_key@@ -211,6 +264,26 @@ def get_openai_client(*, prefer_openrouter: bool = False) -> "AsyncOpenAI | Nonereturn None+def openrouter_helper_cost_provider() -> str:+ """Cost-log provider for a client from ``get_openai_client(prefer_openrouter=True)``.++ Mirrors that function's routing so the ``PlatformCostLog`` row names the+ endpoint the call physically hit, not the chat transport identity:++ - **Local transport** → ``"ollama"`` — the self-hosted endpoint+ ``get_openai_client`` returns unconditionally under ``CHAT_USE_LOCAL``.+ - **Every other transport** → ``"open_router"``. ``prefer_openrouter=True``+ only ever returns an OpenRouter client or ``None`` — it never falls back+ to direct Anthropic — so any call that actually billed went through+ OpenRouter, even under ``subscription`` / ``direct_anthropic`` transport+ with an ``OPEN_ROUTER_API_KEY`` present. Keying off+ ``transport.cost_log_provider`` here would mislabel those as ``"anthropic"``.+ """+ from backend.copilot.sdk.env import config as chat_cfg++ return "ollama" if chat_cfg.transport.name == "local" else "open_router"++# ============ Notification Queue Helpers ============ #diff --git a/autogpt_platform/backend/backend/util/clients_test.py b/autogpt_platform/backend/backend/util/clients_test.pyindex 5fc7f64d91..96f6a0a349 100644--- a/autogpt_platform/backend/backend/util/clients_test.py+++ b/autogpt_platform/backend/backend/util/clients_test.py@@ -4,15 +4,27 @@ from unittest.mock import MagicMock, patchimport pytest-from backend.util.clients import get_openai_client+from backend.util.clients import (+ _get_local_openai_client,+ get_openai_client,+ openrouter_helper_cost_provider,+)@pytest.fixture(autouse=True)def _clear_client_cache():- """Clear the @cached singleton between tests."""+ """Clear the @cached client singletons between tests.++ ``_get_local_openai_client`` is a separate ``@cached`` instance from+ ``get_openai_client``; clearing only the latter leaves a stale local+ ``AsyncOpenAI`` aimed at a previous endpoint after a test monkeypatches+ transport/URL. Clear both.+ """get_openai_client.cache_clear()+ _get_local_openai_client.cache_clear()yieldget_openai_client.cache_clear()+ _get_local_openai_client.cache_clear()def _mock_secrets(*, openai_key: str = "", openrouter_key: str = "") -> MagicMock:@@ -67,3 +79,63 @@ class TestGetOpenaiClientPreferOpenrouter:with patch("backend.util.clients.settings") as mock_settings:mock_settings.secrets = secretsassert get_openai_client(prefer_openrouter=True) is None+++class TestOpenrouterHelperCostProvider:+ """``openrouter_helper_cost_provider`` labels the cost row by the endpoint+ ``get_openai_client(prefer_openrouter=True)`` actually routes to, not the+ chat transport identity."""++ def _patch_transport(self, monkeypatch, cfg):+ monkeypatch.setattr("backend.copilot.sdk.env.config", cfg)++ def test_local_transport_is_ollama(self, monkeypatch):+ from backend.copilot.config import ChatConfig++ cfg = ChatConfig(use_local=True, api_key="ollama", base_url="http://h:11434/v1")+ self._patch_transport(monkeypatch, cfg)+ assert openrouter_helper_cost_provider() == "ollama"++ def test_subscription_transport_is_open_router(self, monkeypatch):+ """Regression: subscription routes the helper through OpenRouter when+ OPEN_ROUTER_API_KEY is present — it must not be logged as ``anthropic``+ (the transport's ``cost_log_provider``)."""+ from backend.copilot.config import ChatConfig++ cfg = ChatConfig(+ use_local=False,+ use_claude_code_subscription=True,+ thinking_standard_model="anthropic/claude-sonnet-4-6",+ thinking_advanced_model="anthropic/claude-opus-4-7",+ aux_api_key="or-aux-key",+ )+ self._patch_transport(monkeypatch, cfg)+ assert openrouter_helper_cost_provider() == "open_router"++ def test_direct_anthropic_transport_is_open_router(self, monkeypatch):+ from backend.copilot.config import ChatConfig++ cfg = ChatConfig(+ use_local=False,+ use_openrouter=False,+ direct_anthropic_api_key="anthropic-key",+ api_key=None,+ base_url=None,+ thinking_standard_model="anthropic/claude-sonnet-4-6",+ thinking_advanced_model="anthropic/claude-opus-4-7",+ aux_api_key="or-aux-key",+ )+ self._patch_transport(monkeypatch, cfg)+ assert openrouter_helper_cost_provider() == "open_router"++ def test_openrouter_transport_is_open_router(self, monkeypatch):+ from backend.copilot.config import ChatConfig++ cfg = ChatConfig(+ use_local=False,+ use_openrouter=True,+ api_key="or-key",+ base_url="https://openrouter.ai/api/v1",+ )+ self._patch_transport(monkeypatch, cfg)+ assert openrouter_helper_cost_provider() == "open_router"diff --git a/autogpt_platform/backend/backend/util/settings.py b/autogpt_platform/backend/backend/util/settings.pyindex 17e68227c7..b6fdfb5691 100644--- a/autogpt_platform/backend/backend/util/settings.py+++ b/autogpt_platform/backend/backend/util/settings.py@@ -232,6 +232,18 @@ class Config(UpdateTrackingModel["Config"], BaseSettings):description="Interval in hours between execution accuracy alert checks.",)+ # Embeddings+ store_embedding_model: str = Field(+ default="text-embedding-3-small",+ description=(+ "Embedding model used by the unified content embeddings service. "+ "Overridable so deployments with a compatible backend (vLLM, "+ "LiteLLM proxy, Ollama with an embedding model pulled, Azure "+ "OpenAI, ...) can swap models without code changes. Model MUST "+ "emit 1536-dim vectors to match the hardcoded pgvector column."+ ),+ )+model_config = SettingsConfigDict(env_file=".env",extra="allow",diff --git a/autogpt_platform/installer/setup-autogpt.bat b/autogpt_platform/installer/setup-autogpt.batindex 1db646d914..7409b72c95 100644--- a/autogpt_platform/installer/setup-autogpt.bat+++ b/autogpt_platform/installer/setup-autogpt.bat@@ -1,18 +1,94 @@@echo offsetlocal enabledelayedexpansion-REM Variables+REM ============================================================================+REM AutoGPT Windows Setup+REM ----------------------------------------------------------------------------+REM Sets up AutoGPT on Windows. Linux/macOS users: setup-autogpt.sh.+REM+REM Optional flags:+REM /with-ollama Install Ollama (via winget), pull a default chat+REM model, and wire backend\.env so AutoPilot runs+REM without any cloud API keys (CHAT_USE_LOCAL=true).+REM See docs/platform/copilot-local-llm.md.+REM /ollama-model=NAME Model to pull (default: hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M).+REM /ollama-host=URL Use an existing Ollama at this URL instead of+REM installing one locally. Skips the Ollama install+REM but still writes the CHAT_USE_LOCAL .env entries.+REM Example: /ollama-host=http://gpu-rig.lab:11434+REM ============================================================================++REM --- Variables ---set SCRIPT_DIR=%~dp0set REPO_DIR=%SCRIPT_DIR%..\..set CLONE_NEEDED=0set LOG_FILE=+set WITH_OLLAMA=0+set OLLAMA_MODEL=hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M+set OLLAMA_HOST_URL=++REM --- Parse args ---+REM NOTE: cmd.exe treats "=" as an argument delimiter (like space / comma /+REM semicolon), so "/ollama-model=foo" arrives as TWO tokens:+REM %1="/ollama-model", %2="foo". We therefore accept BOTH the "=" form+REM (present when the arg is quoted or otherwise not split) AND the bare+REM flag + next-token form, shifting an extra time for the latter so the+REM value isn't reparsed as a flag. (The .sh has no such issue — bash keeps+REM "--ollama-model=foo" as a single word.)+:parse_args+if "%~1"=="" goto args_done+set ARG=%~1+if /I "%ARG%"=="/with-ollama" (+ set WITH_OLLAMA=1+) else if /I "%ARG:~0,14%"=="/ollama-model=" (+ set OLLAMA_MODEL=%ARG:~14%+ set WITH_OLLAMA=1+) else if /I "%ARG%"=="/ollama-model" (+ set "OLLAMA_MODEL=%~2"+ set WITH_OLLAMA=1+ shift+) else if /I "%ARG:~0,13%"=="/ollama-host=" (+ set OLLAMA_HOST_URL=%ARG:~13%+ set WITH_OLLAMA=1+) else if /I "%ARG%"=="/ollama-host" (+ set "OLLAMA_HOST_URL=%~2"+ set WITH_OLLAMA=1+ shift+) else if /I "%ARG%"=="/h" (+ goto print_help+) else if /I "%ARG%"=="/help" (+ goto print_help+) else if /I "%ARG%"=="-h" (+ goto print_help+) else if /I "%ARG%"=="--help" (+ goto print_help+) else (+ echo Unknown flag: %ARG%+ echo Run with /help for usage.+ exit /b 2+)+shift+goto parse_args++:print_help+echo AutoGPT Windows Setup+echo.+echo Optional flags:+echo /with-ollama Install Ollama + pull default chat model + wire .env+echo /ollama-model=NAME Model tag to pull (default: %OLLAMA_MODEL%)+echo /ollama-host=URL Use existing Ollama at URL instead of installing+echo.+echo See docs/platform/copilot-local-llm.md for details.+exit /b 0++:args_doneecho =============================echo AutoGPT Windows Setupecho =============================echo.-REM Check prerequisites+REM --- Check prerequisites ---echo Checking prerequisites...where git >nul 2>nulif errorlevel 1 (@@ -20,7 +96,7 @@ if errorlevel 1 (pauseexit /b 1)-echo Git is installed.+echo Git is installed.where docker >nul 2>nulif errorlevel 1 (@@ -28,10 +104,23 @@ if errorlevel 1 (pauseexit /b 1)-echo Docker is installed.+echo Docker is installed.++if "%WITH_OLLAMA%"=="1" (+ REM curl ships with Windows 10/11 1803+ as curl.exe; we use it for+ REM the Ollama API probes and remote model-pull check, same as the+ REM Linux/macOS script. PowerShell's Invoke-WebRequest would also+ REM work but mixing tools makes the .bat harder to follow.+ where curl >nul 2>nul+ if errorlevel 1 (+ echo curl is not installed but /with-ollama needs it. Install curl ^(or update to Windows 10 1803+ which ships it^) and re-run.+ pause+ exit /b 1+ )+)echo.-REM Detect repo+REM --- Detect repo ---if exist "%REPO_DIR%\.git" (echo Using existing AutoGPT repository.set CLONE_NEEDED=0@@ -40,8 +129,8 @@ if exist "%REPO_DIR%\.git" (set CLONE_NEEDED=1)-REM Clone repo if needed-if %CLONE_NEEDED%==1 (+REM --- Clone repo if needed ---+if "%CLONE_NEEDED%"=="1" (echo Cloning AutoGPT repository...git clone https://github.com/Significant-Gravitas/AutoGPT.git "%REPO_DIR%"if errorlevel 1 (@@ -53,7 +142,13 @@ if %CLONE_NEEDED%==1 ()echo.-REM Navigate to autogpt_platform+REM --- Bootstrap Ollama (optional) ---+if "%WITH_OLLAMA%"=="1" (+ call :bootstrap_ollama || exit /b 1+ call :write_local_env || exit /b 1+)++REM --- Navigate to autogpt_platform ---cd /d "%REPO_DIR%\autogpt_platform"if errorlevel 1 (echo Failed to navigate to autogpt_platform directory.@@ -61,10 +156,9 @@ if errorlevel 1 (exit /b 1)-REM Create logs directoryif not exist logs mkdir logs-REM Run docker compose with logging+REM --- Run docker compose ---echo Starting AutoGPT services with Docker Compose...echo This may take a few minutes on first run...echo.@@ -75,8 +169,8 @@ if errorlevel 1 (echo.echo Common issues:echo - Docker is not running- echo - Insufficient disk space- echo - Port conflicts (check if ports 3000, 8000, etc. are in use)+ echo - Insufficient disk space+ echo - Port conflicts ^(check if ports 3000, 8000, etc. are in use^)pauseexit /b 1)@@ -87,9 +181,210 @@ echo =============================echo.echo Access AutoGPT at: http://localhost:3000echo API available at: http://localhost:8000+if "%WITH_OLLAMA%"=="1" (+ echo.+ echo AutoPilot wired to Ollama ^(model: %OLLAMA_MODEL%^)+ echo Extended-thinking mode auto-downgrades to fast — Ollama doesn't speak+ echo Anthropic's wire protocol. See docs/platform/copilot-local-llm.md.+)echo.echo To stop services: docker compose downecho To view logs: docker compose logs -fecho.-echo Press any key to exit (services will keep running)...-pause >nul\ No newline at end of file+echo Press any key to exit ^(services will keep running^)...+pause >nul+exit /b 0++REM ============================================================================+REM Subroutines+REM ============================================================================++:bootstrap_ollama+if not "%OLLAMA_HOST_URL%"=="" (+ REM Normalize remote URL: strip a trailing slash and an optional /v1+ REM so the operator can pass either the Ollama root+ REM ^(http://host:11434^) or a copy-pasted CHAT_BASE_URL ^(.../v1^).+ set OLLAMA_ROOT=%OLLAMA_HOST_URL%+ if "!OLLAMA_ROOT:~-1!"=="/" set OLLAMA_ROOT=!OLLAMA_ROOT:~0,-1!+ if /I "!OLLAMA_ROOT:~-3!"=="/v1" set OLLAMA_ROOT=!OLLAMA_ROOT:~0,-3!+ echo Using existing Ollama at !OLLAMA_ROOT!+ curl -sf "!OLLAMA_ROOT!/api/version" >nul+ if errorlevel 1 (+ echo Cannot reach Ollama at !OLLAMA_ROOT! — is it running and listening on 0.0.0.0?+ pause+ exit /b 1+ )+ REM Check whether the model is present on the remote; pull if not.+ curl -sf "!OLLAMA_ROOT!/api/tags" | findstr /C:"\"name\":\"%OLLAMA_MODEL%\"" >nul+ if errorlevel 1 (+ echo Model '%OLLAMA_MODEL%' missing on remote — requesting pull...+ REM /api/pull streams NDJSON; a registry 404 or network failure+ REM lands as an "error" object in the body rather than a non-2xx+ REM status, so we capture the stream to a file and grep for an+ REM explicit success / error frame.+ curl -sf -N "!OLLAMA_ROOT!/api/pull" -H "Content-Type: application/json" -d "{\"name\":\"%OLLAMA_MODEL%\"}" > "%TEMP%\ollama_pull.log"+ if errorlevel 1 (+ echo Pull request to !OLLAMA_ROOT!/api/pull failed+ pause+ exit /b 1+ )+ findstr /C:"\"error\"" "%TEMP%\ollama_pull.log" >nul+ if not errorlevel 1 (+ echo Pull of %OLLAMA_MODEL% failed. See %TEMP%\ollama_pull.log+ pause+ exit /b 1+ )+ findstr /C:"\"status\":\"success\"" "%TEMP%\ollama_pull.log" >nul+ if errorlevel 1 (+ echo Pull of %OLLAMA_MODEL% did not report success. See %TEMP%\ollama_pull.log+ pause+ exit /b 1+ )+ echo Pulled %OLLAMA_MODEL% on remote.+ ) else (+ echo Model %OLLAMA_MODEL% present on remote.+ )+ REM Stash the normalized root so write_local_env can reuse it.+ set OLLAMA_HOST_URL=!OLLAMA_ROOT!+ exit /b 0+)++REM Local Ollama install path. Prefer winget — it's preinstalled on+REM Windows 11 and most Windows 10 hosts that have App Installer.+REM If absent, point the operator at the official .exe rather than+REM piping a downloaded installer at them silently.+where ollama >nul 2>nul+if errorlevel 1 (+ where winget >nul 2>nul+ if errorlevel 1 (+ echo Ollama is not installed and winget is not available.+ echo Download and install Ollama from https://ollama.com/download/windows ^(default options^), then re-run this script.+ pause+ exit /b 1+ )+ echo Installing Ollama via winget...+ winget install --id Ollama.Ollama --silent --accept-source-agreements --accept-package-agreements+ if errorlevel 1 (+ echo winget install Ollama.Ollama failed.+ echo Download Ollama manually from https://ollama.com/download/windows and re-run.+ pause+ exit /b 1+ )+) else (+ echo Ollama already installed.+)++REM Set Ollama env vars for the current user so the desktop tray app+REM and any future `ollama serve` shell inherit them.+REM+REM - OLLAMA_HOST=0.0.0.0:11434 so containers can reach it via+REM host.docker.internal ^(which Docker Desktop on Windows auto-injects+REM in every container's /etc/hosts^).+REM - OLLAMA_CONTEXT_LENGTH=32768 because the OpenAI shim does NOT+REM honor options.num_ctx in the request body ^(ollama/ollama#2714^);+REM Ollama silently caps every request at the 4 k default otherwise,+REM truncating AutoPilot's ~8 k system prompt.+REM+REM setx writes to HKCU but does NOT update the current cmd.exe session+REM — so we also export into this shell so the readiness probe below+REM and any post-script user shells see the new values immediately.+echo Setting OLLAMA_HOST and OLLAMA_CONTEXT_LENGTH ^(user env^)...+setx OLLAMA_HOST "0.0.0.0:11434" >nul+setx OLLAMA_CONTEXT_LENGTH "32768" >nul+set OLLAMA_HOST=0.0.0.0:11434+set OLLAMA_CONTEXT_LENGTH=32768++REM Restart Ollama so it picks up the new env. The Windows installer+REM registers Ollama as a background app that re-spawns on user login;+REM we kill it and start `ollama serve` so this run uses the new env+REM without waiting for a reboot.+taskkill /F /IM ollama.exe /T >nul 2>nul+taskkill /F /IM "ollama app.exe" /T >nul 2>nul+start "" /B ollama serve >nul 2>nul++REM Wait up to 30 s for /api/version. The serve process takes a+REM moment to bind on first launch, esp. on Windows Defender systems.+echo Waiting for Ollama to come up on http://localhost:11434 ...+set /a _try=0+:ollama_wait+set /a _try+=1+curl -sf http://localhost:11434/api/version >nul+if not errorlevel 1 goto ollama_ready+if %_try% GEQ 30 (+ echo Ollama did not become reachable on localhost:11434 within 30s.+ echo Open the Ollama tray app once to grant network permissions, then re-run.+ pause+ exit /b 1+)+timeout /t 1 /nobreak >nul+goto ollama_wait++:ollama_ready+echo Pulling model: %OLLAMA_MODEL% ^(this may take several minutes^)...+ollama pull "%OLLAMA_MODEL%"+if errorlevel 1 (+ echo Failed to pull %OLLAMA_MODEL%+ pause+ exit /b 1+)+echo Ollama ready: http://localhost:11434+exit /b 0+++:write_local_env+REM Write backend\.env wiring for the local transport. We use+REM host.docker.internal rather than 127.0.0.1 because Docker Desktop+REM on Windows auto-injects it in every container's /etc/hosts —+REM 127.0.0.1 inside a container points at the container, not the host.+REM+REM This block is idempotent: marker-bounded, so a re-run replaces our+REM lines and nothing else. We use a PowerShell one-liner instead of a+REM batch sed-loop because batch's line editing is genuinely painful+REM ^(no in-place edit, no regex address ranges^), and PowerShell ships+REM with every supported Windows.+cd /d "%REPO_DIR%\autogpt_platform\backend"+if errorlevel 1 (+ echo no backend dir+ exit /b 1+)+if not exist .env copy /Y .env.default .env >nul++set HOST_URL=+if not "%OLLAMA_HOST_URL%"=="" (+ set HOST_URL=%OLLAMA_HOST_URL%+) else (+ set HOST_URL=http://host.docker.internal:11434+)++set START_MARKER=# === Local-LLM AutoPilot wiring (added by setup-autogpt.bat /with-ollama) ===+set END_MARKER=# === End Local-LLM AutoPilot wiring ===++REM Strip any previous block we wrote so re-runs don't accumulate.+REM ``-replace`` with ``(?s)`` makes the regex span newlines; the+REM markers contain regex metacharacters ^(``.``, ``(``, ``)``^), so we+REM ``[Regex]::Escape`` them before splicing into the pattern.+powershell -NoProfile -Command "$start = [Regex]::Escape($env:START_MARKER); $end = [Regex]::Escape($env:END_MARKER); $p = (Resolve-Path .env).Path; $content = Get-Content -Raw $p; if ($null -eq $content) { $content = '' }; $content = $content -replace ('(?s)' + $start + '.*?' + $end + '\r?\n?'), ''; [IO.File]::WriteAllText($p, $content)"++REM Append a fresh block via per-line >> redirects — NOT a parenthesised+REM ( ... ) >> .env group. START_MARKER ends in ")" (...with-ollama) ===),+REM and an unescaped ")" inside a () block closes the group early, so the+REM marker and every line after it get echoed to the console instead of+REM written to .env (CHAT_USE_LOCAL never lands -> AutoPilot 401s). No+REM space before ">>" so model slugs don't gain a trailing space.+REM Ollama-side env knobs OLLAMA_HOST and OLLAMA_CONTEXT_LENGTH are set on+REM the host via setx above, NOT in backend\.env ^(.env is read by+REM containers, where those vars belong to the Ollama process itself^).+echo.>>.env+echo %START_MARKER%>>.env+echo # See docs/platform/copilot-local-llm.md for the full reference.>>.env+echo CHAT_USE_LOCAL=true>>.env+echo CHAT_BASE_URL=%HOST_URL%/v1>>.env+echo CHAT_API_KEY=ollama>>.env+echo CHAT_FAST_STANDARD_MODEL=%OLLAMA_MODEL%>>.env+echo CHAT_FAST_ADVANCED_MODEL=%OLLAMA_MODEL%>>.env+echo OLLAMA_HOST=%HOST_URL%>>.env+echo %END_MARKER%>>.env++echo wrote backend\.env ^(CHAT_USE_LOCAL=true, Ollama at %HOST_URL%^)+cd /d "%REPO_DIR%"+exit /b 0diff --git a/autogpt_platform/installer/setup-autogpt.sh b/autogpt_platform/installer/setup-autogpt.shindex f5bb238de8..24672b803e 100755--- a/autogpt_platform/installer/setup-autogpt.sh+++ b/autogpt_platform/installer/setup-autogpt.sh@@ -1,10 +1,22 @@#!/bin/bash# -------------------------------------------------------------------------------# AutoGPT Setup Script+# AutoGPT Setup Script (Linux + macOS)# -------------------------------------------------------------------------------# This script automates the installation and setup of AutoGPT on Linux systems.+# This script automates the installation and setup of AutoGPT.# It checks prerequisites, clones the repository, and starts all services.+# Windows users: see setup-autogpt.bat.+#+# Optional flags:+# --with-ollama Also install Ollama, pull a default chat model, and+# wire backend/.env so AutoPilot runs without any+# cloud API keys (CHAT_USE_LOCAL=true). See+# docs/platform/copilot-local-llm.md.+# --ollama-model=NAME Model to pull (default: hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M).+# --ollama-host=URL Use an existing Ollama at this URL instead of+# installing one locally. Skips the Ollama install+# but still writes the CHAT_USE_LOCAL .env entries.+# Example: --ollama-host=http://gpu-rig.lab:11434# ------------------------------------------------------------------------------# --- Global Variables ---@@ -20,6 +32,32 @@ CLONE_NEEDED=falseDOCKER_CMD="docker"DOCKER_COMPOSE_CMD="docker compose"LOG_FILE=""+WITH_OLLAMA=false+OLLAMA_MODEL="hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M"+OLLAMA_HOST_URL=""++# OS-family detection — Linux and macOS install Ollama very differently+# (systemd unit + curl-pipe-sh vs launchd-managed brew/dmg app), bind the+# host-to-container reachable IP differently (LAN IP / bridge vs+# host.docker.internal), and set Ollama env differently (drop-in+# /etc/systemd vs launchctl setenv). One central detector beats sprinkling+# ``uname -s`` checks through every helper.+OS_FAMILY="unknown"+case "$(uname -s)" in+ Linux*) OS_FAMILY="linux" ;;+ Darwin*) OS_FAMILY="macos" ;;+ *) OS_FAMILY="unknown" ;;+esac++for arg in "$@"; do+ case "$arg" in+ --with-ollama) WITH_OLLAMA=true ;;+ --ollama-model=*) OLLAMA_MODEL="${arg#*=}"; WITH_OLLAMA=true ;;+ --ollama-host=*) OLLAMA_HOST_URL="${arg#*=}"; WITH_OLLAMA=true ;;+ -h|--help) sed -n '4,19p' "$0"; exit 0 ;;+ *) echo "Unknown flag: $arg" >&2; exit 2 ;;+ esac+doneprint_color() {printf "${!1}%s${NC}\n" "$2"@@ -48,18 +86,32 @@ handle_error() {check_prerequisites() {print_color "BLUE" "Checking prerequisites..."-++ if [ "$OS_FAMILY" = "unknown" ]; then+ handle_error "Unsupported OS: $(uname -s). This script supports Linux and macOS — Windows users should run setup-autogpt.bat."+ fi+ print_color "GREEN" "✓ OS family: $OS_FAMILY"+if ! command -v git &> /dev/null; thenhandle_error "Git is not installed. Please install it and try again."elseprint_color "GREEN" "✓ Git is installed"fi-+if ! command -v docker &> /dev/null; thenhandle_error "Docker is not installed. Please install it and try again."elseprint_color "GREEN" "✓ Docker is installed"fi++ # ``--with-ollama`` shells out to curl for: the Ollama install-script+ # download, version/tags/pull probes against local + remote backends,+ # and the post-restart readiness loop. A minimal host without curl+ # would otherwise fail mid-setup with an opaque ``command not found``;+ # surfacing it here keeps the prerequisite contract in one place.+ if [ "$WITH_OLLAMA" = true ] && ! command -v curl &> /dev/null; then+ handle_error "curl is not installed but --with-ollama needs it (for the Ollama install + API probes). Install curl and re-run."+ fiif ! docker info &> /dev/null; thenprint_color "YELLOW" "Using sudo for Docker commands..."@@ -97,6 +149,278 @@ clone_repo() {fi}+bootstrap_ollama() {+ # Only runs when --with-ollama is set. Splits installing Ollama (which+ # we skip if --ollama-host points at an existing one) from pulling the+ # model (which still happens against the remote in case the operator+ # forgot). The systemd drop-in binds Ollama to all interfaces so+ # docker containers on the same host can reach it via the bridge —+ # without it, OLLAMA_HOST defaults to 127.0.0.1 and containers see+ # connection refused.+ if [ -n "$OLLAMA_HOST_URL" ]; then+ # Normalize: strip trailing slash and an optional ``/v1`` so that+ # ``--ollama-host`` accepts either the Ollama root+ # (``http://host:11434``) or a copy-pasted ``CHAT_BASE_URL`` value+ # (``http://host:11434/v1``). Without this, an operator passing the+ # latter would have us probe ``/v1/api/version`` (404) and write+ # ``CHAT_BASE_URL=…/v1/v1`` into the .env.+ local OLLAMA_ROOT="${OLLAMA_HOST_URL%/}"+ OLLAMA_ROOT="${OLLAMA_ROOT%/v1}"+ print_color "BLUE" "Using existing Ollama at $OLLAMA_ROOT"+ if ! curl -sf "${OLLAMA_ROOT}/api/version" > /dev/null; then+ handle_error "Cannot reach Ollama at $OLLAMA_ROOT — is it running and listening on 0.0.0.0?"+ fi+ # Validate the configured model is present on the remote host;+ # pull it if not. Without this, the install reports "ready" but+ # the first chat turn fails with "model not found" — a setup+ # script that returns 0 should mean the platform is *usable*.+ # ``grep -F`` (fixed string) so model names containing regex+ # metacharacters (``hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M`` has ``.`` and+ # ``:``) match literally, not as wildcards.+ if ! curl -sf "${OLLAMA_ROOT}/api/tags" \+ | grep -Fq "\"name\":\"$OLLAMA_MODEL\""; then+ print_color "BLUE" "Model '$OLLAMA_MODEL' missing on remote — requesting pull..."+ # ``/api/pull`` returns HTTP 200 immediately and streams NDJSON+ # progress lines. A genuine failure (registry 404, network blip+ # mid-download) appears as a JSON object with an ``error`` field+ # in the response body — NOT as a non-2xx status — so ``curl -f``+ # alone reports success and the install lies about being usable.+ # We capture the stream and grep for an explicit success or+ # error frame to surface the truth.+ local pull_log+ pull_log=$(curl -sf -N "${OLLAMA_ROOT}/api/pull" \+ -H "Content-Type: application/json" \+ -d "{\"name\":\"$OLLAMA_MODEL\"}") \+ || handle_error "Pull request to $OLLAMA_ROOT/api/pull failed"+ if grep -q '"error"' <<< "$pull_log"; then+ local err+ err=$(grep -m1 '"error"' <<< "$pull_log")+ handle_error "Pull of $OLLAMA_MODEL failed: $err"+ fi+ if ! grep -q '"status":"success"' <<< "$pull_log"; then+ handle_error "Pull of $OLLAMA_MODEL did not report success — last frame: $(tail -1 <<< "$pull_log")"+ fi+ print_color "GREEN" "✓ Pulled $OLLAMA_MODEL on remote"+ else+ print_color "GREEN" "✓ Model $OLLAMA_MODEL present on remote"+ fi+ # Stash the normalized root so write_local_env doesn't have to+ # repeat the trim. Plain global var is fine — bash functions+ # share the parent's scope unless ``local`` is used.+ OLLAMA_HOST_URL="$OLLAMA_ROOT"+ return+ fi+ if [ "$OS_FAMILY" = "macos" ]; then+ _bootstrap_ollama_macos+ else+ _bootstrap_ollama_linux+ fi+}++_bootstrap_ollama_linux() {+ if ! command -v ollama &> /dev/null; then+ print_color "BLUE" "Installing Ollama (https://ollama.com/install.sh)..."+ curl -fsSL https://ollama.com/install.sh | sh || handle_error "Ollama install failed"+ else+ print_color "GREEN" "✓ Ollama already installed ($(ollama --version 2>&1 | head -1))"+ fi+ # systemd drop-in: bind to all interfaces (so containers can reach it)+ # AND raise the context window from Ollama's 4 k default. Without+ # OLLAMA_CONTEXT_LENGTH, Ollama silently truncates AutoPilot's ~8 k+ # system prompt to 4 k regardless of the model's advertised window+ # — the OpenAI shim does NOT honor `options.num_ctx` in the request+ # body (ollama/ollama#2714), only the env / Modelfile knob does.+ sudo mkdir -p /etc/systemd/system/ollama.service.d+ sudo tee /etc/systemd/system/ollama.service.d/host.conf > /dev/null <<'OLLAMA_DROPIN'+[Service]+Environment="OLLAMA_HOST=0.0.0.0:11434"+Environment="OLLAMA_CONTEXT_LENGTH=32768"+OLLAMA_DROPIN+ sudo systemctl daemon-reload+ sudo systemctl restart ollama+ for _ in $(seq 1 20); do+ curl -sf http://localhost:11434/api/version >/dev/null && break+ sleep 1+ done+ print_color "BLUE" "Pulling model: $OLLAMA_MODEL (this may take several minutes)..."+ ollama pull "$OLLAMA_MODEL" || handle_error "Failed to pull $OLLAMA_MODEL"+ print_color "GREEN" "✓ Ollama ready: http://localhost:11434"+}++_bootstrap_ollama_macos() {+ # macOS Ollama is a launchd-managed .app, not a systemd unit. The+ # canonical install paths are (1) ``brew install ollama`` (formula+ # = headless server; cask = full .app), or (2) the official .dmg+ # from ollama.com. We prefer brew when present because it's+ # scriptable; otherwise we point the operator at the .dmg.+ # Install the official Ollama via the Homebrew *cask* (ollama-app), NOT the+ # ``ollama`` formula. The formula's darwin-arm64 bottle ships the server+ # without the llama-server runner (libexec/lib/ollama holds only the MLX+ # metal lib), so it pulls models fine but 500s on every GGUF inference with+ # "llama-server binary not found". The cask is the full Ollama.app and+ # bundles the runner at Contents/Resources/llama-server.+ local runner="/Applications/Ollama.app/Contents/Resources/llama-server"+ if [ -x "$runner" ]; then+ print_color "GREEN" "✓ Ollama already installed with runner ($(ollama --version 2>&1 | head -1))"+ elif command -v brew &> /dev/null; then+ # A runner-less formula install leaves an ``ollama`` on PATH that can't+ # run models — replace it with the cask rather than skipping on+ # ``command -v``.+ if brew list --formula ollama &> /dev/null; then+ print_color "YELLOW" "Replacing runner-less Ollama formula with the official cask..."+ brew uninstall ollama &> /dev/null || true+ fi+ print_color "BLUE" "Installing Ollama (official app) via Homebrew cask..."+ brew install --cask ollama-app || handle_error "brew install --cask ollama-app failed"+ else+ handle_error "Ollama is not installed and Homebrew is not available. Install Homebrew (https://brew.sh) and re-run, or download Ollama from https://ollama.com/download/mac and re-run with --ollama-host=http://localhost:11434."+ fi+ # Set Ollama env globally for launchd-spawned processes. On macOS,+ # ``launchctl setenv`` is the only knob that survives Ollama.app+ # being relaunched by launchd — exporting in shell won't reach it.+ # **But ``launchctl setenv`` does NOT update an already-running+ # process** — it writes to launchd's env table, which is read at+ # next spawn. If Ollama.app is already running (tray icon visible,+ # carrying its old OLLAMA_HOST=127.0.0.1 default), the script will+ # otherwise report success while the running app continues to+ # truncate context at 4 k and bind only to loopback. Kill the+ # existing instance(s) before re-launching so the new env takes+ # effect.+ launchctl setenv OLLAMA_HOST "0.0.0.0:11434" \+ || handle_error "launchctl setenv OLLAMA_HOST failed"+ launchctl setenv OLLAMA_CONTEXT_LENGTH "32768" \+ || handle_error "launchctl setenv OLLAMA_CONTEXT_LENGTH failed"+ # Stop any currently-running Ollama (tray app, brew service, raw+ # ``ollama serve``). ``pkill`` matches by name; ``|| true`` so the+ # script doesn't abort when nothing is running.+ osascript -e 'quit app "Ollama"' >/dev/null 2>&1 || true+ pkill -f "ollama serve" >/dev/null 2>&1 || true+ if brew services list 2>/dev/null | grep -q '^ollama'; then+ brew services stop ollama >/dev/null 2>&1 || true+ fi+ # Wait briefly for the port to release.+ for _ in $(seq 1 5); do+ if ! lsof -nP -iTCP:11434 -sTCP:LISTEN >/dev/null 2>&1; then break; fi+ sleep 1+ done+ # Restart Ollama headlessly. ``launchctl setenv`` above only reaches+ # launchd-spawned GUI launches of Ollama.app — a shell-spawned+ # ``ollama serve`` inherits THIS shell's env, not launchd's, so it would+ # otherwise bind 127.0.0.1 and truncate context at Ollama's 4k default.+ # Export the same vars on the serve invocation so the headless server+ # honors them too. ``disown`` so the background job survives this script's+ # exit even in shells with ``shopt -s huponexit`` (login shells, some CI).+ OLLAMA_HOST="0.0.0.0:11434" OLLAMA_CONTEXT_LENGTH="32768" \+ nohup ollama serve >/dev/null 2>&1 &+ disown 2>/dev/null || true+ for _ in $(seq 1 20); do+ curl -sf http://localhost:11434/api/version >/dev/null && break+ sleep 1+ done+ if ! curl -sf http://localhost:11434/api/version >/dev/null; then+ handle_error "Ollama did not become reachable on localhost:11434. If you installed via the .dmg, open Ollama.app once to grant it network permissions, then re-run."+ fi+ print_color "BLUE" "Pulling model: $OLLAMA_MODEL (this may take several minutes)..."+ ollama pull "$OLLAMA_MODEL" || handle_error "Failed to pull $OLLAMA_MODEL"+ print_color "GREEN" "✓ Ollama ready: http://localhost:11434"+}++write_local_env() {+ # Wire backend/.env so the new ChatConfig.local transport activates and+ # AutoPilot routes through Ollama with no cloud API keys. Uses the host+ # LAN IP (or the explicit --ollama-host URL) so containers on Linux+ # can reach Ollama without docker-compose extra_hosts gymnastics.+ cd "$REPO_DIR/autogpt_platform/backend" || handle_error "no backend dir"+ [ -f .env ] || cp .env.default .env+ local host_url+ if [ -n "$OLLAMA_HOST_URL" ]; then+ # ``bootstrap_ollama`` already stripped the trailing slash + any+ # ``/v1`` from the operator-supplied URL; trust the normalized form.+ host_url="$OLLAMA_HOST_URL"+ elif [ "$OS_FAMILY" = "macos" ]; then+ # On macOS Docker Desktop auto-injects ``host.docker.internal``+ # into every container's /etc/hosts. Colima, Rancher Desktop,+ # and Lima/nerdctl do NOT — those runtimes need the host's LAN+ # IP instead, otherwise every container DNS lookup fails with+ # ``getaddrinfo ENOTFOUND host.docker.internal`` and the+ # installer would report success while the platform is unusable.+ # Detect by probing ``docker context show`` for the Desktop+ # context name; fall back to a LAN IP for non-Desktop runtimes.+ local docker_ctx+ docker_ctx=$(docker context show 2>/dev/null || echo "")+ if [ "$docker_ctx" = "desktop-linux" ] || [ "$docker_ctx" = "default" ]; then+ host_url="http://host.docker.internal:11434"+ else+ # Colima / Rancher Desktop / Lima — get the LAN IP that the+ # VM can route to. ``ipconfig getifaddr en0`` is the canonical+ # macOS one-liner for "the active interface's IPv4".+ local host_ip+ host_ip=$(ipconfig getifaddr en0 2>/dev/null \+ || ipconfig getifaddr en1 2>/dev/null \+ || echo "")+ if [ -z "$host_ip" ]; then+ handle_error "Could not detect a LAN IP for non-Docker-Desktop runtime ($docker_ctx). Re-run with --ollama-host=http://<your-LAN-IP>:11434."+ fi+ host_url="http://${host_ip}:11434"+ fi+ else+ # Linux: containers can't reach the host via host.docker.internal+ # unless compose wires it. ``hostname -I`` (Linux-only) gives the+ # first non-loopback IPv4, which the bridge network always reaches.+ # We fall back to 127.0.0.1 only when -I returns nothing+ # (e.g. a host with no LAN IPs); in that case the operator will+ # need to override CHAT_BASE_URL by hand.+ local host_ip+ host_ip=$(hostname -I 2>/dev/null | awk '{print $1}')+ : "${host_ip:=127.0.0.1}"+ host_url="http://${host_ip}:11434"+ fi+ # Strip ONLY the bounded block we wrote previously (idempotent re-run).+ # Earlier draft used '/MARKER/,$d' which deletes from marker to EOF —+ # any user-added lines after the block were silently lost on every+ # re-run. The start/end markers below let sed range-delete the exact+ # block we own and nothing else.+ local START_MARKER='# === Local-LLM AutoPilot wiring (added by setup-autogpt.sh --with-ollama) ==='+ local END_MARKER='# === End Local-LLM AutoPilot wiring ==='+ if grep -qF "$START_MARKER" .env; then+ # Use ``/`` as the address-pattern delimiter — the markers contain+ # ``#`` so picking ``#`` would terminate the regex on the very first+ # marker character, leaving sed to match every line and delete the+ # whole file. ``/`` is safe because the markers contain no ``/``.+ # Escape BRE metacharacters in the markers (``.`` from+ # ``setup-autogpt.sh``, etc.) so the address pattern matches the+ # literal marker line and nothing that happens to differ by one+ # character. ``grep -qF`` above ensures we only run when the exact+ # marker is present.+ local START_RE END_RE+ START_RE=$(printf '%s\n' "$START_MARKER" | sed 's/[].[\*^$/]/\\&/g')+ END_RE=$(printf '%s\n' "$END_MARKER" | sed 's/[].[\*^$/]/\\&/g')+ # ``sed -i`` is incompatible between GNU (Linux) and BSD (macOS):+ # GNU treats ``-i`` alone as in-place; BSD requires an extension+ # argument (``-i ''``) or it eats the next arg as the suffix.+ # ``sed -i.bak`` works on both — we delete the .bak afterwards.+ sed -i.bak "/$START_RE/,/$END_RE/d" .env && rm -f .env.bak+ fi+ {+ echo+ echo "$START_MARKER"+ echo "# See docs/platform/copilot-local-llm.md for the full reference."+ echo "CHAT_USE_LOCAL=true"+ echo "CHAT_BASE_URL=${host_url}/v1"+ echo "CHAT_API_KEY=ollama"+ echo "CHAT_FAST_STANDARD_MODEL=$OLLAMA_MODEL"+ echo "CHAT_FAST_ADVANCED_MODEL=$OLLAMA_MODEL"+ # title_model + simulation_model auto-derive from fast_standard_model+ # under the local transport — no need to set them explicitly.+ # OLLAMA_HOST is the block-layer LLM (separate from the chat path);+ # set it too so the AI Text Generator block points at the same backend.+ echo "OLLAMA_HOST=${host_url}"+ echo "$END_MARKER"+ } >> .env+ cd ..+ print_color "GREEN" "✓ wrote backend/.env (CHAT_USE_LOCAL=true, Ollama at $host_url)"+}+run_docker() {cd "$REPO_DIR/autogpt_platform" || handle_error "Failed to navigate to autogpt_platform"@@ -127,8 +451,12 @@ main() {check_prerequisitesdetect_repoclone_repo+ if [ "$WITH_OLLAMA" = true ]; then+ bootstrap_ollama+ write_local_env+ firun_docker-+echoprint_color "GREEN" "============================="print_color "GREEN" " Setup Complete!"@@ -136,6 +464,13 @@ main() {echoprint_color "BLUE" "🚀 Access AutoGPT at: http://localhost:3000"print_color "BLUE" "📡 API available at: http://localhost:8000"+ if [ "$WITH_OLLAMA" = true ]; then+ echo+ print_color "BLUE" "🦙 AutoPilot wired to Ollama (model: $OLLAMA_MODEL)"+ print_color "YELLOW" " Extended-thinking mode auto-downgrades to fast — Ollama"+ print_color "YELLOW" " doesn't speak Anthropic's wire protocol. See"+ print_color "YELLOW" " docs/platform/copilot-local-llm.md."+ fiechoprint_color "YELLOW" "To stop services: docker compose down"print_color "YELLOW" "To view logs: docker compose logs -f"diff --git a/docs/platform/SUMMARY.md b/docs/platform/SUMMARY.mdindex 29830d1b47..14ec66457a 100644--- a/docs/platform/SUMMARY.md+++ b/docs/platform/SUMMARY.md@@ -26,6 +26,7 @@* [Using Google Gemini](gemini.md)* [Using Ollama](ollama.md)+* [AutoPilot on a self-hosted LLM (no API keys)](copilot-local-llm.md)* [Using AI/ML API](aimlapi.md)* [Using D-ID](d_id.md)diff --git a/docs/platform/copilot-local-llm.md b/docs/platform/copilot-local-llm.mdnew file mode 100644index 0000000000..6372ffbb54--- /dev/null+++ b/docs/platform/copilot-local-llm.md@@ -0,0 +1,348 @@+# Running AutoPilot on a self-hosted LLM++> **Important**: This page covers the **AutoPilot chat path** — the+> conversational agent on `/copilot`. For the *block-layer* AI Text+> Generator block (used inside agent graphs you build yourself), see+> [Running Ollama with AutoGPT](ollama.md). The two paths read different+> env vars, so configuring one does not configure the other.+>+> Self-hosting only — the cloud `agpt.co` deployment routes AutoPilot+> through Anthropic / OpenRouter and ignores the variables below.++This guide makes the AutoPilot chat work **without an Anthropic, OpenAI,+or OpenRouter key** by routing it through any **OpenAI-compatible HTTP+endpoint you control**.++The transport is called `local` because it's the typical case, but+``CHAT_BASE_URL`` is just a URL — every deployment shape below works+equally well:++| Scenario | `CHAT_BASE_URL` |+| --- | --- |+| Ollama on the same Docker host (most common) | `http://192.168.1.42:11434/v1` (LAN IP) |+| Ollama on the same Docker host, via Docker Desktop | `http://host.docker.internal:11434/v1` |+| Ollama on a separate LAN box | `http://ollama.lab.local:11434/v1` |+| Ollama behind an HTTPS reverse proxy on the public internet | `https://ollama.example.com/v1` |+| [vLLM](https://docs.vllm.ai/en/latest/serving/openai_compatible_server.html), [LocalAI](https://localai.io/), [LM Studio](https://lmstudio.ai/), [LiteLLM proxy](https://docs.litellm.ai/docs/simple_proxy) | their respective `/v1` URLs |+| A managed OpenAI-compatible API you don't pay AutoGPT for | its `/v1` URL |++Anything that speaks the OpenAI `/v1/chat/completions` shape — including+`tools=[...]` for function calling — will work. The rest of this guide+uses Ollama as the running example because it's the easiest, but+substitute your own endpoint anywhere you see `http://...:11434/v1`.++## How it works++AutoPilot's `ChatConfig` (`backend/backend/copilot/config.py`) recognises+four chat transports. When `CHAT_USE_LOCAL=true`:++| Transport behaviour | Local |+| --- | --- |+| Routes the baseline (fast) path to `CHAT_BASE_URL` over OpenAI-compatible HTTP | ✅ |+| Supports the SDK / extended-thinking path (Claude Agent SDK) | ❌ — auto-downgrades to fast |+| `api_key` falls back to `OPEN_ROUTER_API_KEY` / `OPENAI_API_KEY` if `CHAT_API_KEY` is unset | ❌ — explicit `CHAT_API_KEY` only |+| Auxiliary models (`title_model`, `simulation_model`) inherit `fast_standard_model` if left at default | ✅ |+| Allows non-`anthropic/*` SDK model slugs (vendor validator skipped) | ✅ |++The downgrade is logged at WARNING when an `extended_thinking` request+arrives — there is no 500. The frontend toggle should already be hidden+because the `CHAT_MODE_OPTION` LaunchDarkly flag defaults off in+self-hosted deployments.++## Required environment variables++In `autogpt_platform/backend/.env`:++```bash+# Turn on the local transport+CHAT_USE_LOCAL=true++# Where the OpenAI-compatible endpoint lives. From inside the docker+# containers this must NOT be 127.0.0.1 / localhost — use the host's LAN+# IP (e.g. 192.168.1.42) or, if you've added the directive to compose,+# host.docker.internal:host-gateway.+CHAT_BASE_URL=http://192.168.1.42:11434/v1++# Any non-empty string — Ollama doesn't validate it. The local transport+# deliberately does NOT fall back to OPENAI_API_KEY (which is usually+# present for graphiti / embedders), so this must be set explicitly.+CHAT_API_KEY=ollama++# The chat model. Bare model names ONLY — provider/model slugs (e.g.+# `anthropic/claude-...`) are passed through verbatim and Ollama can't+# resolve them. See "Picking a model" below.+CHAT_FAST_STANDARD_MODEL=hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M++# Optional — overrides for advanced tier and aux models. If you leave+# them out, the local transport derives title_model and simulation_model+# from CHAT_FAST_STANDARD_MODEL automatically; CHAT_FAST_ADVANCED_MODEL+# stays at its cloud default and you should set it to the same Ollama+# slug (or a bigger one if you have the VRAM).+CHAT_FAST_ADVANCED_MODEL=hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M+```++## Picking a model++The platform's chat loop calls **OpenAI-style tool-calling** on every+turn, streams responses, and ships an ~8 k-token system prompt. Pick a+model that handles all three.++| Tier | Recommended Ollama tag | Why | Footprint |+| --- | --- | --- | --- |+| **Default** | `hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M` | Unsloth-recommended; solid OpenAI-shim tool-calling at 4B; 256 k native context; reasoning model (the chat UI renders its thinking separately from the answer) | ~3.4 GB resident; runs on a 16 GB laptop, GPU-accelerated |+| **Tight RAM** | `qwen3:4b` | Smaller; native tools; set `think: false` to avoid the unclosed-`<think>` tool-call render bug | ~3-4 GB resident |+| **GPU / advanced** | `qwen3:14b-instruct-q4_K_M` | Best tool-selection accuracy in this size class | ~12 GB VRAM |++Pull whichever you choose:++```bash+ollama pull hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M+```++## Context window — set it once, on the backend++Ollama defaults `num_ctx` to **4096 tokens regardless of the model's+advertised window** ([ollama/ollama#2714](https://github.com/ollama/ollama/issues/2714)).+That's smaller than AutoPilot's system prompt + tool schemas — without a+larger window Ollama only sees the *end* of the instructions and responses+are incoherent or 500 outright.++Set the window **once, on the server**, via `OLLAMA_CONTEXT_LENGTH`. There is+**no AutoGPT-side context config** to keep in sync: AutoPilot reads the+backend's *actual* loaded window back at runtime — Ollama `/api/ps`, llama.cpp+`/props`, vLLM / LM Studio `/v1/models` — and compacts the conversation under+it. Backends that don't report a window (LiteLLM proxy, Jan,+text-generation-webui) fall back to assuming 32k.++Use **at least 24k** (32768 recommended): below that, the system prompt ++tools leave almost no room for conversation and AutoPilot logs a warning.++The installer sets `OLLAMA_CONTEXT_LENGTH` for you. Manual setup per platform:++**Linux** (systemd drop-in):++```ini+# /etc/systemd/system/ollama.service.d/host.conf+[Service]+Environment="OLLAMA_HOST=0.0.0.0:11434"+Environment="OLLAMA_CONTEXT_LENGTH=32768"+```++Then `sudo systemctl daemon-reload && sudo systemctl restart ollama`.++**macOS** (launchctl, persists across logins for launchd-spawned processes):++```bash+launchctl setenv OLLAMA_HOST 0.0.0.0:11434+launchctl setenv OLLAMA_CONTEXT_LENGTH 32768+# Then restart Ollama — either:+brew services restart ollama # if installed via the brew formula+# …or quit the menu-bar app and relaunch it (the .dmg install)+```++**Windows** (user-scope env vars, persists across reboots):++```powershell+setx OLLAMA_HOST "0.0.0.0:11434"+setx OLLAMA_CONTEXT_LENGTH "32768"+# Then quit Ollama from the system tray and relaunch it+# (setx writes to HKCU but does NOT update already-running processes).+```++Verify on any platform with `ollama ps` (the `CONTEXT` column should+show your value, e.g. 32768). If you change it, AutoPilot picks up the+new window automatically on the next turn — nothing else to update.++## Networking — same host, different host, or remote++The endpoint can be on the same machine, on the LAN, or anywhere+internet-reachable. Pick whichever matches your deployment shape:++### Same host as the AutoGPT containers++How containers reach the host depends on whether you're on Docker+Desktop (macOS / Windows) or native Docker (Linux):++**macOS + Windows (Docker Desktop)** — every container already has a+`host.docker.internal` entry pointing at the host. No extra wiring:++```bash+CHAT_BASE_URL=http://host.docker.internal:11434/v1+```++Still set `OLLAMA_HOST=0.0.0.0:11434` so the .app/tray-managed Ollama+accepts the connection from the Desktop network — by default it binds+only to `127.0.0.1`.++**Linux (native Docker)** — there's no auto-injected+`host.docker.internal`. Pick one:++1. **Use the LAN IP** in `CHAT_BASE_URL` — simplest, works everywhere.+2. **Bind Ollama to all interfaces:** `OLLAMA_HOST=0.0.0.0:11434` (set+ in the systemd unit or a drop-in), so containers reach it via the+ bridge gateway.+3. **Add `extra_hosts: ["host.docker.internal:host-gateway"]`** to the+ chat services in `autogpt_platform/docker-compose.yml`.++The bundled installer does these for you on a fresh box:++| Platform | Command |+| --- | --- |+| Linux | `installer/setup-autogpt.sh --with-ollama` |+| macOS | `installer/setup-autogpt.sh --with-ollama` |+| Windows | `installer\setup-autogpt.bat /with-ollama` |++### Different LAN box (dedicated GPU server, NAS, …)++Set `CHAT_BASE_URL` to the box's hostname or IP:++```bash+CHAT_BASE_URL=http://gpu-rig.lab.local:11434/v1+```++On the Ollama box, set `OLLAMA_HOST=0.0.0.0:11434` so it accepts+non-loopback connections, and either open port 11434 in the firewall+for your AutoGPT host's IP or put both behind a private VPN /+WireGuard mesh.++### Remote / public-internet endpoint++Two approaches, in increasing order of "please do this":++1. **Trusted private network** (Tailscale, WireGuard, ZeroTier,+ corporate VPN). Treat the remote endpoint exactly like a LAN box.+2. **Public HTTPS with auth** — terminate TLS at a reverse proxy+ (Caddy, nginx, Cloudflare Tunnel) in front of Ollama / vLLM /+ whatever, and require a bearer token. Set:++ ```bash+ CHAT_BASE_URL=https://ollama.example.com/v1+ CHAT_API_KEY=<the-bearer-the-proxy-checks>+ ```++> **Do not** expose raw Ollama on the public internet. Ollama itself+> performs **no authentication** — anyone who can reach `:11434` can+> use (and exhaust) your model. Always front it with a proxy that+> enforces a token.++## Other platform features that use the local transport++The `local` transport isn't just for AutoPilot chat. The same client+flows to every backend helper that needs an LLM, so a single+`CHAT_USE_LOCAL=true` install also covers:++- **Dry-run block simulator** — when a user clicks "Test" in the agent+ builder, blocks role-play their execution against an LLM rather than+ hitting external APIs. Uses `ChatConfig.simulation_model`+ (auto-derived to `fast_standard_model` under local).+- **Onboarding business-understanding extraction** — the post-signup+ Tally form is extracted into structured suggestions via the LLM.+ Uses `ChatConfig.title_model`.+- **Long-run prompt compression** — the chat / agent loop summarizes+ message history when context grows beyond a threshold.+- **Marketplace semantic search** — the store generates embeddings for+ agent descriptions to power hybrid (lexical + semantic) ranking.+ Hybrid search degrades gracefully to lexical-only when no embedding+ backend is available.++### Embeddings (marketplace search, agent uploads)++The store's embedding model is overridable via env so deployments with+a compatible backend (vLLM, LiteLLM proxy, Ollama with an embedding+model pulled, Azure OpenAI) can swap models without a code change.+**The replacement model must emit 1536-dim vectors** — the pgvector+column is declared `vector(1536)` in `schema.prisma` and inserts with+any other dim hard-fail.++```bash+# Default — OpenAI text-embedding-3-small (1536 dim):+STORE_EMBEDDING_MODEL=text-embedding-3-small++# Example: nomic-embed-text on Ollama emits 768 dims natively, so it+# DOES NOT fit the existing schema — picking it would break every+# publish + reindex. Use a 1536-dim model instead, e.g.+# text-embedding-ada-002 (OpenAI legacy) or one of the LiteLLM proxy's+# 1536-dim shims. Custom-dim support would need a schema migration+# beyond the scope of this guide.+```++> **pgvector dimension is fixed in the schema, not configurable at+> runtime.** A model that emits a different vector length will succeed+> at the embedding call and fail at every subsequent `INSERT`. If you+> need a different dim, you'll need to fork the schema and migrate+> existing rows — it's not a runtime knob.++If you don't configure an embedding backend at all, marketplace+hybrid search auto-degrades to lexical-only (no semantic ranking) —+not fatal, just less smart.++## Verifying the wiring++After `docker compose up -d`:++```bash+# 1. CHAT_USE_LOCAL is in the live container env+docker exec autogpt_platform-copilot_executor-1 env | grep ^CHAT_+# CHAT_USE_LOCAL=true+# CHAT_BASE_URL=http://192.168.1.42:11434/v1+# ...++# 2. Send a turn from the UI, then confirm baseline routing in the log+docker logs autogpt_platform-copilot_executor-1 | grep -E "Using.*service"+# [CoPilotExecutor|...] Using baseline service (mode=default)++# 3. Confirm Ollama saw the request — per platform:++# Linux (systemd-managed Ollama):+journalctl -u ollama --since "1 minute ago" | grep "POST"+# [GIN] ... | 200 | 7.5s | ... | POST "/v1/chat/completions"++# macOS (brew formula):+tail -F "$(brew --prefix)/var/log/ollama.log" | grep "POST"+# macOS (.app from ollama.com): logs live in ~/.ollama/logs/server.log+tail -F ~/.ollama/logs/server.log | grep "POST"++# Windows: the Ollama tray app writes to %LOCALAPPDATA%\Ollama\server.log+powershell -Command "Get-Content $env:LOCALAPPDATA\Ollama\server.log -Wait | Select-String POST"+```++If `Using baseline service` appears and Ollama logs a 200, the+end-to-end path is working — any remaining errors are model / RAM /+quantization concerns rather than config-routing bugs.++## Troubleshooting++**Frontend shows "The assistant encountered an error"** — check the+copilot_executor log for the upstream error. Common causes:+- `model requires more system memory (X GiB) than is available (Y GiB)`+ → free RAM (stop ClamAV, raise VM memory) or pick a smaller model+- `model "..." not found` → `ollama pull <slug>` first+- `connection refused` → containers can't reach the host on `:11434`;+ see "Container → host networking" above++**`api_key` is `None` even though I set `OPENAI_API_KEY`** — by design.+The local transport requires an explicit `CHAT_API_KEY` so a stray cloud+key set for graphiti / embedders doesn't silently bind to your local+backend as the bearer token.++**Title generation fails / returns "Untitled chat"** — `title_model`+should auto-inherit `fast_standard_model` under the local transport. If+you've explicitly set `CHAT_TITLE_MODEL=openai/gpt-4o-mini` somewhere,+remove it.++**Slow first response** — Ollama loads the model into RAM on the first+request, which can take 5-15 s for 8 B models on CPU. Subsequent+requests are much faster while the model stays resident.++**Every AutoPilot turn takes minutes on CPU** — expected on CPU-only+hosts, not a hang. AutoPilot ships a ~3 k-token system prompt and the+model must *prefill* (compute KV-cache state for) every token of that+prompt before the first output token is emitted. On 4 CPU cores an+8 B Q4 model prefills at roughly **3-4 tokens/sec**, so a fresh turn+takes ~10-15 min just to start generating. Title generation (~70-token+prompt) finishes in seconds because there's almost nothing to prefill.+A consumer GPU brings this down to seconds. If you're CPU-only and+just want to validate the install end-to-end, tail the Ollama server+log (see the per-platform commands in "Verifying the wiring" above)+and watch for the `POST /v1/chat/completions` line — once it appears+with a 200, prefill finished and the model is generating.diff --git a/docs/platform/installer.md b/docs/platform/installer.mdindex a1bce35e83..173625e74a 100644--- a/docs/platform/installer.md+++ b/docs/platform/installer.md@@ -45,6 +45,44 @@ If you prefer, you can manually download and run the installer scripts:These scripts are located in the `autogpt_platform/installer/` directory.+## Running fully offline with a local LLM (Ollama)++Both installer scripts accept an opt-in flag that installs+[Ollama](https://ollama.com), pulls a default chat model, and wires+`backend/.env` so AutoPilot runs **without any cloud API keys**. This+is useful for air-gapped or privacy-sensitive deployments — see+[Running AutoPilot on a self-hosted LLM](copilot-local-llm.md) for the+full reference.++### Linux / macOS++```bash+cd autogpt_platform/installer+./setup-autogpt.sh --with-ollama+# Optional overrides:+# --ollama-model=qwen3:14b-instruct-q4_K_M+# --ollama-host=http://gpu-rig.lab:11434 # use an existing Ollama+```++### Windows++```cmd+cd autogpt_platform\installer+setup-autogpt.bat /with-ollama+REM Optional overrides:+REM /ollama-model=qwen3:14b-instruct-q4_K_M+REM /ollama-host=http://gpu-rig.lab:11434+```++The installer:++1. Installs Ollama (skipped if already present, or if `--ollama-host` points at an existing one).+2. Configures `OLLAMA_HOST=0.0.0.0:11434` + `OLLAMA_CONTEXT_LENGTH=32768` so containers can reach it and so AutoPilot's ~8 k system prompt isn't truncated by Ollama's 4 k default.+3. Pulls the chat model (default `hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M`).+4. Appends a marker-bounded block to `autogpt_platform/backend/.env` with `CHAT_USE_LOCAL=true` plus the `CHAT_BASE_URL` / `CHAT_API_KEY` / `CHAT_*_MODEL` overrides.++Re-running with `--with-ollama` is idempotent — the wiring block is rewritten in place.+## After InstallationOnce the installation is complete: