tollfree 0.1.0__tar.gz

tollfree-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.env
+.venv/
+__pycache__/
+
+# build artifacts
+dist/
+build/
+*.egg-info/
+
+# node
+node_modules/

tollfree-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.5
+Name: tollfree
+Version: 0.1.0
+Summary: One chat() call over free-tier LLM providers, with automatic model + provider failover.
+Project-URL: Homepage, https://github.com/luarss/free-llm-router
+Project-URL: Source, https://github.com/luarss/free-llm-router
+Author-email: luarss <song.luar@a5x.ai>
+License: MIT
+Keywords: failover,free-tier,groq,llm,openai,router
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: requests>=2.31
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# tollfree (Python)
+
+One `chat()` call over free-tier LLM providers, with automatic failover:
+**rotate a provider's models first, then fall over to the next provider.**
+
+Keys are read straight from `.env`. Missing keys are skipped automatically — you
+only need one to start.
+
+## Install
+
+```bash
+pip install tollfree     # or: uv add tollfree
+```
+
+## Use
+
+```python
+from tollfree import chat
+
+reply = chat("Explain the CAP theorem in two sentences.")
+
+# with metadata about which provider/model actually answered:
+reply, meta = chat("hi", return_meta=True, temperature=0.2)
+# meta -> {'provider': 'google', 'model': 'gemini-3.6-flash'}
+```
+
+CLI:
+
+```bash
+tollfree "your prompt here"   # chat
+tollfree probe                # verify keys + limits, spends no completion tokens
+```
+
+## Failover logic
+
+```
+for provider in PROVIDERS:          # priority order (providers.json)
+  for model in provider.models:     # default = first
+    try  -> return on success
+    401/403             -> skip whole provider (bad key)
+    429/404/5xx/timeout -> next model, then next provider
+raise AllProvidersFailed            # only when everything is exhausted
+```
+
+## Configuration
+
+Set keys in `.env` (or the environment):
+
+```
+GROQ_API_KEY=
+CEREBRAS_API_KEY=
+GEMINI_API_KEY=
+OPENROUTER_API_KEY=
+MISTRAL_API_KEY=
+ZAI_API_KEY=
+```
+
+The provider/model registry is `providers.json`, kept in sync from the
+[central repo](https://github.com/luarss/free-llm-router) which is the source of
+truth for both the Python and npm packages.

tollfree-0.1.0/README.md

@@ -0,0 +1,60 @@
+# tollfree (Python)
+
+One `chat()` call over free-tier LLM providers, with automatic failover:
+**rotate a provider's models first, then fall over to the next provider.**
+
+Keys are read straight from `.env`. Missing keys are skipped automatically — you
+only need one to start.
+
+## Install
+
+```bash
+pip install tollfree     # or: uv add tollfree
+```
+
+## Use
+
+```python
+from tollfree import chat
+
+reply = chat("Explain the CAP theorem in two sentences.")
+
+# with metadata about which provider/model actually answered:
+reply, meta = chat("hi", return_meta=True, temperature=0.2)
+# meta -> {'provider': 'google', 'model': 'gemini-3.6-flash'}
+```
+
+CLI:
+
+```bash
+tollfree "your prompt here"   # chat
+tollfree probe                # verify keys + limits, spends no completion tokens
+```
+
+## Failover logic
+
+```
+for provider in PROVIDERS:          # priority order (providers.json)
+  for model in provider.models:     # default = first
+    try  -> return on success
+    401/403             -> skip whole provider (bad key)
+    429/404/5xx/timeout -> next model, then next provider
+raise AllProvidersFailed            # only when everything is exhausted
+```
+
+## Configuration
+
+Set keys in `.env` (or the environment):
+
+```
+GROQ_API_KEY=
+CEREBRAS_API_KEY=
+GEMINI_API_KEY=
+OPENROUTER_API_KEY=
+MISTRAL_API_KEY=
+ZAI_API_KEY=
+```
+
+The provider/model registry is `providers.json`, kept in sync from the
+[central repo](https://github.com/luarss/free-llm-router) which is the source of
+truth for both the Python and npm packages.

tollfree-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tollfree"
+version = "0.1.0"
+description = "One chat() call over free-tier LLM providers, with automatic model + provider failover."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "luarss", email = "song.luar@a5x.ai" }]
+keywords = ["llm", "openai", "groq", "failover", "router", "free-tier"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "requests>=2.31",
+    "python-dotenv>=1.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8.0"]
+
+[project.urls]
+Homepage = "https://github.com/luarss/free-llm-router"
+Source = "https://github.com/luarss/free-llm-router"
+
+[project.scripts]
+tollfree = "tollfree.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tollfree"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/tollfree/providers.json" = "tollfree/providers.json"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/tollfree", "README.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

tollfree-0.1.0/src/tollfree/__init__.py

@@ -0,0 +1,9 @@
+"""tollfree — one chat() call over free-tier LLM providers, with automatic
+model + provider failover. See https://github.com/luarss/free-llm-router."""
+
+from ._registry import PROVIDERS
+from .probe import probe, probe_all
+from .router import AllProvidersFailed, chat
+
+__all__ = ["chat", "probe", "probe_all", "PROVIDERS", "AllProvidersFailed"]
+__version__ = "0.1.0"

tollfree-0.1.0/src/tollfree/_registry.py

@@ -0,0 +1,17 @@
+"""Load the canonical provider registry bundled with the package.
+
+The registry lives in providers.json (kept in sync from the repo root by
+scripts/sync-providers). Loading it here keeps a single source of truth.
+"""
+
+import json
+from importlib.resources import files
+
+
+def load_providers():
+    """Return the provider list from the bundled providers.json."""
+    raw = files(__package__).joinpath("providers.json").read_text(encoding="utf-8")
+    return json.loads(raw)["providers"]
+
+
+PROVIDERS = load_providers()

tollfree-0.1.0/src/tollfree/cli.py

@@ -0,0 +1,23 @@
+"""Console entry point: `tollfree "prompt"` to chat, `tollfree probe` to check keys."""
+
+import sys
+
+from .probe import probe_all
+from .router import chat
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+
+    if argv and argv[0] == "probe":
+        probe_all()
+        return
+
+    q = " ".join(argv) or "Say hello in one short sentence."
+    answer, meta = chat(q, return_meta=True, verbose=True)
+    print(f"\n--- {meta['provider']} / {meta['model']} ---")
+    print(answer)
+
+
+if __name__ == "__main__":
+    main()

tollfree-0.1.0/src/tollfree/probe.py

@@ -0,0 +1,88 @@
+"""
+Probe providers WITHOUT spending completion quota.
+
+For each provider that has a key in .env, this:
+  - GET /models          -> verifies the key + auth, lists available models
+                            (free; does not consume chat/token quota)
+  - prints any rate-limit headers the provider returns (real remaining quota)
+  - for OpenRouter, also GET /key for credit/limit/usage
+"""
+
+import os
+
+import requests
+from dotenv import load_dotenv
+
+from ._registry import PROVIDERS
+
+load_dotenv()
+
+# Header names providers use to advertise limits/quota. We match loosely.
+_LIMIT_HINTS = ("ratelimit", "rate-limit", "retry-after", "x-request", "quota")
+
+_TIMEOUT = 20
+
+
+def _limit_headers(headers):
+    out = {}
+    for k, v in headers.items():
+        lk = k.lower()
+        if any(h in lk for h in _LIMIT_HINTS):
+            out[k] = v
+    return out
+
+
+def probe(provider):
+    """Probe a single provider dict; prints a status line (and any limit headers)."""
+    key = os.getenv(provider["key_env"])
+    name = provider["name"]
+    if not key:
+        print(f"— {name:12s} SKIP  (no {provider['key_env']} in .env)")
+        return
+
+    try:
+        r = requests.get(
+            f"{provider['base_url']}/models",
+            headers={"Authorization": f"Bearer {key}"},
+            timeout=_TIMEOUT,
+        )
+    except requests.RequestException as e:
+        print(f"✘ {name:12s} NET   ({e})")
+        return
+
+    if r.status_code == 200:
+        try:
+            models = r.json().get("data", [])
+            n = len(models)
+        except ValueError:
+            n = "?"
+        print(f"✔ {name:12s} OK    key valid, {n} models visible")
+    elif r.status_code in (401, 403):
+        print(f"✘ {name:12s} AUTH  HTTP {r.status_code} — bad/expired key")
+    else:
+        print(f"⚠ {name:12s} HTTP {r.status_code} — {r.text[:80]}")
+
+    for hk, hv in _limit_headers(r.headers).items():
+        print(f"      · {hk}: {hv}")
+
+    # OpenRouter exposes exact limit/usage/credit for free.
+    if name == "openrouter" and r.status_code == 200:
+        try:
+            kr = requests.get(
+                "https://openrouter.ai/api/v1/key",
+                headers={"Authorization": f"Bearer {key}"},
+                timeout=_TIMEOUT,
+            ).json().get("data", {})
+            print(
+                f"      · usage=${kr.get('usage')} limit=${kr.get('limit')} "
+                f"free_tier={kr.get('is_free_tier')}"
+            )
+        except requests.RequestException:
+            pass
+
+
+def probe_all():
+    """Probe every provider in the registry."""
+    print("Probing providers (no completion tokens spent)\n")
+    for p in PROVIDERS:
+        probe(p)

tollfree-0.1.0/src/tollfree/providers.json

@@ -0,0 +1,60 @@
+{
+  "_comment": "Canonical provider registry — single source of truth for both the PyPI and npm packages. Priority order matters (top = tried first). Every provider speaks the OpenAI-compatible /chat/completions API, so the only per-provider data is base_url, the env var holding the key, and the model list (first model = default). To add a provider: add a block and set its key env var. Run scripts/sync-providers to copy this into both packages.",
+  "providers": [
+    {
+      "name": "groq",
+      "base_url": "https://api.groq.com/openai/v1",
+      "key_env": "GROQ_API_KEY",
+      "models": [
+        "llama-3.3-70b-versatile",
+        "llama-3.1-8b-instant",
+        "qwen/qwen3-32b"
+      ]
+    },
+    {
+      "name": "cerebras",
+      "base_url": "https://api.cerebras.ai/v1",
+      "key_env": "CEREBRAS_API_KEY",
+      "models": [
+        "llama-3.3-70b",
+        "llama3.1-8b",
+        "qwen-3-32b"
+      ]
+    },
+    {
+      "name": "google",
+      "base_url": "https://generativelanguage.googleapis.com/v1beta/openai",
+      "key_env": "GEMINI_API_KEY",
+      "models": [
+        "gemini-3.6-flash",
+        "gemini-3.5-flash-lite"
+      ]
+    },
+    {
+      "name": "openrouter",
+      "base_url": "https://openrouter.ai/api/v1",
+      "key_env": "OPENROUTER_API_KEY",
+      "models": [
+        "meta-llama/llama-3.3-70b-instruct:free",
+        "google/gemini-2.0-flash-exp:free"
+      ]
+    },
+    {
+      "name": "mistral",
+      "base_url": "https://api.mistral.ai/v1",
+      "key_env": "MISTRAL_API_KEY",
+      "models": [
+        "mistral-small-latest",
+        "open-mistral-nemo"
+      ]
+    },
+    {
+      "name": "zai",
+      "base_url": "https://api.z.ai/api/paas/v4",
+      "key_env": "ZAI_API_KEY",
+      "models": [
+        "glm-4-flash"
+      ]
+    }
+  ]
+}

tollfree-0.1.0/src/tollfree/router.py

@@ -0,0 +1,115 @@
+"""
+tollfree router: one chat() call, automatic model + provider failover.
+
+Rotation order:
+  1. Within a provider, rotate through its models (default first).
+  2. When a provider's models are all exhausted, fall over to the next provider.
+
+Usage:
+    from tollfree import chat
+    reply = chat("Explain CAP theorem in two sentences.")
+    print(reply)
+
+    # or with full message history / options
+    reply, meta = chat(
+        messages=[{"role": "user", "content": "hi"}],
+        temperature=0.2,
+        return_meta=True,
+    )
+    print(meta)  # {'provider': 'groq', 'model': 'llama-3.3-70b-versatile'}
+"""
+
+import os
+
+import requests
+from dotenv import load_dotenv
+
+from ._registry import PROVIDERS
+
+load_dotenv()  # pulls keys from .env in cwd
+
+# HTTP statuses that mean "this key/provider is unusable — skip the whole provider"
+_SKIP_PROVIDER_STATUSES = {401, 403}
+# Any other >=400 is treated as retryable: try next model, then next provider.
+
+_TIMEOUT = 60  # seconds per request
+
+
+class AllProvidersFailed(Exception):
+    """Raised when every configured model on every provider failed."""
+
+
+class _SkipProvider(Exception):
+    pass
+
+
+class _TryNextModel(Exception):
+    pass
+
+
+def _call(provider, model, messages, **params):
+    """Single OpenAI-compatible request. Returns assistant text or raises."""
+    key = os.getenv(provider["key_env"])
+    if not key:
+        raise _SkipProvider(f"no key ({provider['key_env']}) in env")
+
+    resp = requests.post(
+        f"{provider['base_url']}/chat/completions",
+        headers={
+            "Authorization": f"Bearer {key}",
+            "Content-Type": "application/json",
+        },
+        json={"model": model, "messages": messages, **params},
+        timeout=_TIMEOUT,
+    )
+
+    if resp.status_code in _SKIP_PROVIDER_STATUSES:
+        raise _SkipProvider(f"HTTP {resp.status_code}: {resp.text[:200]}")
+    if resp.status_code >= 400:
+        # retryable at the model level (bad model name, rate limit, 5xx, ...)
+        raise _TryNextModel(f"HTTP {resp.status_code}: {resp.text[:200]}")
+
+    return resp.json()["choices"][0]["message"]["content"]
+
+
+def chat(prompt=None, messages=None, return_meta=False, verbose=False, **params):
+    """
+    Send a chat request, failing over across models then providers.
+
+    Pass either `prompt` (str) or `messages` (OpenAI-format list). Extra kwargs
+    (temperature, max_tokens, ...) are forwarded to the API verbatim.
+    """
+    if messages is None:
+        if prompt is None:
+            raise ValueError("provide either `prompt` or `messages`")
+        messages = [{"role": "user", "content": prompt}]
+
+    errors = []  # (provider, model, reason) for diagnostics
+
+    for provider in PROVIDERS:
+        for model in provider["models"]:
+            try:
+                text = _call(provider, model, messages, **params)
+                if verbose:
+                    print(f"[ok] {provider['name']} / {model}")
+                if return_meta:
+                    return text, {"provider": provider["name"], "model": model}
+                return text
+            except _SkipProvider as e:
+                if verbose:
+                    print(f"[skip provider] {provider['name']}: {e}")
+                errors.append((provider["name"], "*", str(e)))
+                break  # stop trying this provider's other models
+            except _TryNextModel as e:
+                if verbose:
+                    print(f"[next model] {provider['name']} / {model}: {e}")
+                errors.append((provider["name"], model, str(e)))
+                continue
+            except (requests.Timeout, requests.ConnectionError) as e:
+                if verbose:
+                    print(f"[network] {provider['name']} / {model}: {e}")
+                errors.append((provider["name"], model, f"network: {e}"))
+                continue
+
+    detail = "\n".join(f"  {p}/{m}: {r}" for p, m, r in errors) or "  (no keys found)"
+    raise AllProvidersFailed(f"All providers/models failed:\n{detail}")