modelrelay 0.2.0__py3-none-any.whl

modelrelay/__init__.py

@@ -0,0 +1,72 @@
+"""modelrelay: one small API to call LLMs anywhere.
+
+    from modelrelay import llm
+    print(llm.chat("Hello!", model="gpt-4o").text)
+"""
+
+from ._util import enable_logging, require
+from .auth import BearerAuth, ClientCredentials, StaticToken, TokenProvider
+from .config import Config
+from .errors import (
+    AuthError,
+    ConfigError,
+    InvalidToolCall,
+    JobFailed,
+    JobTimeout,
+    ModelRelayError,
+    PayloadTooLarge,
+    ProviderError,
+    StreamInterrupted,
+    UnexpectedResponse,
+)
+from .relay import Relay
+from .transports import JobState, JobsTransport, OpenAICompatible, Transport
+from .types import ChatRequest, Event, Image, Response, ToolCall, Usage
+
+__version__ = "0.2.0"
+
+
+class _DefaultRelay:
+    """`llm`: a Relay created on first use from the default config."""
+
+    _relay: Relay | None = None
+
+    def __getattr__(self, name):
+        if _DefaultRelay._relay is None:
+            _DefaultRelay._relay = Relay()
+        return getattr(_DefaultRelay._relay, name)
+
+
+llm = _DefaultRelay()
+
+__all__ = [
+    "AuthError",
+    "BearerAuth",
+    "ChatRequest",
+    "ClientCredentials",
+    "Config",
+    "ConfigError",
+    "Event",
+    "Image",
+    "InvalidToolCall",
+    "JobFailed",
+    "JobState",
+    "JobTimeout",
+    "JobsTransport",
+    "ModelRelayError",
+    "OpenAICompatible",
+    "PayloadTooLarge",
+    "ProviderError",
+    "Relay",
+    "Response",
+    "StaticToken",
+    "StreamInterrupted",
+    "TokenProvider",
+    "ToolCall",
+    "Transport",
+    "UnexpectedResponse",
+    "Usage",
+    "enable_logging",
+    "llm",
+    "require",
+]

modelrelay/_util.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import importlib.util
+import logging
+import os
+import sys
+from importlib import import_module
+from importlib.metadata import entry_points
+from pathlib import Path
+
+from .errors import ConfigError, UnexpectedResponse
+
+log = logging.getLogger("modelrelay")
+log.addHandler(logging.NullHandler())  # silent unless the app or MODELRELAY_LOG turns logs on; errors still raise
+_MISSING = object()
+
+
+def dig(obj, path: str, default=None):
+    """dig({"a": {"b": [1, 2]}}, "a.b.1") -> 2. Returns `default` when the path is missing."""
+    for key in path.split("."):
+        if isinstance(obj, dict) and key in obj:
+            obj = obj[key]
+        elif isinstance(obj, list) and key.isdigit() and int(key) < len(obj):
+            obj = obj[int(key)]
+        else:
+            return default
+    return obj
+
+
+def require(obj, path: str, what: str = ""):
+    """Like dig(), but raises UnexpectedResponse (with the full payload) when the path is missing."""
+    value = dig(obj, path, _MISSING)
+    if value is _MISSING or value is None:
+        label = f" ({what})" if what else ""
+        raise UnexpectedResponse(f"Field '{path}'{label} not found in response", body=obj)
+    return value
+
+
+def adapters_dir() -> Path:
+    """~/.modelrelay/adapters: single-file adapters that live on this machine only."""
+    from .config import config_dir
+    return config_dir() / "adapters"
+
+
+def load_object(name: str, group: str, builtins: dict):
+    """Resolves, in this order:
+    - a builtin name ("openai_compatible", "jobs", ...);
+    - "module:Class", where module is a file in ~/.modelrelay/adapters/ (module.py);
+    - "package.module:Class" importable from the environment;
+    - an entry point registered under `group` by an installed package.
+    """
+    if name in builtins:
+        return builtins[name]
+    if ":" in name:
+        module, attr = name.split(":", 1)
+        local = adapters_dir() / f"{module}.py"
+        mod = _load_file(local, module) if "." not in module and local.is_file() else import_module(module)
+        if not hasattr(mod, attr):
+            raise ConfigError(f"'{attr}' not found in {getattr(mod, '__file__', module)}")
+        return getattr(mod, attr)
+    for ep in entry_points(group=group):
+        if ep.name == name:
+            return ep.load()
+    raise ConfigError(
+        f"Unknown '{name}' for {group}. Use one of {sorted(builtins)}, 'file:Class' for a file in "
+        f"{adapters_dir()}, a 'package.module:Class' path, or an entry point in the '{group}' group."
+    )
+
+
+def _load_file(path: Path, module: str):
+    key = f"modelrelay_adapters.{module}"
+    if key in sys.modules:
+        return sys.modules[key]
+    spec = importlib.util.spec_from_file_location(key, path)
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules[key] = mod
+    try:
+        spec.loader.exec_module(mod)
+    except Exception:
+        del sys.modules[key]
+        raise
+    log.debug("loaded adapter %s", path)
+    return mod
+
+
+def enable_logging(level: str | int = "DEBUG") -> None:
+    """Prints modelrelay's logs to stderr. Same as setting MODELRELAY_LOG=debug."""
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s"))
+    log.addHandler(handler)
+    log.setLevel(level.upper() if isinstance(level, str) else level)
+
+
+if os.environ.get("MODELRELAY_LOG"):
+    enable_logging(os.environ["MODELRELAY_LOG"])

modelrelay/auth.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import os
+import threading
+import time
+from typing import Callable
+
+import httpx
+
+from ._util import dig, log
+from .errors import AuthError, ConfigError
+
+
+class TokenProvider:
+    """Gives out a valid bearer token. `refreshable` providers get a second chance on 401/403."""
+
+    refreshable = False
+
+    def get_token(self) -> str:
+        raise NotImplementedError
+
+    def invalidate(self) -> None:
+        pass
+
+
+class StaticToken(TokenProvider):
+    """A fixed API key. It never expires."""
+
+    def __init__(self, token: str | None, missing_hint: str = ""):
+        self._token = token
+        self._missing_hint = missing_hint
+
+    def get_token(self) -> str:
+        if not self._token:
+            raise ConfigError(f"No API key configured. {self._missing_hint}".strip())
+        return self._token
+
+
+class ClientCredentials(TokenProvider):
+    """Exchanges a client id + secret for a token that lasts `ttl_minutes`.
+
+    The token is renewed `refresh_margin_seconds` before it expires. The endpoint's
+    field names are configurable; subclass and override `fetch_token` when the
+    exchange is more unusual than that.
+    """
+
+    refreshable = True
+
+    def __init__(
+        self,
+        http: httpx.Client,
+        *,
+        token_url: str,
+        client_id: str | None,
+        client_secret: str | None,
+        ttl_minutes: float = 30,
+        refresh_margin_seconds: float = 120,
+        request_format: str = "json",
+        id_field: str = "client_id",
+        secret_field: str = "client_secret",
+        token_field: str = "access_token",
+        extra_fields: dict | None = None,
+        clock: Callable[[], float] = time.monotonic,
+    ):
+        if request_format not in ("json", "form"):
+            raise ConfigError("auth_options.request_format must be 'json' or 'form'")
+        self.http = http
+        self.token_url = token_url
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.ttl = ttl_minutes * 60
+        self.margin = min(refresh_margin_seconds, self.ttl / 2)
+        self.request_format = request_format
+        self.id_field = id_field
+        self.secret_field = secret_field
+        self.token_field = token_field
+        self.extra_fields = extra_fields or {}
+        self._clock = clock
+        self._lock = threading.Lock()
+        self._token: str | None = None
+        self._expires_at = 0.0
+
+    def get_token(self) -> str:
+        with self._lock:
+            if self._token is None or self._clock() >= self._expires_at - self.margin:
+                log.info("requesting a new token from %s", self.token_url)
+                self._token = self.fetch_token()
+                self._expires_at = self._clock() + self.ttl
+            return self._token
+
+    def invalidate(self) -> None:
+        with self._lock:
+            self._token = None
+
+    def fetch_token(self) -> str:
+        if not self.client_id or not self.client_secret:
+            raise ConfigError(
+                "client_credentials needs a client id and secret: set auth_options.client_id and "
+                "auth_options.client_secret in the config file (or $MODELRELAY_CLIENT_ID / $MODELRELAY_CLIENT_SECRET)."
+            )
+        body = {self.id_field: self.client_id, self.secret_field: self.client_secret, **self.extra_fields}
+        kwargs = {"json": body} if self.request_format == "json" else {"data": body}
+        try:
+            r = self.http.post(self.token_url, **kwargs)
+        except httpx.HTTPError as e:
+            raise AuthError(f"Could not reach the token endpoint: {type(e).__name__}: {e}", url=self.token_url) from e
+        if r.status_code >= 400:
+            raise AuthError(f"Token endpoint answered HTTP {r.status_code}: {r.text[:500]}",
+                            url=self.token_url, status=r.status_code)
+        try:
+            data = r.json()
+        except ValueError as e:
+            raise AuthError(f"Token endpoint did not return JSON: {r.text[:500]!r}", url=self.token_url) from e
+        token = dig(data, self.token_field)
+        if not token:
+            fields = sorted(data) if isinstance(data, dict) else type(data).__name__
+            raise AuthError(f"Token endpoint response has no '{self.token_field}' field (top-level fields: {fields})",
+                            url=self.token_url)
+        return token
+
+
+class BearerAuth(httpx.Auth):
+    """Adds the token to every request; on 401/403 renews it once and retries."""
+
+    def __init__(self, provider: TokenProvider):
+        self.provider = provider
+
+    def auth_flow(self, request):
+        request.headers["Authorization"] = f"Bearer {self.provider.get_token()}"
+        response = yield request
+        if response.status_code in (401, 403) and self.provider.refreshable:
+            log.info("HTTP %s on %s %s: renewing the token and retrying once",
+                     response.status_code, request.method, request.url)
+            self.provider.invalidate()
+            request.headers["Authorization"] = f"Bearer {self.provider.get_token()}"
+            yield request
+
+
+BUILTIN_AUTH = {"static": StaticToken, "client_credentials": ClientCredentials}
+
+
+def build_token_provider(config, http: httpx.Client) -> TokenProvider:
+    from ._util import load_object
+
+    options = dict(config.auth_options)
+    if config.auth == "static":
+        key = config.api_key or os.environ.get(config.api_key_env)
+        where = config.source or "built in code"
+        return StaticToken(key, missing_hint=f"Set `api_key`, or the {config.api_key_env} environment variable. Config: {where}")
+    if config.auth == "client_credentials":
+        if "token_url" not in options:
+            raise ConfigError("auth_options.token_url is required for client_credentials.")
+        # Values in the file win; the environment variables are only a fallback.
+        id_env = options.pop("client_id_env", "MODELRELAY_CLIENT_ID")
+        secret_env = options.pop("client_secret_env", "MODELRELAY_CLIENT_SECRET")
+        return ClientCredentials(
+            http,
+            client_id=options.pop("client_id", None) or os.environ.get(id_env),
+            client_secret=options.pop("client_secret", None) or os.environ.get(secret_env),
+            **options,
+        )
+    cls = load_object(config.auth, "modelrelay.auth", BUILTIN_AUTH)
+    return cls(http, **options)

modelrelay/cli.py

@@ -0,0 +1,200 @@
+"""Command line: `modelrelay init` creates a config, `modelrelay show` prints the one in use,
+`modelrelay serve` exposes it as a local OpenAI-compatible endpoint, with a setup screen at /."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from importlib.resources import files
+
+from ._util import adapters_dir
+from .config import DEFAULT_PROFILE, Config, config_dir
+from .errors import ModelRelayError
+
+TEMPLATES = {
+    "openrouter": '''\
+# modelrelay config: OpenRouter
+base_url = "https://openrouter.ai/api/v1"
+api_key_env = "OPENROUTER_API_KEY"   # or put the key here: api_key = "sk-or-..."
+
+# Roles: apps ask for a role, this file picks the model.
+#   "text"  reads: conversation, and the images the app sends (pick a model with image input if the app sends images)
+#   "image" generates images (a model with image output)
+# A role can carry default params, e.g. how hard the model thinks:
+#   "text" = { model = "provider/model", reasoning_effort = "medium" }   # minimal | low | medium | high
+[models]   # name used in code = name the provider expects
+"text" = "google/gemini-2.5-flash"               # reads (text + images)
+"image" = "google/gemini-2.5-flash-image"        # generates images
+"gpt-4o-mini" = "openai/gpt-4o-mini"
+"gemini-2.5-flash" = "google/gemini-2.5-flash"
+"gemini-2.5-flash-image" = "google/gemini-2.5-flash-image"
+
+# Per-app models (optional). Provider and credentials above are shared by every app; an app
+# section only lists the names it wants resolved differently. Apps say who they are with the
+# X-Modelrelay-App header (modelrelay serve) or Relay(app="..."). Check with: modelrelay show --app <app>
+# [apps.wotan.models]
+# "text" = { model = "anthropic/claude-opus-5-5", reasoning_effort = "high" }
+# [apps.sagadeck.models]
+# "image" = "google/gemini-3-pro-image"
+''',
+    "openai": '''\
+# modelrelay config: OpenAI
+base_url = "https://api.openai.com/v1"
+api_key_env = "OPENAI_API_KEY"   # or put the key here: api_key = "sk-..."
+
+# Roles: apps ask for a role, this file picks the model.
+#   "text"  reads: conversation, and the images the app sends (pick a model with image input if the app sends images)
+#   "image" generates images (a model with image output)
+# A role can carry default params, e.g. how hard the model thinks:
+#   "text" = { model = "provider/model", reasoning_effort = "medium" }   # minimal | low | medium | high
+[models]
+"text" = "gpt-4o"            # reads (text + images)
+
+# Per-app models (optional). Provider and credentials above are shared by every app; an app
+# section only lists the names it wants resolved differently. Apps say who they are with the
+# X-Modelrelay-App header (modelrelay serve) or Relay(app="..."). Check with: modelrelay show --app <app>
+# [apps.wotan.models]
+# "text" = { model = "anthropic/claude-opus-5-5", reasoning_effort = "high" }
+# [apps.sagadeck.models]
+# "image" = "google/gemini-3-pro-image"
+''',
+    "gateway": '''\
+# modelrelay config: a gateway with a job API, an OpenAI-compatible proxy and expiring tokens.
+# One file uses both paths with the same token. Fill in the values, then run: modelrelay show
+# The job API adapter is adapters/gateway.py, next to this file.
+base_url = "https://gateway.example.com/v1"
+
+transport = "gateway:GatewayJobs"        # chat(): the job API (adapters/gateway.py, class GatewayJobs)
+stream_transport = "openai_compatible"   # stream(): the proxy, text as it is generated
+                                         # if the proxy goes away: stream_transport = "gateway:GatewayJobs"
+tools_mode = "native"                    # or "emulated"
+max_payload_mb = 20
+# ca_bundle = "C:/certs/company-ca.pem"  # or: verify_ssl = false
+
+auth = "client_credentials"
+[auth_options]
+token_url = "https://identity.example.com/token"
+token_field = "access_token"             # dotted path in the token response
+ttl_minutes = 30
+client_id = ""                           # this file stays in your user folder; `modelrelay show` masks these
+client_secret = ""
+
+# Roles: apps ask for a role, this file picks the model.
+#   "text"  reads: conversation, and the images the app sends (pick a model with image input if the app sends images)
+#   "image" generates images (a model with image output)
+# A role can carry default params, e.g. how hard the model thinks:
+#   "text" = { model = "provider/model", reasoning_effort = "medium" }   # minimal | low | medium | high
+[models]
+# "gpt-4o" = "region;gpt-4o"
+# "text" = "region;gpt-4o"   # reads (text + images)
+
+# Per-app models (optional). Provider and credentials above are shared by every app; an app
+# section only lists the names it wants resolved differently. Apps say who they are with the
+# X-Modelrelay-App header (modelrelay serve) or Relay(app="..."). Check with: modelrelay show --app <app>
+# [apps.wotan.models]
+# "text" = { model = "anthropic/claude-opus-5-5", reasoning_effort = "high" }
+# [apps.sagadeck.models]
+# "image" = "google/gemini-3-pro-image"
+
+[transports."gateway:GatewayJobs"]
+base_url = "https://gateway.example.com/jobs-api"
+poll_interval = 0.5
+poll_max_interval = 5
+max_wait_seconds = 900
+
+[transports.openai_compatible]
+base_url = "https://proxy.example.com/v1"
+''',
+}
+
+# Extra files created next to a template's config (path relative to ~/.modelrelay).
+TEMPLATE_FILES = {"gateway": {"adapters/gateway.py": "gateway_adapter.py"}}
+
+SECRET_KEYS = {"api_key", "client_secret", "client_id"}
+
+
+def init(profile: str, template: str) -> int:
+    path = config_dir() / f"{profile}.toml"
+    if path.exists():
+        print(f"{path} already exists; nothing changed. Edit it, or delete it and run init again.")
+        return 1
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(TEMPLATES[template], encoding="utf-8")
+    print(f"Created {path} from the '{template}' template.")
+    for relative, resource in TEMPLATE_FILES.get(template, {}).items():
+        extra = config_dir() / relative
+        if extra.exists():
+            print(f"Kept the existing {extra}.")
+            continue
+        extra.parent.mkdir(parents=True, exist_ok=True)
+        extra.write_text((files("modelrelay") / "templates" / resource).read_text(encoding="utf-8"), encoding="utf-8")
+        print(f"Created {extra}.")
+    print("Edit the file(s), then check with: modelrelay show"
+          + (f" --profile {profile}" if profile != DEFAULT_PROFILE else ""))
+    return 0
+
+
+def show(profile: str | None, app: str | None = None) -> int:
+    config = Config.load(profile=profile)
+    print(f"config file: {config.source}")
+    print(f"adapters folder: {adapters_dir()}")
+    if app:
+        own = (config.apps.get(app) or {}).get("models", {})
+        print(f"models for app '{app}'" + ("" if app in config.apps else f" (no [apps.{app}] section: using [models])") + ":")
+        for name in config.entries_for(app):
+            target, params = config.route(name, app)
+            provider = config.provider_for(name, app)
+            params = {**({"provider": provider} if provider and config.providers else {}), **params}
+            extra = "  (" + ", ".join(f"{k}={v}" for k, v in params.items()) + ")" if params else ""
+            print(f"  {name} = {target}{extra}" + ("   <- [apps.%s.models]" % app if name in own else ""))
+        return 0
+    for name, value in vars(config).items():
+        if name == "source":
+            continue
+        print(f"{name} = {_mask(name, value)}")
+    return 0
+
+
+def _mask(name, value):
+    if isinstance(value, dict):
+        return {k: _mask(k, v) for k, v in value.items()}
+    if name in SECRET_KEYS and value:
+        return "***"
+    return value
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="modelrelay")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_init = sub.add_parser("init", help=f"create {config_dir()}/<profile>.toml")
+    p_init.add_argument("--profile", default=DEFAULT_PROFILE)
+    p_init.add_argument("--template", choices=sorted(TEMPLATES), default="openrouter")
+
+    p_show = sub.add_parser("show", help="print the config in use (secrets masked)")
+    p_show.add_argument("--profile")
+    p_show.add_argument("--app", help="only the models this app gets ([models] + [apps.<app>.models])")
+
+    p_serve = sub.add_parser("serve", help="local OpenAI-compatible endpoint (/v1/chat/completions) using the config")
+    p_serve.add_argument("--profile")
+    p_serve.add_argument("--host", default="127.0.0.1")
+    p_serve.add_argument("--port", type=int, default=8765)
+    p_serve.add_argument("--api-key", help="require this bearer token (default: $MODELRELAY_SERVE_KEY, else none)")
+    p_serve.add_argument("--public-url", help="address of the setup screen behind a login proxy, e.g. https://example.com/ia/")
+
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "init":
+            return init(args.profile, args.template)
+        if args.command == "serve":
+            from .server import serve
+            serve(host=args.host, port=args.port, api_key=args.api_key, profile=args.profile, public_url=args.public_url)
+            return 0
+        return show(args.profile, args.app)
+    except ModelRelayError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())