chore: merge develop -> main for v0.28.3

OpenAICompatProvider fails fast with a clear ModelProviderError when no
API key is configured, instead of the cryptic httpx "Illegal header
value b'Bearer '". See CHANGELOG.md [v0.28.3].

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: fulfarodev

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [v0.28.3] - 2026-05-22
+
+### Fixed
+- `OpenAICompatProvider` now fails fast with a clear `ModelProviderError` (`code=model_missing_api_key`) when no API key is configured. Previously it built an empty `Authorization: Bearer ` header and the request died with the cryptic `httpx.LocalProtocolError: Illegal header value b'Bearer '`; the router surfaced that as the last-error string with no hint that a key was simply missing. The error now reads `No API key for OpenAI-compatible provider (model '...')` and names the expected env var. Router fallback is unaffected — the provider raises at request time like any other failure (`astromesh/providers/openai_compat.py`)
+
 ## [v0.28.2] - 2026-05-20
 
 No changes to the `astromesh` core package; this release tracks the

astromesh/__init__.py

@@ -1,3 +1,3 @@
 """Astromesh Agent Runtime Platform."""
 
-__version__ = "0.28.2"
+__version__ = "0.28.3"

astromesh/providers/openai_compat.py

@@ -8,6 +8,8 @@
 
 import httpx
 
+from astromesh.errors import ModelProviderError
+
 from .base import CompletionChunk, CompletionResponse
 
 # Pricing per 1 000 tokens (input, output) in USD
@@ -29,14 +31,24 @@ def __init__(self, config: dict[str, Any] | None = None) -> None:
         self.model: str = config.get("model", "gpt-4o")
         self.timeout: float = config.get("timeout", 120.0)
 
+        env_var = config.get("api_key_env", "OPENAI_API_KEY")
         api_key = config.get("api_key")
         if not api_key:
-            env_var = config.get("api_key_env", "OPENAI_API_KEY")
             api_key = os.environ.get(env_var, "")
         self.api_key: str = api_key
+        self.api_key_env: str = env_var
         self._client: httpx.AsyncClient | None = None
 
     async def _get_client(self) -> httpx.AsyncClient:
+        if not self.api_key:
+            raise ModelProviderError(
+                f"No API key for OpenAI-compatible provider (model '{self.model}').",
+                hint=(
+                    f"Set the {self.api_key_env} environment variable, or pass "
+                    f"'api_key' in the provider config. Endpoint: {self.base_url}"
+                ),
+                code="model_missing_api_key",
+            )
         if self._client is None or self._client.is_closed:
             self._client = httpx.AsyncClient(
                 base_url=self.base_url,

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "astromesh"
-version = "0.28.2"
+version = "0.28.3"
 description = "Astromesh Agent Runtime Platform — multi-model, multi-pattern AI agent runtime"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -76,7 +76,7 @@ line-length = 100
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.28.2"
+version = "0.28.3"
 version_files = [
     "pyproject.toml:version",
     "astromesh/__init__.py:__version__",

tests/test_providers.py

@@ -3,8 +3,10 @@
 from __future__ import annotations
 
 import httpx
+import pytest
 import respx
 
+from astromesh.errors import ModelProviderError
 from astromesh.providers.base import CompletionResponse
 from astromesh.providers.hf_tgi_provider import HFTGIProvider
 from astromesh.providers.llamacpp_provider import LlamaCppProvider
@@ -122,6 +124,26 @@ def test_openai_compat_supports_tools():
     assert provider.supports_tools() is True
 
 
+async def test_openai_compat_missing_api_key_fails_fast(monkeypatch):
+    """No API key → fail fast with a clear ModelProviderError instead of an
+    empty 'Authorization: Bearer ' header that httpx rejects as illegal."""
+    monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
+
+    provider = OpenAICompatProvider(
+        {
+            "base_url": "https://api.anthropic.com/v1",
+            "model": "claude-sonnet-4-6",
+            "api_key_env": "ANTHROPIC_API_KEY",
+        }
+    )
+
+    with pytest.raises(ModelProviderError) as exc_info:
+        await provider.complete(MESSAGES)
+
+    assert exc_info.value.code == "model_missing_api_key"
+    assert "ANTHROPIC_API_KEY" in exc_info.value.hint
+
+
 # ===================================================================
 # vLLM
 # ===================================================================