dbl-gateway 0.3.2__tar.gz

dbl_gateway-0.3.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lukas Pfister
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dbl_gateway-0.3.2/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: dbl-gateway
+Version: 0.3.2
+Summary: DBL Gateway
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dbl-core<0.4.0,>=0.3.2
+Requires-Dist: dbl-policy<0.2.0,>=0.1.0
+Requires-Dist: dbl-main<0.4.0,>=0.3.0
+Requires-Dist: dbl-ingress<0.2.0,>=0.1.1
+Requires-Dist: kl-kernel-logic<0.6.0,>=0.5.0
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn>=0.27.0
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Requires-Dist: ruff<1,>=0.5; extra == "dev"
+Requires-Dist: mypy<2,>=1.10; extra == "dev"
+Requires-Dist: dbl-reference>=0.2.0; extra == "dev"
+Provides-Extra: oidc
+Requires-Dist: python-jose[cryptography]<4,>=3.3; extra == "oidc"
+Dynamic: license-file
+
+# DBL Gateway 0.3.2
+
+Authoritative DBL and KL gateway. This service is the single writer for append-only trails,
+applies policy via dbl-policy, and executes via kl-kernel-logic. UI and boundary services
+consume its snapshots and emit INTENT only.
+
+This release stabilizes the 0.3.x stackline and does not introduce new wire contracts.
+
+Compatible stack versions:
+- dbl-core==0.3.2
+- dbl-policy==0.1.0
+- dbl-main==0.3.0
+- kl-kernel-logic==0.5.0
+
+## Quickstart (PowerShell)
+
+```powershell
+py -3.11 -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install -e ".[dev]"
+```
+
+Run the gateway:
+```powershell
+dbl-gateway serve --db .\data\trail.sqlite --host 127.0.0.1 --port 8010
+```
+
+Run with uvicorn:
+```powershell
+$env:DBL_GATEWAY_DB=".\data\trail.sqlite"
+py -3.11 -m uvicorn dbl_gateway.app:app --host 127.0.0.1 --port 8010
+```
+
+## Endpoints
+
+Write:
+- POST `/ingress/intent`
+
+Read:
+- GET `/snapshot`
+- GET `/capabilities`
+- GET `/healthz`
+
+## Environment contract
+
+See `docs/env_contract.md`.
+
+## Notes
+
+- The gateway is the only component that performs governance and execution.
+- All stabilization is expressed explicitly via DECISION events.
+- Boundary and UI clients do not import dbl-core or dbl-policy.
+- The gateway uses dbl-core for canonicalization and digest computation.

dbl_gateway-0.3.2/README.md

@@ -0,0 +1,53 @@
+# DBL Gateway 0.3.2
+
+Authoritative DBL and KL gateway. This service is the single writer for append-only trails,
+applies policy via dbl-policy, and executes via kl-kernel-logic. UI and boundary services
+consume its snapshots and emit INTENT only.
+
+This release stabilizes the 0.3.x stackline and does not introduce new wire contracts.
+
+Compatible stack versions:
+- dbl-core==0.3.2
+- dbl-policy==0.1.0
+- dbl-main==0.3.0
+- kl-kernel-logic==0.5.0
+
+## Quickstart (PowerShell)
+
+```powershell
+py -3.11 -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install -e ".[dev]"
+```
+
+Run the gateway:
+```powershell
+dbl-gateway serve --db .\data\trail.sqlite --host 127.0.0.1 --port 8010
+```
+
+Run with uvicorn:
+```powershell
+$env:DBL_GATEWAY_DB=".\data\trail.sqlite"
+py -3.11 -m uvicorn dbl_gateway.app:app --host 127.0.0.1 --port 8010
+```
+
+## Endpoints
+
+Write:
+- POST `/ingress/intent`
+
+Read:
+- GET `/snapshot`
+- GET `/capabilities`
+- GET `/healthz`
+
+## Environment contract
+
+See `docs/env_contract.md`.
+
+## Notes
+
+- The gateway is the only component that performs governance and execution.
+- All stabilization is expressed explicitly via DECISION events.
+- Boundary and UI clients do not import dbl-core or dbl-policy.
+- The gateway uses dbl-core for canonicalization and digest computation.

dbl_gateway-0.3.2/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dbl-gateway"
+version = "0.3.2"
+description = "DBL Gateway"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+
+dependencies = [
+  "dbl-core>=0.3.2,<0.4.0",
+  "dbl-policy>=0.1.0,<0.2.0",
+  "dbl-main>=0.3.0,<0.4.0",
+  "dbl-ingress>=0.1.1,<0.2.0",
+  "kl-kernel-logic>=0.5.0,<0.6.0",
+  "fastapi>=0.110.0",
+  "uvicorn>=0.27.0",
+  "httpx>=0.27.0",
+]
+
+[project.scripts]
+dbl-gateway = "dbl_gateway.app:main"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8,<9",
+  "ruff>=0.5,<1",
+  "mypy>=1.10,<2",
+  "dbl-reference>=0.2.0",
+]
+oidc = [
+  "python-jose[cryptography]>=3.3,<4",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+license-files = ["LICENSE"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["dbl_gateway*"]
+exclude = ["tests*", "docs*", "scripts*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+filterwarnings = [
+  "ignore:.*on_event is deprecated.*:DeprecationWarning",
+]
+addopts = ["-q", "--strict-markers", "--strict-config"]

dbl_gateway-0.3.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dbl_gateway-0.3.2/src/dbl_gateway/__init__.py

@@ -0,0 +1 @@
+__all__ = ["app"]

dbl_gateway-0.3.2/src/dbl_gateway/adapters/__init__.py

@@ -0,0 +1,9 @@
+from .execution_adapter_kl import KlExecutionAdapter
+from .policy_adapter_dbl_policy import DblPolicyAdapter
+from .store_adapter_sqlite import SQLiteStoreAdapter
+
+__all__ = [
+    "DblPolicyAdapter",
+    "KlExecutionAdapter",
+    "SQLiteStoreAdapter",
+]

dbl_gateway-0.3.2/src/dbl_gateway/adapters/execution_adapter_kl.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from dbl_core import normalize_trace
+
+from ..ports.execution_port import ExecutionPort, ExecutionResult
+from ..providers import anthropic, openai
+from ..providers.errors import ProviderError
+from ..capabilities import resolve_provider
+
+
+@dataclass(frozen=True)
+class KlExecutionAdapter(ExecutionPort):
+    async def run(self, intent_event: Mapping[str, Any]) -> ExecutionResult:
+        payload = intent_event.get("payload")
+        if not isinstance(payload, Mapping):
+            return ExecutionResult(error={"message": "invalid payload"})
+        requested_model_id = payload.get("requested_model_id")
+        model_id = str(requested_model_id) if requested_model_id else ""
+        provider, reason = resolve_provider(model_id)
+        if provider is None or reason is not None:
+            return ExecutionResult(
+                provider=provider,
+                model_id=model_id,
+                error={"provider": provider, "message": reason or "model.unavailable"},
+            )
+        message = _extract_message(payload)
+        if message is None:
+            return ExecutionResult(provider=provider, model_id=model_id, error={"message": "input.invalid"})
+        call = _select_provider(provider)
+        try:
+            output_text, trace, trace_digest, error = await _call_kernel(message, model_id, provider, call)
+            return ExecutionResult(
+                output_text=output_text,
+                provider=provider,
+                model_id=model_id,
+                trace=trace,
+                trace_digest=trace_digest,
+                error=error,
+            )
+        except Exception:
+            return ExecutionResult(
+                provider=provider,
+                model_id=model_id,
+                error={
+                    "provider": provider,
+                    "message": "execution failed",
+                },
+            )
+
+
+def schedule_execution(coro: asyncio.Task | asyncio.Future | Any) -> None:
+    asyncio.create_task(coro)
+
+
+def _select_provider(name: str):
+    if name == "openai":
+        return openai.execute
+    if name == "anthropic":
+        return anthropic.execute
+    raise RuntimeError("unsupported provider")
+
+
+async def _call_kernel(message: str, model_id: str, provider: str, provider_call):
+    import kl_kernel_logic
+
+    psi = kl_kernel_logic.PsiDefinition(
+        psi_type="llm",
+        name=provider,
+        metadata={"model_id": model_id},
+    )
+    kernel = kl_kernel_logic.Kernel()
+
+    def _task(message: str, model_id: str) -> dict[str, object]:
+        try:
+            return {"ok": True, "output": provider_call(message, model_id)}
+        except ProviderError as exc:
+            return {
+                "ok": False,
+                "error": {
+                    "status_code": exc.status_code,
+                    "code": exc.code,
+                    "message": str(exc),
+                },
+            }
+
+    trace = await asyncio.to_thread(
+        kernel.execute,
+        psi=psi,
+        task=_task,
+        metadata={"provider": provider, "model_id": model_id},
+        message=message,
+        model_id=model_id,
+    )
+    trace_dict, trace_digest_value = normalize_trace(trace)
+    if not trace.success:
+        return (
+            "",
+            trace_dict,
+            trace_digest_value,
+            {
+                "provider": provider,
+                "message": trace.error or "execution failed",
+                "failure_code": getattr(trace.failure_code, "value", None),
+            },
+        )
+    output = trace.output
+    if isinstance(output, dict) and output.get("ok") is False:
+        err = output.get("error") if isinstance(output.get("error"), dict) else {}
+        return (
+            "",
+            trace_dict,
+            trace_digest_value,
+            {
+                "provider": provider,
+                "status_code": err.get("status_code"),
+                "code": err.get("code"),
+                "message": str(err.get("message") or "execution failed"),
+            },
+        )
+    if isinstance(output, dict) and "output" in output:
+        return str(output.get("output") or ""), trace_dict, trace_digest_value, None
+    return str(output or ""), trace_dict, trace_digest_value, None
+
+
+def _extract_message(payload: Mapping[str, Any]) -> str | None:
+    message = payload.get("message")
+    if isinstance(message, str) and message.strip():
+        return message.strip()
+    return None

dbl_gateway-0.3.2/src/dbl_gateway/adapters/policy_adapter_dbl_policy.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib import import_module
+from typing import Any, Mapping, get_type_hints
+
+from dbl_policy import Policy, PolicyContext, PolicyDecision, decision_to_dbl_event
+
+from ..ports.policy_port import DecisionResult, PolicyPort
+
+
+ALLOWED_CONTEXT_KEYS = {
+    "stream_id",
+    "lane",
+    "actor",
+    "intent_type",
+    "correlation_id",
+    "payload",
+}
+
+
+@dataclass(frozen=True)
+class DblPolicyAdapter(PolicyPort):
+    def decide(self, authoritative_input: Mapping[str, Any]) -> DecisionResult:
+        context = _build_policy_context(authoritative_input)
+        decision = _evaluate_policy(context)
+        gate_event = decision_to_dbl_event(decision, authoritative_input["correlation_id"])
+        policy_version = _policy_version_as_int(decision.policy_version.value)
+        return DecisionResult(
+            decision=decision.outcome.value,
+            reason_codes=[decision.reason_code],
+            policy_id=decision.policy_id.value,
+            policy_version=policy_version,
+            gate_event=gate_event,
+        )
+
+
+def _build_policy_context(authoritative_input: Mapping[str, Any]) -> PolicyContext:
+    filtered = {key: authoritative_input.get(key) for key in ALLOWED_CONTEXT_KEYS}
+    tenant = authoritative_input.get("tenant_id", "unknown")
+    tenant_type = _tenant_id_type()
+    try:
+        tenant_value = tenant_type(str(tenant))
+    except Exception as exc:
+        raise RuntimeError("invalid tenant_id") from exc
+    return PolicyContext(tenant_id=tenant_value, inputs=filtered)
+
+
+def _evaluate_policy(context: PolicyContext) -> PolicyDecision:
+    policy = _load_policy()
+    return policy.evaluate(context)
+
+
+def _load_policy() -> Policy:
+    module_path = _get_env("DBL_GATEWAY_POLICY_MODULE")
+    obj_name = _get_env("DBL_GATEWAY_POLICY_OBJECT", "policy")
+    module = import_module(module_path)
+    obj = getattr(module, obj_name, None)
+    if obj is None:
+        raise RuntimeError("policy object not found")
+    if callable(obj) and not hasattr(obj, "evaluate"):
+        return obj()  # type: ignore[return-value]
+    return obj  # type: ignore[return-value]
+
+
+def _get_env(name: str, default: str | None = None) -> str:
+    import os
+
+    value = os.getenv(name, "")
+    if value:
+        return value
+    if default is None:
+        raise RuntimeError(f"{name} is required")
+    return default
+
+
+def _tenant_id_type() -> type:
+    hints = get_type_hints(PolicyContext)
+    tenant_type = hints.get("tenant_id")
+    if not isinstance(tenant_type, type):
+        raise RuntimeError("PolicyContext.tenant_id type missing")
+    return tenant_type
+
+
+def _policy_version_as_int(value: object) -> int:
+    try:
+        if isinstance(value, str):
+            text = value.strip()
+            if text == "":
+                raise ValueError("empty")
+            if "." in text:
+                text = text.split(".", 1)[0]
+            return int(text)
+        return int(value)
+    except (TypeError, ValueError) as exc:
+        raise RuntimeError("policy_version must be int") from exc

dbl_gateway-0.3.2/src/dbl_gateway/adapters/store_adapter_sqlite.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..ports.store_port import StorePort
+from ..store.sqlite import SQLiteStore
+
+
+@dataclass
+class SQLiteStoreAdapter(StorePort):
+    _store: SQLiteStore
+
+    @classmethod
+    def from_path(cls, db_path: Path) -> "SQLiteStoreAdapter":
+        return cls(SQLiteStore(db_path))
+
+    def append(
+        self,
+        *,
+        kind: str,
+        lane: str,
+        actor: str,
+        intent_type: str,
+        stream_id: str,
+        correlation_id: str,
+        payload: dict[str, object],
+    ):
+        return self._store.append(
+            kind=kind,
+            lane=lane,
+            actor=actor,
+            intent_type=intent_type,
+            stream_id=stream_id,
+            correlation_id=correlation_id,
+            payload=payload,
+        )
+
+    def snapshot(
+        self,
+        *,
+        limit: int,
+        offset: int,
+        stream_id: str | None = None,
+        lane: str | None = None,
+    ):
+        return self._store.snapshot(
+            limit=limit,
+            offset=offset,
+            stream_id=stream_id,
+            lane=lane,
+        )
+
+    def close(self) -> None:
+        self._store.close()

dbl_gateway-0.3.2/src/dbl_gateway/admission.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from dbl_ingress import (
+    AdmissionError,
+    InvalidInputError,
+    AdmissionRecord,
+    shape_input,
+    ADMISSION_INVALID_INPUT,
+    ADMISSION_SECRETS_PRESENT,
+)
+
+
+SECRET_KEYS = {"api_key", "authorization", "token", "secret", "bearer"}
+
+
+@dataclass(frozen=True)
+class AdmissionFailure(Exception):
+    reason_code: str
+    detail: str
+
+
+def admit_and_shape_intent(payload: Mapping[str, Any], *, raw_payload: Mapping[str, Any] | None = None) -> AdmissionRecord:
+    if raw_payload is not None and _contains_secrets(raw_payload):
+        raise AdmissionFailure(reason_code=ADMISSION_SECRETS_PRESENT, detail="secrets detected in payload")
+    if _contains_secrets(payload):
+        raise AdmissionFailure(reason_code=ADMISSION_SECRETS_PRESENT, detail="secrets detected in payload")
+
+    correlation_id = payload.get("correlation_id")
+    deterministic = payload.get("deterministic")
+    observational = payload.get("observational")
+
+    if not isinstance(correlation_id, str) or not correlation_id.strip():
+        raise AdmissionFailure(reason_code=ADMISSION_INVALID_INPUT, detail="correlation_id must be a non-empty string")
+    if not isinstance(deterministic, Mapping):
+        raise AdmissionFailure(reason_code=ADMISSION_INVALID_INPUT, detail="deterministic must be an object")
+    if observational is not None and not isinstance(observational, Mapping):
+        raise AdmissionFailure(reason_code=ADMISSION_INVALID_INPUT, detail="observational must be an object if provided")
+
+    try:
+        record = shape_input(
+            correlation_id=correlation_id,
+            deterministic=deterministic,
+            observational=observational,
+        )
+    except InvalidInputError as exc:
+        raise AdmissionFailure(reason_code=exc.reason_code, detail=str(exc)) from exc
+    except AdmissionError as exc:
+        reason = getattr(exc, "reason_code", ADMISSION_INVALID_INPUT)
+        raise AdmissionFailure(reason_code=reason, detail=str(exc)) from exc
+    return record
+
+
+def _contains_secrets(value: object) -> bool:
+    if isinstance(value, Mapping):
+        for key, item in value.items():
+            if isinstance(key, str) and key.lower() in SECRET_KEYS:
+                if isinstance(item, str) and item.strip():
+                    return True
+            if _contains_secrets(item):
+                return True
+        return False
+    if isinstance(value, list):
+        return any(_contains_secrets(item) for item in value)
+    return False