omkit 0.0.2__tar.gz

omkit-0.0.2/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: omkit
+Version: 0.0.2
+Summary: Multi-tenant SaaS scaffolding for Python services.
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.13
+Requires-Dist: pydantic-settings>=2.13
+Requires-Dist: asyncpg>=0.31
+Requires-Dist: redis>=7.4
+Requires-Dist: structlog>=25.5
+Requires-Dist: cryptography>=47.0
+Requires-Dist: tenacity>=9.1
+Requires-Dist: prometheus_client>=0.25
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: sqlalchemy[asyncio]>=2.0.49
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.136.0; extra == "dev"
+Requires-Dist: pytest>=9.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.3; extra == "dev"
+Requires-Dist: redis>=7.4; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Provides-Extra: tracing
+Requires-Dist: opentelemetry-api>=1.41.0; extra == "tracing"
+Requires-Dist: opentelemetry-sdk>=1.41.0; extra == "tracing"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.41.0; extra == "tracing"
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.62b0; extra == "tracing"
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.62b0; extra == "tracing"
+Provides-Extra: metrics
+Requires-Dist: prometheus-fastapi-instrumentator>=7.1; extra == "metrics"

omkit-0.0.2/README.md

@@ -0,0 +1,17 @@
+# omkit
+
+Multi-tenant SaaS scaffolding for Python services. Pooled Postgres with RLS, Valkey eventbus, BYOK secrets, LLM provider abstraction, FastAPI observability middleware, and tenant-scoped session/job primitives.
+
+```
+pip install git+https://github.com/omurlabs/omkit-python@v0.0.1
+```
+
+```python
+from omkit.dbpool import create_pool
+from omkit.eventbus import EventBus
+from omkit.settings import SettingsManager
+```
+
+Status: v0.0.1 — initial extraction. API is pre-stable; expect renames before v0.1.
+
+License: Apache-2.0 (planned).

omkit-0.0.2/omkit/__init__.py

@@ -0,0 +1,18 @@
+"""omkit — multi-tenant SaaS scaffolding for Python services.
+
+Public surface re-exports a small set of commonly-used helpers. Internal
+primitives are available via the submodules directly.
+"""
+from omkit.http import build_tenant_client
+from omkit.metrics import mount_metrics
+from omkit.settings import SettingsManager
+from omkit import tenant
+from omkit.tracing import instrument_fastapi
+
+__all__ = [
+    "build_tenant_client",
+    "mount_metrics",
+    "SettingsManager",
+    "tenant",
+    "instrument_fastapi",
+]

omkit-0.0.2/omkit/cleanup.py

@@ -0,0 +1,62 @@
+"""packages/omur-sdk/omkit/cleanup.py — Coordinated periodic cleanup task runner.
+
+Loop.run() fires the provided ``task`` coroutine every ``interval`` seconds
+while holding ``pg_try_advisory_lock(lock_key)`` — horizontally scaled
+replicas of the same service won't double-execute the cleanup. Lock
+contention turns the tick into a silent no-op.
+
+exports: class Loop
+rules:   The Loop class must maintain a single persistent connection pool instance throughout its lifetime and cannot be instantiated without a valid pool argument. The run() method implements a blocking infinite loop that should only be called once per Loop instance and cannot be interrupted without external process termination. All database operations within the loop must use async context management to ensure proper connection handling and automatic release back to the pool.
+agent:   ollama/qwen3-coder:latest | ollama | 2026-05-01 | codedna-cli | initial CodeDNA annotation pass
+message: 
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Awaitable, Callable
+
+log = logging.getLogger(__name__)
+
+
+class Loop:
+    def __init__(
+        self,
+        pool,
+        *,
+        lock_key: int,
+        interval: float,
+        task: Callable[[], Awaitable[None]],
+        name: str = "cleanup-loop",
+    ):
+        self._pool = pool
+        self._lock_key = lock_key
+        self._interval = interval
+        self._task = task
+        self._name = name
+
+    async def run(self) -> None:
+        """
+        Rules:   The function runs an infinite loop that must be properly cancelled or stopped to prevent resource leaks. The _tick() method and _interval attribute must be properly initialized before calling this function.
+        """
+        while True:
+            try:
+                await self._tick()
+            except Exception as e:
+                log.warning("%s: tick failed: %s", self._name, e)
+            await asyncio.sleep(self._interval)
+
+    async def _tick(self) -> None:
+        async with self._pool.acquire() as conn:
+            got = await conn.fetchval(
+                "SELECT pg_try_advisory_lock($1)", self._lock_key
+            )
+            if not got:
+                return
+            try:
+                await self._task()
+            finally:
+                await conn.execute(
+                    "SELECT pg_advisory_unlock($1)", self._lock_key
+                )

omkit-0.0.2/omkit/config.py

@@ -0,0 +1,60 @@
+"""Shared base settings for services using omkit.
+
+Subclass BaseServiceSettings in each service and add service-specific
+fields. Pydantic-settings maps UPPERCASE env vars to these fields
+automatically.
+"""
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class BaseServiceSettings(BaseSettings):
+    """Common env vars shared across backend services."""
+
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    # Runtime
+    RUNTIME_MODE: str = "standalone"
+    TENANT_TOKEN: str = ""
+    settings_key: str = Field(default="", alias="SETTINGS_KEY")
+
+    # CORS
+    CORS_ORIGINS: str = ""
+
+    # PostgreSQL
+    POSTGRES_HOST: str = "postgres"
+    POSTGRES_PORT: int = 5432
+    POSTGRES_DB: str = ""
+    POSTGRES_USER: str = ""
+    POSTGRES_PASSWORD: str = ""
+
+    # Valkey (Redis-compatible, Apache 2.0)
+    VALKEY_HOST: str = "valkey"
+    VALKEY_PORT: int = 6379
+    VALKEY_PASSWORD: str = ""
+
+    # Ollama
+    OLLAMA_HOST: str = "http://ollama:11434"
+    OLLAMA_CHAT_MODEL: str = "qwen3:8b"
+
+    @property
+    def postgres_dsn(self) -> str:
+        return (
+            f"postgresql+asyncpg://{self.POSTGRES_USER}:{self.POSTGRES_PASSWORD}"
+            f"@{self.POSTGRES_HOST}:{self.POSTGRES_PORT}/{self.POSTGRES_DB}"
+        )
+
+    @property
+    def postgres_dsn_raw(self) -> str:
+        """Plain postgresql:// DSN for drivers that don't accept asyncpg dialect."""
+        return (
+            f"postgresql://{self.POSTGRES_USER}:{self.POSTGRES_PASSWORD}"
+            f"@{self.POSTGRES_HOST}:{self.POSTGRES_PORT}/{self.POSTGRES_DB}"
+        )
+
+    @property
+    def valkey_url(self) -> str:
+        if self.VALKEY_PASSWORD:
+            return f"redis://:{self.VALKEY_PASSWORD}@{self.VALKEY_HOST}:{self.VALKEY_PORT}"
+        return f"redis://{self.VALKEY_HOST}:{self.VALKEY_PORT}"

omkit-0.0.2/omkit/cost.py

@@ -0,0 +1,78 @@
+"""omkit.cost — provider cost telemetry.
+
+Records a Prometheus counter ``cost_units_total`` with a fixed
+low-cardinality label set so VictoriaMetrics scrape stays cheap:
+
+- ``service``       — emitting service name.
+- ``provider``      — backend identifier (``local``, ``voyage``, ``openai``, …).
+- ``op``            — operation name (``embed``, ``parse_pages``,
+                      ``rerank``, ``stt_seconds``, ``tts_chars``).
+- ``tenant_bucket`` — coarse tenant grouping (``system`` / ``trial`` /
+                      ``paid``); never the raw tenant_id (cardinality).
+
+The ``units`` argument is the billable count for the operation
+(``tokens``, ``pages``, ``audio_seconds``, …). Dollar projection lives
+out of scope — a static price-table joins counter values in Grafana.
+"""
+
+from __future__ import annotations
+
+from typing import Final, Literal
+
+from prometheus_client import Counter
+
+TenantBucket = Literal["system", "trial", "paid"]
+
+_VALID_BUCKETS: Final[frozenset[str]] = frozenset({"system", "trial", "paid"})
+
+COST_UNITS_TOTAL: Final[Counter] = Counter(
+    "cost_units_total",
+    "Billable units emitted by a provider call (tokens, pages, seconds, chars).",
+    labelnames=("service", "provider", "op", "tenant_bucket"),
+)
+
+
+def record_cost(
+    *,
+    service: str,
+    provider: str,
+    op: str,
+    units: float,
+    tenant_bucket: TenantBucket | str,
+) -> None:
+    """Increment ``cost_units_total`` for one provider call.
+
+    Args:
+        service: Emitting service name.
+        provider: Backend identifier (``local``, ``voyage``, ``openai``, …).
+        op: Operation name (``embed``, ``parse_pages``, ``rerank``,
+            ``stt_seconds``, ``tts_chars``).
+        units: Billable count for the operation (tokens, pages,
+            audio_seconds, character_count). Non-positive values are a
+            no-op — counters cannot decrease and a non-positive input is
+            always a caller bug.
+        tenant_bucket: Coarse tenant grouping. Unknown values are
+            normalised to ``trial`` so an instrumentation typo does not
+            silently inflate the ``paid`` bucket.
+
+    Returns:
+        None — emission is best-effort. Failure to record never raises;
+        the caller is on a hot path and a metric blip must not break it.
+    """
+
+    if units <= 0:
+        return
+    bucket = tenant_bucket if tenant_bucket in _VALID_BUCKETS else "trial"
+    try:
+        COST_UNITS_TOTAL.labels(
+            service=service,
+            provider=provider,
+            op=op,
+            tenant_bucket=bucket,
+        ).inc(units)
+    except Exception:
+        # Counter emission is best-effort — never propagate.
+        return
+
+
+__all__ = ["COST_UNITS_TOTAL", "TenantBucket", "record_cost"]

omkit-0.0.2/omkit/data/__init__.py

@@ -0,0 +1,33 @@
+"""packages/omur-sdk/omkit/data/__init__.py — re-exports DB pool and session-store primitives.
+
+Additive grouping. Flat-module imports continue to work.
+
+exports: none
+rules:   The module must maintain backward compatibility for all existing data import paths and cannot introduce breaking changes to the public API surface. All data processing functions must be thread-safe and handle concurrent access without race conditions. The module cannot depend on external packages beyond the standard library and explicitly declared dependencies in the package manifest.
+agent:   ollama/qwen3-coder:latest | ollama | 2026-05-01 | codedna-cli | initial CodeDNA annotation pass
+message: 
+"""
+
+from omkit.dbpool import (
+    build_retrieval_engine,
+    create_pool,
+    new_session_pool,
+    sqlalchemy_asyncpg_connect_args,
+)
+from omkit.sessions import (
+    NotFound,
+    Session,
+    SessionStore,
+    new_store,
+)
+
+__all__ = [
+    "build_retrieval_engine",
+    "create_pool",
+    "new_session_pool",
+    "sqlalchemy_asyncpg_connect_args",
+    "SessionStore",
+    "Session",
+    "NotFound",
+    "new_store",
+]

omkit-0.0.2/omkit/dbpool.py

@@ -0,0 +1,139 @@
+"""packages/omur-sdk/omkit/dbpool.py — asyncpg pool helper that enforces a Postgres role via the init coroutine.
+
+Runs ``SET ROLE <role>`` on every new physical connection so the role is
+guaranteed even across reconnects — the async equivalent of pgx's
+``AfterConnect`` hook. This is the defence-in-depth mechanism we rely on
+after removing PgBouncer (which previously took care of the role reset via
+``server_reset_query``).
+
+exports: sqlalchemy_asyncpg_connect_args(role) | new_session_pool(dsn) | create_pool(dsn) | build_retrieval_engine(dsn)
+rules:   The module must maintain backward compatibility with existing SQLAlchemy and asyncpg integration patterns, and all database connection handling must adhere to async/await semantics throughout.
+agent:   ollama/qwen3-coder:latest | ollama | 2026-05-01 | codedna-cli | initial CodeDNA annotation pass
+message: 
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+import asyncpg
+
+
+def sqlalchemy_asyncpg_connect_args(role: str | None = "omur_app") -> dict[str, Any]:
+    """Return ``connect_args`` for ``create_async_engine(..., connect_args=...)``.
+
+    Keeps the engine pgbouncer-transaction-mode-compatible
+    (``statement_cache_size=0``, ``prepared_statement_cache_size=0``) and,
+    when ``role`` is non-empty, applies ``SET ROLE <role>`` at connection
+    startup via asyncpg's ``server_settings`` dict so every pool
+    checkout already runs as the restricted role without any sync-event
+    listener. Pass ``role=None`` to opt out.
+
+    Running the role switch through ``server_settings`` (rather than a
+    sync ``"connect"`` event listener that calls ``dbapi_conn.cursor()``)
+    avoids a greenlet race between SQLAlchemy's async adapter and
+    asyncpg's connection init — the listener would occasionally see a
+    half-initialized DBAPI connection and raise ``'NoneType' object
+    has no attribute 'cursor'`` / ``'commit'``. asyncpg issues
+    ``SET name = value`` for every entry in ``server_settings`` during
+    the connection handshake, before the connection is handed to the
+    pool, so the role is always in place by the time SQLAlchemy sees
+    the connection.
+
+    Rules:   The function assumes that the `role` parameter is either a valid PostgreSQL role name or None. If a role is provided, it must exist in the database, and the calling user must have permission to switch to that role.
+    """
+    args: dict[str, Any] = {
+        "statement_cache_size": 0,
+        "prepared_statement_cache_size": 0,
+    }
+    if role:
+        args["server_settings"] = {"role": role}
+    return args
+
+
+def build_retrieval_engine(dsn: str):
+    """Build the dedicated SQLAlchemy retrieval engine shared by frontal + marrow.
+
+    Tuning matches Option A of the hybrid-search spec:
+    pool_size=10, max_overflow=0, pool_timeout=2 — pool exhaustion fast-fails as
+    TimeoutError so the caller can map to HTTP 503 instead of unbounded queue
+    waits. Keeps retrieval traffic isolated from the ingestion pool.
+
+    Returns an async engine; caller binds it to its own AsyncSession class
+    (sqlalchemy vs sqlmodel session subclass).
+    """
+    from sqlalchemy.ext.asyncio import create_async_engine
+
+    return create_async_engine(
+        dsn,
+        echo=False,
+        pool_size=10,
+        max_overflow=0,
+        pool_timeout=2,
+        connect_args=sqlalchemy_asyncpg_connect_args(),
+    )
+
+
+async def new_session_pool(dsn: str, **kwargs) -> asyncpg.Pool:
+    """Build an asyncpg pool for :class:`omkit.sessions.PostgresSessionStore`.
+
+    The session pool intentionally does **not** run ``SET ROLE omur_app``
+    on each new connection. Token-based session lookup (``get``/``delete``)
+    takes an opaque token without knowing the tenant, so SELECT/DELETE
+    under a role that's subject to the ``sessions_tenant_isolation`` RLS
+    policy would silently return zero rows. Connecting as the default
+    ``omur`` superuser (which has ``BYPASSRLS``) lets token lookup cross
+    tenants; writes (``put``, ``list``) still run inside a transaction
+    that sets ``app.tenant_id`` so RLS is honored for multi-tenant
+    mutations.
+
+    Use this helper in service lifespans that need a SessionStore. For
+    pools that back RLS-enforced app queries, use :func:`create_pool`
+    with ``role='omur_app'`` instead.
+
+    Rules:   The function intentionally avoids setting a role on connections to allow cross-tenant session lookups. Future developers must understand that this design relies on the `omur` superuser having `BYPASSRLS` privileges to ensure proper behavior.
+    """
+    return await create_pool(dsn, **kwargs)
+
+
+def _normalize_dsn(dsn: str) -> str:
+    """Strip a SQLAlchemy dialect suffix like ``+asyncpg`` from the URL
+    scheme so asyncpg accepts a DSN that was originally shaped for
+    ``create_async_engine``."""
+    return re.sub(r"^(postgres(?:ql)?)\+[a-z0-9_]+://", r"\1://", dsn, count=1)
+
+
+async def create_pool(
+    dsn: str,
+    *,
+    role: Optional[str] = None,
+    min_size: int = 1,
+    max_size: int = 10,
+    **kwargs,
+) -> asyncpg.Pool:
+    """Create an asyncpg pool. If ``role`` is given, every new physical
+    connection runs ``SET ROLE "<role>"`` via the init coroutine.
+
+    ``statement_cache_size`` defaults to ``0`` so that pgbouncer in
+    transaction mode can be reintroduced as a pure config change
+    (prepared statements don't survive across pgbouncer's per-transaction
+    server rotation). Callers can override by passing ``statement_cache_size``
+
+    Rules:   If `role` is provided, it must be a valid PostgreSQL role name, and the calling user must have the necessary permissions to execute `SET ROLE <role>`. Additionally, `statement_cache_size` is defaulted to 0 for pgbouncer compatibility, but callers can override this if needed.
+    explicitly."""
+
+    async def _init(conn: asyncpg.Connection) -> None:
+        if role:
+            await conn.execute(f'SET ROLE "{role}"')
+
+    if role:
+        kwargs.setdefault("init", _init)
+    kwargs.setdefault("statement_cache_size", 0)
+
+    return await asyncpg.create_pool(
+        _normalize_dsn(dsn),
+        min_size=min_size,
+        max_size=max_size,
+        **kwargs,
+    )

omkit-0.0.2/omkit/encryption.py

@@ -0,0 +1,58 @@
+"""packages/omur-sdk/omkit/encryption.py — Fernet-based encryption utilities for Omur settings secrets.
+
+exports: generate_key() | encrypt_value(plaintext, key) | decrypt_value(ciphertext, key) | mask_secret(value)
+rules:   The encryption module must maintain backward compatibility with all existing encrypted data formats and key structures. All cryptographic operations must be deterministic and reproducible across different runtime environments. The module cannot introduce any external dependencies beyond the standard library and the fernet package.
+agent:   ollama/qwen3-coder:latest | ollama | 2026-05-01 | codedna-cli | initial CodeDNA annotation pass
+message: 
+"""
+
+from cryptography.fernet import Fernet, InvalidToken
+
+
+def generate_key() -> str:
+    """Generate a new Fernet-compatible key (URL-safe base64).
+
+    Rules:   Key must be stored securely and never logged or exposed in plaintext. The generated key is URL-safe base64 encoded and should be persisted in a secure key management system.
+    """
+    return Fernet.generate_key().decode()
+
+
+def encrypt_value(plaintext: str, key: str) -> str:
+    """Encrypt a string value. Returns base64-encoded ciphertext.
+
+    Rules:   The key must be a valid Fernet-compatible key (URL-safe base64 encoded string) or the function will raise a ValueError.
+    """
+    f = Fernet(key.encode())
+    return f.encrypt(plaintext.encode()).decode()
+
+
+def decrypt_value(ciphertext: str, key: str) -> str:
+    """Decrypt a base64-encoded ciphertext string.
+
+    Raises cryptography.fernet.InvalidToken if the key is wrong or the
+    token is malformed/tampered.
+
+    Rules:   The key must match the one used for encryption, and the ciphertext must be a valid Fernet token; otherwise, cryptography.fernet.InvalidToken will be raised.
+    """
+    f = Fernet(key.encode())
+    return f.decrypt(ciphertext.encode()).decode()
+
+
+def mask_secret(value: str | None) -> str | None:
+    """Mask a secret for API display.
+
+    - Values >= 10 chars: first 4 + '****' + last 4  (e.g. 'sk-a****Xk2f')
+    - Values 4-9 chars:   first 2 + '****' + last 2  (e.g. 'ab****ef')
+    - Values < 4 chars:   '****'
+    - None or empty:      returns None
+
+    Rules:   The function assumes ASCII-compatible strings; non-ASCII characters may produce unexpected masking behavior due to byte-level string slicing.
+    """
+    if not value:
+        return None
+    n = len(value)
+    if n >= 10:
+        return value[:4] + "****" + value[-4:]
+    if n >= 4:
+        return value[:2] + "****" + value[-2:]
+    return "****"