Metadata-Version: 2.4
Name: fastloom
Version: 0.4.41
Summary: Core package
Requires-Python: >=3.12,<3.14
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
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: rabbit
Provides-Extra: redis
Provides-Extra: requests
Provides-Extra: test
Requires-Dist: babel (>=2.17.0,<3.0.0)
Requires-Dist: beanie (>=2.0.0,<3.0.0) ; extra == "mongo"
Requires-Dist: celery (>=5.5.3,<6.0.0) ; extra == "celery"
Requires-Dist: deepdiff (>=9.0.0,<10.0.0) ; extra == "test"
Requires-Dist: fastapi (>=0,<1) ; extra == "fastapi"
Requires-Dist: fastmcp (>=3.2.1,<4.0.0) ; extra == "mcp"
Requires-Dist: faststream[confluent,otel] ; extra == "kafka"
Requires-Dist: faststream[otel,rabbit] ; extra == "rabbit"
Requires-Dist: faststream[redis] ; extra == "redis"
Requires-Dist: freezegun (>=1.5.5,<2.0.0) ; extra == "test"
Requires-Dist: httpx (>=0.28.0,<0.29.0) ; extra == "httpx"
Requires-Dist: ipykernel (>=6.30.0,<7.0.0) ; extra == "dev"
Requires-Dist: jdatetime (>=4.1.1,<5.0.0)
Requires-Dist: jinja2 (>=3.1.6,<4.0.0)
Requires-Dist: logfire[asgi,celery,fastapi,httpx,openai,pymongo,redis,requests,system-metrics] (>=4.0.0,<5.0.0)
Requires-Dist: mypy (>=1.19,<2.0.0) ; extra == "dev"
Requires-Dist: openai (>=1,<2) ; extra == "openai"
Requires-Dist: opentelemetry-distro
Requires-Dist: opentelemetry-exporter-otlp
Requires-Dist: opentelemetry-instrumentation-aio-pika ; extra == "rabbit"
Requires-Dist: opentelemetry-instrumentation-confluent-kafka ; extra == "kafka"
Requires-Dist: orjson (==3.10.14)
Requires-Dist: pre-commit (>=4.5,<5.0.0) ; extra == "dev"
Requires-Dist: pydantic[email] (>=2.12,<3.0.0)
Requires-Dist: pytest (>=9.0.3,<10.0.0) ; extra == "test"
Requires-Dist: pytest-asyncio (>=1.3.0,<2.0.0) ; extra == "test"
Requires-Dist: pytest-cov (>=7.1.0,<8.0.0) ; extra == "test"
Requires-Dist: pytest-lazy-fixtures (>=1.4.0,<2.0.0) ; extra == "test"
Requires-Dist: pytest-mock (>=3.15.1,<4.0.0) ; extra == "test"
Requires-Dist: pytest-xdist (>=3.8.0,<4.0.0) ; extra == "test"
Requires-Dist: python-jose (>=3.5.0,<4.0.0)
Requires-Dist: python-multipart ; extra == "fastapi"
Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
Requires-Dist: redis-om (>=1.0,<2.0) ; extra == "redis"
Requires-Dist: requests (>=2.32.0,<3.0.0) ; extra == "requests"
Requires-Dist: ruff (>=0.15,<0.16.0) ; extra == "dev"
Requires-Dist: sentry-sdk[fastapi] (>=2.0.0,<3.0.0)
Requires-Dist: testcontainers (>=4.14.2,<5.0.0) ; extra == "test"
Requires-Dist: uvicorn (>=0.35.0,<0.36.0)
Requires-Dist: uvicorn ; extra == "fastapi"
Requires-Dist: uvicorn ; extra == "kafka"
Requires-Dist: uvicorn ; extra == "rabbit"
Project-URL: Repository, https://github.com/aradng/FastLoom
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`).
- 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
poetry add fastloom -E fastapi -E mongo -E 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.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 via FastStream)
    - Event-driven publish/subscribe with retries and DLX-based backoff
    - 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)
- DB (Mongo/Beanie) → [docs/db.md](docs/db.md)
- Signals (Rabbit) → [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)

---

## 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.

