freelm 0.1.0__tar.gz

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

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+    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
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Test
+        run: pytest -q

freelm-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release
+
+# Publishes to PyPI when a v* tag is pushed.
+# Uses PyPI Trusted Publishing (OIDC) — configure the publisher on PyPI first:
+#   https://docs.pypi.org/trusted-publishers/  (project: freelm, workflow: release.yml)
+# No API token/secret required once trusted publishing is set up.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

freelm-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.DS_Store
+*.log
+.coverage
+htmlcov/

freelm-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to `freelm` are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/); versioning is [SemVer](https://semver.org/).
+
+## [0.1.0] - 2026-06-07
+
+Initial release.
+
+### Added
+- `FreeLLM` (sync) and `AsyncFreeLLM` (async) always-up chat clients.
+- Providers (OpenAI-compatible HTTP): OpenRouter, Google AI Studio (Gemini), NVIDIA NIM.
+- Fault tolerance: per-key circuit breaker, cross-provider failover, retry classification
+  (429 cooldown/rotate, 5xx/timeout backoff, 401 key-disable, model errors → next model).
+- Model-scoped vs key-scoped 429 handling (OpenRouter free models throttle per-model upstream).
+- Quota guard: per-key requests/minute token bucket + requests/day counter.
+- Routing strategies: `priority`, `round_robin`, `quota_aware`, `latency`.
+- Virtual models (`auto`, `chat:fast`, `chat:large`, ...) resolved per provider.
+- Dynamic model discovery via `GET /models` with disk cache (TTL, `0600`) and
+  live → cache → hardcoded fallback. `list_free_models()` helper.
+- OpenAI drop-in shim: `freelm.compat.OpenAI` / `AsyncOpenAI`.
+- `FreeLLM.from_env()` config from environment; `llm.health()` introspection.
+
+[0.1.0]: https://github.com/shihabshahrier/freelm/releases/tag/v0.1.0

freelm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shihab Shahriar Antor / Shahriar Labs
+
+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.

freelm-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: freelm
+Version: 0.1.0
+Summary: One always-up LLM client over free-tier providers (OpenRouter, Google AI Studio, NVIDIA NIM) with auto key-rotation, failover, circuit breaking and quota-aware routing.
+Project-URL: Homepage, https://github.com/shihabshahrier/freelm
+Project-URL: Issues, https://github.com/shihabshahrier/freelm/issues
+Author-email: Shihab Shahriar Antor <shahriarlabs@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,failover,free,gemini,llm,nvidia-nim,openai,openrouter,router
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: anyio>=4; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# freelm
+
+**One always-up LLM client over free-tier providers.** Drop in your OpenRouter, Google AI Studio, and/or NVIDIA NIM keys, and `freelm` gives you a single chat call that auto-rotates keys, fails over across providers, paces itself to each tier's limits, and trips circuit breakers on dead keys — so your app keeps talking to an LLM even when one source rate-limits or dies.
+
+> Python first. JS/TS and Go ports planned (the core is spec-driven for portability).
+
+## Why
+
+LLMs show up in nearly every project, and they cost money — but there's a lot of *free* capacity scattered across providers:
+
+- **OpenRouter** — free models (`:free`), ~50 req/day under $10 credit, ~1000/day at ≥$10.
+- **Google AI Studio (Gemini)** — generous free tier; Tier 1 (billing on) lifts limits hard.
+- **NVIDIA NIM** (`build.nvidia.com`) — many models free against build credits.
+
+`freelm` pools them behind one fault-tolerant client.
+
+## Install
+
+```bash
+pip install freelm
+```
+
+## Quick start
+
+```python
+import freelm
+
+llm = freelm.FreeLLM.from_env()          # reads keys from environment
+print(llm.text("Explain black holes in one sentence."))
+```
+
+Explicit config:
+
+```python
+from freelm import FreeLLM, OpenRouter, GoogleAIStudio, NIM
+
+llm = FreeLLM(
+    providers=[
+        OpenRouter("sk-or-...", tier="free"),       # or tier="credit" if ≥ $10
+        GoogleAIStudio("AIza...", tier="free"),      # or tier="tier1"
+        NIM("nvapi-..."),
+    ],
+    strategy="quota_aware",   # priority | round_robin | quota_aware | latency
+)
+
+resp = llm.chat(
+    [{"role": "user", "content": "Write a haiku about failover."}],
+    model="chat:fast",        # virtual model, see below
+)
+print(resp.text, "via", resp.provider)
+```
+
+Async is symmetric:
+
+```python
+from freelm import AsyncFreeLLM
+
+async with AsyncFreeLLM.from_env() as llm:
+    print(await llm.text("hi"))
+```
+
+## Drop-in OpenAI shim
+
+```python
+# from openai import OpenAI
+from freelm.compat import OpenAI
+
+client = OpenAI()                          # backed by FreeLLM.from_env()
+r = client.chat.completions.create(
+    model="auto",
+    messages=[{"role": "user", "content": "hi"}],
+)
+print(r.choices[0].message.content)
+```
+
+## Environment variables
+
+| Provider | Key vars (first match wins) | Tier var |
+|----------|------------------------------|----------|
+| OpenRouter | `OPENROUTER_API_KEY` / `FREELM_OPENROUTER_KEYS` | `FREELM_OPENROUTER_TIER` (`free`\|`credit`) |
+| Google AI Studio | `GEMINI_API_KEY` / `GOOGLE_API_KEY` / `GOOGLE_AI_STUDIO_KEY` / `FREELM_GOOGLE_KEYS` | `FREELM_GOOGLE_TIER` (`free`\|`tier1`) |
+| NVIDIA NIM | `NVIDIA_API_KEY` / `NIM_API_KEY` / `FREELM_NIM_KEYS` | `FREELM_NIM_TIER` (`free`) |
+
+Multiple keys per provider: comma-separate them.
+
+## Virtual models
+
+Names differ per provider, so ask by intent and `freelm` maps to a concrete model:
+
+| Alias | Meaning |
+|-------|---------|
+| `auto` / `chat` | any available chat model (registry order) |
+| `chat:large` / `large` | a larger/stronger model |
+| `chat:fast` / `fast` | a fast/cheap model |
+| `chat:small` / `small` | smallest model |
+| `vendor/model-id` | passthrough — use exactly this model |
+
+Override the table per provider with `models=[ModelSpec(...)]`.
+
+## Dynamic model discovery
+
+Free model IDs churn constantly, so `freelm` **doesn't trust its hardcoded list**. For OpenRouter (on by default), it queries `GET /models` on first use, derives tags (`large`/`fast`/`small`, plus `tools`/`vision`/`reasoning` from `supported_parameters`), and caches the list to disk.
+
+Resolution order: **live API → disk cache → hardcoded fallback** (so it still works offline / key-less).
+
+```python
+from freelm import list_free_models
+
+for m in list_free_models()[:5]:        # live OpenRouter free models, cached
+    print(m.id, m.tags, m.ctx)
+```
+
+Control it:
+
+```python
+OpenRouter("sk-or-...", discover=True, discover_free_only=True, cache_ttl=3600)
+GoogleAIStudio("AIza...", discover=True)   # opt-in for other providers' /models
+
+llm.refresh_models()                        # force re-fetch on next call
+```
+
+| Env var | Default | Meaning |
+|---------|---------|---------|
+| `FREELM_CACHE_DIR` | `~/.cache/freelm` | where the model cache lives (file is `0600`) |
+| `FREELM_CACHE_TTL` | `3600` | cache lifetime in seconds |
+
+## How "always-up" works
+
+- **Key pool** per provider, round-robined to spread load.
+- **Failover chain**: key → next key → next provider until one succeeds.
+- **Circuit breaker** per key: opens after repeated failures, half-opens after a cooldown — no hammering a dead key.
+- **Retry classification**: `429` → cool the key & rotate; `5xx`/timeout → breaker + backoff; `401/403` → disable the key; `4xx` model errors → try another model/provider; other `4xx` → surfaced as a caller bug.
+- **Quota guard**: per-key requests/minute (token bucket) + requests/day counter, so a key predicted to be exhausted is skipped before you waste a call.
+- **`wait=True`** (optional): briefly sleep until a key frees up instead of failing, bounded by `max_wait`.
+
+Inspect live state any time:
+
+```python
+for row in llm.health():
+    print(row)   # provider, key (masked), ready, breaker, rpd_used, last_error, latency
+```
+
+## Roadmap
+
+- v1.1 — streaming (SSE normalization across providers)
+- v1.2 — persistent quota tracking (sqlite/json) + tighter tier pacing
+- v1.3 — tool / function-calling normalization
+- v2 — embeddings, vision; JS/TS and Go ports
+
+## License
+
+MIT © Shahriar Labs
+
+> Free-tier model lists change often — `freelm` discovers OpenRouter models live and caches them, so you rarely touch the hardcoded list. Tier **rate-limit numbers** are still heuristic defaults; override `rpm`/`rpd`/`tier` as providers evolve.

freelm-0.1.0/README.md

@@ -0,0 +1,154 @@
+# freelm
+
+**One always-up LLM client over free-tier providers.** Drop in your OpenRouter, Google AI Studio, and/or NVIDIA NIM keys, and `freelm` gives you a single chat call that auto-rotates keys, fails over across providers, paces itself to each tier's limits, and trips circuit breakers on dead keys — so your app keeps talking to an LLM even when one source rate-limits or dies.
+
+> Python first. JS/TS and Go ports planned (the core is spec-driven for portability).
+
+## Why
+
+LLMs show up in nearly every project, and they cost money — but there's a lot of *free* capacity scattered across providers:
+
+- **OpenRouter** — free models (`:free`), ~50 req/day under $10 credit, ~1000/day at ≥$10.
+- **Google AI Studio (Gemini)** — generous free tier; Tier 1 (billing on) lifts limits hard.
+- **NVIDIA NIM** (`build.nvidia.com`) — many models free against build credits.
+
+`freelm` pools them behind one fault-tolerant client.
+
+## Install
+
+```bash
+pip install freelm
+```
+
+## Quick start
+
+```python
+import freelm
+
+llm = freelm.FreeLLM.from_env()          # reads keys from environment
+print(llm.text("Explain black holes in one sentence."))
+```
+
+Explicit config:
+
+```python
+from freelm import FreeLLM, OpenRouter, GoogleAIStudio, NIM
+
+llm = FreeLLM(
+    providers=[
+        OpenRouter("sk-or-...", tier="free"),       # or tier="credit" if ≥ $10
+        GoogleAIStudio("AIza...", tier="free"),      # or tier="tier1"
+        NIM("nvapi-..."),
+    ],
+    strategy="quota_aware",   # priority | round_robin | quota_aware | latency
+)
+
+resp = llm.chat(
+    [{"role": "user", "content": "Write a haiku about failover."}],
+    model="chat:fast",        # virtual model, see below
+)
+print(resp.text, "via", resp.provider)
+```
+
+Async is symmetric:
+
+```python
+from freelm import AsyncFreeLLM
+
+async with AsyncFreeLLM.from_env() as llm:
+    print(await llm.text("hi"))
+```
+
+## Drop-in OpenAI shim
+
+```python
+# from openai import OpenAI
+from freelm.compat import OpenAI
+
+client = OpenAI()                          # backed by FreeLLM.from_env()
+r = client.chat.completions.create(
+    model="auto",
+    messages=[{"role": "user", "content": "hi"}],
+)
+print(r.choices[0].message.content)
+```
+
+## Environment variables
+
+| Provider | Key vars (first match wins) | Tier var |
+|----------|------------------------------|----------|
+| OpenRouter | `OPENROUTER_API_KEY` / `FREELM_OPENROUTER_KEYS` | `FREELM_OPENROUTER_TIER` (`free`\|`credit`) |
+| Google AI Studio | `GEMINI_API_KEY` / `GOOGLE_API_KEY` / `GOOGLE_AI_STUDIO_KEY` / `FREELM_GOOGLE_KEYS` | `FREELM_GOOGLE_TIER` (`free`\|`tier1`) |
+| NVIDIA NIM | `NVIDIA_API_KEY` / `NIM_API_KEY` / `FREELM_NIM_KEYS` | `FREELM_NIM_TIER` (`free`) |
+
+Multiple keys per provider: comma-separate them.
+
+## Virtual models
+
+Names differ per provider, so ask by intent and `freelm` maps to a concrete model:
+
+| Alias | Meaning |
+|-------|---------|
+| `auto` / `chat` | any available chat model (registry order) |
+| `chat:large` / `large` | a larger/stronger model |
+| `chat:fast` / `fast` | a fast/cheap model |
+| `chat:small` / `small` | smallest model |
+| `vendor/model-id` | passthrough — use exactly this model |
+
+Override the table per provider with `models=[ModelSpec(...)]`.
+
+## Dynamic model discovery
+
+Free model IDs churn constantly, so `freelm` **doesn't trust its hardcoded list**. For OpenRouter (on by default), it queries `GET /models` on first use, derives tags (`large`/`fast`/`small`, plus `tools`/`vision`/`reasoning` from `supported_parameters`), and caches the list to disk.
+
+Resolution order: **live API → disk cache → hardcoded fallback** (so it still works offline / key-less).
+
+```python
+from freelm import list_free_models
+
+for m in list_free_models()[:5]:        # live OpenRouter free models, cached
+    print(m.id, m.tags, m.ctx)
+```
+
+Control it:
+
+```python
+OpenRouter("sk-or-...", discover=True, discover_free_only=True, cache_ttl=3600)
+GoogleAIStudio("AIza...", discover=True)   # opt-in for other providers' /models
+
+llm.refresh_models()                        # force re-fetch on next call
+```
+
+| Env var | Default | Meaning |
+|---------|---------|---------|
+| `FREELM_CACHE_DIR` | `~/.cache/freelm` | where the model cache lives (file is `0600`) |
+| `FREELM_CACHE_TTL` | `3600` | cache lifetime in seconds |
+
+## How "always-up" works
+
+- **Key pool** per provider, round-robined to spread load.
+- **Failover chain**: key → next key → next provider until one succeeds.
+- **Circuit breaker** per key: opens after repeated failures, half-opens after a cooldown — no hammering a dead key.
+- **Retry classification**: `429` → cool the key & rotate; `5xx`/timeout → breaker + backoff; `401/403` → disable the key; `4xx` model errors → try another model/provider; other `4xx` → surfaced as a caller bug.
+- **Quota guard**: per-key requests/minute (token bucket) + requests/day counter, so a key predicted to be exhausted is skipped before you waste a call.
+- **`wait=True`** (optional): briefly sleep until a key frees up instead of failing, bounded by `max_wait`.
+
+Inspect live state any time:
+
+```python
+for row in llm.health():
+    print(row)   # provider, key (masked), ready, breaker, rpd_used, last_error, latency
+```
+
+## Roadmap
+
+- v1.1 — streaming (SSE normalization across providers)
+- v1.2 — persistent quota tracking (sqlite/json) + tighter tier pacing
+- v1.3 — tool / function-calling normalization
+- v2 — embeddings, vision; JS/TS and Go ports
+
+## License
+
+MIT © Shahriar Labs
+
+> Free-tier model lists change often — `freelm` discovers OpenRouter models live and caches them, so you rarely touch the hardcoded list. Tier **rate-limit numbers** are still heuristic defaults; override `rpm`/`rpd`/`tier` as providers evolve.

freelm-0.1.0/examples/basic.py

@@ -0,0 +1,22 @@
+"""Run me:  python examples/basic.py
+
+Set at least one of OPENROUTER_API_KEY / GEMINI_API_KEY / NVIDIA_API_KEY first.
+"""
+from freelm import FreeLLM
+
+
+def main() -> None:
+    # Reads keys + tiers from environment.
+    llm = FreeLLM.from_env(strategy="quota_aware")
+
+    print(llm.text("Explain prompt caching in one sentence.", model="chat:fast"))
+
+    print("\n--- key health ---")
+    for row in llm.health():
+        print(row)
+
+    llm.close()
+
+
+if __name__ == "__main__":
+    main()

freelm-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "freelm"
+version = "0.1.0"
+description = "One always-up LLM client over free-tier providers (OpenRouter, Google AI Studio, NVIDIA NIM) with auto key-rotation, failover, circuit breaking and quota-aware routing."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Shihab Shahriar Antor", email = "shahriarlabs@gmail.com" }]
+keywords = ["llm", "openrouter", "gemini", "nvidia-nim", "free", "failover", "router", "openai", "ai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "respx>=0.20", "anyio>=4"]
+
+[project.urls]
+Homepage = "https://github.com/shihabshahrier/freelm"
+Issues = "https://github.com/shihabshahrier/freelm/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/freelm"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

freelm-0.1.0/src/freelm/__init__.py

@@ -0,0 +1,63 @@
+"""freelm — one always-up LLM client over free-tier providers.
+
+Quick start::
+
+    import freelm
+    llm = freelm.FreeLLM.from_env()
+    print(llm.text("Explain black holes in one sentence."))
+
+Explicit config::
+
+    from freelm import FreeLLM, OpenRouter, GoogleAIStudio, NIM
+    llm = FreeLLM(
+        providers=[OpenRouter("sk-or-..."), GoogleAIStudio("AIza..."), NIM("nvapi-...")],
+        strategy="quota_aware",
+    )
+"""
+from __future__ import annotations
+
+from ._types import ChatRequest, ChatResponse, Choice, Message, Usage
+from .client import AsyncFreeLLM, FreeLLM
+from .config import providers_from_env
+from .discovery import list_free_models
+from .errors import (
+    AuthError,
+    ConfigError,
+    FreeLLMError,
+    ModelNotFound,
+    NoProvidersAvailable,
+    ProviderError,
+    RateLimited,
+    Transient,
+)
+from .providers import Gemini, GoogleAIStudio, NIM, OpenRouter, Provider
+from .registry import ModelSpec
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "FreeLLM",
+    "AsyncFreeLLM",
+    "Provider",
+    "OpenRouter",
+    "GoogleAIStudio",
+    "Gemini",
+    "NIM",
+    "ModelSpec",
+    "Message",
+    "ChatRequest",
+    "ChatResponse",
+    "Choice",
+    "Usage",
+    "providers_from_env",
+    "list_free_models",
+    "FreeLLMError",
+    "ConfigError",
+    "ProviderError",
+    "AuthError",
+    "RateLimited",
+    "Transient",
+    "ModelNotFound",
+    "NoProvidersAvailable",
+    "__version__",
+]

freelm-0.1.0/src/freelm/_backoff.py

@@ -0,0 +1,13 @@
+"""Exponential backoff with full jitter."""
+from __future__ import annotations
+
+import random
+
+
+def compute_delay(attempt: int, base: float = 0.5, factor: float = 2.0, cap: float = 30.0, jitter: bool = True) -> float:
+    """Delay (seconds) for a given retry attempt (1-based)."""
+    attempt = max(1, attempt)
+    raw = min(cap, base * (factor ** (attempt - 1)))
+    if jitter:
+        return random.uniform(0.0, raw)
+    return raw

freelm-0.1.0/src/freelm/_breaker.py

@@ -0,0 +1,41 @@
+"""Per-key circuit breaker. Time is injected (monotonic seconds) for testability."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+CLOSED = "closed"
+OPEN = "open"
+HALF_OPEN = "half_open"
+
+
+@dataclass
+class CircuitBreaker:
+    fail_threshold: int = 4
+    cooldown: float = 30.0
+    state: str = CLOSED
+    failures: int = 0
+    opened_at: float = 0.0
+
+    def allow(self, now: float) -> bool:
+        """May a request go through right now?"""
+        if self.state == OPEN:
+            if now - self.opened_at >= self.cooldown:
+                self.state = HALF_OPEN
+                return True
+            return False
+        return True
+
+    def on_success(self) -> None:
+        self.failures = 0
+        self.state = CLOSED
+
+    def on_failure(self, now: float) -> None:
+        self.failures += 1
+        if self.state == HALF_OPEN or self.failures >= self.fail_threshold:
+            self.state = OPEN
+            self.opened_at = now
+
+    def time_until_half_open(self, now: float) -> float:
+        if self.state != OPEN:
+            return 0.0
+        return max(0.0, self.cooldown - (now - self.opened_at))