ftouter 0.1.0__tar.gz

ftouter-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: ftouter
+Version: 0.1.0
+Summary: A resilient runtime layer for free/cheap-tier LLM APIs
+Author-email: Your Name <you@example.com>
+License-Expression: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests
+Requires-Dist: python-dotenv
+
+# ftouter
+
+A resilient runtime layer for free and cheap-tier LLM APIs.
+
+Free-tier LLM providers are unreliable in ways that break production apps silently: models get deprecated overnight, quotas zero out without warning, and providers add card requirements with no notice. `ftouter` sits between your app and multiple providers, automatically falling back to the next available model when one fails — so a single dead endpoint doesn't take down your whole app.
+
+## Features
+
+- **Automatic fallback** across multiple providers and models
+- **Cooldown handling** — a model that fails gets temporarily skipped instead of retried every call
+- **Clear failure reasons** — distinguishes rate limits, deprecated models, bad keys, and server errors instead of generic exceptions
+- **Zero config to start** — just add your API keys and call `.complete()`
+- Five ready-made routers for different use cases: `chat_models`, `general_models`, `reasoning_models`, `tool_call_models`, `vision_models`
+
+## Installation
+
+```bash
+pip install ftouter
+```
+
+## Quickstart
+
+1. Create a `.env` file in your project root with the API keys for the providers you want to use:
+
+```env
+GROQ_API_KEY=your_key_here
+OPENROUTER_API_KEY=your_key_here
+MISTRAL_API_KEY=your_key_here
+```
+
+You don't need all three — `ftouter` skips any provider whose key isn't set and falls through to the next one.
+
+2. Use it in your code:
+
+```python
+from ftouter import chat_models
+from dotenv import load_dotenv
+
+load_dotenv()
+
+result = chat_models.complete([
+    {"role": "user", "content": "Say hi in 5 words"}
+])
+
+print(result["choices"][0]["message"]["content"])
+```
+
+## Available routers
+
+| Router | Use case |
+|---|---|
+| `chat_models.complete()` | General-purpose conversational completions |
+| `general_models.complete()` | General-purpose tasks, pooled across all other routers |
+| `reasoning_models.complete()` | Tasks that benefit from reasoning-focused models |
+| `tool_call_models.complete()` | Completions that use function/tool calling |
+| `vision_models.complete()` | Completions that include image input |
+
+Each router tries a prioritized list of models across providers and automatically moves to the next one on failure.
+
+## Vision
+
+`vision_models.complete()` takes the same message format as the others — an image is just another block inside `content`, either an `https://` URL or a base64 `data:` URI:
+
+```python
+import base64
+from ftouter import vision_models
+from dotenv import load_dotenv
+
+load_dotenv()
+
+with open("example.jpg", "rb") as image_file:
+    image_data = base64.b64encode(image_file.read()).decode("utf-8")
+
+result = vision_models.complete([
+    {
+        "role": "user",
+        "content": [
+            {"type": "text", "text": "what's in this image?"},
+            {
+                "type": "image_url",
+                "image_url": {
+                    "url": f"data:image/jpeg;base64,{image_data}"
+                }
+            }
+        ]
+    }
+])
+print(result["choices"][0]["message"]["content"])
+```
+
+Vision draws from Groq, OpenRouter, and Mistral like the other routers, plus two vision-specific providers — add their keys to `.env` only if you want them in the fallback chain, `ftouter` skips them otherwise like any other missing key:
+
+```env
+GEMINI_API_KEY=your_key_here
+MOONDREAM_API_KEY=your_key_here
+```
+
+Note: base64 image support is confirmed for Groq and Gemini. OpenRouter should accept it (same spec, not independently verified here). Moondream's exact behavior with base64 input is unconfirmed — test it directly if you're relying on that provider.
+
+## How fallback works
+
+When you call `.complete()`, `ftouter`:
+
+1. Tries the first available (not-on-cooldown) model in its list
+2. If it fails, records *why* (rate limit, deprecated model, bad key, server error, etc.) and puts that model on a cooldown timer
+3. Moves to the next model and repeats
+4. Returns the first successful response
+5. Raises `RuntimeError` only if every model in the list is exhausted or on cooldown
+
+This means a single provider having a bad day doesn't crash your app — it just quietly routes around it.
+
+## Getting free API keys
+
+- **Groq** — [console.groq.com](https://console.groq.com)
+- **OpenRouter** — [openrouter.ai](https://openrouter.ai)
+- **Mistral** — [console.mistral.ai](https://console.mistral.ai)
+- **Gemini** (vision only) — [aistudio.google.com](https://aistudio.google.com)
+- **Moondream** (vision only) — [moondream.ai](https://moondream.ai)
+
+## Handling errors
+
+If every provider fails, `.complete()` raises a `RuntimeError`:
+
+```python
+try:
+    result = chat_models.complete([{"role": "user", "content": "Hello"}])
+    print(result["choices"][0]["message"]["content"])
+except RuntimeError as e:
+    print(f"All providers failed: {e}")
+```
+
+## Contributing
+
+Issues and pull requests are welcome. If you'd like to add support for another provider, open an issue first so the model list and provider config stay consistent.
+
+https://github.com/Irfan-gitt
+
+## License
+
+MIT

ftouter-0.1.0/README.md

@@ -0,0 +1,140 @@
+# ftouter
+
+A resilient runtime layer for free and cheap-tier LLM APIs.
+
+Free-tier LLM providers are unreliable in ways that break production apps silently: models get deprecated overnight, quotas zero out without warning, and providers add card requirements with no notice. `ftouter` sits between your app and multiple providers, automatically falling back to the next available model when one fails — so a single dead endpoint doesn't take down your whole app.
+
+## Features
+
+- **Automatic fallback** across multiple providers and models
+- **Cooldown handling** — a model that fails gets temporarily skipped instead of retried every call
+- **Clear failure reasons** — distinguishes rate limits, deprecated models, bad keys, and server errors instead of generic exceptions
+- **Zero config to start** — just add your API keys and call `.complete()`
+- Five ready-made routers for different use cases: `chat_models`, `general_models`, `reasoning_models`, `tool_call_models`, `vision_models`
+
+## Installation
+
+```bash
+pip install ftouter
+```
+
+## Quickstart
+
+1. Create a `.env` file in your project root with the API keys for the providers you want to use:
+
+```env
+GROQ_API_KEY=your_key_here
+OPENROUTER_API_KEY=your_key_here
+MISTRAL_API_KEY=your_key_here
+```
+
+You don't need all three — `ftouter` skips any provider whose key isn't set and falls through to the next one.
+
+2. Use it in your code:
+
+```python
+from ftouter import chat_models
+from dotenv import load_dotenv
+
+load_dotenv()
+
+result = chat_models.complete([
+    {"role": "user", "content": "Say hi in 5 words"}
+])
+
+print(result["choices"][0]["message"]["content"])
+```
+
+## Available routers
+
+| Router | Use case |
+|---|---|
+| `chat_models.complete()` | General-purpose conversational completions |
+| `general_models.complete()` | General-purpose tasks, pooled across all other routers |
+| `reasoning_models.complete()` | Tasks that benefit from reasoning-focused models |
+| `tool_call_models.complete()` | Completions that use function/tool calling |
+| `vision_models.complete()` | Completions that include image input |
+
+Each router tries a prioritized list of models across providers and automatically moves to the next one on failure.
+
+## Vision
+
+`vision_models.complete()` takes the same message format as the others — an image is just another block inside `content`, either an `https://` URL or a base64 `data:` URI:
+
+```python
+import base64
+from ftouter import vision_models
+from dotenv import load_dotenv
+
+load_dotenv()
+
+with open("example.jpg", "rb") as image_file:
+    image_data = base64.b64encode(image_file.read()).decode("utf-8")
+
+result = vision_models.complete([
+    {
+        "role": "user",
+        "content": [
+            {"type": "text", "text": "what's in this image?"},
+            {
+                "type": "image_url",
+                "image_url": {
+                    "url": f"data:image/jpeg;base64,{image_data}"
+                }
+            }
+        ]
+    }
+])
+print(result["choices"][0]["message"]["content"])
+```
+
+Vision draws from Groq, OpenRouter, and Mistral like the other routers, plus two vision-specific providers — add their keys to `.env` only if you want them in the fallback chain, `ftouter` skips them otherwise like any other missing key:
+
+```env
+GEMINI_API_KEY=your_key_here
+MOONDREAM_API_KEY=your_key_here
+```
+
+Note: base64 image support is confirmed for Groq and Gemini. OpenRouter should accept it (same spec, not independently verified here). Moondream's exact behavior with base64 input is unconfirmed — test it directly if you're relying on that provider.
+
+## How fallback works
+
+When you call `.complete()`, `ftouter`:
+
+1. Tries the first available (not-on-cooldown) model in its list
+2. If it fails, records *why* (rate limit, deprecated model, bad key, server error, etc.) and puts that model on a cooldown timer
+3. Moves to the next model and repeats
+4. Returns the first successful response
+5. Raises `RuntimeError` only if every model in the list is exhausted or on cooldown
+
+This means a single provider having a bad day doesn't crash your app — it just quietly routes around it.
+
+## Getting free API keys
+
+- **Groq** — [console.groq.com](https://console.groq.com)
+- **OpenRouter** — [openrouter.ai](https://openrouter.ai)
+- **Mistral** — [console.mistral.ai](https://console.mistral.ai)
+- **Gemini** (vision only) — [aistudio.google.com](https://aistudio.google.com)
+- **Moondream** (vision only) — [moondream.ai](https://moondream.ai)
+
+## Handling errors
+
+If every provider fails, `.complete()` raises a `RuntimeError`:
+
+```python
+try:
+    result = chat_models.complete([{"role": "user", "content": "Hello"}])
+    print(result["choices"][0]["message"]["content"])
+except RuntimeError as e:
+    print(f"All providers failed: {e}")
+```
+
+## Contributing
+
+Issues and pull requests are welcome. If you'd like to add support for another provider, open an issue first so the model list and provider config stay consistent.
+
+https://github.com/Irfan-gitt
+
+## License
+
+MIT

ftouter-0.1.0/ftouter/__init__.py

@@ -0,0 +1,13 @@
+from .providers import PROVIDER_INFO
+from . import chat_models, reasoning_models, tool_calling_models, general_models, vision_models
+from .router import check_available_models
+
+__all__ = [
+    "PROVIDER_INFO",
+    "chat_models",
+    "reasoning_models",
+    "tool_calling_models",
+    "general_models",
+    "vision_models",
+    "check_available_models",
+]

ftouter-0.1.0/ftouter/chat_models.py

@@ -0,0 +1,94 @@
+import os
+import time
+import requests
+
+from .providers import PROVIDER_INFO
+
+
+MODELS = [
+    ("groq", "qwen/qwen3.8-27b"),
+    ("groq", "openai/gpt-oss-120b"),
+    ("groq", "openai/gpt-oss-20b"),
+    ("groq", "allam-2-7b"),
+    ("openrouter", "google/gemma-4-26b-a4b-it:free"),
+    ("openrouter", "google/gemma-4-31b-it:free"),
+    ("openrouter", "nvidia/nemotron-3-super-120b-a12b:free"),
+    ("openrouter", "nvidia/nemotron-3.5-lightning:free"),
+    ("openrouter", "liquid/lfm-2.5-2.6b:free"),
+    ("mistral", "magistral-medium-latest"),
+]
+
+COOLDOWN_SECONDS = 30 * 60
+_cooldown = {}
+
+
+def _reason(status_code, message=""):
+    text = (message or "").lower()
+    if any(k in text for k in ("decommission", "deprecated", "no longer supported", "retired")):
+        return f"model deprecated by provider — {message}"
+    if status_code in (401, 403):
+        return "wrong or invalid API key"
+    if status_code == 404:
+        return "model not found — likely deprecated or renamed"
+    if status_code == 429:
+        return "rate limited — free quota exhausted"
+    if status_code == 400:
+        return f"bad request — {message}" if message else "bad request — check parameters or unsupported feature"
+    if status_code and status_code >= 500:
+        return "provider server error — temporary, try again later"
+    if message:
+        return message
+    return f"request failed (status {status_code})"
+
+
+def complete(messages, **kwargs):
+    now = time.time()
+    for provider, model_id in MODELS:
+        if _cooldown.get((provider, model_id), 0) > now:
+            continue
+
+        info = PROVIDER_INFO[provider]
+        key = os.getenv(info["env_key"])
+        if not key:
+            continue
+
+        try:
+            resp = requests.post(
+                f"{info['base_url']}/chat/completions",
+                headers={"Authorization": f"Bearer {key}"},
+                json={"model": model_id, "messages": messages, **kwargs},
+                timeout=30,
+            )
+        except requests.exceptions.Timeout:
+            print(f"{provider}/{model_id} failed: request timed out")
+            _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+            continue
+        except requests.exceptions.ConnectionError:
+            print(
+                f"{provider}/{model_id} failed: could not reach provider (connection error)")
+            _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+            continue
+        except requests.exceptions.RequestException as e:
+            print(f"{provider}/{model_id} failed: request error — {e}")
+            _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+            continue
+
+        try:
+            data = resp.json()
+        except ValueError:
+            print(
+                f"{provider}/{model_id} failed: response wasn't valid JSON (status {resp.status_code})")
+            _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+            continue
+
+        if resp.status_code == 200 and "choices" in data:
+            return data
+
+        err = data.get("error")
+        message = err.get("message") if isinstance(err, dict) else err
+        reason = _reason(resp.status_code, message)
+        print(f"{provider}/{model_id} failed: {reason}")
+        _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+
+    raise RuntimeError(
+        "all chat models are currently unavailable or on cooldown")

ftouter-0.1.0/ftouter/general_models.py

@@ -0,0 +1,84 @@
+import os
+import time
+import requests
+
+from .providers import PROVIDER_INFO
+from . import chat_models, reasoning_models, tool_calling_models
+
+# every model across all three categories, deduped, order preserved
+MODELS = list(dict.fromkeys(chat_models.MODELS +
+              reasoning_models.MODELS + tool_calling_models.MODELS))
+
+COOLDOWN_SECONDS = 30 * 60
+_cooldown = {}
+
+
+def _reason(status_code, message=""):
+    text = (message or "").lower()
+    if any(k in text for k in ("decommission", "deprecated", "no longer supported", "retired")):
+        return f"model deprecated by provider — {message}"
+    if status_code in (401, 403):
+        return "wrong or invalid API key"
+    if status_code == 404:
+        return "model not found — likely deprecated or renamed"
+    if status_code == 429:
+        return "rate limited — free quota exhausted"
+    if status_code == 400:
+        return f"bad request — {message}" if message else "bad request — check parameters or unsupported feature"
+    if status_code and status_code >= 500:
+        return "provider server error — temporary, try again later"
+    if message:
+        return message
+    return f"request failed (status {status_code})"
+
+
+def complete(messages, **kwargs):
+    now = time.time()
+    for provider, model_id in MODELS:
+        if _cooldown.get((provider, model_id), 0) > now:
+            continue
+
+        info = PROVIDER_INFO[provider]
+        key = os.getenv(info["env_key"])
+        if not key:
+            continue
+
+        try:
+            resp = requests.post(
+                f"{info['base_url']}/chat/completions",
+                headers={"Authorization": f"Bearer {key}"},
+                json={"model": model_id, "messages": messages, **kwargs},
+                timeout=30,
+            )
+        except requests.exceptions.Timeout:
+            print(f"{provider}/{model_id} failed: request timed out")
+            _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+            continue
+        except requests.exceptions.ConnectionError:
+            print(
+                f"{provider}/{model_id} failed: could not reach provider (connection error)")
+            _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+            continue
+        except requests.exceptions.RequestException as e:
+            print(f"{provider}/{model_id} failed: request error — {e}")
+            _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+            continue
+
+        try:
+            data = resp.json()
+        except ValueError:
+            print(
+                f"{provider}/{model_id} failed: response wasn't valid JSON (status {resp.status_code})")
+            _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+            continue
+
+        if resp.status_code == 200 and "choices" in data:
+            return data
+
+        err = data.get("error")
+        message = err.get("message") if isinstance(err, dict) else err
+        reason = _reason(resp.status_code, message)
+        print(f"{provider}/{model_id} failed: {reason}")
+        _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+
+    raise RuntimeError("all models are currently unavailable or on cooldown")

ftouter-0.1.0/ftouter/providers.py

@@ -0,0 +1,7 @@
+PROVIDER_INFO = {
+    "groq": {"base_url": "https://api.groq.com/openai/v1", "env_key": "GROQ_API_KEY"},
+    "openrouter": {"base_url": "https://openrouter.ai/api/v1", "env_key": "OPENROUTER_API_KEY"},
+    "mistral": {"base_url": "https://api.mistral.ai/v1", "env_key": "MISTRAL_API_KEY"},
+    "gemini": {"base_url": "https://generativelanguage.googleapis.com/v1beta/openai", "env_key": "GEMINI_API_KEY"},
+    "moondream": {"base_url": "https://api.moondream.ai/v1", "env_key": "MOONDREAM_API_KEY"},
+}

ftouter-0.1.0/ftouter/reasoning_models.py

@@ -0,0 +1,88 @@
+import os
+import time
+import requests
+
+from .providers import PROVIDER_INFO
+
+
+MODELS = [
+    ("groq", "qwen/qwen3.8-27b"),
+    ("openrouter", "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free"),
+    ("openrouter", "nvidia/nemotron-3-ultra-550b-a55b:free"),
+    ("mistral", "magistral-medium-latest"),
+]
+
+COOLDOWN_SECONDS = 30 * 60
+_cooldown = {}
+
+
+def _reason(status_code, message=""):
+    text = (message or "").lower()
+    if any(k in text for k in ("decommission", "deprecated", "no longer supported", "retired")):
+        return f"model deprecated by provider — {message}"
+    if status_code in (401, 403):
+        return "wrong or invalid API key"
+    if status_code == 404:
+        return "model not found — likely deprecated or renamed"
+    if status_code == 429:
+        return "rate limited — free quota exhausted"
+    if status_code == 400:
+        return f"bad request — {message}" if message else "bad request — check parameters or unsupported feature"
+    if status_code and status_code >= 500:
+        return "provider server error — temporary, try again later"
+    if message:
+        return message
+    return f"request failed (status {status_code})"
+
+
+def complete(messages, **kwargs):
+    now = time.time()
+    for provider, model_id in MODELS:
+        if _cooldown.get((provider, model_id), 0) > now:
+            continue
+
+        info = PROVIDER_INFO[provider]
+        key = os.getenv(info["env_key"])
+        if not key:
+            continue
+
+        try:
+            resp = requests.post(
+                f"{info['base_url']}/chat/completions",
+                headers={"Authorization": f"Bearer {key}"},
+                json={"model": model_id, "messages": messages, **kwargs},
+                timeout=30,
+            )
+        except requests.exceptions.Timeout:
+            print(f"{provider}/{model_id} failed: request timed out")
+            _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+            continue
+        except requests.exceptions.ConnectionError:
+            print(
+                f"{provider}/{model_id} failed: could not reach provider (connection error)")
+            _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+            continue
+        except requests.exceptions.RequestException as e:
+            print(f"{provider}/{model_id} failed: request error — {e}")
+            _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+            continue
+
+        try:
+            data = resp.json()
+        except ValueError:
+            print(
+                f"{provider}/{model_id} failed: response wasn't valid JSON (status {resp.status_code})")
+            _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+            continue
+
+        if resp.status_code == 200 and "choices" in data:
+            return data
+
+        err = data.get("error")
+        message = err.get("message") if isinstance(err, dict) else err
+        reason = _reason(resp.status_code, message)
+        print(f"{provider}/{model_id} failed: {reason}")
+        _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+
+    raise RuntimeError(
+        "all reasoning models are currently unavailable or on cooldown")

ftouter-0.1.0/ftouter/router.py

@@ -0,0 +1,39 @@
+import os
+import requests
+
+from .providers import PROVIDER_INFO
+from . import chat_models, reasoning_models, tool_calling_models, vision_models
+
+
+def _configured_by_provider():
+    configured = {}
+    for module in (chat_models, reasoning_models, tool_calling_models, vision_models):
+        for provider, model_id in module.MODELS:
+            configured.setdefault(provider, set()).add(model_id)
+    return configured
+
+
+def check_available_models():
+    configured = _configured_by_provider()
+    results = {}
+    for provider, model_ids in configured.items():
+        info = PROVIDER_INFO[provider]
+        key = os.getenv(info["env_key"])
+        if not key:
+            results[provider] = {"status": "no_key"}
+            continue
+        try:
+            resp = requests.get(
+                f"{info['base_url']}/models",
+                headers={"Authorization": f"Bearer {key}"},
+                timeout=10,
+            )
+            resp.raise_for_status()
+            live_ids = {m["id"] for m in resp.json()["data"]}
+            results[provider] = {
+                "status": "ok",
+                "missing": sorted(model_ids - live_ids),
+            }
+        except Exception as e:
+            results[provider] = {"status": "error", "error": str(e)}
+    return results

ftouter-0.1.0/ftouter/tool_calling_models.py

@@ -0,0 +1,90 @@
+import os
+import time
+import requests
+
+from .providers import PROVIDER_INFO
+
+
+# Only confirmed tool-calling models go here. cohere/north-mini-code and the
+# poolside/laguna models are plausible but unverified — add them once tested.
+MODELS = [
+    ("groq", "qwen/qwen3.8-27b"),
+    ("groq", "openai/gpt-oss-120b"),
+    ("groq", "openai/gpt-oss-20b"),
+    ("openrouter", "openrouter/free"),
+]
+
+COOLDOWN_SECONDS = 30 * 60
+_cooldown = {}
+
+
+def _reason(status_code, message=""):
+    text = (message or "").lower()
+    if any(k in text for k in ("decommission", "deprecated", "no longer supported", "retired")):
+        return f"model deprecated by provider — {message}"
+    if status_code in (401, 403):
+        return "wrong or invalid API key"
+    if status_code == 404:
+        return "model not found — likely deprecated or renamed"
+    if status_code == 429:
+        return "rate limited — free quota exhausted"
+    if status_code == 400:
+        return f"bad request — {message}" if message else "bad request — check parameters or unsupported feature"
+    if status_code and status_code >= 500:
+        return "provider server error — temporary, try again later"
+    if message:
+        return message
+    return f"request failed (status {status_code})"
+
+
+def complete(messages, **kwargs):
+    now = time.time()
+    for provider, model_id in MODELS:
+        if _cooldown.get((provider, model_id), 0) > now:
+            continue
+
+        info = PROVIDER_INFO[provider]
+        key = os.getenv(info["env_key"])
+        if not key:
+            continue
+
+        try:
+            resp = requests.post(
+                f"{info['base_url']}/chat/completions",
+                headers={"Authorization": f"Bearer {key}"},
+                json={"model": model_id, "messages": messages, **kwargs},
+                timeout=30,
+            )
+        except requests.exceptions.Timeout:
+            print(f"{provider}/{model_id} failed: request timed out")
+            _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+            continue
+        except requests.exceptions.ConnectionError:
+            print(
+                f"{provider}/{model_id} failed: could not reach provider (connection error)")
+            _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+            continue
+        except requests.exceptions.RequestException as e:
+            print(f"{provider}/{model_id} failed: request error — {e}")
+            _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+            continue
+
+        try:
+            data = resp.json()
+        except ValueError:
+            print(
+                f"{provider}/{model_id} failed: response wasn't valid JSON (status {resp.status_code})")
+            _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+            continue
+
+        if resp.status_code == 200 and "choices" in data:
+            return data
+
+        err = data.get("error")
+        message = err.get("message") if isinstance(err, dict) else err
+        reason = _reason(resp.status_code, message)
+        print(f"{provider}/{model_id} failed: {reason}")
+        _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+
+    raise RuntimeError(
+        "all tool_call models are currently unavailable or on cooldown")

ftouter-0.1.0/ftouter/vision_models.py

@@ -0,0 +1,92 @@
+import os
+import time
+import requests
+
+from .providers import PROVIDER_INFO
+
+
+# Moondream model id below is unconfirmed — verify the exact string in their
+# dashboard/docs before relying on it, everything else here is verified.
+MODELS = [
+    ("groq", "qwen/qwen3.8-27b"),
+    ("gemini", "gemini-2.5-flash"),
+    ("openrouter", "google/gemma-4-26b-a4b-it:free"),
+    ("openrouter", "google/gemma-4-31b-it:free"),
+    ("openrouter", "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free"),
+    ("moondream", "moondream-3-preview"),
+]
+
+COOLDOWN_SECONDS = 30 * 60
+_cooldown = {}
+
+
+def _reason(status_code, message=""):
+    text = (message or "").lower()
+    if any(k in text for k in ("decommission", "deprecated", "no longer supported", "retired")):
+        return f"model deprecated by provider — {message}"
+    if status_code in (401, 403):
+        return "wrong or invalid API key"
+    if status_code == 404:
+        return "model not found — likely deprecated or renamed"
+    if status_code == 429:
+        return "rate limited — free quota exhausted"
+    if status_code == 400:
+        return f"bad request — {message}" if message else "bad request — check parameters or unsupported feature"
+    if status_code and status_code >= 500:
+        return "provider server error — temporary, try again later"
+    if message:
+        return message
+    return f"request failed (status {status_code})"
+
+
+def complete(messages, **kwargs):
+    now = time.time()
+    for provider, model_id in MODELS:
+        if _cooldown.get((provider, model_id), 0) > now:
+            continue
+
+        info = PROVIDER_INFO[provider]
+        key = os.getenv(info["env_key"])
+        if not key:
+            continue
+
+        try:
+            resp = requests.post(
+                f"{info['base_url']}/chat/completions",
+                headers={"Authorization": f"Bearer {key}"},
+                json={"model": model_id, "messages": messages, **kwargs},
+                timeout=30,
+            )
+        except requests.exceptions.Timeout:
+            print(f"{provider}/{model_id} failed: request timed out")
+            _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+            continue
+        except requests.exceptions.ConnectionError:
+            print(
+                f"{provider}/{model_id} failed: could not reach provider (connection error)")
+            _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+            continue
+        except requests.exceptions.RequestException as e:
+            print(f"{provider}/{model_id} failed: request error — {e}")
+            _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+            continue
+
+        try:
+            data = resp.json()
+        except ValueError:
+            print(
+                f"{provider}/{model_id} failed: response wasn't valid JSON (status {resp.status_code})")
+            _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+            continue
+
+        if resp.status_code == 200 and "choices" in data:
+            return data
+
+        err = data.get("error")
+        message = err.get("message") if isinstance(err, dict) else err
+        reason = _reason(resp.status_code, message)
+        print(f"{provider}/{model_id} failed: {reason}")
+        _cooldown[(provider, model_id)] = now + COOLDOWN_SECONDS
+
+    raise RuntimeError(
+        "all vision models are currently unavailable or on cooldown")

ftouter-0.1.0/ftouter.egg-info/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: ftouter
+Version: 0.1.0
+Summary: A resilient runtime layer for free/cheap-tier LLM APIs
+Author-email: Your Name <you@example.com>
+License-Expression: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests
+Requires-Dist: python-dotenv
+
+# ftouter
+
+A resilient runtime layer for free and cheap-tier LLM APIs.
+
+Free-tier LLM providers are unreliable in ways that break production apps silently: models get deprecated overnight, quotas zero out without warning, and providers add card requirements with no notice. `ftouter` sits between your app and multiple providers, automatically falling back to the next available model when one fails — so a single dead endpoint doesn't take down your whole app.
+
+## Features
+
+- **Automatic fallback** across multiple providers and models
+- **Cooldown handling** — a model that fails gets temporarily skipped instead of retried every call
+- **Clear failure reasons** — distinguishes rate limits, deprecated models, bad keys, and server errors instead of generic exceptions
+- **Zero config to start** — just add your API keys and call `.complete()`
+- Five ready-made routers for different use cases: `chat_models`, `general_models`, `reasoning_models`, `tool_call_models`, `vision_models`
+
+## Installation
+
+```bash
+pip install ftouter
+```
+
+## Quickstart
+
+1. Create a `.env` file in your project root with the API keys for the providers you want to use:
+
+```env
+GROQ_API_KEY=your_key_here
+OPENROUTER_API_KEY=your_key_here
+MISTRAL_API_KEY=your_key_here
+```
+
+You don't need all three — `ftouter` skips any provider whose key isn't set and falls through to the next one.
+
+2. Use it in your code:
+
+```python
+from ftouter import chat_models
+from dotenv import load_dotenv
+
+load_dotenv()
+
+result = chat_models.complete([
+    {"role": "user", "content": "Say hi in 5 words"}
+])
+
+print(result["choices"][0]["message"]["content"])
+```
+
+## Available routers
+
+| Router | Use case |
+|---|---|
+| `chat_models.complete()` | General-purpose conversational completions |
+| `general_models.complete()` | General-purpose tasks, pooled across all other routers |
+| `reasoning_models.complete()` | Tasks that benefit from reasoning-focused models |
+| `tool_call_models.complete()` | Completions that use function/tool calling |
+| `vision_models.complete()` | Completions that include image input |
+
+Each router tries a prioritized list of models across providers and automatically moves to the next one on failure.
+
+## Vision
+
+`vision_models.complete()` takes the same message format as the others — an image is just another block inside `content`, either an `https://` URL or a base64 `data:` URI:
+
+```python
+import base64
+from ftouter import vision_models
+from dotenv import load_dotenv
+
+load_dotenv()
+
+with open("example.jpg", "rb") as image_file:
+    image_data = base64.b64encode(image_file.read()).decode("utf-8")
+
+result = vision_models.complete([
+    {
+        "role": "user",
+        "content": [
+            {"type": "text", "text": "what's in this image?"},
+            {
+                "type": "image_url",
+                "image_url": {
+                    "url": f"data:image/jpeg;base64,{image_data}"
+                }
+            }
+        ]
+    }
+])
+print(result["choices"][0]["message"]["content"])
+```
+
+Vision draws from Groq, OpenRouter, and Mistral like the other routers, plus two vision-specific providers — add their keys to `.env` only if you want them in the fallback chain, `ftouter` skips them otherwise like any other missing key:
+
+```env
+GEMINI_API_KEY=your_key_here
+MOONDREAM_API_KEY=your_key_here
+```
+
+Note: base64 image support is confirmed for Groq and Gemini. OpenRouter should accept it (same spec, not independently verified here). Moondream's exact behavior with base64 input is unconfirmed — test it directly if you're relying on that provider.
+
+## How fallback works
+
+When you call `.complete()`, `ftouter`:
+
+1. Tries the first available (not-on-cooldown) model in its list
+2. If it fails, records *why* (rate limit, deprecated model, bad key, server error, etc.) and puts that model on a cooldown timer
+3. Moves to the next model and repeats
+4. Returns the first successful response
+5. Raises `RuntimeError` only if every model in the list is exhausted or on cooldown
+
+This means a single provider having a bad day doesn't crash your app — it just quietly routes around it.
+
+## Getting free API keys
+
+- **Groq** — [console.groq.com](https://console.groq.com)
+- **OpenRouter** — [openrouter.ai](https://openrouter.ai)
+- **Mistral** — [console.mistral.ai](https://console.mistral.ai)
+- **Gemini** (vision only) — [aistudio.google.com](https://aistudio.google.com)
+- **Moondream** (vision only) — [moondream.ai](https://moondream.ai)
+
+## Handling errors
+
+If every provider fails, `.complete()` raises a `RuntimeError`:
+
+```python
+try:
+    result = chat_models.complete([{"role": "user", "content": "Hello"}])
+    print(result["choices"][0]["message"]["content"])
+except RuntimeError as e:
+    print(f"All providers failed: {e}")
+```
+
+## Contributing
+
+Issues and pull requests are welcome. If you'd like to add support for another provider, open an issue first so the model list and provider config stay consistent.
+
+https://github.com/Irfan-gitt
+
+## License
+
+MIT

ftouter-0.1.0/ftouter.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+ftouter/__init__.py
+ftouter/chat_models.py
+ftouter/general_models.py
+ftouter/providers.py
+ftouter/reasoning_models.py
+ftouter/router.py
+ftouter/tool_calling_models.py
+ftouter/vision_models.py
+ftouter.egg-info/PKG-INFO
+ftouter.egg-info/SOURCES.txt
+ftouter.egg-info/dependency_links.txt
+ftouter.egg-info/requires.txt
+ftouter.egg-info/top_level.txt

ftouter-0.1.0/ftouter.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ftouter-0.1.0/ftouter.egg-info/requires.txt

@@ -0,0 +1,2 @@
+requests
+python-dotenv

ftouter-0.1.0/ftouter.egg-info/top_level.txt

@@ -0,0 +1 @@
+ftouter

ftouter-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ftouter"
+version = "0.1.0"
+description = "A resilient runtime layer for free/cheap-tier LLM APIs"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+authors = [{name = "Your Name", email = "you@example.com"}]
+dependencies = [
+    "requests",
+    "python-dotenv",
+]
+
+[tool.setuptools.packages.find]
+include = ["ftouter*"]

ftouter-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+