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.17.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.17.0
File Size Uploaded Provenance Actions
zae_limiter-0.17.0.tar.gz 3.0 MB With provenance Details for zae_limiter-0.17.0.tar.gz

Built distribution (wheel)

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

Total release size: 3.8 MB

Release files / zae_limiter-0.17.0.tar.gz

Download URL zae_limiter-0.17.0.tar.gz
Size 3.0 MB
Tags Source
SHA-256 checksum
How to use checksums
28b163651fbe06d0c2af4429b48a7564ebb31f80aa1c496f7b1b22250b318dc9
BLAKE2b-256 checksum
How to use checksums
62fb4db3f69b2056b1f5370afb4a33eaaebb65dbfc1e7694c5a70c743e6f38a1
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 Oct 26, 2026.

Transparency log

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

Download URL zae_limiter-0.17.0-py3-none-any.whl
Size 797.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bddb2f24246f987e078176df5e63a41a56b6b97400146c1227c4087e6f47b3f2
BLAKE2b-256 checksum
How to use checksums
524ba2401cdcc15f94f25fd1b9e13546048b406e113014f4b01d7183597f455a
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 Oct 26, 2026.

Transparency log

Security for zae-limiter 0.17.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.17.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 Oct 26, 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