llm-cascade 0.1.0__tar.gz

llm_cascade-0.1.0/.env.example

@@ -0,0 +1,18 @@
+# Copy this file to `.env` and fill in the keys you plan to use.
+# llm-cascade never requires any of these -- with none set, only the local
+# Ollama tier works; each key you add unlocks the next tier in the cascade.
+
+# Paid tier -- required for the `light`/`heavy` tiers and as the final safety net.
+# Get a key at https://console.anthropic.com/
+ANTHROPIC_API_KEY=
+
+# Free tier -- required to use OpenRouter's `:free` models ($0, rate-limited).
+# Get a key at https://openrouter.ai/
+OPENROUTER_API_KEY=
+
+# Optional: sent as the `HTTP-Referer` header on OpenRouter requests (some
+# integrations use this for attribution). Omitted if unset.
+LLM_CASCADE_HTTP_REFERER=
+
+# Optional: sent as the `X-Title` header on OpenRouter requests. Omitted if unset.
+LLM_CASCADE_APP_TITLE=

llm_cascade-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: python -m pip install -e ".[dev,anthropic]"
+
+      - name: Lint (ruff)
+        run: ruff check .
+
+      - name: Test (pytest)
+        run: pytest tests/ -v

llm_cascade-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+wheels/
+pip-wheel-metadata/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# llm-cascade runtime state (savings ledger, local config)
+.llm_cascade/

llm_cascade-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-15
+
+### Added
+
+- Initial release.
+- `route()` / `complete()` / `complete_json()` core API with a free-first cascade:
+  local Ollama -> OpenRouter free models -> paid Anthropic API.
+- Automatic fallback on provider overload, and a final degrade-to-free safety net
+  if the paid API is unreachable for any reason.
+- `pick()` to resolve a task or tier name to its routing config, and `stats()` to
+  read the cumulative savings ledger.
+- `llm-cascade` CLI (`--task`, `--routes`, `--stats`, `--json`).
+- Configuration via optional TOML file (`~/.llm_cascade/routes.toml` or
+  `LLM_CASCADE_CONFIG`) with environment variable overrides.
+- Zero required third-party dependencies (optional `[anthropic]` extra).

llm_cascade-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 luandv92
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

llm_cascade-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: llm-cascade
+Version: 0.1.0
+Summary: Free-first LLM routing for Python: local Ollama -> OpenRouter free models -> paid Anthropic API, with automatic fallback and a savings ledger.
+Project-URL: Homepage, https://github.com/luandv92/llm-cascade
+Project-URL: Repository, https://github.com/luandv92/llm-cascade
+Project-URL: Issues, https://github.com/luandv92/llm-cascade/issues
+Project-URL: Changelog, https://github.com/luandv92/llm-cascade/blob/main/CHANGELOG.md
+Author: luandv92
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,anthropic,claude,cost-optimization,llm,ollama,openrouter,router
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: tomli>=2.0.1; python_version < '3.11'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40.0; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# llm-cascade
+
+[![CI](https://github.com/luandv92/llm-cascade/actions/workflows/ci.yml/badge.svg)](https://github.com/luandv92/llm-cascade/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/llm-cascade.svg)](https://pypi.org/project/llm-cascade/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python versions](https://img.shields.io/pypi/pyversions/llm-cascade.svg)](https://pypi.org/project/llm-cascade/)
+
+Free-first LLM routing for Python: local Ollama ($0) -> OpenRouter free models
+($0) -> paid Anthropic API, with automatic fallback and a savings ledger.
+Zero required dependencies.
+
+## Why
+
+Most teams route every prompt to the same frontier model regardless of how
+hard the task actually is, and the API bill grows with usage instead of with
+value delivered. llm-cascade flips that: it tries the cheapest tier that can
+plausibly do the job first, and only escalates when that tier is unreachable
+or genuinely too weak for the task. In production, that means classification,
+extraction, and summarization run for $0 on a local model or a free cloud
+model, while code review, planning, and long-form writing still get a
+frontier model -- and if the paid API is ever down or out of credits, your
+scheduled jobs degrade to a free tier instead of crashing.
+
+## Install
+
+```bash
+pip install llm-cascade
+```
+
+The base package has **zero required third-party dependencies**. To use the
+paid Anthropic tier, install the extra:
+
+```bash
+pip install "llm-cascade[anthropic]"
+```
+
+Without it, the local (Ollama) and free-cloud (OpenRouter) tiers still work
+end to end -- you'll only see an error if a task actually routes to the paid
+tier and the SDK isn't installed.
+
+## Quickstart
+
+```python
+from llm_cascade import route
+
+result = route("summarize", "Paste a long document here...")
+print(result.text)        # the completion
+print(result.tier)        # which tier served it: trivial/local/cheap/light/heavy
+print(result.model)       # e.g. "local:ollama", "openrouter:qwen/...", "claude-sonnet-5"
+print(result.cost_usd)    # 0.0 for local/free-cloud tiers
+```
+
+Or from the command line:
+
+```bash
+llm-cascade "Summarize this text: ..." --task summarize
+llm-cascade --routes   # show the tier ladder and task -> tier table
+llm-cascade --stats    # show cumulative cost and free-vs-paid call counts
+```
+
+## How routing works
+
+Each call resolves a **task name** (or a tier name directly) to a **tier**,
+then runs that tier's provider chain in order until one succeeds:
+
+| Tier      | Chain                                            | Use for                                  |
+|-----------|---------------------------------------------------|-------------------------------------------|
+| `trivial` | local Ollama only ($0)                            | high-volume micro-tasks, never worth the network |
+| `local`   | local Ollama ($0) -> OpenRouter free ($0) -> paid  | mechanical NLP: classify, extract, summarize, translate |
+| `cheap`   | OpenRouter free ($0) -> paid                       | manual opt-in tier, invoke directly with `task="cheap"` |
+| `light`   | paid (Sonnet); free-cloud only if `LLM_CASCADE_LIGHT_FREE=1` | customer-facing copy that needs reliable polish |
+| `heavy`   | paid (Opus), adaptive thinking, high effort        | real reasoning: code, review, planning, long-form |
+
+If the paid API call fails for *any* reason -- bad or revoked key, no
+credits, a provider outage, a network blip -- llm-cascade degrades to the
+free tiers instead of raising, so scheduled or automated callers don't break
+outright. It only raises once every tier has been tried and failed.
+
+The default task -> tier table:
+
+```
+classify, extract, summarize, translate, chat  -> local
+rewrite                                        -> light
+code, review, plan, creative                   -> heavy
+```
+
+Anything not in that table falls back to `default_task_tier` (`light` by
+default). See `config/routes.example.toml` for the full, commented schema.
+
+## Configuration
+
+Configuration is resolved with this precedence (lowest to highest):
+
+1. Built-in defaults.
+2. An optional TOML file: `~/.llm_cascade/routes.toml`, or the path given in
+   `LLM_CASCADE_CONFIG`.
+3. Environment variables, for the handful of settings that make sense as env
+   vars.
+
+Copy [`config/routes.example.toml`](config/routes.example.toml) to
+`~/.llm_cascade/routes.toml` to add your own task names, retune which tier
+handles a task, or override model ids and pricing.
+
+Environment variables:
+
+| Variable | Purpose |
+|---|---|
+| `ANTHROPIC_API_KEY` | Enables the paid tier (`light`/`heavy`, and the final safety net). |
+| `OPENROUTER_API_KEY` | Enables the free-cloud tier (OpenRouter `:free` models). |
+| `LLM_CASCADE_CONFIG` | Path to a TOML config file, instead of `~/.llm_cascade/routes.toml`. |
+| `LLM_CASCADE_LOG_PATH` | Path to the savings ledger, instead of `~/.llm_cascade/log.jsonl`. |
+| `LLM_CASCADE_LIGHT_FREE` | Set to `1` to try free-cloud first on the `light` tier too. |
+| `LLM_CASCADE_NO_FREE_CLOUD` | Set to any value to disable the free-cloud tier globally. |
+| `LLM_CASCADE_HTTP_REFERER` / `LLM_CASCADE_APP_TITLE` | Sent as `HTTP-Referer` / `X-Title` on OpenRouter requests (optional; omitted if unset). |
+| `LLM_CASCADE_OPENROUTER_MODEL` / `LLM_CASCADE_OPENROUTER_MODELS` | Override the free model (singular) or ordered list (comma-separated) tried on OpenRouter. |
+| `LLM_CASCADE_OLLAMA_BASE_URL` | Ollama server URL (default `http://localhost:11434`). |
+
+See [`.env.example`](.env.example) for a copy-pasteable starting point.
+
+## Savings ledger
+
+Every call -- free or paid -- appends one line to a JSONL ledger
+(`~/.llm_cascade/log.jsonl` by default). `stats()` / `llm-cascade --stats`
+summarize it:
+
+```bash
+$ llm-cascade --stats
+{
+  "paid_calls": 3,
+  "free_calls": 41,
+  "total_cost_usd": 0.0842,
+  "by_model": {
+    "local:ollama": 30,
+    "openrouter:qwen/qwen3-next-80b-a3b-instruct:free": 11,
+    "claude-sonnet-5": 3
+  }
+}
+```
+
+## Comparison
+
+Unlike heavier multi-provider routers, llm-cascade ships with zero required
+dependencies and a single opinionated cascade -- it's a routing policy you can
+read in one file, not a platform.
+
+## Contributing
+
+Issues and pull requests are welcome at
+[github.com/luandv92/llm-cascade](https://github.com/luandv92/llm-cascade).
+Before opening a PR:
+
+```bash
+pip install -e ".[dev,anthropic]"
+ruff check .
+pytest tests/ -v
+```
+
+Tests never touch real networks -- Ollama, OpenRouter, and the Anthropic SDK
+are all mocked (see `tests/conftest.py`).
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

llm_cascade-0.1.0/README.md

@@ -0,0 +1,163 @@
+# llm-cascade
+
+[![CI](https://github.com/luandv92/llm-cascade/actions/workflows/ci.yml/badge.svg)](https://github.com/luandv92/llm-cascade/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/llm-cascade.svg)](https://pypi.org/project/llm-cascade/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python versions](https://img.shields.io/pypi/pyversions/llm-cascade.svg)](https://pypi.org/project/llm-cascade/)
+
+Free-first LLM routing for Python: local Ollama ($0) -> OpenRouter free models
+($0) -> paid Anthropic API, with automatic fallback and a savings ledger.
+Zero required dependencies.
+
+## Why
+
+Most teams route every prompt to the same frontier model regardless of how
+hard the task actually is, and the API bill grows with usage instead of with
+value delivered. llm-cascade flips that: it tries the cheapest tier that can
+plausibly do the job first, and only escalates when that tier is unreachable
+or genuinely too weak for the task. In production, that means classification,
+extraction, and summarization run for $0 on a local model or a free cloud
+model, while code review, planning, and long-form writing still get a
+frontier model -- and if the paid API is ever down or out of credits, your
+scheduled jobs degrade to a free tier instead of crashing.
+
+## Install
+
+```bash
+pip install llm-cascade
+```
+
+The base package has **zero required third-party dependencies**. To use the
+paid Anthropic tier, install the extra:
+
+```bash
+pip install "llm-cascade[anthropic]"
+```
+
+Without it, the local (Ollama) and free-cloud (OpenRouter) tiers still work
+end to end -- you'll only see an error if a task actually routes to the paid
+tier and the SDK isn't installed.
+
+## Quickstart
+
+```python
+from llm_cascade import route
+
+result = route("summarize", "Paste a long document here...")
+print(result.text)        # the completion
+print(result.tier)        # which tier served it: trivial/local/cheap/light/heavy
+print(result.model)       # e.g. "local:ollama", "openrouter:qwen/...", "claude-sonnet-5"
+print(result.cost_usd)    # 0.0 for local/free-cloud tiers
+```
+
+Or from the command line:
+
+```bash
+llm-cascade "Summarize this text: ..." --task summarize
+llm-cascade --routes   # show the tier ladder and task -> tier table
+llm-cascade --stats    # show cumulative cost and free-vs-paid call counts
+```
+
+## How routing works
+
+Each call resolves a **task name** (or a tier name directly) to a **tier**,
+then runs that tier's provider chain in order until one succeeds:
+
+| Tier      | Chain                                            | Use for                                  |
+|-----------|---------------------------------------------------|-------------------------------------------|
+| `trivial` | local Ollama only ($0)                            | high-volume micro-tasks, never worth the network |
+| `local`   | local Ollama ($0) -> OpenRouter free ($0) -> paid  | mechanical NLP: classify, extract, summarize, translate |
+| `cheap`   | OpenRouter free ($0) -> paid                       | manual opt-in tier, invoke directly with `task="cheap"` |
+| `light`   | paid (Sonnet); free-cloud only if `LLM_CASCADE_LIGHT_FREE=1` | customer-facing copy that needs reliable polish |
+| `heavy`   | paid (Opus), adaptive thinking, high effort        | real reasoning: code, review, planning, long-form |
+
+If the paid API call fails for *any* reason -- bad or revoked key, no
+credits, a provider outage, a network blip -- llm-cascade degrades to the
+free tiers instead of raising, so scheduled or automated callers don't break
+outright. It only raises once every tier has been tried and failed.
+
+The default task -> tier table:
+
+```
+classify, extract, summarize, translate, chat  -> local
+rewrite                                        -> light
+code, review, plan, creative                   -> heavy
+```
+
+Anything not in that table falls back to `default_task_tier` (`light` by
+default). See `config/routes.example.toml` for the full, commented schema.
+
+## Configuration
+
+Configuration is resolved with this precedence (lowest to highest):
+
+1. Built-in defaults.
+2. An optional TOML file: `~/.llm_cascade/routes.toml`, or the path given in
+   `LLM_CASCADE_CONFIG`.
+3. Environment variables, for the handful of settings that make sense as env
+   vars.
+
+Copy [`config/routes.example.toml`](config/routes.example.toml) to
+`~/.llm_cascade/routes.toml` to add your own task names, retune which tier
+handles a task, or override model ids and pricing.
+
+Environment variables:
+
+| Variable | Purpose |
+|---|---|
+| `ANTHROPIC_API_KEY` | Enables the paid tier (`light`/`heavy`, and the final safety net). |
+| `OPENROUTER_API_KEY` | Enables the free-cloud tier (OpenRouter `:free` models). |
+| `LLM_CASCADE_CONFIG` | Path to a TOML config file, instead of `~/.llm_cascade/routes.toml`. |
+| `LLM_CASCADE_LOG_PATH` | Path to the savings ledger, instead of `~/.llm_cascade/log.jsonl`. |
+| `LLM_CASCADE_LIGHT_FREE` | Set to `1` to try free-cloud first on the `light` tier too. |
+| `LLM_CASCADE_NO_FREE_CLOUD` | Set to any value to disable the free-cloud tier globally. |
+| `LLM_CASCADE_HTTP_REFERER` / `LLM_CASCADE_APP_TITLE` | Sent as `HTTP-Referer` / `X-Title` on OpenRouter requests (optional; omitted if unset). |
+| `LLM_CASCADE_OPENROUTER_MODEL` / `LLM_CASCADE_OPENROUTER_MODELS` | Override the free model (singular) or ordered list (comma-separated) tried on OpenRouter. |
+| `LLM_CASCADE_OLLAMA_BASE_URL` | Ollama server URL (default `http://localhost:11434`). |
+
+See [`.env.example`](.env.example) for a copy-pasteable starting point.
+
+## Savings ledger
+
+Every call -- free or paid -- appends one line to a JSONL ledger
+(`~/.llm_cascade/log.jsonl` by default). `stats()` / `llm-cascade --stats`
+summarize it:
+
+```bash
+$ llm-cascade --stats
+{
+  "paid_calls": 3,
+  "free_calls": 41,
+  "total_cost_usd": 0.0842,
+  "by_model": {
+    "local:ollama": 30,
+    "openrouter:qwen/qwen3-next-80b-a3b-instruct:free": 11,
+    "claude-sonnet-5": 3
+  }
+}
+```
+
+## Comparison
+
+Unlike heavier multi-provider routers, llm-cascade ships with zero required
+dependencies and a single opinionated cascade -- it's a routing policy you can
+read in one file, not a platform.
+
+## Contributing
+
+Issues and pull requests are welcome at
+[github.com/luandv92/llm-cascade](https://github.com/luandv92/llm-cascade).
+Before opening a PR:
+
+```bash
+pip install -e ".[dev,anthropic]"
+ruff check .
+pytest tests/ -v
+```
+
+Tests never touch real networks -- Ollama, OpenRouter, and the Anthropic SDK
+are all mocked (see `tests/conftest.py`).
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

llm_cascade-0.1.0/config/routes.example.toml

@@ -0,0 +1,56 @@
+# Example llm-cascade configuration.
+#
+# Copy this file to one of:
+#   ~/.llm_cascade/routes.toml            (default location)
+#   any path, then set LLM_CASCADE_CONFIG=/path/to/routes.toml
+#
+# Every section is optional. Anything you omit falls back to the built-in
+# default shown in comments. Environment variables (see .env.example) always
+# take precedence over this file for the settings they control (API keys,
+# HTTP headers, the log path, and the free-cloud opt-in/kill-switch).
+
+# Override which concrete model id backs each named tier.
+[models]
+opus = "claude-opus-4-8"
+sonnet = "claude-sonnet-5"
+haiku = "claude-haiku-4-5"
+
+# USD price per 1M tokens, as [input, output]. Used only to compute the numbers
+# shown by `llm-cascade --stats` -- it does not affect what you're actually
+# billed by Anthropic.
+[pricing]
+claude-opus-4-8 = [5.0, 25.0]
+claude-sonnet-5 = [2.0, 10.0]
+claude-haiku-4-5 = [1.0, 5.0]
+
+# The policy: which tier handles each task name. Tiers are "trivial" (local
+# only, $0), "local" (local -> free cloud -> paid, safety net), "cheap" (free
+# cloud -> paid, manual-only tier), "light" (paid Sonnet, free-cloud opt-in),
+# and "heavy" (paid Opus, adaptive thinking). Add your own task names here --
+# anything not listed falls back to `default_task_tier`.
+[task_routes]
+classify = "local"
+extract = "local"
+summarize = "local"
+translate = "local"
+rewrite = "light"
+code = "heavy"
+review = "heavy"
+plan = "heavy"
+creative = "heavy"
+chat = "local"
+# my_custom_task = "heavy"
+
+# Tier used for any task name not found in [task_routes] above.
+default_task_tier = "light"
+
+# OpenRouter ":free" models tried in order for the free-cloud tier. Listed from
+# different providers so rate limits are uncorrelated -- if one is saturated,
+# the next is usually open.
+openrouter_models = [
+    "meta-llama/llama-3.3-70b-instruct:free",
+    "qwen/qwen3-next-80b-a3b-instruct:free",
+    "google/gemma-4-31b-it:free",
+    "nvidia/nemotron-3-super-120b-a12b:free",
+    "nousresearch/hermes-3-llama-3.1-405b:free",
+]

llm_cascade-0.1.0/examples/quickstart.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""Quickstart for llm-cascade.
+
+Run it as-is with no configuration to see the local-only ("trivial") tier, or
+set ANTHROPIC_API_KEY / OPENROUTER_API_KEY to unlock the higher tiers.
+
+    python examples/quickstart.py
+"""
+from __future__ import annotations
+
+from llm_cascade import complete, complete_json, pick, route, stats
+
+
+def main() -> None:
+    # route() is the main entrypoint: it returns a Completion with the text,
+    # the tier and model that served it, and the USD cost (0.0 for free tiers).
+    result = route("summarize", "Summarize: the quick brown fox jumps over the lazy dog.")
+    print(f"[{result.tier} -> {result.model}, ${result.cost_usd:.4f}]")
+    print(result.text)
+    print()
+
+    # complete() is a thin wrapper that returns just the text.
+    caption = complete("Write one short, upbeat product tagline.", task="creative")
+    print("Tagline:", caption)
+    print()
+
+    # complete_json() asks the model for structured output and parses it.
+    try:
+        data = complete_json(
+            'Extract as JSON: {"name": str, "age": int}. Text: "Alice is 30 years old."',
+            task="extract",
+        )
+        print("Extracted JSON:", data)
+    except Exception as e:  # pragma: no cover - depends on which tier is available
+        print("complete_json skipped:", e)
+    print()
+
+    # pick() resolves a task name to its routing config without running anything.
+    print("Route for 'code':", pick("code"))
+    print()
+
+    # stats() reads the cumulative savings ledger (~/.llm_cascade/log.jsonl).
+    print("Savings ledger:", stats())
+
+
+if __name__ == "__main__":
+    main()

llm_cascade-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "llm-cascade"
+version = "0.1.0"
+description = "Free-first LLM routing for Python: local Ollama -> OpenRouter free models -> paid Anthropic API, with automatic fallback and a savings ledger."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "luandv92" },
+]
+keywords = [
+    "llm",
+    "router",
+    "anthropic",
+    "claude",
+    "ollama",
+    "openrouter",
+    "cost-optimization",
+    "ai",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+
+# Zero required third-party dependencies. `tomli` only backfills the stdlib
+# `tomllib` parser (added in Python 3.11) for older interpreters.
+dependencies = [
+    "tomli>=2.0.1; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+anthropic = [
+    "anthropic>=0.40.0",
+]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+]
+
+[project.urls]
+Homepage = "https://github.com/luandv92/llm-cascade"
+Repository = "https://github.com/luandv92/llm-cascade"
+Issues = "https://github.com/luandv92/llm-cascade/issues"
+Changelog = "https://github.com/luandv92/llm-cascade/blob/main/CHANGELOG.md"
+
+[project.scripts]
+llm-cascade = "llm_cascade.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/llm_cascade"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]