omkit

Multi-tenant SaaS scaffolding for Python services.

omkit is the Python side of Omur Labs' shared service toolkit. It bundles the boring-but-load-bearing pieces every tenant-isolated service needs: a Postgres pool that enforces Row-Level Security per connection, a pluggable event bus (Postgres LISTEN/NOTIFY or Valkey), session and settings stores, an LLM provider registry, BYOK encryption helpers, FastAPI observability middleware, and a cross-runtime job-queue envelope that interoperates with the Go sibling.

• Status: v0.2.0 — internal API stable.
• Python: >=3.12
• License: Apache-2.0
• Sibling: omkit-go — same primitives, same envelope contract, same RLS conventions.

Install

pip install git+https://github.com/omurlabs/omkit-python@v0.2.0

Optional extras:

pip install "omkit[tracing,metrics] @ git+https://github.com/omurlabs/omkit-python@v0.2.0"

Quickstart

A minimal tenant-aware FastAPI service wired up with the pieces omkit gives you:

from fastapi import FastAPI
from omkit.dbpool import create_pool
from omkit.tenant import TenantMiddleware
from omkit.transport import (
    configure_logging,
    init_tracing,
    instrument_fastapi,
    mount_metrics,
    mount_health_endpoints,
)

configure_logging()
init_tracing(service_name="my-service")

app = FastAPI()
app.add_middleware(TenantMiddleware)
instrument_fastapi(app)
mount_metrics(app)
mount_health_endpoints(app)

pool = await create_pool("postgresql://...")  # role-scoped, RLS-aware

Tenant context is set by TenantMiddleware and read by everything downstream (pool, event bus, logger, HTTP client, job envelope) via omkit.tenant.

Module index

Data & storage

Events & async

Job queue

Observability & resilience

Multi-tenant & config

LLM & security

Internal

omkit.internal holds private helpers (currently crypto.py). Not part of the stable surface — do not import.

Subpackage facades

Five subpackages re-export grouped primitives. Prefer importing from a facade when you only need the "shape" of a concern; reach into a flat module when you need a less common symbol.

Cross-SDK job envelope

omkit.jobqueue.Envelope is the same wire contract used by omkit-go/jobqueue. A Python streaq worker and a Go Asynq worker can publish and consume each other's jobs as long as they agree on ENVELOPE_VERSION and share the tenant routing rules. Pair it with a shared Valkey instance and either runtime can pick up either runtime's work.

Development

git clone git@github.com:omurlabs/omkit-python.git
cd omkit-python
pip install -e ".[dev,tracing,metrics]"

# Unit tests (no external services)
pytest

# Integration tests against a real Postgres
./scripts/test-with-postgres.sh

Test layout mirrors the module layout; every public module and facade has a matching tests/test_*.py.