Metadata-Version: 2.4
Name: dbl-gateway
Version: 0.9.11
Summary: DBL Gateway
Author-email: Lukas Pfister <228201683+lukaspfisterch@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/lukaspfisterch/dbl-gateway
Project-URL: Repository, https://github.com/lukaspfisterch/dbl-gateway
Project-URL: Issues, https://github.com/lukaspfisterch/dbl-gateway/issues
Keywords: dbl,gateway,llm,policy,deterministic,audit
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Internet :: WWW/HTTP
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.4.0,>=0.3.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: ensdg<0.5.0,>=0.4.0; extra == "dev"
Provides-Extra: oidc
Requires-Dist: python-jose[cryptography]<4,>=3.3; extra == "oidc"
Dynamic: license-file

# dbl-gateway

[![pytest](https://github.com/lukaspfisterch/dbl-gateway/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/lukaspfisterch/dbl-gateway/actions/workflows/tests.yml)
[![PyPI](https://img.shields.io/pypi/v/dbl-gateway.svg)](https://pypi.org/project/dbl-gateway/)
[![Python >=3.11](https://img.shields.io/badge/python-%3E%3D3.11-3776AB.svg)](https://pypi.org/project/dbl-gateway/)

Inspect and replay LLM governance decisions.

Every request produces a decision chain:
what was requested, what was decided, what was executed.

- **Inspect** any decision: see what was requested, allowed, and executed
- **Replay** a decision to reconstruct why it was allowed or denied
- **Swap** the policy, re-evaluate the same input, compare outcomes

No API keys required:

```bash
docker compose --profile demo up
```

Open [http://localhost:8010/ui](http://localhost:8010/ui) and click **Start Demo**.

The demo runs scripted scenarios through the full governance pipeline.
Use **Manual Intent** in the observer to submit your own requests —
the gateway is a working runtime, not just a demo harness.

![Observer UI](pictures/demorun.png)

## How it works

Every request passes through the same deterministic chain:

    INTENT  →  DECISION  →  PROOF  →  EXECUTION

**INTENT** records what was asked.
**DECISION** records what policy allowed — the only normative event.
**PROOF** records what will be sent to the provider.
**EXECUTION** records what happened.

Execution output never feeds back into policy.

Part of the [Deterministic Boundary Layer](https://github.com/lukaspfisterch/deterministic-boundary-layer) architecture.

## Use your own provider

```bash
cp .env.example .env        # add one API key (OpenAI, Anthropic, or Ollama)
docker compose up
```

One active provider is enough. See [.env.example](.env.example) for all options.

## Install

```bash
pip install dbl-gateway
```

Or from source:

```bash
pip install -e .
```

## Reference implementation

`dbl-gateway` instantiates the Deterministic Boundary Layer (DBL) as a runtime
system.

It realizes the event chain INTENT → DECISION → PROOF → EXECUTION, where
DECISION events are recorded before any execution and remain the only
normative layer. Execution outputs are treated as non-normative observations.

The gateway enforces the core invariants of the model:
- append-only event stream
- strict ordering of DECISION before EXECUTION
- governance input purity (authoritative inputs only)
- deterministic replay under fixed inputs and policy configuration

As such, it serves both as a usable governed gateway and as a reference
instantiation of the DBL model.

For empirical validation, including replay equivalence and policy variation
benchmarks, see
[EMPIRICAL_VALIDATION.md](docs/EMPIRICAL_VALIDATION.md).

## Observer UI

Open `/ui` to watch the event chain in real time.

The built-in observer includes the event stream, decision replay, chain
verification, a policy inspector for DECISION events, manual intent
submission, and the integrated demo controller.

## Documentation

- [QUICKSTART.md](docs/QUICKSTART.md) — first request, reading events, UI verification
- [ARCHITECTURE.md](docs/ARCHITECTURE.md) — surfaces, component ownership, invariants
- [EMPIRICAL_VALIDATION.md](docs/EMPIRICAL_VALIDATION.md) — optional replay bench and policy-diff notes
- [wire_contract.md](docs/wire_contract.md) — envelope format, tool gating, budget, refs
- [env_contract.md](docs/env_contract.md) — all environment variables
- [observer.md](docs/observer.md) — UI layout and verification routes
- [demo.md](docs/demo.md) — demo modes and scenario definition
- [Full manifest](docs/MANIFEST.md)
