Z User
v3.1.0: Part B architecture migration — eliminate Hugging Face inference credit dependency
6c516b6 | 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. | |