Skip to main content

Limitr for Python

Most flexible usage & margin control for AI. Change prices, limits, and contracts for users and agents as easily as a git commit, live.

Limitr decides what each customer can use and what it costs. You write your plans, limits, and prices in one policy file. Before your app does something a customer pays for (a model call, an export, an API request), it asks Limitr: is this allowed? Limitr answers, counts the usage, and tells you what to bill and what it cost you. It runs inside your app, and Limitr Cloud is the hosted side when you want it.

pip install limitr

Quick start

Here's a policy, policy.yaml. AI tokens cost the customer $20 per million and cost you $8. The free plan gets 50k tokens a month. The pro plan gets 2M, can go over (and pay for it), and can export PDFs:

policy:
  credits:
    ai_token: { price: { amount: 0.00002 }, overhead_cost: 0.000008 }
  plans:
    free:
      default: true
      entitlements:
        chat: { limit: { credit: ai_token, value: 50000, resets: true } }
    pro:
      entitlements:
        chat: { limit: { credit: ai_token, mode: soft, value: 2000000, resets: true } }
        export_pdf: {}   # no limit: a feature flag
from limitr import Limitr

limitr = Limitr(open('policy.yaml').read(), 'yaml')
limitr.add_handler('billing', lambda name, event: print('bill acme:', event['overage_price']) if name == 'meter-overage' else None)

limitr.ensure_customer('acme', 'pro')
limitr.allow('acme', 'export_pdf')        # True
limitr.allow('acme', 'chat', 2_100_000)   # True, 100k over the limit, so it prints "bill acme: 2.0"

limitr.ensure_customer('ada')             # no plan given, so ada is on free
d = limitr.check('ada', 'chat', 60_000, detail=True)
print(d['allowed'], d['reason'], d['remaining'])   # False limit 50000.0

Policies can also be JSON, TOML, a dict, or Stof (the default, for functions and rules of your own). The tutorial goes from here in 15 short, runnable chapters.

LLM calls: reserve, then settle

A call's size is only known when it's done, and calls run at the same time. Hold room first, then record what the call really used:

hold = limitr.reserve('ada', 'chat', 4096)         # or leave the value out to hold the predicted size
if not hold:
    return 'out of tokens'
res = client.messages.create(model=model, max_tokens=4096, messages=messages)
limitr.settle('ada', 'chat', hold, res.usage.input_tokens + res.usage.output_tokens,
              {'model': model, 'input': res.usage.input_tokens, 'output': res.usage.output_tokens})

Events and state

limitr.add_handler('billing', lambda name, event: print(name, event))   # objects arrive as dicts

saved = limitr.customers()          # all customer state: store it anywhere
restored = Limitr(policy_source)
restored.load_customers(saved)

Event handlers run during the call that sent the event, so don't call the policy from one; queue the work instead.

Limitr Cloud

The same calls, with the policy, customer state, ledgers, invoices, contracts, and Limitr Analyst managed in Limitr Cloud:

import os
from limitr import Limitr

limitr = Limitr.cloud(os.environ['LIMITR_TOKEN'])   # None if Cloud refuses the token (it logs why)

limitr.ensure_customer('ada')       # loaded from Cloud if it has her, else created here
if limitr.allow('ada', 'chat', 1200):
    ...

limitr.close()                      # on shutdown: sends the usage still batched

The policy follows what you publish in Cloud, live. A customer the engine hasn't seen is loaded from Cloud the first time a call needs it, and usage goes back to Cloud over a WebSocket, batched (batch_ms, 250 by default). Calls are refused while the connection is down (deny_unconnected=True, the default), and it reconnects on its own.

Limitr Network

Services that sell to agents, and agents that pay for them, with signed vouchers instead of API keys. A service publishes its plans and routes from its policy, and serves them with one handler:

network = weather.network(secret_key=os.environ['WEATHER_SECRET_KEY'])
app = network.wsgi(lambda call: {'city': call.query.get('city'), 'forecast': 'sunny'})   # gunicorn, Flask, Django

An agent signs a voucher (up to this much, on this plan, until then) and gets the service's routes as tools:

agent = Limitr('policy: {}')
tools = agent.network().connect('https://weather.example', 'agent', 0.03, time.time() * 1000 + 3_600_000)
agent.claude_tools()                                          # pass to Claude as `tools`
agent.run_capability('acme_weather_forecast', {'city': 'Boston'})

The Network tutorial covers metering, a provider's own tools, operators and budgets, and identity and discovery, and demos/network runs a provider and an agent in two processes. It's the same protocol as the TypeScript SDK's, so either side can be either language.

Notes

  • Every method is one engine call, run one at a time (a lock guards the document), so a single allow is safe across threads. Use reserve and settle when concurrent calls must not overspend together.
  • Method names match the TypeScript SDK in snake_case (ensureCustomer is ensure_customer), and options are keyword arguments (allow(customer, entitlement, value, detail=True)).
  • Skills teach your coding agent to use Limitr: limitr-py (this SDK), limitr (policies, every engine function, and every event), and limitr-network. They're zips in content/, and in the Limitr plugin for Claude Code (/plugin marketplace add dev-formata-io/limitr).

Docs: limitr.dev. Policy semantics: the policy reference. Source: github.com/dev-formata-io/limitr. Chat: Discord. Apache 2.0.

Metadata

Release files for limitr 0.8.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for limitr 0.8.7
File Size Uploaded Provenance Actions
limitr-0.8.7.tar.gz 236.1 kB With provenance Details for limitr-0.8.7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for limitr 0.8.7
File Interpreter ABI Platform Actions
limitr-0.8.7-py3-none-any.whl Python 3 none any Details for limitr-0.8.7-py3-none-any.whl

Total release size: 475.0 kB

Release files / limitr-0.8.7.tar.gz

Download URL limitr-0.8.7.tar.gz
Size 236.1 kB
Tags Source
SHA-256 checksum
How to use checksums
e265451d9a8e2c45119c5a16aea123ed61cb98d213bef2558e3fc23f4e18597f
BLAKE2b-256 checksum
How to use checksums
94b0983a9a7916342cb29d880b874ab10b70e00f56d6c584f34c167986435fe1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / limitr-0.8.7-py3-none-any.whl

Download URL limitr-0.8.7-py3-none-any.whl
Size 238.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4b255c8c5cbfc115bd8e17738b3e820300e87e9454cb041e0d0683c24abce025
BLAKE2b-256 checksum
How to use checksums
98ee765053cf380c13b3599cfd62c4bf850c4bc1e2194dfb69afe86d28f021b7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for limitr 0.8.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for limitr-0.8.7.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.8.7 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page