---
title: BRIDGE Modul X API
emoji: 🔧
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false
---

# BRIDGE Modul X — Email Validation API

7-layer email validation engine powered by FastAPI.

## Autonomous engine architecture (v3.1.0)

Fully self-hosted verification core — **zero external paid dependencies**:

- **DNS/MX worker** — free public DoH resolvers (Google + Cloudflare) with a
  dual-resolver consistency check (`dns_inconsistent` risk signal).
- **SMTP probe worker** — built-in autonomous mailbox probing on port 25
  (or a remote worker via `SMTP_WORKER_URL`); degrades gracefully to
  `unknown` where egress is blocked and routes those to the scorer.
- **AI risk scorer** — LOCAL in-process transformers inference (zero-shot NLI,
  DistilBERT-class default `typeform/distilbert-base-uncased-mnli`). Weights
  are baked into the image at build (`HF_HOME=/app/models`); a running
  container makes **no network calls** for scoring: no Inference API, no
  token, no credits. Circuit breaker + rule-based heuristic fallback inside.
- **Verdict cache** — Redis sidecar (in-memory TTL fallback), domain-level
  catch-all (72h) + definitive mailbox verdicts (24h) + PII-free feature
  score cache (1h).

Normalized verdict per spec Phase 5: `deterministic_verdict` -> `ai_risk_score`
/ `ai_label` / `fallback_used`; a catch-all is never collapsed into `valid`.
Inference burn rate is exposed at `/api/v1/metrics/inference` (target <5% of
verifications on a port-25 host).

## Runtime configuration

Copy `.env.example` to `.env` for local development and replace placeholder
values locally. Redis is optional for the API cache: the application does not
create or claim cloud databases automatically. If no Redis URL is configured
or Redis is unavailable, cache operations use the in-memory TTL fallback.

For Upstash, use the database's TLS `rediss://` connection URL with database
index `/0`; do not disable certificate verification. The Upstash Developer API
key manages resources and is not needed by the app runtime. Keep it out of
`.env` files and deployment secrets unless an isolated operator tool explicitly
needs it. Upstash Free's single-database limit does not imply Celery broker and
result-backend compatibility; verify key-prefix isolation and real worker
round-trips before enabling production bulk jobs.

`Dockerfile.hf` starts the FastAPI web process only. A Celery worker must be
deployed and supervised separately before asynchronous bulk processing is
considered available. A Redis ping alone is not a worker readiness check.

## Scoring contract

Scores use `0-39` for high risk/invalid, `40-74` for medium risk/risky, and
`75-100` for low risk/valid. A transient DNS lookup returns a fixed score of
`50` and `DNS_TRANSIENT_FAILURE: -50`; fast mode applies
`FAST_MODE_SKIPPED_MAILBOX_CHECK: -30` and caps the result at `70`. Missing mail
routes, disposable domains, syntax failures, and a specific SMTP `550 5.1.1`
mailbox-not-found response (or an explicit legacy `550 User Unknown` response)
score `0`. Catch-all and role-based results are capped at `74`. A generic SMTP
`550`, SMTP connection failure, or other inconclusive probe is not treated as
proof that a mailbox does not exist; inconclusive SMTP is capped at `70`.

## Production configuration gate

Set `APP_ENVIRONMENT=production` in the live deployment. Startup then fails
closed unless `DEBUG=false`, `LICENSE_ENFORCEMENT=true`, Supabase URL and
service-role credentials are configured, and every `CORS_ORIGINS` entry is an
HTTPS origin. Keep service-role credentials in the platform's secret store,
never in source control or frontend variables. Keep development settings
(`APP_ENVIRONMENT=development`, localhost CORS, demo licensing) local only.

## Backend checks

From this directory, install the development dependencies into the project
virtual environment and run the test, lint, and compile checks:

```powershell
.\venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\venv\Scripts\python.exe -m pytest --collect-only -q
.\venv\Scripts\python.exe -m pytest -q
.\venv\Scripts\python.exe -m ruff check app tests
.\venv\Scripts\python.exe -m compileall -q app tests
```

Use the project virtual environment for these commands. Running tests with a
different system Python can fail during collection even when the backend
dependencies are installed in `venv`. `pytest.ini` limits collection to the
unit-test directory so `test_connections.py` remains a manually invoked,
environment-dependent integration diagnostic and does not contact live
services during CI.