mowa 0.1.0__py3-none-any.whl

mowa/__init__.py

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

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,6 @@
+mowa/__init__.py,sha256=zMh_QIRsScpg5manL4LEOGAufPNxPHgDfhQ92pnWNlc,137
+mowa/client.py,sha256=kxMXat_HsiwcZ3V4jPGqzU7iIMEYnWjsZNyNLNONVrM,12007
+mowa/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mowa-0.1.0.dist-info/METADATA,sha256=qiii4VXDyJfgl_AGu89hvtt2-XP9P6TkpsnOXJpWbZs,2413
+mowa-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+mowa-0.1.0.dist-info/RECORD,,

mowa-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any