Metadata-Version: 2.3
Name: fastloom
Version: 0.5.8
Summary: Core package
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Dist: jdatetime>=4.1.1,<6.0.0
Requires-Dist: python-jose>=3.5.0,<4.0.0
Requires-Dist: pydantic[email]>=2.12,<3.0.0
Requires-Dist: uvicorn>=0.35.0,<0.52.0
Requires-Dist: orjson>=3.10.14,<4.0.0
Requires-Dist: pyyaml>=6.0.2,<7.0.0
Requires-Dist: logfire[system-metrics,asgi,fastapi,celery,httpx,requests,redis,pymongo,openai]>=4.0.0,<5.0.0
Requires-Dist: sentry-sdk[fastapi]>=2.0.0,<3.0.0
Requires-Dist: opentelemetry-distro
Requires-Dist: opentelemetry-exporter-otlp
Requires-Dist: babel>=2.17.0,<3.0.0
Requires-Dist: jinja2>=3.1.6,<4.0.0
Requires-Dist: celery>=5.5.3,<6.0.0 ; extra == 'celery'
Requires-Dist: prek>=0.5,<0.6 ; extra == 'dev'
Requires-Dist: ruff>=0.15,<0.16.0 ; extra == 'dev'
Requires-Dist: mypy>=1.19,<3.0.0 ; extra == 'dev'
Requires-Dist: ipykernel>=6.30.0,<8.0.0 ; extra == 'dev'
Requires-Dist: fastapi>=0,<1 ; extra == 'fastapi'
Requires-Dist: uvicorn ; extra == 'fastapi'
Requires-Dist: python-multipart ; extra == 'fastapi'
Requires-Dist: httpx>=0.28.0,<0.29.0 ; extra == 'httpx'
Requires-Dist: uvicorn ; extra == 'kafka'
Requires-Dist: faststream[otel,confluent] ; extra == 'kafka'
Requires-Dist: fastmcp>=3.4.4,<4.0.0 ; extra == 'mcp'
Requires-Dist: beanie>=2.0.0,<3.0.0 ; extra == 'mongo'
Requires-Dist: openai>=1,<3 ; extra == 'openai'
Requires-Dist: starlette>=0.40.0,<2.0.0 ; extra == 'policy'
Requires-Dist: click>=8.1.0,<9.0.0 ; extra == 'policy'
Requires-Dist: uvicorn ; extra == 'rabbit'
Requires-Dist: faststream[otel,rabbit] ; extra == 'rabbit'
Requires-Dist: opentelemetry-instrumentation-aio-pika ; extra == 'rabbit'
Requires-Dist: faststream[redis] ; extra == 'redis'
Requires-Dist: redis-om>=1.0,<2.0 ; extra == 'redis'
Requires-Dist: fastapi-redis-sdk[otel]>=0.7.0,<0.8.0 ; extra == 'redis'
Requires-Dist: requests>=2.32.0,<3.0.0 ; extra == 'requests'
Requires-Dist: pytest>=9.0.3,<10.0.0 ; extra == 'test'
Requires-Dist: pytest-mock>=3.15.1,<4.0.0 ; extra == 'test'
Requires-Dist: pytest-cov>=7.1.0,<8.0.0 ; extra == 'test'
Requires-Dist: pytest-xdist>=3.8.0,<4.0.0 ; extra == 'test'
Requires-Dist: pytest-asyncio>=1.3.0,<2.0.0 ; extra == 'test'
Requires-Dist: testcontainers>=4.14.2,<5.0.0 ; extra == 'test'
Requires-Dist: deepdiff>=9.0.0,<10.0.0 ; extra == 'test'
Requires-Dist: freezegun>=1.5.5,<2.0.0 ; extra == 'test'
Requires-Dist: pytest-lazy-fixtures>=1.4.0,<2.0.0 ; extra == 'test'
Requires-Dist: httpx2>=2.5.0,<3.0.0 ; extra == 'test'
Requires-Python: >=3.12, <3.14
Project-URL: Repository, https://github.com/aradng/FastLoom
Provides-Extra: celery
Provides-Extra: dev
Provides-Extra: fastapi
Provides-Extra: httpx
Provides-Extra: kafka
Provides-Extra: mcp
Provides-Extra: mongo
Provides-Extra: openai
Provides-Extra: policy
Provides-Extra: rabbit
Provides-Extra: redis
Provides-Extra: requests
Provides-Extra: test
Description-Content-Type: text/markdown

# Fastloom – The Open Foundation for Building Event-Driven Services

Fastloom is a lightweight, batteries-included foundation for building modern backends. Define your settings, schemas, and endpoints; Fastloom wires up the rest: FastAPI, Mongo (Beanie), Rabbit (FastStream), metrics/traces/logs/errors, and more.

Think of it as the glue for your stack: web, messaging, caching, DB, observability, and integrations with best-in-class tools.

---

## Why Fastloom

- No boilerplate: minimal scaffolding/templating; most wiring is handled inside the library.
- Composable: opt into only what you need via extras (`fastapi`, `rabbit`, `kafka`, `mongo`, `redis`, `mcp`, `celery`, `openai`, `policy`).
- Pydantic-first: type-safe models, validators, and clear input/output contracts.
- Multi-tenant by design: tenant context flows through DI and storage.
- AuthN/Z via DI: OIDC token introspection and pluggable PDP (ABAC/RBAC/ReBAC) hooks.
- Event-driven ready: publish/subscribe with routing keys and health.
- Observability-native: metrics, traces, logs from day one.
- Self-hostable: production parity with a cloud/aaS setup.

---

## Integrated Services (the platform)

Fastloom plugs into a family of self-hostable services:

- IAM → OIDC/SSO, authN/Z, RBAC/ABAC/ReBAC.
- Notify → realtime notifications, Pusher-compatible API.
- Pulse → user activity + event tracking with OpenTelemetry hooks.
- File → object storage on MinIO (S3-compatible).
- Finance, Subscription, SMS/Email, Meet, Persona → optional services you can wire in.

Each service is:
- self-hostable (Docker Compose or Helm),
- BaaS-available.

---

## Quick start

```bash
# Install fastloom with the extras you need
uv add "fastloom[fastapi,mongo,rabbit]"
```

A minimal service is two files at the project root — `settings.py` and `app.py` — plus a `tenants.yaml` for defaults:

```python
# settings.py
from fastloom.db.settings import MongoSettings
from fastloom.launcher.settings import LauncherSettings
from fastloom.observability.settings import ObservabilitySettings
from fastloom.settings.general import BaseGeneralSettings
from fastloom.signals.rabbit.settings import RabbitmqSettings


class Settings(
    BaseGeneralSettings,
    LauncherSettings,
    MongoSettings,
    RabbitmqSettings,
    ObservabilitySettings,
): ...
```

```python
# app.py
from fastapi import APIRouter

from fastloom.launcher.schemas import App

from my_service import models, signals

router = APIRouter()


@router.get("/ping")
async def ping() -> dict[str, str]:
    return {"pong": "ok"}


app = App(
    routes=[(router, "", "Health")],
    models_module=models,
    signals_module=signals,
)
```

```yaml
# tenants.yaml
default:
    ENVIRONMENT: development
    PROJECT_NAME: my_service
    MONGO_URI: mongodb://localhost:27017
    MONGO_DATABASE: my_service
    RABBIT_URI: amqp://guest:guest@localhost:5672/
```

Run with the bundled CLI (registered as `launch` via `[project.scripts]`):

```bash
launch
```

See [docs/quickstart.md](docs/quickstart.md) for a fuller walkthrough.

---

## What you get out of the box

- App orchestrator (`fastloom.launcher`)
    - Discovers your routes, models, signals, and healthchecks from `app.py` / `settings.py`
    - Exposes settings and health endpoints (public toggle via `LauncherSettings.SETTINGS_PUBLIC`)
- FastAPI-native
    - Dependency-injected request/tenant context and guards
    - Clear routing, OpenAPI, and dependency injection patterns
- Auth & Access
    - DI-based guards with OIDC / OAuth2 token introspection
    - Optional IAM sidecar for introspection + ACL
- Multi-tenancy
    - Tenant-aware DI context across web, DB, and messaging
    - Per-tenant settings endpoint backed by DB + cache, with `tenants.yaml` defaults
- Database layer (MongoDB via Beanie)
    - Created/updated mixins, pagination utilities, typed helpers
    - Auto model discovery for DB init via `App.models_module`
- Signals / Messaging (Rabbit + Kafka via FastStream)
    - Rabbit: event-driven publish/subscribe with retries and DLX-based backoff
    - Kafka: subscriber/publisher wiring for consuming topics (e.g. Debezium CDC), with `NACK_ON_ERROR`-backed exponential backoff by default
    - Subscriber wiring and healthchecks
    - Auto-streamed `BaseDocumentSignal` Beanie models
- Observability
    - OpenTelemetry distro + OTLP exporter, Logfire, Sentry (errors + profiling)
- I18N
    - Exception handler and template utils with Babel/Jinja2
- Healthchecks
    - Automatic app/DB/messaging/cache checks + system routes
- MCP
    - Optional FastMCP mount with bearer auth forwarding
- Pydantic-native schemas and validators
    - Schema In/Out validation for request/response contracts
    - Common types and validators (`fastloom.types`)

Dive deeper in the docs below.

---

## Documentation

- Quickstart → [docs/quickstart.md](docs/quickstart.md)
- Conventions → [docs/conventions.md](docs/conventions.md)
- Launcher & App model → [docs/launcher.md](docs/launcher.md)
- Settings & Configs → [docs/settings.md](docs/settings.md)
- Tenant → [docs/tenant.md](docs/tenant.md)
- Auth → [docs/auth.md](docs/auth.md)
- Policy (OPA route coverage) → [docs/policy.md](docs/policy.md)
- DB (Mongo/Beanie) → [docs/db.md](docs/db.md)
- Signals (Rabbit / Kafka) → [docs/signals.md](docs/signals.md)
- Cache (Redis) → [docs/cache.md](docs/cache.md)
- Healthchecks → [docs/healthcheck.md](docs/healthcheck.md)
- Observability → [docs/observability.md](docs/observability.md)
- File storage → [docs/file.md](docs/file.md)
- I18N → [docs/i18n.md](docs/i18n.md)
- MCP → [docs/mcp.md](docs/mcp.md)
- Testing → [docs/test.md](docs/test.md)
- Internal testing (fastloom's own suite) → [docs/internal-testing.md](docs/internal-testing.md)

---

## Claude Code integration

If you build services on top of fastloom and use Claude Code, you can install the `fastloom-sdk` plugin. It bundles:

- **Scaffolding skills** — `scaffold-fastloom-service`, `add-fastloom-route`, `add-rabbit-subscriber`.
- **Audit skill** — `audit-fastloom-settings` flags misuse in your `settings.py` / `tenants.yaml`.
- **Reference skill** — `fastloom-reference` ships the full `docs/` so Claude can ground its answers in the canonical documentation instead of guessing from training data.

```bash
/plugin marketplace add aradng/FastLoom
/plugin install fastloom-sdk@fastloom
```

Skills auto-activate from context (e.g. asking "how does fastloom auth work?" triggers `fastloom-reference`); explicit invocation is `/fastloom-sdk:<skill-name>`. The plugin is opt-in per user and doesn't ship via PyPI — it's distributed through the marketplace in this same repo.

---

## Roadmap

- More CLI scaffolds and blueprints.
- Automatic `pydantic-ai` agentic tool creation from APIs.
- Migrate PDP to [`OPAL`](https://github.com/permitio/opal) / [`opa`](https://github.com/open-policy-agent/opa) based.
