# grelmicro

> grelmicro is a lightweight, async-first Python toolkit that ships microservice patterns as small composable modules with pluggable backends. It provides distributed locks, leader election, rate limiting, circuit breakers, cache, a transactional outbox, task scheduling, logging, tracing, metrics, and health checks. The same primitives serve microservices, a modular monolith, or a self-contained system.

Each primitive is a protocol, so you can swap Redis for PostgreSQL, SQLite, Kubernetes, or in-memory without changing application code. grelmicro is async-first, type-safe, and fully tested, and it drops into FastAPI, FastStream, and any asyncio stack. It is pre-1.0 and follows semantic versioning.

## Getting started

- [Introduction](https://grelmicro.grel.info/): what grelmicro is and the problem it solves.
- [Installation](https://grelmicro.grel.info/installation/): install with pip, uv, or poetry, plus optional extras for Redis, PostgreSQL, SQLite, Kubernetes, OpenTelemetry, and structlog.
- [First steps](https://grelmicro.grel.info/first-steps/): wire an app and use your first primitive.
- [Wiring](https://grelmicro.grel.info/wiring/): providers, components, and the application lifespan.

## User guide

- [Cache](https://grelmicro.grel.info/cache/): the `@cached` decorator with local and distributed stampede protection.
- [Idempotency](https://grelmicro.grel.info/idempotency/): idempotency keys that make a retried operation safe.
- [Coordination](https://grelmicro.grel.info/coordination/): distributed `Lock`, `TaskLock`, and `LeaderElection`.
- [Outbox](https://grelmicro.grel.info/outbox/): a transactional outbox that delivers messages at least once after your database transaction commits.
- [Task Scheduler](https://grelmicro.grel.info/task/): interval and cron tasks with durable, distributed at-most-once execution.
- [Resilience](https://grelmicro.grel.info/resilience/): circuit breaker and rate limiter with pluggable algorithms.
- [Health](https://grelmicro.grel.info/health/): a health check registry with FastAPI liveness and readiness integration.
- [Logging](https://grelmicro.grel.info/logging/): 12-factor logging with JSON, LOGFMT, TEXT, or PRETTY output.
- [Tracing](https://grelmicro.grel.info/tracing/): OpenTelemetry spans and structured log context through `@instrument`.
- [Metrics](https://grelmicro.grel.info/metrics/): OpenTelemetry metrics with a `@measure` decorator and a Prometheus router.
- [Configuration](https://grelmicro.grel.info/config/): reconfigure live components from a ConfigMap, Secret, or file.
- [Testing](https://grelmicro.grel.info/testing/): test grelmicro apps with the in-memory backends.

## API reference

- [API reference](https://grelmicro.grel.info/reference/cache/): reference for every public module, generated from the source docstrings.

## Architecture

- [Architecture](https://grelmicro.grel.info/architecture/): design decisions, backends, asyncio model, and internals.

## Optional

- [Comparison](https://grelmicro.grel.info/comparison/): grelmicro next to aiocache, slowapi, pybreaker, tenacity, and aioredlock.
- [Benchmarks](https://grelmicro.grel.info/benchmarks/): performance measurements for the primitives.
- [Changelog](https://grelmicro.grel.info/changelog/): release notes for every version.
- [Contributing](https://github.com/grelinfo/grelmicro/blob/main/CONTRIBUTING.md): how to report bugs, request features, and contribute code.
