bront 0.1.0__tar.gz

bront-0.1.0/.dockerignore

@@ -0,0 +1,8 @@
+.git
+.venv
+.env
+__pycache__
+.pytest_cache
+.ruff_cache
+tests
+docs

bront-0.1.0/.env.example

@@ -0,0 +1,9 @@
+# Copy to .env for gateway runs outside Docker Compose.
+BRONT_PRIMARY_URL=http://127.0.0.1:8001
+BRONT_FALLBACK_URL=http://127.0.0.1:8002
+# Set to triton when running the gateway locally against a Triton primary.
+# compose.triton.yaml sets this automatically for its gateway container.
+BRONT_PRIMARY_PROTOCOL=mock
+BRONT_REQUEST_TIMEOUT_SECONDS=1
+BRONT_FAILURE_THRESHOLD=3
+BRONT_RECOVERY_TIMEOUT_SECONDS=10

bront-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,102 @@
+name: CI
+on: [push, pull_request]
+
+jobs:
+    check:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: astral-sh/setup-uv@v6
+              with:
+                  version: "0.11.21"
+                  enable-cache: true
+            - run: uv sync --frozen
+            - run: uv run ruff check .
+            - run: uv run ruff format --check .
+            - run: uv run ty check --python-version 3.12
+            - run: docker compose config --quiet
+            - run: docker compose -f compose.triton.yaml config --quiet
+            - run: docker compose up --build --wait --wait-timeout 120
+            - run: docker compose exec -T gateway /app/.venv/bin/python --version
+            - run: uv run python scripts/smoke_compose.py
+            - name: Compose logs
+              if: failure()
+              run: docker compose logs --no-color
+            - name: Stop Compose services
+              if: always()
+              run: docker compose down
+
+    scenarios:
+        runs-on: ubuntu-latest
+        timeout-minutes: 10
+        env:
+            COMPOSE_FILE: compose.yaml:compose.scenarios.yaml
+            COMPOSE_PROJECT_NAME: bront-scenarios-ci
+        steps:
+            - uses: actions/checkout@v4
+            - uses: astral-sh/setup-uv@v6
+              with:
+                  version: "0.11.21"
+                  enable-cache: true
+            - run: uv sync --frozen
+            - run: docker compose config --quiet
+            - name: Start scenario stack
+              run: docker compose up --build --wait --wait-timeout 120
+            - name: Run reusable proxy scenarios
+              run: |
+                  uv run --frozen bront run examples/scenarios/proxy-outage.toml --output reports/scenarios/proxy-outage.json
+                  uv run --frozen bront run examples/scenarios/proxy-delay.toml --output reports/scenarios/proxy-delay.json
+            - name: Render scenario HTML
+              if: always() && hashFiles('reports/scenarios/*.json') != ''
+              run: |
+                  for source in reports/scenarios/*.json; do
+                    uv run --frozen bront report "$source" --output "${source%.json}.html"
+                  done
+            - name: Upload scenario reports
+              if: always() && hashFiles('reports/scenarios/*.json') != ''
+              uses: actions/upload-artifact@v7
+              with:
+                  name: scenario-reports
+                  path: reports/scenarios/
+                  if-no-files-found: error
+                  retention-days: 14
+            - name: Scenario Compose logs
+              if: failure()
+              run: docker compose logs --no-color
+            - name: Stop scenario services
+              if: always()
+              run: docker compose down
+
+    python-compatibility:
+        runs-on: ubuntu-latest
+        timeout-minutes: 10
+        strategy:
+            fail-fast: false
+            matrix:
+                python: ["3.12", "3.13", "3.14"]
+        env:
+            UV_PYTHON: ${{ matrix.python }}
+        steps:
+            - uses: actions/checkout@v4
+            - uses: astral-sh/setup-uv@v6
+              with:
+                  version: "0.11.21"
+                  enable-cache: true
+            - run: uv sync --frozen --python "${{ matrix.python }}"
+            - run: uv run --frozen pytest
+            - name: Build and install the standalone package
+              run: |
+                  uv build
+                  uv venv --python "${{ matrix.python }}" "$RUNNER_TEMP/bront-core"
+                  uv pip install --python "$RUNNER_TEMP/bront-core/bin/python" dist/bront-*.whl
+                  "$RUNNER_TEMP/bront-core/bin/python" -c "import importlib.util; import bront.cli; assert importlib.util.find_spec('fastapi') is None"
+            - name: Verify HTTP runs, comparisons, interruption handling, and HTML reports
+              run: '"$RUNNER_TEMP/bront-core/bin/python" scripts/smoke_external.py'
+            - name: Upload external endpoint reports
+              if: always() && hashFiles('reports/external/*.json') != ''
+              uses: actions/upload-artifact@v7
+              with:
+                  name: external-endpoint-reports-py${{ matrix.python }}
+                  path: reports/external/
+                  if-no-files-found: error
+                  retention-days: 14

bront-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+*.egg-info/
+.env
+.DS_Store
+/reports/

bront-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

bront-0.1.0/Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.14-slim AS cli
+
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 UV_PYTHON_DOWNLOADS=never
+WORKDIR /app
+RUN pip install --no-cache-dir uv==0.11.21
+COPY .python-version pyproject.toml uv.lock README.md ./
+COPY src ./src
+RUN uv sync --frozen --no-dev --no-editable
+RUN useradd --create-home --uid 10001 app
+USER app
+CMD ["/app/.venv/bin/bront", "--help"]
+
+FROM cli AS reference
+USER root
+RUN uv sync --frozen --no-dev --no-editable --extra reference
+USER app
+EXPOSE 8000
+CMD ["/app/.venv/bin/uvicorn", "bront.reference.gateway:app", "--host", "0.0.0.0", "--port", "8000"]

bront-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frank Lee
+
+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.

bront-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.5
+Name: bront
+Version: 0.1.0
+Summary: Validate and measure inference endpoints, with a reference failover gateway
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: rich<16,>=14
+Requires-Dist: typer<1,>=0.20
+Provides-Extra: reference
+Requires-Dist: fastapi<1,>=0.115; extra == 'reference'
+Requires-Dist: prometheus-client<1,>=0.21; extra == 'reference'
+Requires-Dist: pydantic-settings<3,>=2.7; extra == 'reference'
+Requires-Dist: uvicorn<1,>=0.34; extra == 'reference'
+Description-Content-Type: text/markdown
+
+# Bront
+
+Repeatable reliability tests and release evidence for inference deployments.
+Bront checks an existing HTTP JSON endpoint against representative inputs,
+correctness assertions, and latency/error limits. Add fault or rollout scenarios,
+compare repeated baseline and candidate runs, and share an offline HTML report.
+Your service does not need to adopt Bront's reference gateway.
+
+## Quickstart
+
+Requires Python 3.12 or newer; tested on CPython 3.12, 3.13, and 3.14. From this checkout:
+
+```sh
+uv sync --frozen
+uv run python examples/http-json/server.py
+```
+
+In another terminal:
+
+```sh
+uv run bront run examples/http-json/suite.toml --output reports/run.json
+uv run bront report reports/run.json --output reports/review.html
+```
+
+Open `reports/review.html` in a browser. The standalone example requires no Docker,
+Kubernetes, Triton, or backend-specific status API.
+
+For your own service, configure the URL, JSONL input cases, expected outputs,
+workload, and assertions in a TOML suite. Read the
+[external endpoint guide](docs/external-endpoints.md) for the supported contract.
+Credentials can reference environment variables; raw payloads and credential values
+are excluded from normal reports.
+
+## Release workflow
+
+```sh
+uv run bront run baseline.toml --repeat 3 --output reports/baseline.json
+uv run bront run candidate.toml --repeat 3 --output reports/candidate.json
+uv run bront compare reports/baseline.json reports/candidate.json \
+  --policy limits.toml --output reports/comparison.json
+uv run bront report reports/comparison.json --output reports/comparison.html
+```
+
+Record deployment metadata and explicitly allow the intended change in the
+comparison policy. Bront checks experiment compatibility before evaluating
+regressions. Missing context, incomplete execution, or insufficient repeat evidence
+cannot produce a passing comparison. Observed variation is not a statistical
+significance test.
+
+| Command | Purpose |
+| --- | --- |
+| `bront run` | Execute a suite, retain samples, and evaluate release assertions. |
+| `bront compare` | Compare compatible repeated experiments against an explicit policy. |
+| `bront report` | Render recorded evidence as self-contained HTML with JSON downloads. |
+
+`run` and `compare` return 0 for passing evidence, 1 for failed checks, and 2 for
+execution/configuration problems or inconclusive/incompatible comparisons.
+Interrupted runs use exit 130 and retain partial evidence. `report` returns 0 when
+rendering succeeds; it does not replace a release gate.
+
+## Guides
+
+- [External endpoints and response validation](docs/external-endpoints.md)
+- [Proxy faults and Kubernetes scenarios](docs/scenarios.md)
+- [Repeated runs and release comparisons](docs/comparisons.md)
+- [Offline HTML reports](docs/reports.md)
+- [Architecture](docs/architecture.md)
+- [Roadmap and remaining validation](docs/proposals/inference-reliability.md)
+
+## Optional reference deployment
+
+The reference gateway, compatible mock fallback, Triton `double` model, fault
+proxy, and monitoring stack exercise the same suite workflow. They are fixtures,
+not required infrastructure for using Bront. Gateway code lives in
+`bront.reference`; its server dependencies are an optional `reference` extra.
+
+```sh
+# Build and start the mock reference stack.
+docker compose up --build --wait
+uv run bront run examples/gateway/suite.toml --output reports/gateway.json
+uv run python scripts/smoke_compose.py
+```
+
+For controlled outage and delay scenarios:
+
+```sh
+docker compose -f compose.yaml -f compose.scenarios.yaml up --build --wait
+uv run bront run examples/scenarios/proxy-outage.toml --output reports/outage.json
+uv run bront run examples/scenarios/proxy-delay.toml --output reports/delay.json
+uv run bront report reports/outage.json --output reports/outage.html
+```
+
+Run one fault experiment at a time against a disposable reference stack. Scenarios
+record control events and restore owned faults on ordinary errors and interruption.
+The [scenario guide](docs/scenarios.md) explains cleanup and recovery boundaries.
+
+See the [Triton walkthrough](docs/triton.md) for the ONNX CPU integration,
+[Kubernetes guide](docs/kubernetes.md) for two independent gateway replicas, and
+[observability guide](docs/observability.md) for per-pod metrics. The `double` model
+is an integration fixture; a trained-model example remains on the roadmap.
+
+For a locally launched gateway, copy `.env.example` to `.env` and install the
+reference dependencies with `uv sync --extra reference`. Entry points are
+`bront.reference.gateway:app` and `bront.reference.mock_backend:app`.
+Reference environment variables use `BRONT_`; metrics use `bront_`.
+The suite runner uses explicit TOML and process environment variables, not `.env`.
+
+## Development and packaging
+
+```sh
+uv sync --frozen
+uv run ruff check .
+uv run ruff format --check .
+uv run ty check --python-version 3.12
+uv run pytest
+uv run python scripts/smoke_external.py
+uv build
+```
+
+The distribution, import package, and CLI are all named `bront`. A core wheel
+installation needs no FastAPI or Prometheus dependencies. Source-checkout dev
+requirements include the reference dependencies to test both workflows.
+No registry publication is required to install a locally built wheel.
+
+The `.python-version` file selects Python 3.14 for default checkout development;
+it is not the package's installation requirement. To work on another supported version:
+
+```sh
+uv sync --python 3.12 --frozen
+uv run --python 3.12 pytest
+```
+
+CI tests the full suite and an isolated wheel installation on Python 3.12, 3.13,
+and 3.14, including the run/compare/report smoke workflow. Ruff and type checking
+target the 3.12 minimum to catch accidental use of newer syntax or APIs.
+The reference Docker images continue using Python 3.14.
+
+The Dockerfile provides a `cli` build target for the tool alone and a default
+`reference` target for the fixture services:
+
+```sh
+docker build --target cli -t bront:cli .
+docker run --rm bront:cli
+```
+
+CI runs lint, types, tests, the reference Compose smoke check, reusable proxy
+scenarios, and the standalone run/compare/report workflow. It uploads JSON and
+HTML artifacts, including evidence retained after failed experiments. Generated
+reports belong under the ignored `reports/` directory rather than in Git.

bront-0.1.0/README.md

@@ -0,0 +1,149 @@
+# Bront
+
+Repeatable reliability tests and release evidence for inference deployments.
+Bront checks an existing HTTP JSON endpoint against representative inputs,
+correctness assertions, and latency/error limits. Add fault or rollout scenarios,
+compare repeated baseline and candidate runs, and share an offline HTML report.
+Your service does not need to adopt Bront's reference gateway.
+
+## Quickstart
+
+Requires Python 3.12 or newer; tested on CPython 3.12, 3.13, and 3.14. From this checkout:
+
+```sh
+uv sync --frozen
+uv run python examples/http-json/server.py
+```
+
+In another terminal:
+
+```sh
+uv run bront run examples/http-json/suite.toml --output reports/run.json
+uv run bront report reports/run.json --output reports/review.html
+```
+
+Open `reports/review.html` in a browser. The standalone example requires no Docker,
+Kubernetes, Triton, or backend-specific status API.
+
+For your own service, configure the URL, JSONL input cases, expected outputs,
+workload, and assertions in a TOML suite. Read the
+[external endpoint guide](docs/external-endpoints.md) for the supported contract.
+Credentials can reference environment variables; raw payloads and credential values
+are excluded from normal reports.
+
+## Release workflow
+
+```sh
+uv run bront run baseline.toml --repeat 3 --output reports/baseline.json
+uv run bront run candidate.toml --repeat 3 --output reports/candidate.json
+uv run bront compare reports/baseline.json reports/candidate.json \
+  --policy limits.toml --output reports/comparison.json
+uv run bront report reports/comparison.json --output reports/comparison.html
+```
+
+Record deployment metadata and explicitly allow the intended change in the
+comparison policy. Bront checks experiment compatibility before evaluating
+regressions. Missing context, incomplete execution, or insufficient repeat evidence
+cannot produce a passing comparison. Observed variation is not a statistical
+significance test.
+
+| Command | Purpose |
+| --- | --- |
+| `bront run` | Execute a suite, retain samples, and evaluate release assertions. |
+| `bront compare` | Compare compatible repeated experiments against an explicit policy. |
+| `bront report` | Render recorded evidence as self-contained HTML with JSON downloads. |
+
+`run` and `compare` return 0 for passing evidence, 1 for failed checks, and 2 for
+execution/configuration problems or inconclusive/incompatible comparisons.
+Interrupted runs use exit 130 and retain partial evidence. `report` returns 0 when
+rendering succeeds; it does not replace a release gate.
+
+## Guides
+
+- [External endpoints and response validation](docs/external-endpoints.md)
+- [Proxy faults and Kubernetes scenarios](docs/scenarios.md)
+- [Repeated runs and release comparisons](docs/comparisons.md)
+- [Offline HTML reports](docs/reports.md)
+- [Architecture](docs/architecture.md)
+- [Roadmap and remaining validation](docs/proposals/inference-reliability.md)
+
+## Optional reference deployment
+
+The reference gateway, compatible mock fallback, Triton `double` model, fault
+proxy, and monitoring stack exercise the same suite workflow. They are fixtures,
+not required infrastructure for using Bront. Gateway code lives in
+`bront.reference`; its server dependencies are an optional `reference` extra.
+
+```sh
+# Build and start the mock reference stack.
+docker compose up --build --wait
+uv run bront run examples/gateway/suite.toml --output reports/gateway.json
+uv run python scripts/smoke_compose.py
+```
+
+For controlled outage and delay scenarios:
+
+```sh
+docker compose -f compose.yaml -f compose.scenarios.yaml up --build --wait
+uv run bront run examples/scenarios/proxy-outage.toml --output reports/outage.json
+uv run bront run examples/scenarios/proxy-delay.toml --output reports/delay.json
+uv run bront report reports/outage.json --output reports/outage.html
+```
+
+Run one fault experiment at a time against a disposable reference stack. Scenarios
+record control events and restore owned faults on ordinary errors and interruption.
+The [scenario guide](docs/scenarios.md) explains cleanup and recovery boundaries.
+
+See the [Triton walkthrough](docs/triton.md) for the ONNX CPU integration,
+[Kubernetes guide](docs/kubernetes.md) for two independent gateway replicas, and
+[observability guide](docs/observability.md) for per-pod metrics. The `double` model
+is an integration fixture; a trained-model example remains on the roadmap.
+
+For a locally launched gateway, copy `.env.example` to `.env` and install the
+reference dependencies with `uv sync --extra reference`. Entry points are
+`bront.reference.gateway:app` and `bront.reference.mock_backend:app`.
+Reference environment variables use `BRONT_`; metrics use `bront_`.
+The suite runner uses explicit TOML and process environment variables, not `.env`.
+
+## Development and packaging
+
+```sh
+uv sync --frozen
+uv run ruff check .
+uv run ruff format --check .
+uv run ty check --python-version 3.12
+uv run pytest
+uv run python scripts/smoke_external.py
+uv build
+```
+
+The distribution, import package, and CLI are all named `bront`. A core wheel
+installation needs no FastAPI or Prometheus dependencies. Source-checkout dev
+requirements include the reference dependencies to test both workflows.
+No registry publication is required to install a locally built wheel.
+
+The `.python-version` file selects Python 3.14 for default checkout development;
+it is not the package's installation requirement. To work on another supported version:
+
+```sh
+uv sync --python 3.12 --frozen
+uv run --python 3.12 pytest
+```
+
+CI tests the full suite and an isolated wheel installation on Python 3.12, 3.13,
+and 3.14, including the run/compare/report smoke workflow. Ruff and type checking
+target the 3.12 minimum to catch accidental use of newer syntax or APIs.
+The reference Docker images continue using Python 3.14.
+
+The Dockerfile provides a `cli` build target for the tool alone and a default
+`reference` target for the fixture services:
+
+```sh
+docker build --target cli -t bront:cli .
+docker run --rm bront:cli
+```
+
+CI runs lint, types, tests, the reference Compose smoke check, reusable proxy
+scenarios, and the standalone run/compare/report workflow. It uploads JSON and
+HTML artifacts, including evidence retained after failed experiments. Generated
+reports belong under the ignored `reports/` directory rather than in Git.

bront-0.1.0/compose.scenarios.yaml

@@ -0,0 +1,20 @@
+# Overlay either compose.yaml or compose.triton.yaml for controlled fault scenarios.
+services:
+    gateway:
+        environment:
+            BRONT_PRIMARY_URL: http://fault-proxy:8666
+        depends_on:
+            fault-proxy:
+                condition: service_healthy
+
+    fault-proxy:
+        image: ghcr.io/shopify/toxiproxy:2.12.0
+        command: ["-host=0.0.0.0", "-config=/config/proxies.json"]
+        ports: ["127.0.0.1:${BRONT_TOXIPROXY_PORT:-18474}:8474"]
+        volumes:
+            - ./deploy/toxiproxy/proxies.json:/config/proxies.json:ro
+        healthcheck:
+            test: ["CMD", "/toxiproxy-cli", "list"]
+            interval: 5s
+            timeout: 3s
+            retries: 10

bront-0.1.0/compose.triton.yaml

@@ -0,0 +1,37 @@
+name: bront
+# Standalone alternative to compose.yaml: docker compose -f compose.triton.yaml up
+services:
+    gateway:
+        extends:
+            file: compose.yaml
+            service: gateway
+        environment:
+            BRONT_PRIMARY_PROTOCOL: triton
+
+    primary:
+        image: nvcr.io/nvidia/tritonserver:26.08-py3
+        init: true
+        command:
+            - tritonserver
+            - --model-repository=/models
+            - --disable-auto-complete-config
+            - --allow-grpc=false
+            - --allow-gpu-metrics=false
+        ports: ["127.0.0.1:${BRONT_PRIMARY_PORT:-8001}:8000"]
+        volumes:
+            - ./deploy/triton/models:/models:ro
+        healthcheck:
+            test:
+                - CMD
+                - python3
+                - -c
+                - "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/v2/models/double/versions/1/ready', timeout=2)"
+            interval: 5s
+            timeout: 3s
+            retries: 12
+            start_period: 30s
+
+    fallback:
+        extends:
+            file: compose.yaml
+            service: fallback

bront-0.1.0/compose.yaml

@@ -0,0 +1,65 @@
+name: bront
+x-service: &service
+    build: .
+    init: true
+    healthcheck:
+        test:
+            [
+                "CMD",
+                "/app/.venv/bin/python",
+                "-c",
+                "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/healthz', timeout=2)",
+            ]
+        interval: 5s
+        timeout: 3s
+        retries: 5
+        start_period: 10s
+
+services:
+    gateway:
+        <<: *service
+        ports: ["127.0.0.1:${BRONT_GATEWAY_PORT:-8000}:8000"]
+        environment:
+            BRONT_PRIMARY_URL: http://primary:8000
+            BRONT_FALLBACK_URL: http://fallback:8000
+            BRONT_REQUEST_TIMEOUT_SECONDS: "1"
+            BRONT_FAILURE_THRESHOLD: "3"
+            BRONT_RECOVERY_TIMEOUT_SECONDS: "10"
+        depends_on:
+            primary:
+                condition: service_healthy
+            fallback:
+                condition: service_healthy
+
+    primary:
+        <<: *service
+        command:
+            [
+                "/app/.venv/bin/uvicorn",
+                "bront.reference.mock_backend:app",
+                "--host",
+                "0.0.0.0",
+                "--port",
+                "8000",
+            ]
+        ports: ["127.0.0.1:${BRONT_PRIMARY_PORT:-8001}:8000"]
+
+    fallback:
+        <<: *service
+        command:
+            [
+                "/app/.venv/bin/uvicorn",
+                "bront.reference.mock_backend:app",
+                "--host",
+                "0.0.0.0",
+                "--port",
+                "8000",
+            ]
+        ports: ["127.0.0.1:${BRONT_FALLBACK_PORT:-8002}:8000"]
+
+    prometheus:
+        image: prom/prometheus:v3.2.1
+        profiles: ["observability"]
+        ports: ["127.0.0.1:9090:9090"]
+        volumes:
+            - ./deploy/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro