Skip to main content

zae-limiter

PyPI version Conda version Python versions License Lint Tests codecov Docs

A rate limiting library backed by DynamoDB using the token bucket algorithm.

Installation

pip install zae-limiter
# or
conda install -c conda-forge zae-limiter

Usage

from zae_limiter import Repository, RateLimiter, SyncRepository, SyncRateLimiter, Limit

# Auto-provisions infrastructure if needed
repo = await Repository.open()
limiter = RateLimiter(repository=repo)

# Sync
sync_repo = SyncRepository.open()
sync_limiter = SyncRateLimiter(repository=sync_repo)

# Define default limits (can be overridden per-entity)
default_limits = [
    Limit.per_minute("rpm", 100),
    Limit.per_minute("tpm", 10_000),
]

async with limiter.acquire(
    entity_id="api-key-123",
    resource="gpt-4",
    limits=default_limits,  # Multiple limits in a single atomic transaction
    consume={"rpm": 1, "tpm": 500},  # Estimate tokens upfront
) as lease:
    response = await call_llm()
    # Reconcile actual usage (can go negative for post-hoc adjustment)
    await lease.adjust(tpm=response.usage.total_tokens - 500)
    # Tokens written to DynamoDB on enter | Rolled back on exception

# Hierarchical entities: create project with stored limits, then API key under it
await limiter.create_entity(entity_id="proj-1", name="Production")
await limiter.set_limits("proj-1", [Limit.per_minute("tpm", 100_000)])  # Project-level
await limiter.create_entity(entity_id="api-key-456", parent_id="proj-1", cascade=True)

# cascade is an entity property — acquire() auto-cascades to parent
with sync_limiter.acquire(
    entity_id="api-key-456",
    resource="gpt-4",
    limits=default_limits,
    consume={"rpm": 1, "tpm": 500},
):
    call_api()

# Multi-tenant: each tenant gets an isolated namespace
tenant_repo = await Repository.open("tenant-alpha")
tenant_limiter = RateLimiter(repository=tenant_repo)

# Cleanup (removes all data)
await repo.delete_stack()

Documentation

Full Documentation

Guide Description
Getting Started Installation, first deployment
Basic Usage Rate limiting patterns, error handling
Hierarchical Limits Parent/child entities, cascade mode
LLM Integration Token estimation and reconciliation
CLI Reference Deploy, status, delete commands
Multi-Tenant Guide Namespace isolation, per-tenant IAM
Production Guide Security, monitoring, cost

Production Deployment

The default deployment includes CloudWatch alarms and usage aggregation. For production, add data recovery and alert routing:

zae-limiter deploy --name my-app --region us-east-1 \
    --pitr-recovery-days 7 \
    --alarm-sns-topic arn:aws:sns:us-east-1:123456789012:alerts

For security best practices, multi-region considerations, and cost estimation, see the Production Guide.

Contributing

git clone https://github.com/zeroae/zae-limiter.git && cd zae-limiter
uv sync --all-extras
pytest

See the Contributing Guide for development setup, testing, and architecture details.

License

MIT

Metadata

Release files for zae-limiter 0.18.0

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

Source distribution (sdist)

Source distribution for zae-limiter 0.18.0
File Size Uploaded Provenance Actions
zae_limiter-0.18.0.tar.gz 3.3 MB With provenance Details for zae_limiter-0.18.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for zae-limiter 0.18.0
File Interpreter ABI Platform Actions
zae_limiter-0.18.0-py3-none-any.whl Python 3 none any Details for zae_limiter-0.18.0-py3-none-any.whl

Total release size: 4.2 MB

Release files / zae_limiter-0.18.0.tar.gz

Download URL zae_limiter-0.18.0.tar.gz
Size 3.3 MB
Tags Source
SHA-256 checksum
How to use checksums
1101094bc0e87471bbdb55425e651b4487be8eacb7915555ee2454ff32b1ec37
BLAKE2b-256 checksum
How to use checksums
12df18960fd1e6fbea548ec5782bf116eae55657aa92c697877dbd066df59c20
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 9, 2026.

Transparency log

Release files / zae_limiter-0.18.0-py3-none-any.whl

Download URL zae_limiter-0.18.0-py3-none-any.whl
Size 892.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0d121fcb6763e72914c256df362346429e941148c44fe651977e82b2f28596cc
BLAKE2b-256 checksum
How to use checksums
e4b26f4087e0a5a9451be7fca7ebc2c85f39c8c1b8148b784a05aebba851f93a
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 9, 2026.

Transparency log

Security for zae-limiter 0.18.0

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 zae_limiter-0.18.0.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 9, 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.

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