mowa 0.1.0__tar.gz

mowa-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+.pytest_cache/
+dist/
+*.egg-info/
+.venv/

mowa-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.5
+Name: mowa
+Version: 0.1.0
+Summary: Load your Mowa agents at runtime.
+Project-URL: Homepage, https://mowa.dev
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.24; extra == 'httpx'
+Description-Content-Type: text/markdown
+
+# mowa
+
+Load your Mowa agents at runtime. Edit the prompt in Mowa, ship it without a deploy.
+
+## Install
+
+```bash
+pip install mowa
+pip install "mowa[httpx]"
+```
+
+No required deps. Uses `httpx` if it's installed, else the standard library.
+
+## Use
+
+```python
+from openai import OpenAI
+from mowa import Mowa
+
+mowa = Mowa()
+openai = OpenAI()
+
+agent = mowa.get_agent(
+    "support",
+    fallback={"system_prompt": "You are a helpful support agent.", "model": "gpt-4o-mini"},
+)
+
+reply = openai.chat.completions.create(
+    model=agent.model,
+    messages=[
+        {"role": "system", "content": agent.system_prompt},
+        {"role": "user", "content": "Where is my order?"},
+    ],
+    temperature=agent.settings.get("temperature"),
+)
+```
+
+`Mowa()` reads `MOWA_API_KEY` and `MOWA_BASE_URL` from the environment. You can also pass `api_key`, `base_url`, `cache_ttl` (default 60s) and `timeout` (default 2s).
+
+## Versions
+
+```python
+mowa.get_agent("support")
+mowa.get_agent("support", version="draft")
+mowa.get_agent("support", version=3)
+```
+
+## Caching and fallback
+
+- First call fetches the agent and keeps it in memory.
+- For the next `cache_ttl` seconds you get the cached copy. No network.
+- After that you still get the cached copy right away, and it refreshes in the background.
+- If the first fetch fails and you passed a `fallback`, you get the fallback. It never raises.
+- With no fallback, it raises `MowaError`.
+
+`agent.source` tells you where it came from: `network`, `cache`, `stale` or `fallback`.
+
+Warm the cache at startup with `mowa.prefetch(["support", "billing"])`. Reset it with `mowa.clear_cache()`.
+
+## Traces
+
+```python
+span.set_attributes(agent.trace_attributes())
+```
+
+Gives `{"mowa.agent": "support", "mowa.version": "v3"}`, so traces link back to the version that ran.
+
+## Raw HTTP
+
+```bash
+curl https://mowa.dev/api/v1/agents/support/live -H "x-api-key: $MOWA_API_KEY"
+```
+
+Add `?version=draft` or `?version=v3`. Send `If-None-Match` with the `ETag` to get a `304` when nothing changed.

mowa-0.1.0/README.md

@@ -0,0 +1,74 @@
+# mowa
+
+Load your Mowa agents at runtime. Edit the prompt in Mowa, ship it without a deploy.
+
+## Install
+
+```bash
+pip install mowa
+pip install "mowa[httpx]"
+```
+
+No required deps. Uses `httpx` if it's installed, else the standard library.
+
+## Use
+
+```python
+from openai import OpenAI
+from mowa import Mowa
+
+mowa = Mowa()
+openai = OpenAI()
+
+agent = mowa.get_agent(
+    "support",
+    fallback={"system_prompt": "You are a helpful support agent.", "model": "gpt-4o-mini"},
+)
+
+reply = openai.chat.completions.create(
+    model=agent.model,
+    messages=[
+        {"role": "system", "content": agent.system_prompt},
+        {"role": "user", "content": "Where is my order?"},
+    ],
+    temperature=agent.settings.get("temperature"),
+)
+```
+
+`Mowa()` reads `MOWA_API_KEY` and `MOWA_BASE_URL` from the environment. You can also pass `api_key`, `base_url`, `cache_ttl` (default 60s) and `timeout` (default 2s).
+
+## Versions
+
+```python
+mowa.get_agent("support")
+mowa.get_agent("support", version="draft")
+mowa.get_agent("support", version=3)
+```
+
+## Caching and fallback
+
+- First call fetches the agent and keeps it in memory.
+- For the next `cache_ttl` seconds you get the cached copy. No network.
+- After that you still get the cached copy right away, and it refreshes in the background.
+- If the first fetch fails and you passed a `fallback`, you get the fallback. It never raises.
+- With no fallback, it raises `MowaError`.
+
+`agent.source` tells you where it came from: `network`, `cache`, `stale` or `fallback`.
+
+Warm the cache at startup with `mowa.prefetch(["support", "billing"])`. Reset it with `mowa.clear_cache()`.
+
+## Traces
+
+```python
+span.set_attributes(agent.trace_attributes())
+```
+
+Gives `{"mowa.agent": "support", "mowa.version": "v3"}`, so traces link back to the version that ran.
+
+## Raw HTTP
+
+```bash
+curl https://mowa.dev/api/v1/agents/support/live -H "x-api-key: $MOWA_API_KEY"
+```
+
+Add `?version=draft` or `?version=v3`. Send `If-None-Match` with the `ETag` to get a `304` when nothing changed.

mowa-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mowa"
+version = "0.1.0"
+description = "Load your Mowa agents at runtime."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = []
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+httpx = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://mowa.dev"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mowa"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

mowa-0.1.0/src/mowa/__init__.py

@@ -0,0 +1,3 @@
+from .client import Agent, Mowa, MowaError, Transport, __version__
+
+__all__ = ["Agent", "Mowa", "MowaError", "Transport", "__version__"]

mowa-0.1.0/src/mowa/client.py

@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+import urllib.error
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field, replace
+from typing import Any, Callable, Dict, Iterable, List, Mapping, Optional, Set, Tuple, Union
+from urllib.parse import quote
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://mowa.dev"
+
+Transport = Callable[[str, Mapping[str, str], float], Tuple[int, Mapping[str, str], bytes]]
+VersionSelector = Union[str, int]
+CacheKey = Tuple[str, str]
+
+
+class MowaError(Exception):
+    def __init__(self, message: str, status: Optional[int] = None, code: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+
+
+@dataclass(frozen=True)
+class Agent:
+    slug: str
+    version: str
+    system_prompt: str
+    model: str
+    provider: Optional[str] = None
+    name: Optional[str] = None
+    settings: Dict[str, Any] = field(default_factory=dict)
+    tools: List[Any] = field(default_factory=list)
+    inputs: List[Any] = field(default_factory=list)
+    outputs: List[Any] = field(default_factory=list)
+    source: str = "network"
+
+    def trace_attributes(self) -> Dict[str, str]:
+        return {"mowa.agent": self.slug, "mowa.version": self.version}
+
+
+@dataclass
+class _CacheEntry:
+    agent: Agent
+    etag: Optional[str]
+    fetched_at: float
+
+
+def urllib_transport(url: str, headers: Mapping[str, str], timeout: float) -> Tuple[int, Mapping[str, str], bytes]:
+    request = urllib.request.Request(url, headers=dict(headers), method="GET")
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return response.status, dict(response.headers.items()), response.read()
+    except urllib.error.HTTPError as error:
+        try:
+            body = error.read()
+        except Exception:
+            body = b""
+        response_headers = dict(error.headers.items()) if error.headers is not None else {}
+        return error.code, response_headers, body or b""
+
+
+class HttpxTransport:
+    def __init__(self) -> None:
+        import httpx
+
+        self._client = httpx.Client(follow_redirects=True)
+
+    def __call__(self, url: str, headers: Mapping[str, str], timeout: float) -> Tuple[int, Mapping[str, str], bytes]:
+        response = self._client.get(url, headers=dict(headers), timeout=timeout)
+        return response.status_code, dict(response.headers.items()), response.content
+
+
+def default_transport() -> Transport:
+    try:
+        return HttpxTransport()
+    except ImportError:
+        return urllib_transport
+
+
+def version_key(version: VersionSelector) -> str:
+    if isinstance(version, bool):
+        raise ValueError("version must be \"live\", \"draft\" or an int like 3.")
+    if isinstance(version, int):
+        if version < 1:
+            raise ValueError("version must be 1 or higher.")
+        return f"v{version}"
+    if isinstance(version, str):
+        cleaned = version.strip().lower()
+        if cleaned in ("live", "draft"):
+            return cleaned
+        if cleaned.startswith("v") and cleaned[1:].isdigit():
+            return cleaned
+        if cleaned.isdigit():
+            return f"v{cleaned}"
+    raise ValueError("version must be \"live\", \"draft\" or an int like 3.")
+
+
+def provider_from_model(model: str) -> Optional[str]:
+    if "/" in model:
+        provider = model.split("/", 1)[0].strip()
+        return provider or None
+    return None
+
+
+def _lowercase_headers(headers: Optional[Mapping[str, str]]) -> Dict[str, str]:
+    return {str(name).lower(): str(value) for name, value in (headers or {}).items()}
+
+
+def _error_from_body(slug: str, status: int, body: bytes) -> MowaError:
+    message = f"HTTP {status}"
+    code: Optional[str] = None
+    try:
+        payload = json.loads(body.decode("utf-8")) if body else None
+    except (ValueError, UnicodeDecodeError):
+        payload = None
+    if isinstance(payload, dict) and isinstance(payload.get("error"), dict):
+        error = payload["error"]
+        if error.get("message"):
+            message = f"{error['message']} (HTTP {status})"
+        if error.get("code"):
+            code = str(error["code"])
+    return MowaError(f"Could not load agent \"{slug}\": {message}", status=status, code=code)
+
+
+def _agent_from_payload(slug: str, requested_version: str, payload: Any) -> Agent:
+    if not isinstance(payload, dict):
+        raise MowaError(f"Could not load agent \"{slug}\": response was not a JSON object.")
+    model = str(payload.get("model") or "")
+    return Agent(
+        slug=str(payload.get("slug") or slug),
+        version=str(payload.get("version") or requested_version),
+        system_prompt=str(payload.get("systemPrompt") or ""),
+        model=model,
+        provider=payload.get("provider") or provider_from_model(model),
+        name=payload.get("name"),
+        settings=dict(payload.get("settings") or {}),
+        tools=list(payload.get("tools") or []),
+        inputs=list(payload.get("inputs") or []),
+        outputs=list(payload.get("outputs") or []),
+        source="network",
+    )
+
+
+def agent_from_fallback(slug: str, fallback: Mapping[str, Any]) -> Agent:
+    model = str(fallback.get("model") or "")
+    return Agent(
+        slug=slug,
+        version="fallback",
+        system_prompt=str(fallback.get("system_prompt") or ""),
+        model=model,
+        provider=fallback.get("provider") or provider_from_model(model),
+        settings=dict(fallback.get("settings") or {}),
+        source="fallback",
+    )
+
+
+class Mowa:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        cache_ttl: float = 60.0,
+        timeout: float = 2.0,
+        transport: Optional[Transport] = None,
+        clock: Optional[Callable[[], float]] = None,
+    ) -> None:
+        resolved_key = api_key if api_key is not None else os.environ.get("MOWA_API_KEY")
+        self.api_key = resolved_key.strip() if resolved_key else None
+        resolved_base = base_url or os.environ.get("MOWA_BASE_URL") or DEFAULT_BASE_URL
+        self.base_url = resolved_base.strip().rstrip("/")
+        self.cache_ttl = float(cache_ttl)
+        self.timeout = float(timeout)
+        self._transport = transport
+        self._clock = clock or time.monotonic
+        self._lock = threading.Lock()
+        self._cache: Dict[CacheKey, _CacheEntry] = {}
+        self._refreshing: Set[CacheKey] = set()
+        self._refresh_threads: List[threading.Thread] = []
+
+    def get_agent(
+        self,
+        slug: str,
+        version: VersionSelector = "live",
+        fallback: Optional[Mapping[str, Any]] = None,
+    ) -> Agent:
+        key = (slug, version_key(version))
+        with self._lock:
+            entry = self._cache.get(key)
+            if entry is not None:
+                if self._clock() - entry.fetched_at < self.cache_ttl:
+                    return replace(entry.agent, source="cache")
+                stale_agent = replace(entry.agent, source="stale")
+            else:
+                stale_agent = None
+        if stale_agent is not None:
+            self._refresh_in_background(key)
+            return stale_agent
+        try:
+            return self._fetch_and_store(key, etag=None)
+        except Exception as error:
+            if fallback is not None:
+                return agent_from_fallback(slug, fallback)
+            if isinstance(error, MowaError):
+                raise
+            reason = str(error) or type(error).__name__
+            raise MowaError(f"Could not load agent \"{slug}\": {reason}") from error
+
+    def prefetch(self, slugs: Iterable[str], version: VersionSelector = "live") -> None:
+        unique_slugs = list(dict.fromkeys(slugs))
+        if not unique_slugs:
+            return
+        with ThreadPoolExecutor(max_workers=min(8, len(unique_slugs))) as pool:
+            for future in [pool.submit(self._prefetch_one, slug, version) for slug in unique_slugs]:
+                future.result()
+
+    def clear_cache(self) -> None:
+        with self._lock:
+            self._cache.clear()
+
+    def wait_for_refresh(self, timeout: Optional[float] = 5.0) -> bool:
+        with self._lock:
+            threads = list(self._refresh_threads)
+        deadline = None if timeout is None else time.monotonic() + timeout
+        for thread in threads:
+            remaining = None if deadline is None else max(0.0, deadline - time.monotonic())
+            thread.join(remaining)
+        with self._lock:
+            self._refresh_threads = [thread for thread in self._refresh_threads if thread.is_alive()]
+            return not self._refresh_threads
+
+    def _prefetch_one(self, slug: str, version: VersionSelector) -> None:
+        try:
+            self.get_agent(slug, version=version)
+        except MowaError:
+            pass
+
+    def _refresh_in_background(self, key: CacheKey) -> None:
+        with self._lock:
+            if key in self._refreshing:
+                return
+            self._refreshing.add(key)
+            thread = threading.Thread(
+                target=self._refresh,
+                args=(key,),
+                name=f"mowa-refresh-{key[0]}-{key[1]}",
+                daemon=True,
+            )
+            self._refresh_threads = [alive for alive in self._refresh_threads if alive.is_alive()]
+            self._refresh_threads.append(thread)
+        thread.start()
+
+    def _refresh(self, key: CacheKey) -> None:
+        try:
+            with self._lock:
+                entry = self._cache.get(key)
+                etag = entry.etag if entry is not None else None
+            self._fetch_and_store(key, etag=etag)
+        except Exception:
+            pass
+        finally:
+            with self._lock:
+                self._refreshing.discard(key)
+
+    def _url_for(self, key: CacheKey) -> str:
+        slug, selected = key
+        url = f"{self.base_url}/api/v1/agents/{quote(slug, safe='')}/live"
+        if selected != "live":
+            url += f"?version={selected}"
+        return url
+
+    def _headers_for(self, etag: Optional[str]) -> Dict[str, str]:
+        headers = {
+            "accept": "application/json",
+            "x-api-key": self.api_key or "",
+            "x-mowa-sdk": f"py/{__version__}",
+            "user-agent": f"mowa-python/{__version__}",
+        }
+        if etag:
+            headers["if-none-match"] = etag
+        return headers
+
+    def _send(self, url: str, headers: Mapping[str, str]) -> Tuple[int, Mapping[str, str], bytes]:
+        if self._transport is None:
+            self._transport = default_transport()
+        return self._transport(url, headers, self.timeout)
+
+    def _fetch_and_store(self, key: CacheKey, etag: Optional[str]) -> Agent:
+        slug, selected = key
+        if not self.api_key:
+            raise MowaError("Set MOWA_API_KEY or pass api_key.")
+        status, raw_headers, body = self._send(self._url_for(key), self._headers_for(etag))
+        response_headers = _lowercase_headers(raw_headers)
+        if status == 304:
+            with self._lock:
+                entry = self._cache.get(key)
+                if entry is None:
+                    raise MowaError(f"Could not load agent \"{slug}\": got 304 with no cached copy.", status=304)
+                entry.fetched_at = self._clock()
+                return entry.agent
+        if not 200 <= status < 300:
+            raise _error_from_body(slug, status, body)
+        try:
+            payload = json.loads(body.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError) as error:
+            raise MowaError(f"Could not load agent \"{slug}\": response was not valid JSON.") from error
+        agent = _agent_from_payload(slug, selected, payload)
+        new_etag = response_headers.get("etag") or (payload.get("etag") if isinstance(payload, dict) else None)
+        with self._lock:
+            self._cache[key] = _CacheEntry(agent=agent, etag=new_etag, fetched_at=self._clock())
+        return agent

mowa-0.1.0/tests/test_client.py

@@ -0,0 +1,395 @@
+import json
+import socket
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+import pytest
+
+from mowa import Agent, Mowa, MowaError, __version__
+from mowa.client import urllib_transport
+
+
+def agent_payload(version="v3", system_prompt="You are helpful.", etag='"etag-1"'):
+    return {
+        "slug": "support",
+        "name": "Support",
+        "version": version,
+        "systemPrompt": system_prompt,
+        "provider": "openai",
+        "model": "gpt-4o-mini",
+        "settings": {"temperature": 0.2},
+        "tools": [{"name": "lookup"}],
+        "inputs": [{"name": "question"}],
+        "outputs": [],
+        "etag": etag,
+    }
+
+
+class FakeClock:
+    def __init__(self):
+        self.now = 1000.0
+
+    def __call__(self):
+        return self.now
+
+    def advance(self, seconds):
+        self.now += seconds
+
+
+class FakeTransport:
+    def __init__(self, *responses):
+        self.responses = list(responses)
+        self.calls = []
+
+    def __call__(self, url, headers, timeout):
+        self.calls.append({"url": url, "headers": dict(headers), "timeout": timeout})
+        response = self.responses.pop(0) if len(self.responses) > 1 else self.responses[0]
+        if isinstance(response, BaseException):
+            raise response
+        return response
+
+
+def ok(payload, etag='"etag-1"'):
+    return 200, {"ETag": etag, "Content-Type": "application/json"}, json.dumps(payload).encode()
+
+
+def not_modified(etag='"etag-1"'):
+    return 304, {"ETag": etag}, b""
+
+
+def make_client(transport, clock=None, **options):
+    return Mowa(
+        api_key="mk_test",
+        base_url="https://example.test/",
+        transport=transport,
+        clock=clock or FakeClock(),
+        **options,
+    )
+
+
+FALLBACK = {"system_prompt": "Be brief.", "model": "anthropic/claude-sonnet-4-5"}
+
+
+def test_first_call_loads_from_network():
+    transport = FakeTransport(ok(agent_payload()))
+    agent = make_client(transport).get_agent("support")
+    assert isinstance(agent, Agent)
+    assert agent.source == "network"
+    assert agent.slug == "support"
+    assert agent.version == "v3"
+    assert agent.system_prompt == "You are helpful."
+    assert agent.provider == "openai"
+    assert agent.model == "gpt-4o-mini"
+    assert agent.settings == {"temperature": 0.2}
+    assert agent.tools == [{"name": "lookup"}]
+    assert transport.calls[0]["url"] == "https://example.test/api/v1/agents/support/live"
+    assert transport.calls[0]["timeout"] == 2.0
+
+
+def test_sends_api_key_and_sdk_headers():
+    transport = FakeTransport(ok(agent_payload()))
+    make_client(transport).get_agent("support")
+    headers = transport.calls[0]["headers"]
+    assert headers["x-api-key"] == "mk_test"
+    assert headers["x-mowa-sdk"] == f"py/{__version__}"
+    assert __version__ == "0.1.0"
+    assert "if-none-match" not in headers
+
+
+def test_fresh_hit_uses_cache_without_network():
+    clock = FakeClock()
+    transport = FakeTransport(ok(agent_payload()))
+    mowa = make_client(transport, clock)
+    mowa.get_agent("support")
+    clock.advance(30)
+    agent = mowa.get_agent("support")
+    assert agent.source == "cache"
+    assert agent.system_prompt == "You are helpful."
+    assert len(transport.calls) == 1
+
+
+def test_stale_returns_copy_and_revalidates_with_304():
+    clock = FakeClock()
+    transport = FakeTransport(ok(agent_payload()), not_modified())
+    mowa = make_client(transport, clock)
+    mowa.get_agent("support")
+    clock.advance(61)
+    stale = mowa.get_agent("support")
+    assert stale.source == "stale"
+    assert stale.system_prompt == "You are helpful."
+    assert mowa.wait_for_refresh()
+    assert len(transport.calls) == 2
+    assert transport.calls[1]["headers"]["if-none-match"] == '"etag-1"'
+    refreshed = mowa.get_agent("support")
+    assert refreshed.source == "cache"
+    assert refreshed.system_prompt == "You are helpful."
+    assert len(transport.calls) == 2
+
+
+def test_stale_revalidation_replaces_copy_on_200():
+    clock = FakeClock()
+    transport = FakeTransport(
+        ok(agent_payload()),
+        ok(agent_payload(version="v4", system_prompt="New prompt.", etag='"etag-2"'), etag='"etag-2"'),
+        not_modified('"etag-2"'),
+    )
+    mowa = make_client(transport, clock)
+    mowa.get_agent("support")
+    clock.advance(61)
+    assert mowa.get_agent("support").system_prompt == "You are helpful."
+    assert mowa.wait_for_refresh()
+    updated = mowa.get_agent("support")
+    assert updated.source == "cache"
+    assert updated.version == "v4"
+    assert updated.system_prompt == "New prompt."
+    clock.advance(61)
+    mowa.get_agent("support")
+    assert mowa.wait_for_refresh()
+    assert transport.calls[2]["headers"]["if-none-match"] == '"etag-2"'
+
+
+def test_failed_revalidation_keeps_stale_copy():
+    clock = FakeClock()
+    transport = FakeTransport(ok(agent_payload()), TimeoutError("timed out"))
+    mowa = make_client(transport, clock)
+    mowa.get_agent("support")
+    clock.advance(61)
+    mowa.get_agent("support")
+    assert mowa.wait_for_refresh()
+    again = mowa.get_agent("support")
+    assert again.source == "stale"
+    assert again.system_prompt == "You are helpful."
+
+
+def test_only_one_revalidation_in_flight_per_key():
+    clock = FakeClock()
+    release = threading.Event()
+    calls = []
+
+    def slow_transport(url, headers, timeout):
+        calls.append(url)
+        if len(calls) == 1:
+            return ok(agent_payload())
+        release.wait(5)
+        return not_modified()
+
+    mowa = make_client(slow_transport, clock)
+    mowa.get_agent("support")
+    clock.advance(61)
+    for _ in range(5):
+        assert mowa.get_agent("support").source == "stale"
+    release.set()
+    assert mowa.wait_for_refresh()
+    assert len(calls) == 2
+
+
+def test_timeout_returns_fallback():
+    transport = FakeTransport(TimeoutError("timed out"))
+    agent = make_client(transport).get_agent("support", fallback=FALLBACK)
+    assert agent.source == "fallback"
+    assert agent.version == "fallback"
+    assert agent.system_prompt == "Be brief."
+    assert agent.model == "anthropic/claude-sonnet-4-5"
+    assert agent.provider == "anthropic"
+    assert agent.settings == {}
+    assert agent.tools == [] and agent.inputs == [] and agent.outputs == []
+
+
+def test_fallback_provider_and_settings_are_used_when_given():
+    transport = FakeTransport(OSError("connection refused"))
+    fallback = {"system_prompt": "Hi.", "model": "gpt-4o", "provider": "openai", "settings": {"temperature": 0}}
+    agent = make_client(transport).get_agent("support", fallback=fallback)
+    assert agent.provider == "openai"
+    assert agent.settings == {"temperature": 0}
+
+
+def test_fallback_without_slash_has_no_provider():
+    transport = FakeTransport(OSError("down"))
+    agent = make_client(transport).get_agent("support", fallback={"system_prompt": "Hi.", "model": "gpt-4o"})
+    assert agent.provider is None
+
+
+def test_bad_json_and_server_errors_return_fallback():
+    for response in [(200, {}, b"not json"), (500, {}, b""), (200, {}, b"[1, 2]")]:
+        agent = make_client(FakeTransport(response)).get_agent("support", fallback=FALLBACK)
+        assert agent.source == "fallback"
+
+
+def test_fallback_is_not_cached():
+    transport = FakeTransport(OSError("down"), ok(agent_payload()))
+    mowa = make_client(transport)
+    assert mowa.get_agent("support", fallback=FALLBACK).source == "fallback"
+    assert mowa.get_agent("support", fallback=FALLBACK).source == "network"
+
+
+def test_no_fallback_raises_mowa_error_on_network_failure():
+    transport = FakeTransport(TimeoutError("timed out"))
+    with pytest.raises(MowaError) as raised:
+        make_client(transport).get_agent("support")
+    assert raised.value.message == 'Could not load agent "support": timed out'
+    assert raised.value.status is None
+
+
+def test_no_fallback_raises_mowa_error_with_server_code():
+    body = json.dumps({"error": {"code": "not_found", "message": 'No agent "support" in production.'}}).encode()
+    transport = FakeTransport((404, {}, body))
+    with pytest.raises(MowaError) as raised:
+        make_client(transport).get_agent("support")
+    assert raised.value.status == 404
+    assert raised.value.code == "not_found"
+    assert 'No agent "support" in production.' in raised.value.message
+
+
+def test_missing_api_key(monkeypatch):
+    monkeypatch.delenv("MOWA_API_KEY", raising=False)
+    transport = FakeTransport(ok(agent_payload()))
+    mowa = Mowa(transport=transport)
+    with pytest.raises(MowaError) as raised:
+        mowa.get_agent("support")
+    assert raised.value.message == "Set MOWA_API_KEY or pass api_key."
+    assert mowa.get_agent("support", fallback=FALLBACK).source == "fallback"
+    assert transport.calls == []
+
+
+def test_reads_key_and_base_url_from_environment(monkeypatch):
+    monkeypatch.setenv("MOWA_API_KEY", "mk_env")
+    monkeypatch.setenv("MOWA_BASE_URL", "http://localhost:3001///")
+    transport = FakeTransport(ok(agent_payload()))
+    mowa = Mowa(transport=transport)
+    mowa.get_agent("support")
+    assert mowa.base_url == "http://localhost:3001"
+    assert transport.calls[0]["url"] == "http://localhost:3001/api/v1/agents/support/live"
+    assert transport.calls[0]["headers"]["x-api-key"] == "mk_env"
+
+
+def test_pinned_version_sends_version_query():
+    transport = FakeTransport(ok(agent_payload()))
+    agent = make_client(transport).get_agent("support", version=3)
+    assert transport.calls[0]["url"] == "https://example.test/api/v1/agents/support/live?version=v3"
+    assert agent.version == "v3"
+
+
+def test_draft_sends_version_query():
+    transport = FakeTransport(ok(agent_payload(version="draft")))
+    agent = make_client(transport).get_agent("support", version="draft")
+    assert transport.calls[0]["url"] == "https://example.test/api/v1/agents/support/live?version=draft"
+    assert agent.version == "draft"
+
+
+def test_versions_are_cached_separately():
+    transport = FakeTransport(ok(agent_payload()))
+    mowa = make_client(transport)
+    mowa.get_agent("support")
+    mowa.get_agent("support", version="draft")
+    mowa.get_agent("support", version=3)
+    assert mowa.get_agent("support", version=3).source == "cache"
+    assert len(transport.calls) == 3
+
+
+def test_invalid_version_raises_value_error():
+    mowa = make_client(FakeTransport(ok(agent_payload())))
+    with pytest.raises(ValueError):
+        mowa.get_agent("support", version="latest")
+    with pytest.raises(ValueError):
+        mowa.get_agent("support", version=True)
+
+
+def test_trace_attributes():
+    agent = make_client(FakeTransport(ok(agent_payload()))).get_agent("support")
+    assert agent.trace_attributes() == {"mowa.agent": "support", "mowa.version": "v3"}
+    fallback = make_client(FakeTransport(OSError("down"))).get_agent("support", fallback=FALLBACK)
+    assert fallback.trace_attributes() == {"mowa.agent": "support", "mowa.version": "fallback"}
+
+
+def test_agent_is_frozen():
+    agent = make_client(FakeTransport(ok(agent_payload()))).get_agent("support")
+    with pytest.raises(Exception):
+        agent.model = "other"
+
+
+def test_prefetch_warms_cache_and_ignores_failures():
+    def transport(url, headers, timeout):
+        if "/broken/" in url:
+            raise OSError("down")
+        return ok(agent_payload())
+
+    mowa = make_client(transport)
+    mowa.prefetch(["support", "billing", "broken"])
+    assert mowa.get_agent("support").source == "cache"
+    assert mowa.get_agent("billing").source == "cache"
+
+
+def test_clear_cache():
+    transport = FakeTransport(ok(agent_payload()))
+    mowa = make_client(transport)
+    mowa.get_agent("support")
+    mowa.clear_cache()
+    assert mowa.get_agent("support").source == "network"
+    assert len(transport.calls) == 2
+
+
+@pytest.fixture
+def local_server():
+    seen = []
+
+    class Handler(BaseHTTPRequestHandler):
+        def do_GET(self):
+            seen.append({"path": self.path, "headers": dict(self.headers.items())})
+            if self.headers.get("If-None-Match") == '"etag-1"':
+                self.send_response(304)
+                self.send_header("ETag", '"etag-1"')
+                self.end_headers()
+                return
+            if self.path.startswith("/api/v1/agents/missing/"):
+                body = json.dumps({"error": {"code": "not_found", "message": "No agent."}}).encode()
+                self.send_response(404)
+            else:
+                body = json.dumps(agent_payload()).encode()
+                self.send_response(200)
+                self.send_header("ETag", '"etag-1"')
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def log_message(self, *args):
+            pass
+
+    with socket.socket() as probe:
+        probe.bind(("127.0.0.1", 0))
+        port = probe.getsockname()[1]
+    server = HTTPServer(("127.0.0.1", port), Handler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    yield f"http://127.0.0.1:{port}", seen
+    server.shutdown()
+    server.server_close()
+
+
+def test_urllib_transport_against_local_server(local_server):
+    base_url, seen = local_server
+    clock = FakeClock()
+    mowa = Mowa(api_key="mk_test", base_url=base_url, transport=urllib_transport, clock=clock)
+    assert mowa.get_agent("support").source == "network"
+    clock.advance(61)
+    assert mowa.get_agent("support").source == "stale"
+    assert mowa.wait_for_refresh()
+    assert mowa.get_agent("support").source == "cache"
+    assert seen[1]["headers"].get("If-None-Match") == '"etag-1"'
+    assert seen[0]["headers"].get("X-Mowa-Sdk") == "py/0.1.0"
+    with pytest.raises(MowaError) as raised:
+        mowa.get_agent("missing")
+    assert raised.value.status == 404
+    assert raised.value.code == "not_found"
+
+
+def test_default_transport_against_local_server(local_server):
+    base_url, seen = local_server
+    clock = FakeClock()
+    mowa = Mowa(api_key="mk_test", base_url=base_url, clock=clock)
+    assert mowa.get_agent("support").source == "network"
+    clock.advance(61)
+    mowa.get_agent("support")
+    assert mowa.wait_for_refresh()
+    assert mowa.get_agent("support").source == "cache"
+    assert len(seen) == 2