README.md

metadata

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:

.\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.