Limitora

Limitora is a typed Python library for provider-agnostic quota and status observations. It keeps provider adapters, composition, caching, output projection, and the CLI behind explicit boundaries so scripts and small tools can inspect status without embedding UI logic or leaking secrets.

Current status: 0.2.0 is the published baseline. The current source tree prepares 0.3.1 with the typed public API, deterministic output projections, a provider-aware limitora status CLI, Codex JSONL support including structural notification-metadata compatibility, opt-in OpenCode Go support, and the additive ValueAvailability.RATE_LIMITED state. 0.3.1 is not published yet.

Supported CPython versions are 3.10 through 3.14. A newer minor is not claimed until CI covers it; an upper bound requires a reproduced incompatibility.

Install and typed quick path

python -m pip install -e .

The public API can be used without invoking a provider:

from datetime import timedelta
from limitora import AuthorizationPolicy, FreshnessPolicy, MetricKind, StatusRequest

request = StatusRequest(
    frozenset({MetricKind.COMMERCIAL_QUOTA}),
    AuthorizationPolicy.DENY_AUTHORIZED_SOURCE,
    FreshnessPolicy(timedelta(minutes=5)),
)
print(request.requested_metrics)

Provider reads require an explicit StatusClient or construction boundary; provider calls are never implicit.

Problem

Local scripting tools that call LLM providers often end up tied to a specific editor, desktop widget, or GUI framework. That coupling makes them hard to test, hard to reuse, and risky to extend. Limitora keeps the provider conversation in a plain Python library so integrations can be thin and optional.

Architecture at a glance

┌─────────────────────────────────────┐
│           consumers / CLI           │
├─────────────────────────────────────┤
│  limitora.cli / limitora.output     │
│  limitora.composition / limitora.api│
│  limitora.core / limitora.models    │
├─────────────────────────────────────┤
│  limitora.providers                 │
│    ├── codex                        │
│    ├── opencode-go                  │
│    └── explicit provider adapters   │
├─────────────────────────────────────┤
│  limitora.providers.cache           │
└─────────────────────────────────────┘

• api and models define the stable typed consumer boundary.
• core coordinates detection and snapshot reads; composition selects one explicit provider.
• providers owns contracts and private adapters; cache is opt-in, in-memory reuse.
• output projects typed results to JSON v1 or human text; cli owns parsing, streams, and exits.

Limitora never imports YASB, PyQt, Waybar, or any UI integration.

Provider support

Public API

The stable root surface includes StatusClient, StatusRequest, freshness types, provider-neutral models, safe provider errors, and the closed construction boundary: CodexJsonlConfig, OpenCodeGoConfig, ProviderConfig, activate_provider, CompositionError, and CompositionErrorKind. Provider dependencies, transports, sessions, and adapters remain internal.

Consumers construct and retain one client for the selected provider:

from limitora import OpenCodeGoConfig, activate_provider

config = OpenCodeGoConfig(api_key)
client = activate_provider(config)

The consuming application owns environment or configuration access and passes the API key explicitly. The limitora status CLI accepts LIMITORA_OPENCODE_API_KEY or --api-key; it never loads .env files. Treat the API key as sensitive. Limitora-controlled representations omit it, and request representations omit credentials, headers, and bodies.

CLI status

limitora status supports --json, --help, and explicit --provider codex|opencode-go activation. Without a provider it performs no provider I/O and reports ERROR: no provider configured on stderr with exit code 4. Routing is documented in cli-activation.md.

Security and privacy

Never store tokens, cookies, sessions, credentials, or provider cache data unredacted in this repository. Diagnostic dumps must be redacted before sharing. Redacted artifacts may use the names *.redacted.json or *.redacted.txt.

Roadmap status

The original provider-status roadmap is concluded/historical for the shipped baseline. Current implementation evidence is in the source and tests; future provider work is not promised.

1. ✅ Typed domain, provider contract, orchestration, and public API.
2. ✅ Codex and OpenCode Go adapters with explicit composition.
3. ✅ In-memory cache and deterministic JSON v1/human projections.
4. ✅ Explicit CLI activation with safe, documented failure boundaries.
5. ⏸ Claude and Gemini remain unimplemented evaluation items.

Future relation to yasb-limitora

A separate yasb-limitora integration may consume this library to connect YASB to LLM providers. That integration will live in its own repository and import Limitora as a normal Python dependency. Limitora itself will remain UI-free.