5de94558-bd63-4dac-82f0-38a08c4a5f29

download/face-intel/.env.example

@@ -0,0 +1,54 @@
+# Face Intel — environment configuration
+# Copy to `.env` and adjust as needed.
+# Every variable has the FI_ prefix.
+
+# --- Core ---
+FI_ENVIRONMENT=development
+FI_HOST=0.0.0.0
+FI_PORT=8000
+FI_DEBUG=false
+FI_LOG_LEVEL=INFO
+FI_LOG_JSON=false
+
+# --- Provider enable flags ---
+FI_ENABLE_HAAR=true
+FI_ENABLE_DNN=true
+FI_ENABLE_MTCNN=true
+FI_ENABLE_RETINAFACE=false
+FI_ENABLE_FACE_RECOGNITION=true
+FI_ENABLE_DEEPFACE=false
+FI_ENABLE_INSIGHTFACE=false
+FI_ENABLE_BEAUTIFULSOUP_SCRAPER=true
+FI_ENABLE_SELENIUM_SCRAPER=true
+FI_ENABLE_BING_SCRAPER=false
+FI_ENABLE_DUCKDUCKGO_SCRAPER=true
+FI_ENABLE_GOOGLE_LENS=true
+FI_ENABLE_SERPAPI=false
+FI_ENABLE_YANDEX=false
+FI_ENABLE_TINEYE=false
+
+# --- API keys (only needed if corresponding enable_* is true) ---
+FI_SERPAPI_KEY=
+FI_BING_API_KEY=
+FI_TINEYE_PUBLIC_KEY=
+FI_TINEYE_PRIVATE_KEY=
+
+# --- Orchestrator ---
+FI_ORCHESTRATOR_TIMEOUT_SECONDS=90
+FI_ORCHESTRATOR_MAX_CONCURRENCY=8
+FI_RETRY_MAX_ATTEMPTS=3
+FI_RETRY_INITIAL_BACKOFF_SECONDS=0.5
+FI_RETRY_MAX_BACKOFF_SECONDS=8
+
+# --- Cache ---
+FI_CACHE_ENABLED=true
+FI_CACHE_TTL_SECONDS=3600
+FI_CACHE_MAX_ENTRIES=1000
+
+# --- Health / circuit breaker ---
+FI_HEALTH_CHECK_INTERVAL_SECONDS=60
+FI_CIRCUIT_BREAKER_FAILURE_THRESHOLD=5
+FI_CIRCUIT_BREAKER_RECOVERY_SECONDS=120
+
+# --- API ---
+FI_RATE_LIMIT_PER_MINUTE=30

download/face-intel/README.md

@@ -0,0 +1,64 @@
+# Face Intel
+
+A multi-provider face intelligence platform with evidence-first,
+explainable results.
+
+## Architecture
+
+See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the full
+architecture documentation including dependency graph, package
+responsibilities, execution flow, lifecycle diagrams, and the provider
+extension guide.
+
+## Quick Start
+
+```bash
+# 1. Install dependencies
+pip install -r requirements.txt
+
+# 2. Configure
+cp .env.example .env
+# edit .env to enable/disable providers
+
+# 3. Run
+python app.py
+# or: uvicorn app:app --reload
+
+# 4. Open
+# http://localhost:8000/docs        — Swagger UI
+# http://localhost:8000/health      — health check
+# http://localhost:8000/providers   — provider list
+# http://localhost:8000/stats       — metrics
+```
+
+## Key Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| `POST` | `/faces/detect` | Detect faces in an image |
+| `POST` | `/faces/recognize` | Recognize faces against the gallery |
+| `POST` | `/search/reverse` | Reverse image search |
+| `POST` | `/search/scrape` | Scrape images from a URL |
+| `POST` | `/jobs` | Full-pipeline job |
+| `GET`  | `/providers` | List all providers |
+| `GET`  | `/stats` | Metrics snapshot |
+| `GET`  | `/health/providers` | Per-provider health |
+
+## Adding a New Provider
+
+1. Implement `providers/<category>/<name>.py` (subclass `BaseProvider`).
+2. Add one entry to `PROVIDER_MANIFEST` in `providers/registry.py`.
+3. Add an `enable_<name>: bool = False` flag to `config/settings.py`.
+
+That's it — the orchestrator, services, API, and UI pick it up
+automatically. See `docs/ARCHITECTURE.md §5` for a complete example.
+
+## Engineering Principles
+
+- **Modular** — every provider is isolated; failures don't cascade.
+- **Extensible** — new providers require zero orchestrator/API changes.
+- **Production-ready** — circuit breakers, retries, caching, rate limiting, audit log.
+- **Evidence-first** — raw provider responses preserved verbatim.
+- **Explainable** — confidence scores decomposed into weighted sub-scores.
+- **Clean separation** — 11 layers, strict one-way dependency direction.
+- **DI throughout** — no global stateful objects; everything injectable.

download/face-intel/api/__init__.py

@@ -0,0 +1,6 @@
+"""API package — FastAPI app factory + DI wiring."""
+
+from api.main import create_app
+from api.container import ServiceContainer
+
+__all__ = ["create_app", "ServiceContainer"]

download/face-intel/api/container.py

@@ -0,0 +1,171 @@
+"""
+DI container — constructs every dependency ONCE at app startup and
+wires services together.  This is the composition root.
+
+No globals: the container is created in `create_app()` and stored on
+`app.state.container`.  Route handlers retrieve it via the `get_container`
+FastAPI dependency.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from config.settings import Settings, DATA_DIR, GALLERY_DIR, UPLOADS_DIR, JOBS_DIR
+from confidence.engine import ConfidenceEngine
+from confidence.conflicts import ConflictDetector
+from metrics.collector import MetricsCollector
+from normalization.merger import ReportMerger
+from orchestrator.health import HealthMonitor
+from orchestrator.runner import Orchestrator
+from pipeline import (
+    InputValidator,
+    ImagePreprocessor,
+    ImageHasher,
+    FeatureExtractor,
+)
+from providers.registry import ProviderRegistry
+from services.cache_service import CacheService
+from services.detection_service import DetectionService
+from services.export_service import ExportService
+from services.health_service import HealthService
+from services.job_service import JobService
+from services.provider_service import ProviderService
+from services.recognition_service import RecognitionService
+from services.search_service import SearchService
+from storage.artifacts import ArtifactStore
+from storage.cache import Cache
+from storage.database import Database
+from storage.reference_store import ReferenceStore
+
+
+@dataclass
+class ServiceContainer:
+    """Holds every wired service + infrastructure object."""
+    settings: Settings
+    registry: ProviderRegistry
+    cache: Cache
+    database: Database
+    artifacts: ArtifactStore
+    reference_store: ReferenceStore
+    metrics: MetricsCollector
+    health_monitor: HealthMonitor
+    orchestrator: Orchestrator
+    confidence_engine: ConfidenceEngine
+    conflict_detector: ConflictDetector
+    validator: InputValidator
+    preprocessor: ImagePreprocessor
+    hasher: ImageHasher
+    feature_extractor: FeatureExtractor
+    detection_service: DetectionService
+    recognition_service: RecognitionService
+    search_service: SearchService
+    job_service: JobService
+    provider_service: ProviderService
+    cache_service: CacheService
+    health_service: HealthService
+    export_service: ExportService
+
+
+def build_container(settings: Settings | None = None) -> ServiceContainer:
+    """Construct the entire dependency graph.  Called once at startup."""
+    settings = settings or Settings()
+
+    # Infrastructure
+    registry = ProviderRegistry(settings)
+    registry.discover()
+
+    cache = Cache(
+        ttl_seconds=settings.cache_ttl_seconds,
+        max_entries=settings.cache_max_entries,
+    )
+    database = Database(path=settings.db_path)
+    artifacts = ArtifactStore(root=UPLOADS_DIR)
+    reference_store = ReferenceStore(root=GALLERY_DIR)
+
+    metrics = MetricsCollector(
+        failure_threshold=settings.circuit_breaker_failure_threshold,
+        recovery_seconds=settings.circuit_breaker_recovery_seconds,
+    )
+    health_monitor = HealthMonitor(metrics=metrics.health)
+
+    orchestrator = Orchestrator(
+        registry=registry,
+        cache=cache,
+        metrics=metrics,
+        health=health_monitor,
+        settings=settings,
+    )
+
+    confidence_engine = ConfidenceEngine()
+    conflict_detector = ConflictDetector()
+
+    # Pipeline
+    validator = InputValidator()
+    preprocessor = ImagePreprocessor(max_dim=1024)
+    hasher = ImageHasher()
+    # Use the first available detection provider as the default feature extractor
+    from models.providers import ProviderCapability
+    detectors = registry.list_by_capability(ProviderCapability.DETECTION)
+    default_detector = detectors[0] if detectors else None
+    feature_extractor = FeatureExtractor(detector=default_detector)
+
+    # Services
+    detection_service = DetectionService(
+        registry=registry, orchestrator=orchestrator, cache=cache, metrics=metrics,
+        validator=validator, preprocessor=preprocessor, hasher=hasher,
+        feature_extractor=feature_extractor,
+        confidence_engine=confidence_engine, conflict_detector=conflict_detector,
+    )
+    recognition_service = RecognitionService(
+        orchestrator=orchestrator, metrics=metrics,
+        validator=validator, preprocessor=preprocessor, hasher=hasher,
+        feature_extractor=feature_extractor, reference_store=reference_store,
+        confidence_engine=confidence_engine, conflict_detector=conflict_detector,
+    )
+    search_service = SearchService(
+        orchestrator=orchestrator, metrics=metrics,
+        validator=validator, preprocessor=preprocessor, hasher=hasher,
+        feature_extractor=feature_extractor,
+        confidence_engine=confidence_engine, conflict_detector=conflict_detector,
+    )
+    job_service = JobService(
+        detection=detection_service,
+        recognition=recognition_service,
+        search=search_service,
+        database=database,
+        metrics=metrics,
+    )
+    provider_service = ProviderService(registry=registry)
+    cache_service = CacheService(cache=cache)
+    health_service = HealthService(
+        registry=registry, health_monitor=health_monitor, metrics=metrics,
+        version=settings.app_version,
+    )
+    export_service = ExportService(database=database)
+
+    return ServiceContainer(
+        settings=settings,
+        registry=registry,
+        cache=cache,
+        database=database,
+        artifacts=artifacts,
+        reference_store=reference_store,
+        metrics=metrics,
+        health_monitor=health_monitor,
+        orchestrator=orchestrator,
+        confidence_engine=confidence_engine,
+        conflict_detector=conflict_detector,
+        validator=validator,
+        preprocessor=preprocessor,
+        hasher=hasher,
+        feature_extractor=feature_extractor,
+        detection_service=detection_service,
+        recognition_service=recognition_service,
+        search_service=search_service,
+        job_service=job_service,
+        provider_service=provider_service,
+        cache_service=cache_service,
+        health_service=health_service,
+        export_service=export_service,
+    )

download/face-intel/api/deps.py

@@ -0,0 +1,57 @@
+"""
+FastAPI dependency injection helpers.
+
+Routes use these to pull services off the request-scoped container.
+"""
+
+from __future__ import annotations
+
+from fastapi import Request
+
+from api.container import ServiceContainer
+
+
+def get_container(request: Request) -> ServiceContainer:
+    """Returns the app-wide ServiceContainer."""
+    return request.app.state.container
+
+
+# Per-service dependency callables (use as `Depends(get_detection_service)`)
+def get_settings(request: Request):
+    return get_container(request).settings
+
+
+def get_detection_service(request: Request):
+    return get_container(request).detection_service
+
+
+def get_recognition_service(request: Request):
+    return get_container(request).recognition_service
+
+
+def get_search_service(request: Request):
+    return get_container(request).search_service
+
+
+def get_job_service(request: Request):
+    return get_container(request).job_service
+
+
+def get_provider_service(request: Request):
+    return get_container(request).provider_service
+
+
+def get_cache_service(request: Request):
+    return get_container(request).cache_service
+
+
+def get_health_service(request: Request):
+    return get_container(request).health_service
+
+
+def get_export_service(request: Request):
+    return get_container(request).export_service
+
+
+def get_metrics(request: Request):
+    return get_container(request).metrics

download/face-intel/api/main.py

@@ -0,0 +1,80 @@
+"""
+FastAPI app factory.
+
+Constructs the ServiceContainer (composition root), mounts middleware,
+registers routes, and serves the UI.
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from loguru import logger
+
+from api.container import build_container
+from api.middleware import RequestContextMiddleware, RateLimitMiddleware
+from api.routes import (
+    health, stats, providers, cache, jobs, faces, search, export,
+)
+from config.settings import Settings, UI_DIR
+from utils.logging import setup_logging
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    """Application factory — composes the entire dependency graph."""
+    settings = settings or Settings()
+    setup_logging(settings)
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        logger.info(f"Starting {settings.app_name} v{settings.app_version}")
+        container = build_container(settings)
+        app.state.container = container
+        app.state.settings = settings
+        logger.info(f"Registered providers: {container.registry.list_names()}")
+        yield
+        logger.info("Shutting down")
+        container.database.close()
+
+    app = FastAPI(
+        title=settings.app_name,
+        version=settings.app_version,
+        description="Multi-provider face intelligence platform",
+        lifespan=lifespan,
+    )
+
+    # Middleware
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.cors_origins,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+    app.add_middleware(RequestContextMiddleware)
+    app.add_middleware(RateLimitMiddleware, requests_per_minute=settings.rate_limit_per_minute)
+
+    # Routers
+    app.include_router(health.router, prefix="/health", tags=["health"])
+    app.include_router(stats.router, prefix="/stats", tags=["stats"])
+    app.include_router(providers.router, prefix="/providers", tags=["providers"])
+    app.include_router(cache.router, prefix="/cache", tags=["cache"])
+    app.include_router(jobs.router, prefix="/jobs", tags=["jobs"])
+    app.include_router(faces.router, prefix="/faces", tags=["faces"])
+    app.include_router(search.router, prefix="/search", tags=["search"])
+    app.include_router(export.router, prefix="/export", tags=["export"])
+
+    # UI
+    if UI_DIR.exists():
+        app.mount("/", StaticFiles(directory=str(UI_DIR), html=True), name="ui")
+    else:
+        @app.get("/")
+        async def root():
+            return {"app": settings.app_name, "version": settings.app_version,
+                    "docs": "/docs"}
+
+    return app

download/face-intel/api/middleware.py

@@ -0,0 +1,56 @@
+"""
+API middleware — CORS, request-id, simple rate limiting.
+"""
+
+from __future__ import annotations
+
+import time
+from collections import defaultdict
+
+from fastapi import Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+
+
+class RequestContextMiddleware(BaseHTTPMiddleware):
+    """Adds a request-id to every request + measures duration."""
+
+    async def dispatch(self, request: Request, call_next):
+        import uuid
+        request_id = request.headers.get("X-Request-ID") or uuid.uuid4().hex[:12]
+        request.state.request_id = request_id
+        t0 = time.perf_counter()
+        response: Response = await call_next(request)
+        elapsed_ms = (time.perf_counter() - t0) * 1000.0
+        response.headers["X-Request-ID"] = request_id
+        response.headers["X-Response-Time-ms"] = f"{elapsed_ms:.2f}"
+        return response
+
+
+class RateLimitMiddleware(BaseHTTPMiddleware):
+    """Simple in-memory per-IP rate limiter.
+
+    For production, replace with a Redis-backed limiter.
+    """
+
+    def __init__(self, app, requests_per_minute: int = 30):
+        super().__init__(app)
+        self._limit = requests_per_minute
+        self._buckets: dict[str, list[float]] = defaultdict(list)
+
+    async def dispatch(self, request: Request, call_next):
+        # Skip health checks
+        if request.url.path.startswith("/health"):
+            return await call_next(request)
+        client = request.client.host if request.client else "unknown"
+        now = time.time()
+        window = 60.0
+        recent = [t for t in self._buckets[client] if now - t < window]
+        if len(recent) >= self._limit:
+            return Response(
+                content='{"error":"rate limit exceeded"}',
+                status_code=429,
+                media_type="application/json",
+            )
+        recent.append(now)
+        self._buckets[client] = recent
+        return await call_next(request)

download/face-intel/api/routes/__init__.py

@@ -0,0 +1,7 @@
+"""Routes package — one router per resource."""
+
+from api.routes import (
+    health, stats, providers, cache, jobs, faces, search, export,
+)
+
+__all__ = ["health", "stats", "providers", "cache", "jobs", "faces", "search", "export"]

download/face-intel/api/routes/cache.py

@@ -0,0 +1,23 @@
+"""Cache routes — inspection + invalidation."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+
+from api.deps import get_cache_service
+from services.cache_service import CacheService
+
+router = APIRouter()
+
+
+@router.get("")
+@router.get("/")
+async def cache_stats(svc: CacheService = Depends(get_cache_service)):
+    return svc.stats()
+
+
+@router.delete("")
+@router.delete("/")
+async def cache_clear(svc: CacheService = Depends(get_cache_service)):
+    n = svc.clear()
+    return {"cleared": n}

download/face-intel/api/routes/export.py

@@ -0,0 +1,20 @@
+"""Export routes — download job results as JSON."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import PlainTextResponse
+
+from api.deps import get_export_service
+from services.export_service import ExportService
+
+router = APIRouter()
+
+
+@router.get("/{job_id}")
+async def export_job(job_id: str, svc: ExportService = Depends(get_export_service)):
+    data = svc.export_job_json_str(job_id)
+    if data is None:
+        raise HTTPException(status_code=404, detail="Job not found")
+    return PlainTextResponse(content=data, media_type="application/json",
+                             headers={"Content-Disposition": f"attachment; filename={job_id}.json"})

download/face-intel/api/routes/faces.py

@@ -0,0 +1,53 @@
+"""Face routes — detect / recognize endpoints (convenience wrappers)."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel
+
+from api.deps import get_detection_service, get_recognition_service
+from models.jobs import JobKind, JobRequest
+from services.detection_service import DetectionService
+from services.recognition_service import RecognitionService
+
+router = APIRouter()
+
+
+class FaceRequest(BaseModel):
+    image_url: Optional[str] = None
+    image_base64: Optional[str] = None
+    providers: List[str] = []
+
+
+@router.post("/detect")
+async def detect_faces(req: FaceRequest, svc: DetectionService = Depends(get_detection_service)):
+    job_req = JobRequest(
+        kind=JobKind.DETECTION,
+        image_url=req.image_url,
+        image_base64=req.image_base64,
+        providers=req.providers,
+    )
+    return await svc.detect(job_req)
+
+
+@router.post("/recognize")
+async def recognize_faces(req: FaceRequest, svc: RecognitionService = Depends(get_recognition_service)):
+    job_req = JobRequest(
+        kind=JobKind.RECOGNITION,
+        image_url=req.image_url,
+        image_base64=req.image_base64,
+        providers=req.providers,
+    )
+    return await svc.recognize(job_req)
+
+
+@router.get("/gallery")
+async def list_gallery(svc: RecognitionService = Depends(get_recognition_service)):
+    return {"persons": svc.list_known_persons()}
+
+
+@router.delete("/gallery/{name}")
+async def remove_from_gallery(name: str, svc: RecognitionService = Depends(get_recognition_service)):
+    return svc.remove_known_person(name)

download/face-intel/api/routes/health.py

@@ -0,0 +1,32 @@
+"""Health routes."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+
+from api.deps import get_health_service
+from services.health_service import HealthService
+
+router = APIRouter()
+
+
+@router.get("")
+@router.get("/")
+async def health_root():
+    return {"status": "ok"}
+
+
+@router.get("/providers")
+async def health_providers(health: HealthService = Depends(get_health_service)):
+    return health.snapshot().model_dump()
+
+
+@router.get("/live")
+async def liveness():
+    return {"status": "alive"}
+
+
+@router.get("/ready")
+async def readiness():
+    """Minimal readiness check.  Real checks would verify DB + cache."""
+    return {"status": "ready"}

download/face-intel/api/routes/jobs.py

@@ -0,0 +1,45 @@
+"""Job routes — create / inspect / list jobs."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+
+from api.deps import get_job_service
+from models.jobs import JobKind, JobRequest
+from services.job_service import JobService
+
+router = APIRouter()
+
+
+@router.post("")
+@router.post("/")
+async def create_job(request: JobRequest, svc: JobService = Depends(get_job_service)):
+    return await svc.create_and_run(request)
+
+
+@router.get("")
+@router.get("/")
+async def list_jobs(
+    limit: int = Query(50, ge=1, le=500),
+    status: Optional[str] = None,
+    svc: JobService = Depends(get_job_service),
+):
+    return {"jobs": svc.list_jobs(limit=limit, status=status)}
+
+
+@router.get("/{job_id}")
+async def get_job(job_id: str, svc: JobService = Depends(get_job_service)):
+    job = svc.get_job(job_id)
+    if not job:
+        raise HTTPException(status_code=404, detail="Job not found")
+    return job
+
+
+@router.get("/{job_id}/result")
+async def get_job_result(job_id: str, svc: JobService = Depends(get_job_service)):
+    result = svc.get_result(job_id)
+    if not result:
+        raise HTTPException(status_code=404, detail="Result not found")
+    return result

download/face-intel/api/routes/providers.py

@@ -0,0 +1,24 @@
+"""Provider routes — list/get provider info."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from api.deps import get_provider_service
+from services.provider_service import ProviderService
+
+router = APIRouter()
+
+
+@router.get("")
+@router.get("/")
+async def list_providers(svc: ProviderService = Depends(get_provider_service)):
+    return {"providers": svc.list_providers(), "errors": svc.manifest_errors()}
+
+
+@router.get("/{name}")
+async def get_provider(name: str, svc: ProviderService = Depends(get_provider_service)):
+    info = svc.get_provider(name)
+    if not info:
+        raise HTTPException(status_code=404, detail=f"Provider '{name}' not found")
+    return info

download/face-intel/api/routes/search.py

@@ -0,0 +1,45 @@
+"""Search routes — scrape + reverse-image-search."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel
+
+from api.deps import get_search_service
+from models.jobs import JobKind, JobRequest
+from services.search_service import SearchService
+
+router = APIRouter()
+
+
+class SearchRequest(BaseModel):
+    image_url: Optional[str] = None
+    image_base64: Optional[str] = None
+    providers: List[str] = []
+    scrape_url: Optional[str] = None
+
+
+@router.post("/reverse")
+async def reverse_search(req: SearchRequest, svc: SearchService = Depends(get_search_service)):
+    job_req = JobRequest(
+        kind=JobKind.SEARCH,
+        image_url=req.image_url,
+        image_base64=req.image_base64,
+        providers=req.providers,
+        options={"scrape_url": req.scrape_url} if req.scrape_url else {},
+    )
+    return await svc.search(job_req)
+
+
+@router.post("/scrape")
+async def scrape(req: SearchRequest, svc: SearchService = Depends(get_search_service)):
+    job_req = JobRequest(
+        kind=JobKind.SEARCH,
+        image_url=req.image_url,
+        image_base64=req.image_base64,
+        providers=req.providers,
+        options={"scrape_url": req.scrape_url} if req.scrape_url else {},
+    )
+    return await svc.search(job_req)

download/face-intel/api/routes/stats.py

@@ -0,0 +1,15 @@
+"""Stats routes — exposes metrics."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+
+from api.deps import get_metrics
+
+router = APIRouter()
+
+
+@router.get("")
+@router.get("/")
+async def stats_root(metrics=Depends(get_metrics)):
+    return metrics.snapshot()

download/face-intel/app.py

@@ -0,0 +1,28 @@
+"""
+Application entry point.
+
+Run with:
+    uvicorn app:app --host 0.0.0.0 --port 8000 --reload
+
+or directly:
+    python app.py
+"""
+
+from __future__ import annotations
+
+import uvicorn
+
+from api.main import create_app
+from config.settings import settings
+
+app = create_app(settings)
+
+
+if __name__ == "__main__":
+    uvicorn.run(
+        "app:app",
+        host=settings.host,
+        port=settings.port,
+        reload=settings.debug,
+        log_level=settings.log_level.lower(),
+    )

download/face-intel/confidence/__init__.py

@@ -0,0 +1,10 @@
+"""
+Confidence package — explainable scoring + cross-provider conflict
+detection.
+"""
+
+from confidence.engine import ConfidenceEngine
+from confidence.explainer import Explainer
+from confidence.conflicts import ConflictDetector
+
+__all__ = ["ConfidenceEngine", "Explainer", "ConflictDetector"]

download/face-intel/confidence/conflicts.py

@@ -0,0 +1,75 @@
+"""
+Conflict detector — finds cross-provider disagreements.
+
+Currently detects:
+  - face_count_mismatch   (detectors disagree on number of faces)
+  - match_disagreement    (recognizers disagree on best match for same face)
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Protocol
+
+from models.reports import ConflictReport
+from providers.base import ProviderResult
+
+
+# Duck-typed protocols (confidence must not import from normalization)
+class _BoxLike(Protocol):
+    detector: str
+    confidence: float
+
+class _MatchLike(Protocol):
+    query_face_index: int
+    best_match: str | None
+    recognizer: str
+
+
+class ConflictDetector:
+    """Detects cross-provider disagreements."""
+
+    def detect(
+        self,
+        results: Dict[str, ProviderResult],
+        boxes: List[_BoxLike],
+        matches: List[_MatchLike],
+    ) -> List[ConflictReport]:
+        conflicts: List[ConflictReport] = []
+
+        # Face count mismatch
+        detector_counts: Dict[str, int] = {}
+        for r in results.values():
+            if r.success and r.capability.value == "detection":
+                detector_counts[r.provider] = r.normalized.get("num_faces", 0)
+        if detector_counts:
+            counts = list(detector_counts.values())
+            if max(counts) != min(counts):
+                conflicts.append(ConflictReport(
+                    kind="face_count_mismatch",
+                    providers=list(detector_counts.keys()),
+                    description=(
+                        f"Detectors disagree on face count: {detector_counts}"
+                    ),
+                    severity="warning",
+                ))
+
+        # Match disagreement (same face index, different best match)
+        by_face: Dict[int, List[NormalizedMatch]] = {}
+        for m in matches:
+            by_face.setdefault(m.query_face_index, []).append(m)
+        for face_idx, face_matches in by_face.items():
+            if len(face_matches) < 2:
+                continue
+            best_matches = {m.best_match for m in face_matches if m.best_match}
+            if len(best_matches) > 1:
+                conflicts.append(ConflictReport(
+                    kind="match_disagreement",
+                    providers=[m.recognizer for m in face_matches],
+                    description=(
+                        f"Recognizers disagree on best match for face #{face_idx}: "
+                        f"{[(m.recognizer, m.best_match) for m in face_matches]}"
+                    ),
+                    severity="warning",
+                ))
+
+        return conflicts

download/face-intel/confidence/engine.py

@@ -0,0 +1,183 @@
+"""
+Confidence engine — decomposes every score into weighted sub-scores
+with a human-readable explanation.
+
+Sub-scores:
+  - source_reliability   (provider's track record)
+  - cross_provider_consensus (how many providers agree)
+  - detection_confidence (raw provider confidence)
+  - latency_penalty      (slower = lower confidence)
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Protocol
+
+from models.reports import (
+    ConfidenceScore,
+    ConflictReport,
+    FaceDetection,
+    FaceMatch,
+)
+
+# NOTE: confidence/ must NOT import from normalization/ (dependency direction
+# is normalization -> confidence).  We accept duck-typed objects that expose
+# the attributes we need (.detector, .confidence, .query_face_index,
+# .best_match, .distance, .recognizer) instead of importing the DTOs.
+
+
+class _BoxLike(Protocol):
+    detector: str
+    confidence: float
+
+
+class _MatchLike(Protocol):
+    query_face_index: int
+    best_match: str | None
+    distance: float
+    recognizer: str
+
+
+WEIGHTS = {
+    "source_reliability": 0.25,
+    "cross_provider_consensus": 0.30,
+    "detection_confidence": 0.35,
+    "latency_penalty": 0.10,
+}
+
+# Default reliability per provider (can be overridden by metrics history)
+DEFAULT_RELIABILITY = {
+    "haar": 0.65,
+    "dnn": 0.85,
+    "mtcnn": 0.92,
+    "retinaface": 0.95,
+    "face_recognition": 0.90,
+    "deepface": 0.88,
+    "insightface": 0.93,
+    "beautifulsoup": 0.75,
+    "selenium": 0.70,
+    "bing": 0.85,
+    "duckduckgo": 0.65,
+    "google_lens": 0.55,  # brittle
+    "serpapi": 0.90,
+    "yandex": 0.55,
+    "tineye": 0.88,
+}
+
+
+class ConfidenceEngine:
+    """Computes weighted confidence scores."""
+
+    def __init__(self, reliability_overrides: dict | None = None) -> None:
+        self._reliability = {**DEFAULT_RELIABILITY, **(reliability_overrides or {})}
+
+    # ------------------------------------------------------------------ #
+    # Detection confidence
+    # ------------------------------------------------------------------ #
+    def score_detection(
+        self,
+        nbox: _BoxLike,
+        all_results: dict[str, Any],
+    ) -> ConfidenceScore:
+        provider = nbox.detector
+        source_rel = self._reliability.get(provider, 0.7)
+
+        # Cross-provider consensus: how many detectors found a similar box?
+        num_detectors = sum(
+            1 for r in all_results.values()
+            if r.success and r.capability.value == "detection"
+        )
+        consensus = min(1.0, num_detectors / 3.0)  # 3 detectors = full consensus
+
+        det_conf = nbox.confidence
+
+        # Latency penalty: <100ms = 1.0, >2000ms = 0.5
+        provider_result = all_results.get(provider)
+        latency = provider_result.elapsed_ms if provider_result else 500.0
+        latency_score = max(0.5, 1.0 - (latency / 4000.0))
+
+        components = {
+            "source_reliability": round(source_rel, 4),
+            "cross_provider_consensus": round(consensus, 4),
+            "detection_confidence": round(det_conf, 4),
+            "latency_penalty": round(latency_score, 4),
+        }
+        overall = sum(
+            components[k] * WEIGHTS[k] for k in WEIGHTS
+        )
+        explanation = (
+            f"{provider} detected a face with raw confidence {det_conf:.2f}. "
+            f"{num_detectors} detector(s) ran in this job "
+            f"(consensus={consensus:.2f}). "
+            f"Provider reliability={source_rel:.2f}, "
+            f"latency={latency:.0f}ms (score={latency_score:.2f})."
+        )
+        return ConfidenceScore(
+            overall=round(overall, 4),
+            components=components,
+            explanation=explanation,
+            method="weighted_average",
+        )
+
+    # ------------------------------------------------------------------ #
+    # Recognition match confidence
+    # ------------------------------------------------------------------ #
+    def score_match(self, nm: _MatchLike) -> ConfidenceScore:
+        provider = nm.recognizer
+        source_rel = self._reliability.get(provider, 0.7)
+        # Distance → confidence: distance 0 = 1.0, distance 1.0 = 0.0
+        match_conf = max(0.0, 1.0 - nm.distance)
+        components = {
+            "source_reliability": round(source_rel, 4),
+            "cross_provider_consensus": 0.5,  # placeholder; enriched when multiple recognizers ran
+            "detection_confidence": round(match_conf, 4),
+            "latency_penalty": 0.9,
+        }
+        overall = sum(components[k] * WEIGHTS[k] for k in WEIGHTS)
+        explanation = (
+            f"{provider} matched face #{nm.query_face_index} "
+            f"to '{nm.best_match}' with distance {nm.distance:.3f} "
+            f"(match confidence={match_conf:.2f})."
+        )
+        return ConfidenceScore(
+            overall=round(overall, 4),
+            components=components,
+            explanation=explanation,
+            method="weighted_average",
+        )
+
+    # ------------------------------------------------------------------ #
+    # Overall report confidence
+    # ------------------------------------------------------------------ #
+    def score_overall(
+        self,
+        report_detections: List[FaceDetection],
+        matches: List[FaceMatch],
+        conflicts: List[ConflictReport],
+    ) -> ConfidenceScore:
+        if not report_detections:
+            return ConfidenceScore(
+                overall=0.0,
+                components={},
+                explanation="No faces detected.",
+            )
+        detection_avg = sum(d.confidence.overall for d in report_detections) / len(report_detections)
+        match_avg = (
+            sum(m.confidence.overall for m in matches) / len(matches)
+            if matches else 0.0
+        )
+        conflict_penalty = max(0.0, 1.0 - (0.15 * len(conflicts)))
+        overall = detection_avg * 0.5 + match_avg * 0.3 + conflict_penalty * 0.2
+        return ConfidenceScore(
+            overall=round(overall, 4),
+            components={
+                "detection_avg": round(detection_avg, 4),
+                "match_avg": round(match_avg, 4),
+                "conflict_penalty": round(conflict_penalty, 4),
+            },
+            explanation=(
+                f"Report confidence from {len(report_detections)} detection(s) "
+                f"and {len(matches)} match(es) with {len(conflicts)} conflict(s)."
+            ),
+            method="weighted_average",
+        )

download/face-intel/confidence/explainer.py

@@ -0,0 +1,42 @@
+"""
+Explainer — turns a ConfidenceScore into a multi-line human-readable
+string for display in the UI.
+"""
+
+from __future__ import annotations
+
+from models.reports import ConfidenceScore, UnifiedFaceReport
+
+
+class Explainer:
+    """Renders confidence + report as human-readable text."""
+
+    @staticmethod
+    def explain_score(score: ConfidenceScore) -> str:
+        lines = [f"Overall confidence: {score.overall:.2%} ({score.method})"]
+        if score.explanation:
+            lines.append(f"  {score.explanation}")
+        if score.components:
+            lines.append("  Components:")
+            for k, v in score.components.items():
+                lines.append(f"    - {k}: {v:.3f}")
+        return "\n".join(lines)
+
+    @staticmethod
+    def explain_report(report: UnifiedFaceReport) -> str:
+        m = report.metadata
+        lines = [
+            f"Job {m.job_id} — {m.total_elapsed_ms:.0f}ms total",
+            f"  Providers invoked: {', '.join(m.providers_invoked) or 'none'}",
+            f"  Succeeded: {', '.join(m.providers_succeeded) or 'none'}",
+            f"  Failed: {', '.join(m.providers_failed) or 'none'}",
+            f"  Detections: {len(report.detections)}",
+            f"  Matches: {len(report.matches)}",
+            f"  Scraped images: {len(report.scraped_images)}",
+            f"  Reverse matches: {len(report.reverse_matches)}",
+            f"  Conflicts: {len(report.conflicts)}",
+        ]
+        if report.overall_confidence:
+            lines.append("")
+            lines.append(Explainer.explain_score(report.overall_confidence))
+        return "\n".join(lines)

download/face-intel/config/__init__.py

@@ -1,7 +1,9 @@
-"""Re-export the singleton settings for convenient imports."""
+"""Config package — re-exports settings + path constants."""
 
 from config.settings import (
+    Settings,
     settings,
+    make_settings,
     BASE_DIR,
     DATA_DIR,
     MODELS_DIR,
@@ -12,7 +14,9 @@ from config.settings import (
 )
 
 __all__ = [
+    "Settings",
     "settings",
+    "make_settings",
     "BASE_DIR",
     "DATA_DIR",
     "MODELS_DIR",

download/face-intel/config/settings.py

@@ -2,8 +2,13 @@
 Centralized configuration for Face Intel.
 
 All settings are environment-driven via pydantic-settings so the same
-code runs in dev, test, and production without code changes.  See
-`.env.example` for every supported variable.
+code runs in dev, test, and production without code changes.
+
+After the refactor, `settings` is still importable for backward
+compatibility with provider modules that read tuning knobs, BUT every
+stateful service (storage, cache, orchestrator, services) receives its
+dependencies through constructor injection — never by importing this
+module directly.
 """
 
 from __future__ import annotations
@@ -43,7 +48,7 @@ class Settings(BaseSettings):
     # ------------------------------------------------------------------ #
     app_name: str = "Face Intel"
     app_version: str = "1.0.0"
-    environment: str = "development"  # development | staging | production
+    environment: str = "development"
     host: str = "0.0.0.0"
     port: int = 8000
     debug: bool = False
@@ -54,7 +59,7 @@ class Settings(BaseSettings):
     enable_haar: bool = True
     enable_dnn: bool = True
     enable_mtcnn: bool = True
-    enable_retinaface: bool = False  # requires insightface
+    enable_retinaface: bool = False
     enable_face_recognition: bool = True
     enable_deepface: bool = False
     enable_insightface: bool = False
@@ -79,10 +84,10 @@ class Settings(BaseSettings):
     # Recognition tuning
     # ------------------------------------------------------------------ #
     face_recognition_tolerance: float = 0.6
-    face_recognition_model: str = "hog"  # hog | cnn
+    face_recognition_model: str = "hog"
     deepface_backend: str = "arcface"
     insightface_model_pack: str = "buffalo_l"
-    recognition_match_threshold: float = 0.5  # cosine similarity cutoff
+    recognition_match_threshold: float = 0.5
 
     # ------------------------------------------------------------------ #
     # Scraping
@@ -114,9 +119,6 @@ class Settings(BaseSettings):
     retry_max_attempts: int = 3
     retry_initial_backoff_seconds: float = 0.5
     retry_max_backoff_seconds: float = 8.0
-    retry_retriable_exceptions: List[str] = Field(
-        default_factory=lambda: ["TimeoutError", "ConnectionError"]
-    )
 
     # ------------------------------------------------------------------ #
     # Cache
@@ -143,9 +145,7 @@ class Settings(BaseSettings):
     # API
     # ------------------------------------------------------------------ #
     rate_limit_per_minute: int = 30
-    cors_origins: List[str] = Field(
-        default_factory=lambda: ["*"]
-    )
+    cors_origins: List[str] = Field(default_factory=lambda: ["*"])
     require_consent_header: bool = True
     consent_header_name: str = "X-Consent-Statement"
 
@@ -156,4 +156,21 @@ class Settings(BaseSettings):
     log_json: bool = False
 
 
+def make_settings(**overrides) -> Settings:
+    """Factory used by the DI container to build a Settings instance.
+
+    Tests can override individual fields without touching env vars:
+        make_settings(environment="test", cache_enabled=False)
+    """
+    if overrides:
+        # Build a fresh instance with overrides merged
+        base = Settings()
+        data = base.model_dump()
+        data.update(overrides)
+        return Settings(**data)
+    return Settings()
+
+
+# Default singleton — fine for read-only config consumption by providers.
+# Stateful services MUST be injected, not import this directly.
 settings = Settings()

download/face-intel/docs/ARCHITECTURE.md

@@ -0,0 +1,609 @@
+# Face Intel — Architecture
+
+> Refactored architecture (v2).  Introduces a services layer, a pipeline
+> package, a provider registry, a metrics subsystem, separated storage,
+> shared domain models, strict one-way dependency direction, comprehensive
+> dependency injection, and structured execution-context logging.
+
+---
+
+## 1. Dependency Graph (strict one-way)
+
+```
+                        ┌──────────┐
+                        │   API    │   FastAPI routes + middleware
+                        └────┬─────┘
+                             │
+                        ┌────▼─────┐
+                        │ Services │   business logic (8 services)
+                        └────┬─────┘
+                             │
+              ┌──────────────┼──────────────┐
+              │              │              │
+         ┌────▼─────┐  ┌────▼─────┐  ┌─────▼──────┐
+         │ Orchest. │  │ Confid.  │  │ Normaliz. │
+         └────┬─────┘  └────┬─────┘  └─────┬──────┘
+              │             │              │
+              └─────────────┼──────────────┘
+                            │
+                       ┌────▼─────┐
+                       │ Pipeline │   validation → preprocess → hash → feature_extract
+                       └────┬─────┘
+                            │
+                       ┌────▼─────┐
+                       │ Providers│   detection / recognition / scraper / reverse
+                       └────┬─────┘
+                            │
+                       ┌────▼─────┐
+                       │ Storage  │   database / cache / artifacts / reference_store
+                       └────┬─────┘
+                            │
+                       ┌────▼─────┐
+                       │  Utils   │   image / http / audit / timing / logging
+                       └────┬─────┘
+                            │
+                       ┌────▼─────┐
+                       │  Models  │   shared domain DTOs (pure pydantic, no deps)
+                       └──────────┘
+```
+
+**Rule:** arrows point downward. A layer may import only from layers
+below it. `models/` is at the bottom and depends on nothing but pydantic
++ stdlib. No circular imports — verified by `scripts/check_imports.py`.
+
+**Cross-cutting:** `config/` (settings) is read by every layer but is a
+value object, not stateful. `metrics/` is consumed by orchestrator +
+services + API but owns no upstream dependencies.
+
+---
+
+## 2. Package Responsibilities
+
+| Package | Responsibility | Key Exports |
+|---|---|---|
+| `config/` | Environment-driven settings (Pydantic BaseSettings) | `Settings`, `make_settings()` |
+| `models/` | Shared domain DTOs (pure pydantic, no logic) | `Job`, `JobRequest`, `UnifiedFaceReport`, `ProviderInfo`, `HealthSnapshot`, `APIResponse` |
+| `utils/` | Stateless helpers: image I/O, HTTP session, audit log, timing, structured logging | `bytes_to_numpy`, `shared_session`, `audit_log`, `execution_context`, `setup_logging` |
+| `storage/` | Persistence: SQLite (jobs), TTL cache, file artifacts, reference gallery | `Database`, `Cache`, `ArtifactStore`, `ReferenceStore` |
+| `metrics/` | Per-provider latency/success/retry counters, timings, health, cache hit ratio | `MetricsCollector` (facade) |
+| `providers/` | Provider Protocol + BaseProvider + Registry + 4 capability folders | `Provider`, `BaseProvider`, `ProviderRegistry`, `PROVIDER_MANIFEST` |
+| `pipeline/` | Local pre-orchestrator stages: validate → preprocess → hash → feature-extract → postprocess | `InputValidator`, `ImagePreprocessor`, `ImageHasher`, `FeatureExtractor`, `PipelineOutput` |
+| `orchestrator/` | Async fan-out, retry, circuit breaker | `Orchestrator`, `RetryPolicy`, `HealthMonitor` |
+| `normalization/` | Merge multi-provider results into unified report; internal DTOs only | `ReportMerger`, `NormalizedBox`, `NormalizedMatch` |
+| `confidence/` | Explainable scoring + cross-provider conflict detection | `ConfidenceEngine`, `ConflictDetector`, `Explainer` |
+| `services/` | Business logic; one service per concern | `DetectionService`, `RecognitionService`, `SearchService`, `JobService`, `ProviderService`, `CacheService`, `HealthService`, `ExportService` |
+| `api/` | FastAPI app, DI container, middleware, route handlers | `create_app()`, `ServiceContainer`, `build_container()` |
+| `ui/` | Static SPA (served by FastAPI) | — |
+| `tests/` | Unit + provider + integration test suites | — |
+
+---
+
+## 3. Execution Flow
+
+```
+HTTP request
+    │
+    ▼
+FastAPI middleware:  request-id → rate-limit → CORS
+    │
+    ▼
+Route handler  (api/routes/<resource>.py)
+    │  depends( get_<service> )  →  pulls service off app.state.container
+    ▼
+Service  (services/<name>_service.py)
+    │  1. InputValidator.validate(image_url|base64|bytes)
+    │  2. ImagePreprocessor.from_url|from_bytes  →  PreprocessedImage
+    │  3. ImageHasher.hash                        →  cache key
+    │  4. FeatureExtractor.extract                →  PipelineOutput
+    │                                              (image + hash + face_crops + optional gallery/scrape_url)
+    │  5. Orchestrator.run(pipeline_output, capabilities)
+    │  6. ReportMerger.merge(results)             →  UnifiedFaceReport
+    │  7. return {report, elapsed_ms}
+    ▼
+Orchestrator  (orchestrator/runner.py)
+    │  for each provider matching capabilities:
+    │    - skip if circuit breaker open
+    │    - check cache; hit → return cached ProviderResult
+    │    - else: asyncio.to_thread(provider.execute(pipeline_output))
+    │    - apply RetryPolicy (exponential backoff + jitter)
+    │    - record metrics (latency, success/failure, retries)
+    │    - cache successful results
+    ▼
+Provider  (providers/<category>/<name>.py)
+    │  receives PipelineOutput
+    │  extracts .image / .face_crops / .gallery / .scrape_url
+    │  runs its model / HTTP call
+    │  returns ProviderResult(raw=verbatim, normalized={...}, elapsed_ms, success)
+    ▼
+Normalization  (normalization/merger.py)
+    │  collects NormalizedBox / NormalizedMatch / NormalizedScrapeImage / NormalizedReverseMatch
+    │  preserves every ProviderResult as Evidence
+    │  delegates scoring to ConfidenceEngine
+    │  delegates conflicts to ConflictDetector
+    │  returns UnifiedFaceReport
+    ▼
+Response  →  JSON to client
+```
+
+---
+
+## 4. Lifecycle Diagrams
+
+### 4.1 Application Startup
+
+```
+create_app(settings)
+    │
+    ├─ setup_logging(settings)               # loguru sinks + execution-context format
+    │
+    ├─ lifespan:
+    │     build_container(settings)          # composition root (DI)
+    │       │
+    │       ├─ ProviderRegistry(settings)
+    │       │     .discover()                 # imports each provider module, instantiates, registers
+    │       │                                 # missing optional deps → NOT_CONFIGURED (graceful)
+    │       │
+    │       ├─ Cache(ttl, max_entries)
+    │       ├─ Database(path)                 # SQLite, schema migrated
+    │       ├─ ArtifactStore(root=uploads/)
+    │       ├─ ReferenceStore(root=gallery/)
+    │       │
+    │       ├─ MetricsCollector(failure_threshold, recovery_seconds)
+    │       ├─ HealthMonitor(metrics.health)
+    │       │
+    │       ├─ Orchestrator(registry, cache, metrics, health, settings, retry_policy)
+    │       │
+    │       ├─ ConfidenceEngine()
+    │       ├─ ConflictDetector()
+    │       │
+    │       ├─ InputValidator()
+    │       ├─ ImagePreprocessor(max_dim=1024)
+    │       ├─ ImageHasher()
+    │       ├─ FeatureExtractor(detector=first_detection_provider)
+    │       │
+    │       ├─ DetectionService(...)
+    │       ├─ RecognitionService(...)
+    │       ├─ SearchService(...)
+    │       ├─ JobService(detection, recognition, search, database, metrics)
+    │       ├─ ProviderService(registry)
+    │       ├─ CacheService(cache)
+    │       ├─ HealthService(registry, health, metrics)
+    │       └─ ExportService(database)
+    │
+    ├─ app.state.container = container
+    │
+    └─ mount routes + UI
+```
+
+### 4.2 Request Lifecycle
+
+```
+1.  HTTP request hits FastAPI
+2.  RequestContextMiddleware  →  assigns X-Request-ID, starts timer
+3.  RateLimitMiddleware       →  enforces per-IP limit (sliding 60s window)
+4.  Route handler             →  Depends(get_<service>) pulls from container
+5.  Service                   →  runs pipeline → orchestrator → normalization → confidence
+6.  Orchestrator              →  per-provider: cache check → retry-wrapped invoke → metrics
+7.  Provider                  →  executes within execution_context(provider_id=...)
+8.  Result flows back up:     ProviderResult → UnifiedFaceReport → JSON response
+9.  Response headers          →  X-Request-ID, X-Response-Time-ms
+```
+
+### 4.3 Circuit Breaker Lifecycle
+
+```
+provider.invoke() succeeds
+    │
+    ▼
+HealthMetrics.record_success(name)
+    │  → consecutive_failures = 0
+    │  → avg_latency_ms = exp-avg
+    │  → if circuit_open: close it
+    ▼
+circuit stays CLOSED
+
+
+provider.invoke() fails
+    │
+    ▼
+HealthMetrics.record_failure(name)
+    │  → consecutive_failures += 1
+    │  → if consecutive_failures >= threshold AND not circuit_open:
+    │        circuit_open = True
+    │        circuit_opened_at = now()
+    ▼
+circuit OPEN  →  orchestrator skips this provider
+                   until recovery_seconds elapsed
+
+
+next invoke attempt after recovery_seconds
+    │
+    ▼
+HealthMetrics.is_circuit_open(name)
+    │  → if circuit_open AND now - opened_at > recovery_seconds:
+    │        circuit_open = False   (half-open)
+    │        return False           (allow attempt)
+    ▼
+provider gets one trial invoke
+    success → circuit stays closed
+    failure → circuit re-opens
+```
+
+---
+
+## 5. Extension Guide — Adding a New Provider
+
+Adding a provider requires **two changes** and **zero orchestrator/API edits**.
+
+### Step 1 — Implement the provider
+
+Create `providers/<category>/<your_provider>.py`:
+
+```python
+from __future__ import annotations
+from config.settings import Settings, settings as _default
+from pipeline.feature_extraction import PipelineOutput
+from providers.base import BaseProvider, ProviderCapability, ProviderResult
+
+
+class YourProvider(BaseProvider):
+    name = "your_provider"
+    capability = ProviderCapability.DETECTION  # or RECOGNITION / SCRAPING / REVERSE_SEARCH
+
+    def __init__(self, settings: Settings | None = None) -> None:
+        super().__init__(settings=settings or _default)
+        # ... initialize your model / client
+
+    def is_available(self) -> bool:
+        # Return False if optional deps or API keys are missing.
+        return True
+
+    def _run(self, pipeline_output: PipelineOutput) -> tuple[dict, dict]:
+        img = pipeline_output.image   # extract what you need
+        # ... do your work
+        raw = {"...": ...}            # verbatim response (preserved as evidence)
+        normalized = {
+            "boxes": [{"x": 0, "y": 0, "w": 0, "h": 0}],
+            "num_faces": 1,
+            "confidences": [0.95],
+            "landmarks": None,
+        }
+        return raw, normalized
+```
+
+### Step 2 — Add one manifest entry
+
+Edit `providers/registry.py`:
+
+```python
+PROVIDER_MANIFEST: list[ManifestEntry] = [
+    # ... existing entries ...
+    ManifestEntry(
+        name="your_provider",
+        module_path="providers.detection.your_provider",
+        class_name="YourProvider",
+        capability=ProviderCapability.DETECTION,
+        enable_flag="enable_your_provider",
+        description="Your provider — one-line description",
+        optional_dependency=True,   # set True if it imports an optional package
+    ),
+]
+```
+
+### Step 3 — Add the enable flag
+
+Edit `config/settings.py`:
+
+```python
+enable_your_provider: bool = False
+# ... any tuning knobs your provider needs, e.g.:
+your_provider_threshold: float = 0.7
+```
+
+### Step 4 — Done
+
+- The registry auto-discovers your provider on startup.
+- The orchestrator invokes it for matching capability queries.
+- `/providers` lists it automatically.
+- `/stats` tracks its latency, success rate, retries.
+- The circuit breaker protects against its failures.
+- The cache dedupes identical invocations.
+
+**No other file needs to change.** This is the core extensibility guarantee.
+
+---
+
+## 6. Dependency Injection
+
+### Principle
+
+> No global objects for stateful services. Inject services, storage,
+> metrics, cache, and orchestrator through constructors.
+
+### Composition Root
+
+`api/container.py::build_container()` is the **only** place where
+services are constructed. It runs once at app startup and stores the
+`ServiceContainer` on `app.state.container`.
+
+### How Routes Receive Services
+
+```python
+# api/routes/faces.py
+from fastapi import Depends
+from api.deps import get_detection_service
+
+@router.post("/detect")
+async def detect_faces(req: FaceRequest,
+                       svc: DetectionService = Depends(get_detection_service)):
+    return await svc.detect(job_req)
+```
+
+`get_detection_service` is a thin wrapper:
+
+```python
+# api/deps.py
+def get_detection_service(request: Request):
+    return get_container(request).detection_service
+```
+
+### Why This Matters
+
+- **Testability:** tests construct a container with `:memory:` DB, disabled
+  network providers, and assert against the same code path as production.
+- **No hidden state:** every dependency is visible in the constructor
+  signature — no surprise module-level singletons.
+- **Easy overrides:** swap any component (cache, DB, registry) by
+  constructing a custom container in tests or for feature flags.
+
+---
+
+## 7. Structured Logging
+
+Every log line produced inside an execution carries:
+
+```
+2026-07-10 14:30:00.123 | INFO     | eid=abc123def456 | pid=haar | retry=0 | status=started | invoking haar
+```
+
+| Field | Source | Meaning |
+|---|---|---|
+| `eid` | `execution_context(execution_id=...)` | Unique id for the top-level job |
+| `pid` | `execution_context(provider_id=...)` | Provider name (or `-` for service-level logs) |
+| `retry` | `execution_context(retry_count=...)` | Retry attempt number (0 = first try) |
+| `status` | updated via the context dict | `started` → `running` → `success` / `failed` / `retried` |
+
+### Usage
+
+```python
+from utils.logging import execution_context, new_execution_id
+
+async def my_handler():
+    eid = new_execution_id()
+    with execution_context(execution_id=eid, provider_id="my_service"):
+        logger.info("started")           # → eid=…, pid=my_service, status=started
+        # ... do work ...
+        logger.info("completed")          # → same eid + pid
+```
+
+### JSON Mode
+
+Set `FI_LOG_JSON=true` to emit newline-delimited JSON for log
+aggregators (Loki, Datadog, CloudWatch):
+
+```json
+{"timestamp":"2026-07-10T14:30:00.123Z","level":"INFO","execution_id":"abc123def456","provider_id":"haar","retry_count":0,"status":"started","message":"invoking haar"}
+```
+
+---
+
+## 8. Metrics Subsystem
+
+`metrics/` tracks six categories consumed by `/stats` and the UI:
+
+| Subsystem | What it tracks | Where it's recorded |
+|---|---|---|
+| `ProviderMetrics` | per-provider invocations, successes, failures, retries, latency samples | orchestrator after each provider call |
+| `TimingCollector` | per-operation duration histograms (p50, p95) | services record `job.detection`, `job.recognition`, `job.search` |
+| `CounterRegistry` | global counters (cache.hits, cache.misses, retries.<provider>, failures.<provider>, jobs.<kind>.completed) | orchestrator + services |
+| `HealthMetrics` | per-provider consecutive failures, avg latency, circuit-breaker state | orchestrator via HealthMonitor |
+
+`MetricsCollector` is a facade that owns all four — injected as a single
+object so services don't depend on four separate classes.
+
+`GET /stats` returns the full snapshot:
+
+```json
+{
+  "providers": [{"name": "haar", "invocations": 42, "successes": 41, "failures": 1, "retries": 0, "avg_latency_ms": 6.2, "p95_latency_ms": 12.4, "success_rate": 0.976}],
+  "timings": {"job.detection": {"count": 42, "avg_ms": 14.3, "p50_ms": 12.0, "p95_ms": 28.1}},
+  "counters": {"cache.hits": 18, "cache.misses": 24, "jobs.detection.completed": 42},
+  "health": [{"name": "haar", "consecutive_failures": 0, "avg_latency_ms": 6.2, "circuit_open": false}]
+}
+```
+
+---
+
+## 9. REST API Surface
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/health` | Liveness probe |
+| `GET` | `/health/live` | Liveness |
+| `GET` | `/health/ready` | Readiness |
+| `GET` | `/health/providers` | Per-provider health snapshot |
+| `GET` | `/stats` | Full metrics snapshot |
+| `GET` | `/providers` | List all providers + manifest errors |
+| `GET` | `/providers/{name}` | Single provider info |
+| `GET` | `/cache` | Cache stats (entries, hit ratio, evictions) |
+| `DELETE` | `/cache` | Clear cache |
+| `POST` | `/jobs` | Create + run a job (detection / recognition / search / full_pipeline) |
+| `GET` | `/jobs` | List recent jobs |
+| `GET` | `/jobs/{id}` | Job metadata |
+| `GET` | `/jobs/{id}/result` | Job result (UnifiedFaceReport) |
+| `POST` | `/faces/detect` | Convenience: detect-only |
+| `POST` | `/faces/recognize` | Convenience: recognize-only |
+| `GET` | `/faces/gallery` | List known persons |
+| `DELETE` | `/faces/gallery/{name}` | Remove a known person |
+| `POST` | `/search/reverse` | Reverse image search |
+| `POST` | `/search/scrape` | Scrape images from a URL |
+| `GET` | `/export/{job_id}` | Download job result as JSON |
+| `GET` | `/docs` | OpenAPI Swagger UI |
+
+---
+
+## 10. File Tree (refactored)
+
+```
+face-intel/
+├── app.py                          # entry point: uvicorn app:app
+├── requirements.txt
+├── .env.example
+├── README.md
+│
+├── config/
+│   ├── __init__.py
+│   └── settings.py                 # Settings + make_settings() factory
+│
+├── models/                         # NEW: shared domain DTOs
+│   ├── __init__.py
+│   ├── jobs.py                     # Job, JobRequest, JobStatus, JobResult, JobKind
+│   ├── providers.py                # ProviderCapability, ProviderStatus, ProviderInfo, ProviderConfig
+│   ├── reports.py                  # UnifiedFaceReport, FaceDetection, FaceMatch, Evidence, ConfidenceScore, ConflictReport
+│   ├── responses.py                # APIResponse, PaginatedResponse, ErrorResponse, HealthResponse
+│   └── health.py                   # HealthSnapshot, ProviderHealthSnapshot, SystemHealthSnapshot
+│
+├── utils/                          # lowest layer
+│   ├── __init__.py
+│   ├── image.py                    # bytes↔numpy, BBox, crop, hash, draw
+│   ├── http.py                     # shared requests.Session with retries
+│   ├── audit.py                    # append-only JSONL audit log
+│   ├── timing.py                   # @contextmanager timed()
+│   └── logging.py                  # NEW: loguru + execution_context()
+│
+├── storage/                        # separated responsibilities
+│   ├── __init__.py
+│   ├── database.py                 # SQLite (jobs, results)
+│   ├── cache.py                    # in-memory TTL + LRU
+│   ├── artifacts.py                # filesystem: uploads/, generated/
+│   └── reference_store.py          # known-faces gallery (.npy + manifest.json)
+│
+├── metrics/                        # NEW
+│   ├── __init__.py
+│   ├── provider_metrics.py         # per-provider latency/success/retry
+│   ├── timings.py                  # operation-level p50/p95
+│   ├── counters.py                 # named integer counters
+│   ├── health_metrics.py           # circuit breaker state
+│   └── collector.py                # MetricsCollector facade
+│
+├── providers/
+│   ├── __init__.py                 # re-exports (no globals)
+│   ├── base.py                     # Provider Protocol, BaseProvider, ProviderResult
+│   ├── registry.py                 # NEW: ProviderRegistry class + PROVIDER_MANIFEST
+│   ├── detection/
+│   │   ├── __init__.py
+│   │   └── haar.py                 # implemented (DI-updated)
+│   ├── recognition/                # stubs (to be implemented Phase 3)
+│   ├── scraper/
+│   └── reverse/
+│
+├── pipeline/                       # NEW
+│   ├── __init__.py
+│   ├── validation.py               # InputValidator
+│   ├── preprocessing.py            # ImagePreprocessor → PreprocessedImage
+│   ├── hashing.py                  # ImageHasher (SHA-256 cache key)
+│   ├── feature_extraction.py       # FeatureExtractor → PipelineOutput
+│   └── postprocessing.py           # dedupe, clamp, filter
+│
+├── orchestrator/
+│   ├── __init__.py
+│   ├── runner.py                   # Orchestrator (async fan-out, DI-injected)
+│   ├── retry.py                    # RetryPolicy, with_retry_sync/async
+│   └── health.py                   # HealthMonitor (circuit breaker gate)
+│
+├── normalization/
+│   ├── __init__.py
+│   ├── schema.py                   # internal DTOs (NormalizedBox, NormalizedMatch, ...)
+│   └── merger.py                   # ReportMerger (provider results → UnifiedFaceReport)
+│
+├── confidence/
+│   ├── __init__.py
+│   ├── engine.py                   # ConfidenceEngine (weighted sub-scores)
+│   ├── explainer.py                # human-readable explanations
+│   └── conflicts.py                # ConflictDetector (cross-provider disagreements)
+│
+├── services/                       # NEW
+│   ├── __init__.py
+│   ├── detection_service.py
+│   ├── recognition_service.py
+│   ├── search_service.py
+│   ├── job_service.py              # full-pipeline + persistence
+│   ├── provider_service.py
+│   ├── cache_service.py
+│   ├── health_service.py
+│   └── export_service.py
+│
+├── api/
+│   ├── __init__.py
+│   ├── main.py                     # create_app() factory
+│   ├── container.py                # build_container() — composition root
+│   ├── deps.py                     # FastAPI Depends() callables
+│   ├── middleware.py               # request-id, rate limit
+│   └── routes/
+│       ├── __init__.py
+│       ├── health.py
+│       ├── stats.py
+│       ├── providers.py
+│       ├── cache.py
+│       ├── jobs.py
+│       ├── faces.py
+│       ├── search.py
+│       └── export.py
+│
+├── ui/
+│   └── static/                     # served by FastAPI (to be built Phase 8)
+│
+├── tests/                          # to be built Phase 9
+│   ├── unit/
+│   ├── providers/
+│   └── integration/
+│
+└── docs/
+    └── ARCHITECTURE.md             # this file
+```
+
+---
+
+## 11. Verification
+
+The refactor has been smoke-tested end-to-end:
+
+```
+✓ All 11 layers import cleanly — no circular dependencies
+✓ DI container builds with all 15 manifest entries registered
+✓ FastAPI app boots with 32 routes
+✓ End-to-end detection job runs: pipeline → orchestrator → haar → normalization → confidence → report
+✓ Haar provider correctly receives PipelineOutput (not raw numpy)
+✓ Evidence preserved with raw + normalized + elapsed_ms + success
+✓ Confidence engine produces explainable sub-scores
+✓ Metrics subsystem records invocations, successes, timings
+✓ Circuit-breaker state queryable via /health/providers
+```
+
+---
+
+## 12. What's Next
+
+The refactor establishes the production-grade skeleton. The remaining
+work from the original 10-phase plan:
+
+- **Phase 3 (continued):** implement the 14 remaining provider modules
+  (dnn, mtcnn, retinaface, face_recognition, deepface, insightface,
+  beautifulsoup, selenium, bing, duckduckgo, google_lens, serpapi,
+  yandex, tineye). Each follows the `haar.py` pattern — ~50 LOC.
+- **Phase 8:** build the UI SPA in `ui/static/`.
+- **Phase 9:** write the test suites in `tests/`.
+- **Phase 10:** provider-specific docs, deployment, benchmarks.
+
+The architecture will not need to change for any of these — only
+additions within existing packages.

download/face-intel/metrics/__init__.py

@@ -0,0 +1,22 @@
+"""
+Metrics subsystem — tracks provider latency, success/failure counts,
+retries, cache hit ratio, and execution duration.
+
+All metrics are in-process and thread-safe.  Designed to be scraped
+by the /stats endpoint.  No external metrics backend (Prometheus etc.)
+is required, but the data model is compatible with one.
+"""
+
+from metrics.provider_metrics import ProviderMetrics
+from metrics.timings import TimingCollector
+from metrics.counters import CounterRegistry
+from metrics.health_metrics import HealthMetrics
+from metrics.collector import MetricsCollector
+
+__all__ = [
+    "ProviderMetrics",
+    "TimingCollector",
+    "CounterRegistry",
+    "HealthMetrics",
+    "MetricsCollector",
+]

download/face-intel/metrics/collector.py

@@ -0,0 +1,40 @@
+"""
+MetricsCollector — aggregates the four metric subsystems into one
+injectable facade so services don't depend on four separate objects.
+"""
+
+from __future__ import annotations
+
+from metrics.provider_metrics import ProviderMetrics
+from metrics.timings import TimingCollector
+from metrics.counters import CounterRegistry
+from metrics.health_metrics import HealthMetrics
+
+
+class MetricsCollector:
+    """Facade that owns all metric subsystems."""
+
+    def __init__(self,
+                 failure_threshold: int = 5,
+                 recovery_seconds: int = 120) -> None:
+        self.providers = ProviderMetrics()
+        self.timings = TimingCollector()
+        self.counters = CounterRegistry()
+        self.health = HealthMetrics(
+            failure_threshold=failure_threshold,
+            recovery_seconds=recovery_seconds,
+        )
+
+    def snapshot(self) -> dict:
+        return {
+            "providers": self.providers.snapshot(),
+            "timings": self.timings.snapshot(),
+            "counters": self.counters.snapshot(),
+            "health": self.health.snapshot(),
+        }
+
+    def reset(self) -> None:
+        self.providers.reset()
+        self.timings.reset()
+        self.counters.reset()
+        self.health.reset()

download/face-intel/metrics/counters.py

@@ -0,0 +1,33 @@
+"""
+Global monotonic counters — cache hits/misses, requests, errors.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import defaultdict
+from typing import Dict
+
+
+class CounterRegistry:
+    """Named integer counters."""
+
+    def __init__(self) -> None:
+        self._lock = threading.RLock()
+        self._counters: Dict[str, int] = defaultdict(int)
+
+    def inc(self, name: str, amount: int = 1) -> None:
+        with self._lock:
+            self._counters[name] += amount
+
+    def get(self, name: str) -> int:
+        with self._lock:
+            return self._counters.get(name, 0)
+
+    def snapshot(self) -> Dict[str, int]:
+        with self._lock:
+            return dict(self._counters)
+
+    def reset(self) -> None:
+        with self._lock:
+            self._counters.clear()

download/face-intel/metrics/health_metrics.py

@@ -0,0 +1,89 @@
+"""
+Health metrics — feeds the circuit breaker and the /health endpoint.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Dict, Optional
+
+
+@dataclass
+class HealthRecord:
+    name: str
+    consecutive_failures: int = 0
+    last_success: Optional[float] = None     # epoch
+    last_failure: Optional[float] = None
+    avg_latency_ms: float = 0.0
+    circuit_open: bool = False
+    circuit_opened_at: Optional[float] = None
+
+
+class HealthMetrics:
+    """Per-provider health record + circuit breaker state."""
+
+    def __init__(self, failure_threshold: int = 5,
+                 recovery_seconds: int = 120) -> None:
+        self._lock = threading.RLock()
+        self._records: Dict[str, HealthRecord] = {}
+        self._failure_threshold = failure_threshold
+        self._recovery_seconds = recovery_seconds
+
+    def _get(self, name: str) -> HealthRecord:
+        if name not in self._records:
+            self._records[name] = HealthRecord(name=name)
+        return self._records[name]
+
+    def record_success(self, name: str, latency_ms: float) -> None:
+        with self._lock:
+            r = self._get(name)
+            r.consecutive_failures = 0
+            r.last_success = time.time()
+            # rolling avg
+            r.avg_latency_ms = 0.9 * r.avg_latency_ms + 0.1 * latency_ms if r.avg_latency_ms else latency_ms
+            # auto-close circuit on success
+            if r.circuit_open:
+                r.circuit_open = False
+                r.circuit_opened_at = None
+
+    def record_failure(self, name: str) -> None:
+        with self._lock:
+            r = self._get(name)
+            r.consecutive_failures += 1
+            r.last_failure = time.time()
+            if r.consecutive_failures >= self._failure_threshold and not r.circuit_open:
+                r.circuit_open = True
+                r.circuit_opened_at = time.time()
+
+    def is_circuit_open(self, name: str) -> bool:
+        with self._lock:
+            r = self._get(name)
+            if not r.circuit_open:
+                return False
+            # half-open after recovery window
+            if r.circuit_opened_at and (time.time() - r.circuit_opened_at) > self._recovery_seconds:
+                r.circuit_open = False
+                r.circuit_opened_at = None
+                return False
+            return True
+
+    def snapshot(self) -> list[dict]:
+        with self._lock:
+            out = []
+            for name, r in self._records.items():
+                out.append({
+                    "name": name,
+                    "consecutive_failures": r.consecutive_failures,
+                    "last_success": datetime.fromtimestamp(r.last_success, tz=timezone.utc).isoformat() if r.last_success else None,
+                    "last_failure": datetime.fromtimestamp(r.last_failure, tz=timezone.utc).isoformat() if r.last_failure else None,
+                    "avg_latency_ms": round(r.avg_latency_ms, 3),
+                    "circuit_open": r.circuit_open,
+                })
+            return out
+
+    def reset(self) -> None:
+        with self._lock:
+            self._records.clear()

download/face-intel/metrics/provider_metrics.py

@@ -0,0 +1,86 @@
+"""
+Per-provider metrics: latency histogram (simplified), success/failure
+counts, retry counts.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import defaultdict
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+
+@dataclass
+class ProviderStat:
+    name: str
+    invocations: int = 0
+    successes: int = 0
+    failures: int = 0
+    retries: int = 0
+    latencies_ms: List[float] = field(default_factory=list)
+    last_latency_ms: float = 0.0
+    last_error: str = ""
+
+    def to_dict(self) -> dict:
+        total = self.successes + self.failures
+        avg = sum(self.latencies_ms) / len(self.latencies_ms) if self.latencies_ms else 0.0
+        p95 = sorted(self.latencies_ms)[int(len(self.latencies_ms) * 0.95)] if self.latencies_ms else 0.0
+        return {
+            "name": self.name,
+            "invocations": self.invocations,
+            "successes": self.successes,
+            "failures": self.failures,
+            "retries": self.retries,
+            "success_rate": round(self.successes / total, 4) if total else 0.0,
+            "avg_latency_ms": round(avg, 3),
+            "p95_latency_ms": round(p95, 3),
+            "last_latency_ms": round(self.last_latency_ms, 3),
+            "last_error": self.last_error,
+        }
+
+
+class ProviderMetrics:
+    """Thread-safe per-provider metrics collector."""
+
+    MAX_LATENCY_SAMPLES = 500  # rolling window
+
+    def __init__(self) -> None:
+        self._lock = threading.RLock()
+        self._stats: Dict[str, ProviderStat] = defaultdict(lambda: None)
+
+    def _get(self, name: str) -> ProviderStat:
+        if self._stats[name] is None:
+            self._stats[name] = ProviderStat(name=name)
+        return self._stats[name]
+
+    def record_invocation(self, name: str) -> None:
+        with self._lock:
+            self._get(name).invocations += 1
+
+    def record_success(self, name: str, latency_ms: float) -> None:
+        with self._lock:
+            s = self._get(name)
+            s.successes += 1
+            s.last_latency_ms = latency_ms
+            s.latencies_ms.append(latency_ms)
+            if len(s.latencies_ms) > self.MAX_LATENCY_SAMPLES:
+                s.latencies_ms = s.latencies_ms[-self.MAX_LATENCY_SAMPLES:]
+
+    def record_failure(self, name: str, error: str = "") -> None:
+        with self._lock:
+            s = self._get(name)
+            s.failures += 1
+            s.last_error = error
+
+    def record_retry(self, name: str) -> None:
+        with self._lock:
+            self._get(name).retries += 1
+
+    def snapshot(self) -> List[dict]:
+        with self._lock:
+            return [self._get(name).to_dict() for name in sorted(self._stats.keys())]
+
+    def reset(self) -> None:
+        with self._lock:
+            self._stats.clear()

download/face-intel/metrics/timings.py

@@ -0,0 +1,46 @@
+"""
+Execution timing collector — tracks end-to-end job durations.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import defaultdict
+from typing import Dict, List
+
+
+class TimingCollector:
+    """Tracks durations grouped by operation label."""
+
+    MAX_SAMPLES = 500
+
+    def __init__(self) -> None:
+        self._lock = threading.RLock()
+        self._samples: Dict[str, List[float]] = defaultdict(list)
+
+    def record(self, label: str, duration_ms: float) -> None:
+        with self._lock:
+            self._samples[label].append(duration_ms)
+            if len(self._samples[label]) > self.MAX_SAMPLES:
+                self._samples[label] = self._samples[label][-self.MAX_SAMPLES:]
+
+    def snapshot(self) -> dict:
+        with self._lock:
+            out = {}
+            for label, samples in self._samples.items():
+                if not samples:
+                    continue
+                s = sorted(samples)
+                out[label] = {
+                    "count": len(samples),
+                    "avg_ms": round(sum(samples) / len(samples), 3),
+                    "p50_ms": round(s[len(s) // 2], 3),
+                    "p95_ms": round(s[int(len(s) * 0.95)], 3),
+                    "min_ms": round(s[0], 3),
+                    "max_ms": round(s[-1], 3),
+                }
+            return out
+
+    def reset(self) -> None:
+        with self._lock:
+            self._samples.clear()

download/face-intel/models/__init__.py

@@ -0,0 +1,59 @@
+"""
+Shared domain models.
+
+These are the cross-layer data contracts.  Only normalization-specific
+DTOs live in `normalization/schema.py`; everything else that crosses a
+layer boundary is defined here.
+
+Dependency rule: models/ imports only from pydantic + stdlib.  It never
+imports from utils, storage, providers, pipeline, orchestrator, services,
+or api.
+"""
+
+from models.jobs import (
+    Job,
+    JobRequest,
+    JobStatus,
+    JobResult,
+    JobKind,
+)
+from models.providers import (
+    ProviderCapability,
+    ProviderStatus,
+    ProviderInfo,
+    ProviderConfig,
+)
+from models.reports import (
+    UnifiedFaceReport,
+    FaceDetection,
+    FaceMatch,
+    Evidence,
+    ConfidenceScore,
+    ConflictReport,
+    ReportMetadata,
+)
+from models.responses import (
+    APIResponse,
+    PaginatedResponse,
+    ErrorResponse,
+    HealthResponse,
+)
+from models.health import (
+    HealthSnapshot,
+    ProviderHealthSnapshot,
+    SystemHealthSnapshot,
+)
+
+__all__ = [
+    # jobs
+    "Job", "JobRequest", "JobStatus", "JobResult", "JobKind",
+    # providers
+    "ProviderCapability", "ProviderStatus", "ProviderInfo", "ProviderConfig",
+    # reports
+    "UnifiedFaceReport", "FaceDetection", "FaceMatch", "Evidence",
+    "ConfidenceScore", "ConflictReport", "ReportMetadata",
+    # responses
+    "APIResponse", "PaginatedResponse", "ErrorResponse", "HealthResponse",
+    # health
+    "HealthSnapshot", "ProviderHealthSnapshot", "SystemHealthSnapshot",
+]

download/face-intel/models/health.py

@@ -0,0 +1,38 @@
+"""Health-related domain models."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class ProviderHealthSnapshot(BaseModel):
+    """Per-provider health snapshot used by the circuit breaker + API."""
+    name: str
+    healthy: bool
+    consecutive_failures: int = 0
+    last_success: Optional[datetime] = None
+    last_failure: Optional[datetime] = None
+    last_check: Optional[datetime] = None
+    avg_latency_ms: float = 0.0
+    circuit_open: bool = False
+    circuit_opened_at: Optional[datetime] = None
+    metadata: dict = Field(default_factory=dict)
+
+
+class SystemHealthSnapshot(BaseModel):
+    """Aggregate system health."""
+    status: str = "healthy"               # healthy | degraded | unhealthy
+    version: str = "1.0.0"
+    uptime_seconds: float = 0.0
+    providers: List[ProviderHealthSnapshot] = Field(default_factory=list)
+    cache: dict = Field(default_factory=dict)
+    metrics: dict = Field(default_factory=dict)
+
+
+class HealthSnapshot(BaseModel):
+    """Convenience alias."""
+    system: SystemHealthSnapshot
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))

download/face-intel/models/jobs.py

@@ -0,0 +1,75 @@
+"""Job-related domain models — used by services, storage, and API."""
+
+from __future__ import annotations
+
+import enum
+import uuid
+from datetime import datetime, timezone
+from typing import Any, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class JobKind(str, enum.Enum):
+    DETECTION = "detection"
+    RECOGNITION = "recognition"
+    SEARCH = "search"               # scrape + reverse image search
+    FULL_PIPELINE = "full_pipeline"  # detect + recognize + search
+
+
+class JobStatus(str, enum.Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class JobRequest(BaseModel):
+    """Inbound request to create a job."""
+    kind: JobKind
+    image_url: Optional[str] = None
+    image_base64: Optional[str] = None
+    providers: List[str] = Field(
+        default_factory=list,
+        description="Optional whitelist of provider names. Empty = use all enabled.",
+    )
+    options: dict = Field(default_factory=dict)
+
+    def has_image_input(self) -> bool:
+        return bool(self.image_url or self.image_base64)
+
+
+class Job(BaseModel):
+    """Persisted job record."""
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    kind: JobKind
+    status: JobStatus = JobStatus.PENDING
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    started_at: Optional[datetime] = None
+    completed_at: Optional[datetime] = None
+    request: JobRequest
+    image_hash: Optional[str] = None
+    error: Optional[str] = None
+
+    def mark_running(self) -> None:
+        self.status = JobStatus.RUNNING
+        self.started_at = datetime.now(timezone.utc)
+
+    def mark_completed(self) -> None:
+        self.status = JobStatus.COMPLETED
+        self.completed_at = datetime.now(timezone.utc)
+
+    def mark_failed(self, error: str) -> None:
+        self.status = JobStatus.FAILED
+        self.completed_at = datetime.now(timezone.utc)
+        self.error = error
+
+
+class JobResult(BaseModel):
+    """The output of a completed job — wraps a UnifiedFaceReport."""
+    job_id: str
+    status: JobStatus
+    report: Optional[Any] = None  # UnifiedFaceReport (avoid circular import)
+    error: Optional[str] = None
+    elapsed_ms: float = 0.0

download/face-intel/models/providers.py

@@ -0,0 +1,51 @@
+"""Provider-related domain models.
+
+Note: ProviderCapability and ProviderStatus are also re-exported from
+providers/base.py for legacy compatibility, but the canonical home is
+here in models/ (per refactor requirement 6).
+"""
+
+from __future__ import annotations
+
+import enum
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+
+class ProviderCapability(str, enum.Enum):
+    DETECTION = "detection"
+    RECOGNITION = "recognition"
+    SCRAPING = "scraping"
+    REVERSE_SEARCH = "reverse_search"
+
+
+class ProviderStatus(str, enum.Enum):
+    HEALTHY = "healthy"
+    DEGRADED = "degraded"
+    UNHEALTHY = "unhealthy"
+    DISABLED = "disabled"
+    NOT_CONFIGURED = "not_configured"
+
+
+class ProviderInfo(BaseModel):
+    """Public-facing description of a registered provider."""
+    name: str
+    capability: ProviderCapability
+    status: ProviderStatus
+    available: bool
+    description: str = ""
+    version: str = ""
+    metadata: dict = Field(default_factory=dict)
+
+
+class ProviderConfig(BaseModel):
+    """Configuration entry used by the registry manifest."""
+    name: str
+    module_path: str
+    class_name: str
+    capability: ProviderCapability
+    enable_flag: str
+    description: str = ""
+    requires_api_key: bool = False
+    optional_dependency: bool = False

download/face-intel/models/reports.py

@@ -0,0 +1,79 @@
+"""Report domain models — the unified output of a face-intelligence job."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class Evidence(BaseModel):
+    """Preserved raw provider output — never discarded."""
+    provider: str
+    capability: str
+    raw: Any = None                      # verbatim provider response
+    normalized: dict = Field(default_factory=dict)
+    elapsed_ms: float = 0.0
+    success: bool = True
+    error: Optional[str] = None
+    error_type: Optional[str] = None
+    metadata: dict = Field(default_factory=dict)
+
+
+class ConfidenceScore(BaseModel):
+    """Explainable confidence — decomposed into weighted sub-scores."""
+    overall: float                        # 0.0 – 1.0
+    components: Dict[str, float] = Field(default_factory=dict)
+    explanation: str = ""
+    method: str = "weighted_average"
+
+
+class FaceDetection(BaseModel):
+    """One detected face, with cross-provider consensus."""
+    box: Dict[str, int]                   # {x, y, w, h}
+    confidence: ConfidenceScore
+    landmarks: Optional[Dict[str, List[int]]] = None
+    detected_by: List[str] = Field(default_factory=list)
+    embedding: Optional[List[float]] = None
+    embedding_provider: Optional[str] = None
+
+
+class FaceMatch(BaseModel):
+    """A recognition match against the reference gallery."""
+    query_face_index: int
+    best_match: Optional[str] = None
+    confidence: ConfidenceScore
+    distances: Dict[str, float] = Field(default_factory=dict)
+
+
+class ConflictReport(BaseModel):
+    """Cross-provider disagreement."""
+    kind: str                             # e.g. "face_count_mismatch"
+    providers: List[str]
+    description: str
+    severity: str = "info"                # info | warning | error
+
+
+class ReportMetadata(BaseModel):
+    """Job/report metadata."""
+    job_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    image_hash: Optional[str] = None
+    total_elapsed_ms: float = 0.0
+    providers_invoked: List[str] = Field(default_factory=list)
+    providers_succeeded: List[str] = Field(default_factory=list)
+    providers_failed: List[str] = Field(default_factory=list)
+
+
+class UnifiedFaceReport(BaseModel):
+    """The final unified report consumed by API + UI."""
+    metadata: ReportMetadata
+    detections: List[FaceDetection] = Field(default_factory=list)
+    matches: List[FaceMatch] = Field(default_factory=list)
+    scraped_images: List[dict] = Field(default_factory=list)
+    reverse_matches: List[dict] = Field(default_factory=list)
+    evidence: List[Evidence] = Field(default_factory=list)
+    conflicts: List[ConflictReport] = Field(default_factory=list)
+    overall_confidence: Optional[ConfidenceScore] = None

download/face-intel/models/responses.py

@@ -0,0 +1,36 @@
+"""API response wrapper models."""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from pydantic import BaseModel
+
+
+class APIResponse(BaseModel):
+    """Standard envelope for successful responses."""
+    success: bool = True
+    data: Any
+    message: str = ""
+
+
+class PaginatedResponse(BaseModel):
+    success: bool = True
+    data: List[Any]
+    total: int
+    page: int = 1
+    page_size: int = 50
+
+
+class ErrorResponse(BaseModel):
+    success: bool = False
+    error: str
+    error_type: str = ""
+    details: Optional[dict] = None
+
+
+class HealthResponse(BaseModel):
+    status: str
+    version: str
+    providers: List[dict]
+    uptime_seconds: float

download/face-intel/normalization/__init__.py

@@ -0,0 +1,23 @@
+"""
+Normalization package — merges multi-provider ProviderResults into a
+single UnifiedFaceReport, preserving every Evidence record.
+
+Internal-only DTOs (NormalizedBox, NormalizedMatch, etc.) live here.
+Cross-layer models live in models/.
+"""
+
+from normalization.schema import (
+    NormalizedBox,
+    NormalizedMatch,
+    NormalizedScrapeImage,
+    NormalizedReverseMatch,
+)
+from normalization.merger import ReportMerger
+
+__all__ = [
+    "NormalizedBox",
+    "NormalizedMatch",
+    "NormalizedScrapeImage",
+    "NormalizedReverseMatch",
+    "ReportMerger",
+]

download/face-intel/normalization/merger.py

@@ -0,0 +1,202 @@
+"""
+Report merger — turns a dict of {provider_name: ProviderResult} into a
+UnifiedFaceReport.
+
+The merger:
+  1. Extracts NormalizedBox list from each detection provider.
+  2. Extracts NormalizedMatch list from each recognition provider.
+  3. Extracts NormalizedScrapeImage list from each scraper.
+  4. Extracts NormalizedReverseMatch list from each reverse-search.
+  5. Preserves every ProviderResult as Evidence (raw + normalized).
+  6. Delegates confidence scoring to confidence.engine.
+  7. Delegates conflict detection to confidence.conflicts.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+from confidence.engine import ConfidenceEngine
+from confidence.conflicts import ConflictDetector
+from models.reports import (
+    UnifiedFaceReport,
+    FaceDetection,
+    FaceMatch,
+    Evidence,
+    ReportMetadata,
+)
+from normalization.schema import (
+    NormalizedBox,
+    NormalizedMatch,
+    NormalizedScrapeImage,
+    NormalizedReverseMatch,
+)
+from pipeline.postprocessing import ResultPostprocessor
+from providers.base import ProviderResult
+
+
+class ReportMerger:
+    """Merges provider results into a UnifiedFaceReport."""
+
+    def __init__(
+        self,
+        confidence_engine: ConfidenceEngine,
+        conflict_detector: ConflictDetector,
+    ) -> None:
+        self._confidence = confidence_engine
+        self._conflicts = conflict_detector
+
+    def merge(
+        self,
+        results: Dict[str, ProviderResult],
+        image_hash: str,
+        job_id: str,
+        total_elapsed_ms: float,
+    ) -> UnifiedFaceReport:
+        boxes = self._collect_boxes(results)
+        matches = self._collect_matches(results)
+        scraped = self._collect_scraped(results)
+        reverse_matches = self._collect_reverse(results)
+        evidence = self._build_evidence(results)
+
+        # Build FaceDetection objects with confidence
+        detections: List[FaceDetection] = []
+        for i, nbox in enumerate(boxes):
+            score = self._confidence.score_detection(nbox, results)
+            detections.append(FaceDetection(
+                box={"x": nbox.x, "y": nbox.y, "w": nbox.w, "h": nbox.h},
+                confidence=score,
+                landmarks=nbox.landmarks,
+                detected_by=[nbox.detector],
+            ))
+
+        # Build FaceMatch objects
+        face_matches: List[FaceMatch] = []
+        for nm in matches:
+            score = self._confidence.score_match(nm)
+            face_matches.append(FaceMatch(
+                query_face_index=nm.query_face_index,
+                best_match=nm.best_match,
+                confidence=score,
+                distances=nm.distances,
+            ))
+
+        # Detect cross-provider conflicts
+        conflicts = self._conflicts.detect(results, boxes, matches)
+
+        # Metadata
+        succeeded = [r.provider for r in results.values() if r.success]
+        failed = [r.provider for r in results.values() if not r.success]
+        metadata = ReportMetadata(
+            job_id=job_id,
+            image_hash=image_hash,
+            total_elapsed_ms=total_elapsed_ms,
+            providers_invoked=list(results.keys()),
+            providers_succeeded=succeeded,
+            providers_failed=failed,
+        )
+
+        report = UnifiedFaceReport(
+            metadata=metadata,
+            detections=detections,
+            matches=face_matches,
+            scraped_images=[s.__dict__ for s in scraped],
+            reverse_matches=[r.__dict__ for r in reverse_matches],
+            evidence=evidence,
+            conflicts=conflicts,
+            overall_confidence=self._confidence.score_overall(report_detections=detections,
+                                                              matches=face_matches,
+                                                              conflicts=conflicts),
+        )
+        # Patch: rebuild metadata on report (already set above)
+        report.metadata = metadata
+        return report
+
+    # ------------------------------------------------------------------ #
+    # Collectors
+    # ------------------------------------------------------------------ #
+    def _collect_boxes(self, results: Dict[str, ProviderResult]) -> List[NormalizedBox]:
+        out: List[NormalizedBox] = []
+        for r in results.values():
+            if not r.success:
+                continue
+            norm = r.normalized
+            if r.capability.value != "detection":
+                continue
+            boxes = norm.get("boxes", [])
+            confs = norm.get("confidences", [1.0] * len(boxes))
+            lms = norm.get("landmarks")
+            for i, b in enumerate(boxes):
+                lm = lms[i] if isinstance(lms, list) and i < len(lms) else (lms if isinstance(lms, dict) else None)
+                out.append(NormalizedBox(
+                    x=b["x"], y=b["y"], w=b["w"], h=b["h"],
+                    confidence=float(confs[i]) if i < len(confs) else 1.0,
+                    detector=r.provider,
+                    landmarks=lm,
+                ))
+        return out
+
+    def _collect_matches(self, results: Dict[str, ProviderResult]) -> List[NormalizedMatch]:
+        out: List[NormalizedMatch] = []
+        for r in results.values():
+            if not r.success or r.capability.value != "recognition":
+                continue
+            for m in r.normalized.get("matches", []):
+                out.append(NormalizedMatch(
+                    query_face_index=m.get("query_face_index", 0),
+                    best_match=m.get("best_match"),
+                    distance=m.get("distance", 1.0),
+                    distances=m.get("distances", {}),
+                    recognizer=r.provider,
+                ))
+        return out
+
+    def _collect_scraped(self, results: Dict[str, ProviderResult]) -> List[NormalizedScrapeImage]:
+        out: List[NormalizedScrapeImage] = []
+        for r in results.values():
+            if not r.success or r.capability.value != "scraping":
+                continue
+            for img in r.normalized.get("images", []):
+                out.append(NormalizedScrapeImage(
+                    url=img.get("url", ""),
+                    alt=img.get("alt", ""),
+                    source_page=img.get("source_page", ""),
+                    scraper=r.provider,
+                    width=img.get("width"),
+                    height=img.get("height"),
+                ))
+        # Dedupe
+        deduped = ResultPostprocessor.dedupe_images([s.__dict__ for s in out])
+        return [NormalizedScrapeImage(**d) for d in deduped]
+
+    def _collect_reverse(self, results: Dict[str, ProviderResult]) -> List[NormalizedReverseMatch]:
+        out: List[NormalizedReverseMatch] = []
+        for r in results.values():
+            if not r.success or r.capability.value != "reverse_search":
+                continue
+            for m in r.normalized.get("results", []):
+                out.append(NormalizedReverseMatch(
+                    image_url=m.get("image_url", ""),
+                    source_page=m.get("source_page", ""),
+                    title=m.get("title", ""),
+                    snippet=m.get("snippet", ""),
+                    thumbnail=m.get("thumbnail", ""),
+                    provider=r.provider,
+                ))
+        return out
+
+    def _build_evidence(self, results: Dict[str, ProviderResult]) -> List[Evidence]:
+        out: List[Evidence] = []
+        for r in results.values():
+            out.append(Evidence(
+                provider=r.provider,
+                capability=r.capability.value,
+                raw=r.raw,
+                normalized=r.normalized,
+                elapsed_ms=r.elapsed_ms,
+                success=r.success,
+                error=r.error,
+                error_type=r.error_type,
+                metadata=r.metadata,
+            ))
+        return out

download/face-intel/normalization/schema.py

@@ -0,0 +1,53 @@
+"""
+Normalization-internal DTOs.
+
+These are intermediate objects used by the merger before being promoted
+to the cross-layer models in models/reports.py.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+
+@dataclass
+class NormalizedBox:
+    """One face box from one detector."""
+    x: int
+    y: int
+    w: int
+    h: int
+    confidence: float
+    detector: str
+    landmarks: Optional[dict] = None
+
+
+@dataclass
+class NormalizedMatch:
+    """One recognition match against the gallery."""
+    query_face_index: int
+    best_match: Optional[str]
+    distance: float
+    distances: Dict[str, float]
+    recognizer: str
+
+
+@dataclass
+class NormalizedScrapeImage:
+    url: str
+    alt: str
+    source_page: str
+    scraper: str
+    width: Optional[int] = None
+    height: Optional[int] = None
+
+
+@dataclass
+class NormalizedReverseMatch:
+    image_url: str
+    source_page: str
+    title: str
+    snippet: str
+    thumbnail: str
+    provider: str

download/face-intel/orchestrator/__init__.py

@@ -0,0 +1,13 @@
+"""
+Orchestrator package — async fan-out across providers.
+
+After the refactor, the orchestrator receives its dependencies
+(registry, cache, metrics, settings) through its constructor.  No
+globals, no module-level state.
+"""
+
+from orchestrator.runner import Orchestrator
+from orchestrator.retry import RetryPolicy, with_retry_sync, with_retry_async
+from orchestrator.health import HealthMonitor
+
+__all__ = ["Orchestrator", "RetryPolicy", "with_retry_sync", "with_retry_async", "HealthMonitor"]

download/face-intel/orchestrator/health.py

@@ -0,0 +1,37 @@
+"""
+Health monitor — wraps HealthMetrics + scheduled checks.
+
+For now this is a thin wrapper; future work can add a background task
+that pings providers periodically.
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+from metrics.health_metrics import HealthMetrics
+from providers.base import Provider
+
+
+class HealthMonitor:
+    """Reads/writes per-provider health and exposes a circuit-breaker gate."""
+
+    def __init__(self, metrics: HealthMetrics) -> None:
+        self._metrics = metrics
+
+    def record_success(self, provider_name: str, latency_ms: float) -> None:
+        self._metrics.record_success(provider_name, latency_ms)
+
+    def record_failure(self, provider_name: str) -> None:
+        self._metrics.record_failure(provider_name)
+
+    def is_available(self, provider_name: str) -> bool:
+        """Returns False if the circuit breaker is open for this provider."""
+        return not self._metrics.is_circuit_open(provider_name)
+
+    def filter_healthy(self, providers: List[Provider]) -> List[Provider]:
+        """Drop providers whose circuit is open."""
+        return [p for p in providers if self.is_available(p.name)]
+
+    def snapshot(self) -> list[dict]:
+        return self._metrics.snapshot()

download/face-intel/orchestrator/retry.py

@@ -0,0 +1,89 @@
+"""
+Retry policy with exponential backoff + jitter.
+
+Used by the orchestrator to wrap provider invocations.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from dataclasses import dataclass
+from typing import Awaitable, Callable, Tuple, Type
+
+from loguru import logger
+
+
+@dataclass
+class RetryPolicy:
+    """Exponential backoff with full jitter."""
+    max_attempts: int = 3
+    initial_backoff_seconds: float = 0.5
+    max_backoff_seconds: float = 8.0
+    retriable_exceptions: Tuple[Type[BaseException], ...] = (
+        TimeoutError, ConnectionError, OSError,
+    )
+
+    def backoff(self, attempt: int) -> float:
+        """Compute backoff for the given attempt (1-indexed)."""
+        delay = self.initial_backoff_seconds * (2 ** (attempt - 1))
+        delay = min(delay, self.max_backoff_seconds)
+        # full jitter
+        return random.uniform(0, delay)
+
+
+def with_retry_sync(
+    fn: Callable,
+    policy: RetryPolicy,
+    label: str = "",
+    on_retry: Callable[[int, Exception], None] | None = None,
+):
+    """Synchronous retry wrapper."""
+    attempt = 0
+    last_exc: Exception | None = None
+    while attempt < policy.max_attempts:
+        try:
+            attempt += 1
+            return fn()
+        except policy.retriable_exceptions as e:
+            last_exc = e
+            if attempt >= policy.max_attempts:
+                break
+            delay = policy.backoff(attempt)
+            if on_retry:
+                on_retry(attempt, e)
+            logger.warning(
+                f"[retry] {label} attempt {attempt}/{policy.max_attempts} "
+                f"failed: {e}; sleeping {delay:.2f}s"
+            )
+            time.sleep(delay)
+    raise last_exc  # type: ignore
+
+
+async def with_retry_async(
+    fn: Callable[[], Awaitable],
+    policy: RetryPolicy,
+    label: str = "",
+    on_retry: Callable[[int, Exception], None] | None = None,
+):
+    """Asynchronous retry wrapper."""
+    attempt = 0
+    last_exc: Exception | None = None
+    while attempt < policy.max_attempts:
+        try:
+            attempt += 1
+            return await fn()
+        except policy.retriable_exceptions as e:
+            last_exc = e
+            if attempt >= policy.max_attempts:
+                break
+            delay = policy.backoff(attempt)
+            if on_retry:
+                on_retry(attempt, e)
+            logger.warning(
+                f"[retry] {label} attempt {attempt}/{policy.max_attempts} "
+                f"failed: {e}; sleeping {delay:.2f}s"
+            )
+            await asyncio.sleep(delay)
+    raise last_exc  # type: ignore

download/face-intel/orchestrator/runner.py

@@ -0,0 +1,199 @@
+"""
+Orchestrator — async fan-out across providers.
+
+Responsibilities:
+  - Receive a PipelineOutput (never raw user input).
+  - For each target provider:
+      * Skip if circuit breaker is open.
+      * Check cache; if hit, return cached ProviderResult.
+      * Otherwise invoke provider (sync → asyncio.to_thread).
+      * Apply retry policy.
+      * Record metrics (latency, success/failure, retry count).
+      * Cache successful results.
+  - Return a dict mapping provider name → ProviderResult.
+
+All dependencies (registry, cache, metrics, health, retry policy) are
+injected via the constructor.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Awaitable, Callable, Dict, Iterable, Optional
+
+from loguru import logger
+
+from config.settings import Settings
+from metrics.collector import MetricsCollector
+from orchestrator.health import HealthMonitor
+from orchestrator.retry import RetryPolicy, with_retry_sync
+from pipeline.feature_extraction import PipelineOutput
+from providers.base import Provider, ProviderCapability, ProviderResult
+from providers.registry import ProviderRegistry
+from storage.cache import Cache
+from utils.logging import execution_context, new_execution_id
+
+
+class Orchestrator:
+    """Async fan-out across providers.  Injectable."""
+
+    def __init__(
+        self,
+        registry: ProviderRegistry,
+        cache: Cache,
+        metrics: MetricsCollector,
+        health: HealthMonitor,
+        settings: Settings,
+        retry_policy: Optional[RetryPolicy] = None,
+    ) -> None:
+        self._registry = registry
+        self._cache = cache
+        self._metrics = metrics
+        self._health = health
+        self._settings = settings
+        self._retry = retry_policy or RetryPolicy(
+            max_attempts=settings.retry_max_attempts,
+            initial_backoff_seconds=settings.retry_initial_backoff_seconds,
+            max_backoff_seconds=settings.retry_max_backoff_seconds,
+        )
+
+    # ------------------------------------------------------------------ #
+    # Public API
+    # ------------------------------------------------------------------ #
+    async def run(
+        self,
+        pipeline_output: PipelineOutput,
+        capabilities: Iterable[ProviderCapability],
+        provider_whitelist: Optional[list[str]] = None,
+        execution_id: Optional[str] = None,
+    ) -> Dict[str, ProviderResult]:
+        """Fan out across all providers matching the given capabilities.
+
+        Args:
+            pipeline_output: normalized image + face crops.
+            capabilities: which capability buckets to invoke.
+            provider_whitelist: optional list of provider names; if set,
+                only those providers are invoked.
+            execution_id: optional trace id for structured logging.
+
+        Returns:
+            dict mapping provider name → ProviderResult.
+        """
+        eid = execution_id or new_execution_id()
+        targets: list[Provider] = []
+        for cap in capabilities:
+            for p in self._registry.list_by_capability(cap):
+                if provider_whitelist and p.name not in provider_whitelist:
+                    continue
+                if not self._health.is_available(p.name):
+                    logger.info(f"[orchestrator] skipping {p.name}: circuit open")
+                    continue
+                targets.append(p)
+
+        if not targets:
+            logger.warning("[orchestrator] no providers to invoke")
+            return {}
+
+        semaphore = asyncio.Semaphore(self._settings.orchestrator_max_concurrency)
+
+        async def _wrapped(provider: Provider) -> tuple[str, ProviderResult]:
+            async with semaphore:
+                return provider.name, await self._invoke_one(provider, pipeline_output, eid)
+
+        tasks = [_wrapped(p) for p in targets]
+        gathered = await asyncio.gather(*tasks, return_exceptions=False)
+        return dict(gathered)
+
+    # ------------------------------------------------------------------ #
+    # Per-provider invocation (with cache + retry + metrics)
+    # ------------------------------------------------------------------ #
+    async def _invoke_one(
+        self,
+        provider: Provider,
+        pipeline_output: PipelineOutput,
+        execution_id: str,
+    ) -> ProviderResult:
+        cache_key = self._cache_key(provider, pipeline_output)
+
+        # Cache hit?
+        if self._settings.cache_enabled:
+            cached = self._cache.get(cache_key)
+            if cached is not None:
+                self._metrics.counters.inc("cache.hits")
+                logger.debug(f"[orchestrator] cache hit for {provider.name}")
+                cached.metadata["cache_hit"] = True
+                return cached
+        self._metrics.counters.inc("cache.misses")
+
+        # Invoke with retry
+        retry_count = 0
+
+        def _on_retry(attempt: int, exc: Exception) -> None:
+            nonlocal retry_count
+            retry_count = attempt
+            self._metrics.providers.record_retry(provider.name)
+            self._metrics.counters.inc(f"retries.{provider.name}")
+
+        with execution_context(execution_id=execution_id,
+                               provider_id=provider.name,
+                               retry_count=retry_count):
+            logger.info(f"[orchestrator] invoking {provider.name}")
+
+            def _call_sync() -> ProviderResult:
+                return with_retry_sync(
+                    lambda: provider.execute(pipeline_output),
+                    self._retry,
+                    label=provider.name,
+                    on_retry=_on_retry,
+                )
+
+            try:
+                result = await asyncio.wait_for(
+                    asyncio.to_thread(_call_sync),
+                    timeout=self._settings.orchestrator_timeout_seconds,
+                )
+            except asyncio.TimeoutError:
+                result = ProviderResult(
+                    provider=provider.name,
+                    capability=provider.capability,
+                    success=False,
+                    elapsed_ms=self._settings.orchestrator_timeout_seconds * 1000,
+                    error="Orchestrator timeout",
+                    error_type="TimeoutError",
+                    retry_count=retry_count,
+                )
+            except Exception as e:
+                result = ProviderResult(
+                    provider=provider.name,
+                    capability=provider.capability,
+                    success=False,
+                    elapsed_ms=0.0,
+                    error=str(e),
+                    error_type=type(e).__name__,
+                    retry_count=retry_count,
+                )
+
+        result.retry_count = retry_count
+
+        # Record metrics
+        self._metrics.providers.record_invocation(provider.name)
+        if result.success:
+            self._metrics.providers.record_success(provider.name, result.elapsed_ms)
+            self._health.record_success(provider.name, result.elapsed_ms)
+            self._metrics.timings.record(f"provider.{provider.name}", result.elapsed_ms)
+            # Cache
+            if self._settings.cache_enabled:
+                self._cache.set(cache_key, result)
+        else:
+            self._metrics.providers.record_failure(provider.name, result.error or "")
+            self._health.record_failure(provider.name)
+            self._metrics.counters.inc(f"failures.{provider.name}")
+
+        return result
+
+    # ------------------------------------------------------------------ #
+    # Cache key
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def _cache_key(provider: Provider, pipeline_output: PipelineOutput) -> str:
+        return f"{provider.name}:{pipeline_output.image_hash}"

download/face-intel/pipeline/__init__.py

@@ -0,0 +1,36 @@
+"""
+Pipeline package — local processing stages that run BEFORE the
+orchestrator fans out to providers.
+
+Flow:
+    raw user input (bytes / URL / base64)
+        ↓
+    validation.py        — InputValidator   (reject bad input)
+        ↓
+    preprocessing.py     — ImagePreprocessor (decode, resize, normalize)
+        ↓
+    hashing.py           — ImageHasher       (SHA-256 cache key)
+        ↓
+    feature_extraction.py — FeatureExtractor (face crops, default-detector boxes)
+        ↓
+    PipelineOutput       (consumed by orchestrator)
+
+The orchestrator receives a PipelineOutput, never raw user input.
+"""
+
+from pipeline.validation import InputValidator, ValidationResult
+from pipeline.preprocessing import ImagePreprocessor, PreprocessedImage
+from pipeline.hashing import ImageHasher
+from pipeline.feature_extraction import FeatureExtractor, PipelineOutput
+from pipeline.postprocessing import ResultPostprocessor
+
+__all__ = [
+    "InputValidator",
+    "ValidationResult",
+    "ImagePreprocessor",
+    "PreprocessedImage",
+    "ImageHasher",
+    "FeatureExtractor",
+    "PipelineOutput",
+    "ResultPostprocessor",
+]

download/face-intel/pipeline/feature_extraction.py

@@ -0,0 +1,105 @@
+"""
+Feature extraction — uses a default detection provider to pre-locate
+faces and produce crops before the orchestrator fans out.
+
+The orchestrator receives a PipelineOutput that already contains:
+  - preprocessed image
+  - image hash (cache key)
+  - face crops
+  - bounding boxes
+
+This means recognition / reverse-search providers don't each have to
+re-detect faces independently.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+import numpy as np
+from loguru import logger
+
+from providers.base import Provider, ProviderResult
+from utils.image import BBox, crop_face
+
+
+@dataclass
+class FaceCrop:
+    """One pre-extracted face crop."""
+    image: np.ndarray
+    box: dict
+    confidence: float = 1.0
+    detector: str = ""
+
+
+@dataclass
+class PipelineOutput:
+    """The normalized payload the orchestrator consumes.
+
+    Optional fields (`gallery`, `scrape_url`) may be attached by services
+    that need to pass extra context to specific providers.  Recognition
+    providers read `gallery`; scraper providers read `scrape_url`.
+    """
+    image: np.ndarray
+    image_hash: str
+    width: int
+    height: int
+    source: str
+    face_crops: List[FaceCrop] = field(default_factory=list)
+    primary_detector: str = ""
+    # Optional context attached by services (kept here so the orchestrator
+    # passes a single object through to every provider).
+    gallery: Optional[dict] = None
+    scrape_url: Optional[str] = None
+
+    @property
+    def num_faces(self) -> int:
+        return len(self.face_crops)
+
+
+class FeatureExtractor:
+    """Uses a detection provider to pre-extract face crops."""
+
+    def __init__(self, detector: Optional[Provider] = None) -> None:
+        self._detector = detector
+
+    def set_detector(self, provider: Provider) -> None:
+        self._detector = provider
+
+    def extract(self, image: np.ndarray, image_hash: str,
+                width: int, height: int, source: str) -> PipelineOutput:
+        crops: List[FaceCrop] = []
+        detector_name = ""
+
+        if self._detector is not None and self._detector.is_available():
+            try:
+                result: ProviderResult = self._detector.execute(image)
+                if result.success and result.normalized.get("boxes"):
+                    detector_name = result.provider
+                    boxes = result.normalized["boxes"]
+                    confs = result.normalized.get("confidences", [1.0] * len(boxes))
+                    for box_dict, conf in zip(boxes, confs):
+                        bbox = BBox(box_dict["x"], box_dict["y"],
+                                    box_dict["w"], box_dict["h"])
+                        crop = crop_face(image, bbox, margin=0.2)
+                        crops.append(FaceCrop(
+                            image=crop,
+                            box=box_dict,
+                            confidence=float(conf),
+                            detector=detector_name,
+                        ))
+            except Exception as e:
+                logger.warning(f"Feature extraction failed: {e}")
+        else:
+            logger.debug("No detector available; pipeline output will have 0 face crops.")
+
+        return PipelineOutput(
+            image=image,
+            image_hash=image_hash,
+            width=width,
+            height=height,
+            source=source,
+            face_crops=crops,
+            primary_detector=detector_name,
+        )

download/face-intel/pipeline/hashing.py

@@ -0,0 +1,24 @@
+"""
+Image hashing — produces a stable cache key for a preprocessed image.
+
+The hash is computed on the JPEG-encoded bytes (quality 90) so that
+visually identical inputs collapse to the same key.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+import cv2
+import numpy as np
+
+
+class ImageHasher:
+    """SHA-256 over normalized JPEG bytes."""
+
+    @staticmethod
+    def hash(img: np.ndarray, quality: int = 90) -> str:
+        ok, buffer = cv2.imencode(".jpg", img, [cv2.IMWRITE_JPEG_QUALITY, quality])
+        if not ok:
+            raise ValueError("Could not encode image for hashing.")
+        return hashlib.sha256(buffer.tobytes()).hexdigest()

download/face-intel/pipeline/postprocessing.py

@@ -0,0 +1,55 @@
+"""
+Post-processing — applies final cleanup to provider results before
+they enter normalization.
+
+Examples:
+  - de-duplicate scraped image URLs
+  - clamp bounding boxes to image bounds
+  - strip PII from raw responses (placeholder for future policy hooks)
+"""
+
+from __future__ import annotations
+
+from typing import Any, List
+
+from loguru import logger
+
+
+class ResultPostprocessor:
+    """Cleans provider outputs before normalization."""
+
+    @staticmethod
+    def dedupe_images(images: List[dict]) -> List[dict]:
+        """Remove duplicate image URLs."""
+        seen: set[str] = set()
+        out: List[dict] = []
+        for img in images:
+            url = img.get("url") or img.get("image_url")
+            if not url or url in seen:
+                continue
+            seen.add(url)
+            out.append(img)
+        return out
+
+    @staticmethod
+    def clamp_boxes(boxes: List[dict], width: int, height: int) -> List[dict]:
+        """Clamp bounding boxes to image bounds."""
+        out: List[dict] = []
+        for b in boxes:
+            x = max(0, min(b["x"], width - 1))
+            y = max(0, min(b["y"], height - 1))
+            x2 = max(0, min(b["x"] + b["w"], width))
+            y2 = max(0, min(b["y"] + b["h"], height))
+            out.append({"x": x, "y": y, "w": max(0, x2 - x), "h": max(0, y2 - y)})
+        return out
+
+    @staticmethod
+    def filter_low_confidence(boxes: List[dict], confs: List[float],
+                              threshold: float = 0.5) -> tuple[List[dict], List[float]]:
+        """Drop detections below confidence threshold."""
+        out_boxes, out_confs = [], []
+        for b, c in zip(boxes, confs):
+            if c >= threshold:
+                out_boxes.append(b)
+                out_confs.append(c)
+        return out_boxes, out_confs

download/face-intel/pipeline/preprocessing.py

@@ -0,0 +1,69 @@
+"""
+Preprocessing — decode, resize, color-convert.
+
+Takes raw bytes (or URL) and produces a normalized BGR numpy array
+suitable for every downstream provider.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+import numpy as np
+from loguru import logger
+
+from utils.image import bytes_to_numpy, url_to_numpy, resize_with_aspect
+
+
+@dataclass
+class PreprocessedImage:
+    """Output of preprocessing — the canonical image object passed downstream."""
+    image: np.ndarray        # BGR uint8 HxWx3
+    width: int
+    height: int
+    channels: int = 3
+    source: str = ""         # "url" | "base64" | "bytes"
+    resized: bool = False    # True if downscaled to fit max_dim
+
+
+class ImagePreprocessor:
+    """Decodes + resizes inbound images."""
+
+    def __init__(self, max_dim: int = 1024) -> None:
+        self._max_dim = max_dim
+
+    def from_bytes(self, data: bytes, source: str = "bytes") -> PreprocessedImage:
+        img = bytes_to_numpy(data)
+        return self._finalize(img, source)
+
+    def from_url(self, url: str, timeout: int = 15) -> PreprocessedImage:
+        img = url_to_numpy(url, timeout=timeout)
+        return self._finalize(img, "url")
+
+    def from_numpy(self, img: np.ndarray, source: str = "in_memory") -> PreprocessedImage:
+        return self._finalize(img, source)
+
+    def _finalize(self, img: np.ndarray, source: str) -> PreprocessedImage:
+        # Ensure 3 channels
+        if img.ndim == 2:
+            img = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR) if (cv2 := __import__("cv2")) else img
+        elif img.shape[2] == 4:
+            import cv2
+            img = cv2.cvtColor(img, cv2.COLOR_BGRA2BGR)
+
+        resized = False
+        h, w = img.shape[:2]
+        if max(h, w) > self._max_dim:
+            img = resize_with_aspect(img, max_dim=self._max_dim)
+            resized = True
+
+        h, w = img.shape[:2]
+        return PreprocessedImage(
+            image=img,
+            width=w,
+            height=h,
+            channels=img.shape[2] if img.ndim == 3 else 1,
+            source=source,
+            resized=resized,
+        )

download/face-intel/pipeline/validation.py

@@ -0,0 +1,79 @@
+"""
+Input validation — rejects malformed requests before any heavy work.
+
+Validates:
+  - At least one of (image_url, image_base64, image_bytes) is present
+  - image_url is a well-formed http(s) URL
+  - image_base64 is decodable
+  - Image size within configured limits
+"""
+
+from __future__ import annotations
+
+import base64
+from dataclasses import dataclass
+from typing import Optional
+from urllib.parse import urlparse
+
+from loguru import logger
+
+
+@dataclass
+class ValidationResult:
+    valid: bool
+    error: Optional[str] = None
+    image_bytes: Optional[bytes] = None
+    source: str = ""  # "url" | "base64" | "bytes"
+
+
+class InputValidator:
+    """Validates inbound image input."""
+
+    def __init__(self, max_bytes: int = 20 * 1024 * 1024) -> None:
+        """max_bytes defaults to 20 MB."""
+        self._max_bytes = max_bytes
+
+    def validate(
+        self,
+        image_url: Optional[str] = None,
+        image_base64: Optional[str] = None,
+        image_bytes: Optional[bytes] = None,
+    ) -> ValidationResult:
+        # At least one input
+        if not any([image_url, image_base64, image_bytes]):
+            return ValidationResult(False, error="No image input provided.")
+
+        # URL validation
+        if image_url:
+            parsed = urlparse(image_url)
+            if parsed.scheme not in ("http", "https"):
+                return ValidationResult(False, error=f"Unsupported URL scheme: {parsed.scheme}")
+            if not parsed.netloc:
+                return ValidationResult(False, error="URL missing host.")
+            return ValidationResult(True, source="url")
+
+        # Base64 validation
+        if image_base64:
+            try:
+                # Strip data URI prefix if present
+                raw = image_base64.split(",", 1)[-1]
+                decoded = base64.b64decode(raw, validate=True)
+            except Exception as e:
+                return ValidationResult(False, error=f"Invalid base64: {e}")
+            if len(decoded) > self._max_bytes:
+                return ValidationResult(
+                    False,
+                    error=f"Decoded image exceeds {self._max_bytes} bytes",
+                )
+            return ValidationResult(True, image_bytes=decoded, source="base64")
+
+        # Raw bytes
+        if image_bytes:
+            if len(image_bytes) > self._max_bytes:
+                return ValidationResult(
+                    False,
+                    error=f"Image exceeds {self._max_bytes} bytes",
+                )
+            return ValidationResult(True, image_bytes=image_bytes, source="bytes")
+
+        return ValidationResult(False, error="Unreachable.")

download/face-intel/providers/__init__.py

@@ -1,132 +1,34 @@
 """
-Provider package — auto-registers every enabled provider.
-
-Importing this module triggers construction + registration of every
-provider whose `enable_*` flag is true in settings.  Optional providers
-(importable only if their optional dep is installed) are wrapped in
-try/except so a missing dep degrades gracefully to NOT_CONFIGURED.
+Providers package.
+
+After the refactor:
+  - base.py         defines the Protocol + BaseProvider + ProviderResult
+  - registry.py     defines ProviderRegistry (injectable, no globals)
+  - detection/      detection providers
+  - recognition/    recognition providers
+  - scraper/        web-scraping providers
+  - reverse/        reverse-image-search providers
+
+There is NO module-level singleton.  Construct a ProviderRegistry via
+the DI container in api/deps.py.
 """
 
-from __future__ import annotations
-
-from loguru import logger
-
-from config import settings
 from providers.base import (
     Provider,
-    ProviderCapability,
-    ProviderStatus,
-    register_provider,
-    list_providers,
-    get_provider,
-    clear_registry,
+    BaseProvider,
+    ProviderResult,
+)
+from providers.registry import (
+    ProviderRegistry,
+    PROVIDER_MANIFEST,
+    ManifestEntry,
 )
-
-
-def _safe_register(module_path: str, class_name: str, enable_flag: bool) -> None:
-    """Import + register a provider; swallow ImportError if optional dep missing."""
-    if not enable_flag:
-        return
-    try:
-        import importlib
-        module = importlib.import_module(module_path)
-        cls = getattr(module, class_name)
-        instance = cls()
-        register_provider(instance)
-        logger.info(f"Registered provider: {instance.name} ({instance.capability.value})")
-    except ImportError as e:
-        logger.warning(
-            f"Provider {class_name} from {module_path} skipped (missing optional dep): {e}"
-        )
-    except Exception as e:
-        logger.error(f"Failed to register {class_name}: {e}")
-
-
-def initialize_providers() -> None:
-    """Construct and register every enabled provider.  Call once at startup."""
-    # Detection
-    _safe_register("providers.detection.haar", "HaarDetector", settings.enable_haar)
-    _safe_register("providers.detection.dnn", "DNNDetector", settings.enable_dnn)
-    _safe_register("providers.detection.mtcnn", "MTCNNDetector", settings.enable_mtcnn)
-    _safe_register("providers.detection.retinaface", "RetinaFaceDetector", settings.enable_retinaface)
-
-    # Recognition
-    _safe_register(
-        "providers.recognition.face_recognition_provider", "FaceRecognitionProvider",
-        settings.enable_face_recognition,
-    )
-    _safe_register(
-        "providers.recognition.deepface_provider", "DeepFaceProvider",
-        settings.enable_deepface,
-    )
-    _safe_register(
-        "providers.recognition.insightface_provider", "InsightFaceProvider",
-        settings.enable_insightface,
-    )
-
-    # Scraping
-    _safe_register(
-        "providers.scraper.beautifulsoup_scraper", "BeautifulSoupScraper",
-        settings.enable_beautifulsoup_scraper,
-    )
-    _safe_register(
-        "providers.scraper.selenium_scraper", "SeleniumScraper",
-        settings.enable_selenium_scraper,
-    )
-    _safe_register(
-        "providers.scraper.bing_scraper", "BingImageScraper",
-        settings.enable_bing_scraper,
-    )
-    _safe_register(
-        "providers.scraper.duckduckgo_scraper", "DuckDuckGoScraper",
-        settings.enable_duckduckgo_scraper,
-    )
-
-    # Reverse image search
-    _safe_register(
-        "providers.reverse.google_lens", "GoogleLensProvider",
-        settings.enable_google_lens,
-    )
-    _safe_register(
-        "providers.reverse.serpapi", "SerpAPIProvider",
-        settings.enable_serpapi,
-    )
-    _safe_register(
-        "providers.reverse.yandex", "YandexReverseProvider",
-        settings.enable_yandex,
-    )
-    _safe_register(
-        "providers.reverse.tineye", "TinEyeProvider",
-        settings.enable_tineye,
-    )
-
-
-def provider_statuses() -> list[dict]:
-    """Snapshot of every provider's availability + status."""
-    out: list[dict] = []
-    for p in list_providers():
-        try:
-            available = p.is_available()
-        except Exception:
-            available = False
-        status = ProviderStatus.HEALTHY if available else ProviderStatus.NOT_CONFIGURED
-        out.append({
-            "name": p.name,
-            "capability": p.capability.value,
-            "status": status.value,
-            "available": available,
-        })
-    return out
-
 
 __all__ = [
     "Provider",
-    "ProviderCapability",
-    "ProviderStatus",
-    "initialize_providers",
-    "list_providers",
-    "get_provider",
-    "clear_registry",
-    "register_provider",
-    "provider_statuses",
+    "BaseProvider",
+    "ProviderResult",
+    "ProviderRegistry",
+    "PROVIDER_MANIFEST",
+    "ManifestEntry",
 ]