https://github.com/zeroae/zae-limiter
Token bucket rate limiter backed by DynamoDB
https://github.com/zeroae/zae-limiter
Last synced: 4 months ago
JSON representation
Token bucket rate limiter backed by DynamoDB
- Host: GitHub
- URL: https://github.com/zeroae/zae-limiter
- Owner: zeroae
- License: mit
- Created: 2026-01-10T01:56:31.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-02-15T01:39:32.000Z (4 months ago)
- Last Synced: 2026-02-15T01:40:21.524Z (4 months ago)
- Language: Python
- Homepage: https://zeroae.github.io/zae-limiter/
- Size: 13 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 66
-
Metadata Files:
- Readme: README.md
- Contributing: docs/contributing/architecture.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://pypi.org/project/zae-limiter/)
[](https://anaconda.org/conda-forge/zae-limiter)
[](https://pypi.org/project/zae-limiter/)
[](https://github.com/zeroae/zae-limiter/blob/main/LICENSE)
[](https://github.com/zeroae/zae-limiter/actions/workflows/ci-lint.yml)
[](https://github.com/zeroae/zae-limiter/actions/workflows/ci-tests.yml)
[](https://codecov.io/gh/zeroae/zae-limiter)
[](https://zeroae.github.io/zae-limiter/)
A rate limiting library backed by DynamoDB using the token bucket algorithm.
## Installation
```bash
pip install zae-limiter
# or
conda install -c conda-forge zae-limiter
```
## Usage
```python
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](https://zeroae.github.io/zae-limiter/)**
| Guide | Description |
|-------|-------------|
| [Getting Started](https://zeroae.github.io/zae-limiter/getting-started/) | Installation, first deployment |
| [Basic Usage](https://zeroae.github.io/zae-limiter/guide/basic-usage/) | Rate limiting patterns, error handling |
| [Hierarchical Limits](https://zeroae.github.io/zae-limiter/guide/hierarchical/) | Parent/child entities, cascade mode |
| [LLM Integration](https://zeroae.github.io/zae-limiter/guide/llm-integration/) | Token estimation and reconciliation |
| [CLI Reference](https://zeroae.github.io/zae-limiter/cli/) | Deploy, status, delete commands |
| [Multi-Tenant Guide](https://zeroae.github.io/zae-limiter/infra/production/#multi-tenant-deployments) | Namespace isolation, per-tenant IAM |
| [Production Guide](https://zeroae.github.io/zae-limiter/infra/production/) | Security, monitoring, cost |
## Production Deployment
The default deployment includes CloudWatch alarms and usage aggregation. For production, add data recovery and alert routing:
```bash
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](https://zeroae.github.io/zae-limiter/infra/production/).
## Contributing
```bash
git clone https://github.com/zeroae/zae-limiter.git && cd zae-limiter
uv sync --all-extras
pytest
```
See the [Contributing Guide](https://zeroae.github.io/zae-limiter/contributing/) for development setup, testing, and architecture details.
## License
MIT