Harden Langfuse prompt backend error mapping

From PR #93 review:

- Map httpx.TransportError (connect/read/timeout/network) to
  PromptStoreUnavailable in LangfusePromptBackend, alongside 503s, so
  PromptManager falls back on transport failures per the PromptBackend
  contract. Adds a transport-timeout unit test.
- Align the opt-in Langfuse integration test's host resolution to the
  SDK's precedence (LANGFUSE_BASE_URL before LANGFUSE_HOST); it had
  framed LANGFUSE_HOST as canonical with the opposite precedence.

Author: chris-colinsky

src/openarmature/prompts/backends/langfuse.py

@@ -17,6 +17,7 @@
 from datetime import UTC, datetime
 from typing import Any, Protocol
 
+import httpx
 from langfuse.api import NotFoundError, ServiceUnavailableError
 from langfuse.model import ChatPromptClient, TextPromptClient
 
@@ -115,7 +116,12 @@ def _get_prompt(self, name: str, label: str) -> TextPromptClient | ChatPromptCli
                 label=label,
                 backend="langfuse",
             ) from exc
-        except ServiceUnavailableError as exc:
+        except (ServiceUnavailableError, httpx.TransportError) as exc:
+            # 503 plus transport-level failures (connect/read/timeout/
+            # network): the SDK surfaces raw httpx errors when there's no
+            # HTTP response to map to a typed error. Per the PromptBackend
+            # contract these are unavailability, so the manager can fall
+            # back. 4xx auth and other errors still propagate.
             raise PromptStoreUnavailable(
                 f"Langfuse unavailable fetching ({name!r}, {label!r}): {exc}",
                 name=name,

tests/unit/test_observability_langfuse_adapter.py

@@ -11,7 +11,7 @@
 
     LANGFUSE_PUBLIC_KEY=pk-lf-... \\
     LANGFUSE_SECRET_KEY=sk-lf-... \\
-    LANGFUSE_HOST=https://cloud.langfuse.com \\
+    LANGFUSE_BASE_URL=https://cloud.langfuse.com \\
         uv run pytest tests/unit/test_observability_langfuse_adapter.py \\
         -m integration -v
 
@@ -160,11 +160,11 @@ async def test_adapter_against_real_langfuse_cloud() -> None:
     if not public_key or not secret_key:
         pytest.skip("LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY not set")
 
-    # LANGFUSE_HOST is the canonical name (matches the SDK's ``host=``
-    # kwarg); LANGFUSE_BASE_URL is the common alias some downstream
-    # configs use. Accept either; LANGFUSE_HOST wins when both set.
+    # Mirror the SDK's precedence: Langfuse() reads LANGFUSE_BASE_URL
+    # first, then LANGFUSE_HOST. Resolve the same order here so this
+    # explicit host matches what a no-arg Langfuse() would pick up.
     host = (
-        os.environ.get("LANGFUSE_HOST") or os.environ.get("LANGFUSE_BASE_URL") or "https://cloud.langfuse.com"
+        os.environ.get("LANGFUSE_BASE_URL") or os.environ.get("LANGFUSE_HOST") or "https://cloud.langfuse.com"
     )
     client = Langfuse(
         public_key=public_key,
@@ -175,7 +175,7 @@ async def test_adapter_against_real_langfuse_cloud() -> None:
     # background export thread is just a logged warning and the test
     # passes while traces vanish.
     assert client.auth_check(), (
-        "Langfuse auth_check failed — verify LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY / LANGFUSE_HOST"
+        "Langfuse auth_check failed — verify LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY / LANGFUSE_BASE_URL"
     )
 
     observer = LangfuseObserver(client=LangfuseSDKAdapter(client))

tests/unit/test_prompts_langfuse.py

@@ -4,6 +4,7 @@
 
 from typing import Any, cast
 
+import httpx
 import pytest
 
 pytest.importorskip("langfuse")
@@ -128,6 +129,16 @@ async def test_service_unavailable_maps_to_store_unavailable() -> None:
         await backend.fetch("greeting", "production")
 
 
+async def test_transport_error_maps_to_store_unavailable() -> None:
+    # A connect/read/timeout/network failure surfaces as a raw httpx
+    # TransportError (no HTTP response to map to a typed SDK error); it
+    # must become PromptStoreUnavailable so PromptManager can fall back.
+    backend = LangfusePromptBackend(_FakeClient(exc=httpx.ConnectTimeout("timed out")))
+
+    with pytest.raises(PromptStoreUnavailable):
+        await backend.fetch("greeting", "production")
+
+
 async def test_sampling_extracted_from_config() -> None:
     client = _text_client(config={"temperature": 0.0, "max_tokens": 256, "model": "gpt-4o"})
     backend = LangfusePromptBackend(_FakeClient(result=client))