Initial deploy: backend + models + photos

.dockerignore

@@ -0,0 +1,34 @@
+# .dockerignore for the Hugging Face Space repo.
+#
+# Copy this file to the ROOT of your HF Space repo alongside Dockerfile.
+#
+# CRITICAL: models/ is NOT excluded here, because the HF Space image MUST
+# contain the runtime model artifacts. (Contrast with the project's root
+# .dockerignore, which DOES exclude models/ since local docker-compose
+# mounts them as a read-only volume.)
+
+.git/
+.gitattributes
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Editor / OS
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+
+# Frontend / Node — the Space serves the backend only.
+node_modules/
+.next/
+
+# Static photos and team logos ARE included in the deployed image.
+# They live at backend/app/static/players/*.jpg and teams/*.png and need
+# to be served by FastAPI's static mount. The deploying user should
+# commit them to the Space repo via Git LFS so they:
+#   1) push reliably without bloating non-LFS git history, and
+#   2) get COPY'd into the Docker image during build.
+# (No exclusion rules here — letting Docker include them on purpose.)

.gitattributes

@@ -33,3 +33,7 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+models/** filter=lfs diff=lfs merge=lfs -text
+*.jsonl filter=lfs diff=lfs merge=lfs -text
+backend/app/static/players/*.jpg filter=lfs diff=lfs merge=lfs -text
+backend/app/static/teams/*.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+backend/.venv/
+
+# Local environment files
+.env
+.env.*
+!.env.example
+!.env.local.example
+
+# Frontend build/dependencies
+node_modules/
+frontend/node_modules/
+frontend/.next/
+frontend/out/
+frontend/dist/
+
+# Non-serving research/training artifacts kept locally only
+models/gp1/
+models/gp2/action_sentences.jsonl
+models/gp2/action2vec.model
+
+# OS/editor noise
+.DS_Store
+Thumbs.db
+*.log

Dockerfile

@@ -0,0 +1,54 @@
+# Hugging Face Space Dockerfile.
+#
+# IMPORTANT: this file is committed in this repo at hf-space/Dockerfile,
+# but is meant to be COPIED to the ROOT of your HF Space repo (not this
+# repo). The HF Space repo layout should be:
+#
+#   <space-repo>/
+#   ├── Dockerfile             ← copy this file here
+#   ├── .dockerignore          ← copy hf-space/.dockerignore here
+#   ├── README.md              ← HF requires this at root
+#   ├── backend/               ← copy from this repo
+#   ├── src/                   ← copy from this repo
+#   └── models/gp2/            ← copy from this repo (tracked via Git LFS)
+#
+# Unlike backend/Dockerfile (which omits models because the local Docker
+# stack mounts them as a volume), this Dockerfile COPIES models/ into the
+# image so the Space is self-contained.
+
+FROM python:3.11-slim
+
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends gcc g++ curl \
+ && rm -rf /var/lib/apt/lists/*
+
+# HF Spaces require the running user to have UID 1000 and HOME=/home/user.
+RUN useradd -m -u 1000 user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+WORKDIR /app
+
+COPY --chown=user backend/requirements.txt /app/backend/requirements.txt
+USER user
+RUN pip install --no-cache-dir --user -r /app/backend/requirements.txt
+USER root
+
+COPY --chown=user backend/ /app/backend/
+COPY --chown=user src/ /app/src/
+COPY --chown=user models/ /app/models/
+
+RUN chown -R user:user /app
+USER user
+WORKDIR /app/backend
+
+ENV PORT=7860 \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+EXPOSE 7860
+
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 --start-period=120s \
+    CMD curl -fsS http://localhost:${PORT}/api/health || exit 1
+
+CMD ["sh", "-c", "uvicorn app.main:app --host 0.0.0.0 --port ${PORT}"]

backend/.dockerignore

@@ -0,0 +1,12 @@
+# Note: the effective ignore for backend builds is ROOT .dockerignore, since
+# the build context is the project root. This file is kept for clarity and
+# in case someone builds with the backend/ directory as the context.
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+tests/
+app/static/players/*
+app/static/teams/*
+!app/static/players/.gitkeep
+!app/static/teams/.gitkeep

backend/Dockerfile

@@ -0,0 +1,43 @@
+# Backend Dockerfile for LOCAL docker-compose use.
+# Build context is the PROJECT ROOT (see docker-compose.yml), so all COPY
+# paths here are relative to the project root, not to backend/.
+#
+# models/ is NOT copied into this image. Local development mounts it via a
+# docker-compose volume (./models:/app/models:ro). For Hugging Face Spaces,
+# use hf-space/Dockerfile, which copies models/ in.
+
+FROM python:3.11-slim
+
+# Build tools required for some scientific-Python wheels on slim images,
+# plus curl for the HEALTHCHECK.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends gcc g++ curl \
+ && rm -rf /var/lib/apt/lists/*
+
+RUN useradd -m -u 1000 appuser
+
+WORKDIR /app
+
+# Install Python deps first (cacheable layer).
+COPY backend/requirements.txt /app/backend/requirements.txt
+RUN pip install --no-cache-dir -r /app/backend/requirements.txt
+
+# Application code.
+COPY backend/ /app/backend/
+COPY src/ /app/src/
+
+RUN chown -R appuser:appuser /app
+
+USER appuser
+WORKDIR /app/backend
+
+ENV PORT=7860 \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+EXPOSE 7860
+
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+    CMD curl -fsS http://localhost:${PORT}/api/health || exit 1
+
+CMD ["sh", "-c", "uvicorn app.main:app --host 0.0.0.0 --port ${PORT}"]

backend/app/config.py

@@ -0,0 +1,29 @@
+"""Backend configuration — env vars and derived paths."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# Path layout: this file lives at /app/backend/app/config.py in the container,
+# so parents[2] is /app — the project root that contains src/ and models/.
+# Same math applies locally.
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+BACKEND_ROOT = Path(__file__).resolve().parents[1]
+APP_DIR = Path(__file__).resolve().parent           # /app/backend/app
+STATIC_DIR = APP_DIR / "static"                     # /app/backend/app/static
+PLAYERS_STATIC_DIR = STATIC_DIR / "players"
+TEAMS_STATIC_DIR = STATIC_DIR / "teams"
+
+PORT = int(os.getenv("PORT", "7860"))
+
+_BASE_CORS_ORIGINS = ["http://localhost:3000"]
+# Permissive by design for v1: any vercel.app subdomain may call the backend.
+# Tradeoff accepted because this is a portfolio/demo backend with no auth and
+# no per-tenant data; locking it down requires the Vercel deployment URL to
+# be known at backend deploy time, which would couple the two deploys.
+CORS_ORIGIN_REGEX = r"https://.*\.vercel\.app"
+
+def cors_origins() -> list[str]:
+    extra = os.getenv("CORS_EXTRA_ORIGINS", "")
+    extras = [o.strip() for o in extra.split(",") if o.strip()]
+    return _BASE_CORS_ORIGINS + extras

backend/app/deps.py

@@ -0,0 +1,13 @@
+"""Shared FastAPI dependencies."""
+from __future__ import annotations
+
+from fastapi import HTTPException, status
+
+from app.services import engine
+
+
+def require_engine() -> None:
+    """Raise 503 if the engine is not in the 'ready' state."""
+    if engine.engine_state != "ready":
+        detail = f"Engine unavailable: {engine.engine_message or 'not loaded'}"
+        raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=detail)

backend/app/main.py

@@ -0,0 +1,82 @@
+"""FastAPI application entry point."""
+from __future__ import annotations
+
+import logging
+import time
+import traceback
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+
+from app.config import CORS_ORIGIN_REGEX, STATIC_DIR, cors_origins
+from app.routes import catalog, health, players, search, validations
+from app.services import engine
+from app.services.jobs import store
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(levelname)s %(name)s %(message)s",
+)
+logger = logging.getLogger("app")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    start = time.monotonic()
+    health._set_start_time(start)
+    logger.info("Starting up. Project root: %s", engine.PROJECT_ROOT if hasattr(engine, "PROJECT_ROOT") else "(unknown)")
+
+    # If the engine module itself failed to import, leave state as "unavailable"
+    # and skip warm-up. App still serves /api/health and /api/upgrades, /api/filters.
+    if engine.scouting_engine is None:
+        logger.warning("Engine module did not import; serving in degraded mode.")
+    else:
+        try:
+            await engine.run_engine(engine.scouting_engine.list_available_players, "", 1)
+            engine.set_state("ready")
+            elapsed = time.monotonic() - start
+            logger.info("Engine ready (warm-up %.2fs)", elapsed)
+        except Exception as e:
+            logger.error("Engine warm-up failed:\n%s", traceback.format_exc())
+            engine.set_state("unavailable", str(e))
+
+    store.start()
+
+    try:
+        yield
+    finally:
+        logger.info("Shutting down.")
+        await store.stop()
+        engine.shutdown_executor()
+
+
+app = FastAPI(
+    title="Replacement Scout API",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=cors_origins(),
+    allow_origin_regex=CORS_ORIGIN_REGEX,
+    allow_credentials=False,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Static images (player photos, team logos). Directory is auto-created on
+# startup; missing individual files are handled by the URL helpers
+# (services/images.py) which return None when a file is absent.
+STATIC_DIR.mkdir(parents=True, exist_ok=True)
+(STATIC_DIR / "players").mkdir(exist_ok=True)
+(STATIC_DIR / "teams").mkdir(exist_ok=True)
+app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")
+
+app.include_router(health.router, prefix="/api")
+app.include_router(catalog.router, prefix="/api")
+app.include_router(players.router, prefix="/api")
+app.include_router(search.router, prefix="/api")
+app.include_router(validations.router, prefix="/api")

backend/app/routes/catalog.py

@@ -0,0 +1,47 @@
+"""
+/api/upgrades and /api/filters.
+
+Both are model-INDEPENDENT — the underlying engine functions are pure
+constant returns and do NOT call _ensure_loaded(). Verified against
+src/gp2/evaluation/scouting_engine.py:145 (list_available_filters) and :291
+(list_available_upgrades). Safe to call even when engine_state is
+'unavailable'.
+"""
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException
+
+from app.services import engine
+
+router = APIRouter()
+
+
+@router.get("/upgrades")
+def get_upgrades() -> dict:
+    if engine.scouting_engine is None:
+        raise HTTPException(503, detail="Engine module failed to import")
+    flat = engine.scouting_engine.list_available_upgrades()
+    grouped: dict[str, list[dict]] = {"onball": [], "offball": []}
+    for u in flat:
+        bucket = u.get("applies_to")
+        if bucket in grouped:
+            grouped[bucket].append(u)
+    return grouped
+
+
+_COMING_SOON_FILTERS = [
+    "min_age",
+    "max_age",
+    "leagues",
+    "min_market_value",
+    "max_market_value",
+]
+
+
+@router.get("/filters")
+def get_filters() -> dict:
+    if engine.scouting_engine is None:
+        raise HTTPException(503, detail="Engine module failed to import")
+    result = dict(engine.scouting_engine.list_available_filters())
+    result["coming_soon"] = _COMING_SOON_FILTERS
+    return result

backend/app/routes/health.py

@@ -0,0 +1,30 @@
+"""Health endpoint. Model-independent — always 200 as long as the app imports."""
+from __future__ import annotations
+
+import time
+
+from fastapi import APIRouter
+
+from app.schemas.common import HealthResponse
+from app.services import engine
+
+router = APIRouter()
+
+# Module-level start time. Set in main.py via _set_start_time on lifespan startup.
+_start_time: float = time.monotonic()
+
+
+def _set_start_time(t: float) -> None:
+    global _start_time
+    _start_time = t
+
+
+@router.get("/health", response_model=HealthResponse)
+def health() -> HealthResponse:
+    return HealthResponse(
+        status="ok",
+        engine_loaded=engine.engine_loaded(),
+        engine_state=engine.engine_state,  # type: ignore[arg-type]
+        engine_message=engine.engine_message,
+        uptime_seconds=round(time.monotonic() - _start_time, 3),
+    )

backend/app/routes/players.py

@@ -0,0 +1,111 @@
+"""Player lookup and similar-players endpoints."""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+
+from app.deps import require_engine
+from app.services import engine, player_index
+from app.services.heatmap import NUM_ZONES, player_heatmap
+from app.services.images import logo_url_for, photo_url_for
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+def _attach_images(p: dict[str, Any], request: Request) -> dict[str, Any]:
+    p = dict(p)  # don't mutate engine's cache
+    p["photo_url"] = photo_url_for(p.get("player_id", ""), request)
+    p["team_logo_url"] = logo_url_for(p.get("team"), request)
+    return p
+
+
+@router.get("/players")
+async def list_players(
+    request: Request,
+    q: str = Query("", description="Accent- and case-insensitive substring match on player name."),
+    limit: int = Query(20, ge=1, le=50),
+    _: None = Depends(require_engine),
+) -> list[dict[str, Any]]:
+    # Use the local accent-insensitive index instead of calling the engine
+    # directly: the engine's matcher does plain Unicode substring, so
+    # `q=mane` would miss "Sadio Mané". The index pulls the full player
+    # list once via the engine (cheap, no inference), pre-strips accents,
+    # then matches in pure Python.
+    try:
+        await player_index.ensure_built()
+        results = player_index.search(q, limit)
+    except Exception as e:
+        logger.exception("/api/players failed")
+        raise HTTPException(500, detail=str(e))
+    return [_attach_images(p, request) for p in results]
+
+
+@router.get("/players/{player_id}")
+async def get_player(
+    player_id: str,
+    request: Request,
+    _: None = Depends(require_engine),
+) -> dict[str, Any]:
+    try:
+        summary = await engine.run_engine(engine.scouting_engine.get_player_summary, player_id)
+    except Exception as e:
+        logger.exception("get_player_summary failed")
+        raise HTTPException(500, detail=str(e))
+    if summary is None:
+        raise HTTPException(404, detail=f"Player not found: {player_id}")
+    return _attach_images(summary, request)
+
+
+@router.get("/players/{player_id}/heatmap")
+async def player_heatmap_endpoint(
+    player_id: str,
+    _: None = Depends(require_engine),
+) -> dict[str, Any]:
+    """
+    Return a 6×3 pitch-zone activity heatmap for a player.
+
+    Aggregates the start-zone of every structured token (on-ball + off-ball)
+    across all of the player's matches in the dataset. Pure modifier tokens
+    (e.g. `progressive_pass`, `cut_inside_right`) have no zone and are skipped.
+
+    Response: {counts: int[18], total: int, num_x: 6, num_y: 3} — counts are
+    indexed row-major from the top-left of the StatsBomb pitch (120×80,
+    attacking left-to-right).
+    """
+    try:
+        counts = await player_heatmap(player_id)
+    except FileNotFoundError as e:
+        raise HTTPException(503, detail=f"Heatmap data unavailable: {e}")
+    except Exception as e:
+        logger.exception("heatmap failed")
+        raise HTTPException(500, detail=str(e))
+    if counts is None:
+        raise HTTPException(404, detail=f"Player not found: {player_id}")
+    return {"counts": counts, "total": sum(counts), "num_x": 6, "num_y": 3, "num_zones": NUM_ZONES}
+
+
+@router.get("/players/{player_id}/similar")
+async def similar_players(
+    player_id: str,
+    request: Request,
+    top_k: int = Query(10, ge=1, le=100),
+    _: None = Depends(require_engine),
+) -> list[dict[str, Any]]:
+    try:
+        result = await engine.run_engine(
+            engine.scouting_engine.search_replacements,
+            sources=[player_id],
+            upgrades=[],
+            top_k=top_k,
+        )
+    except ValueError as e:
+        # Engine raises ValueError for unknown sources / no sources resolved.
+        raise HTTPException(404, detail=str(e))
+    except Exception as e:
+        logger.exception("similar search failed")
+        raise HTTPException(500, detail=str(e))
+    return [_attach_images(c, request) for c in result.get("candidates", [])]

backend/app/routes/search.py

@@ -0,0 +1,92 @@
+"""
+POST /api/search — synchronous if no upgrades, otherwise enqueued as an async job.
+GET  /api/search/{job_id} — model-independent job-state lookup.
+"""
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
+
+from app.deps import require_engine
+from app.schemas.search import (
+    JobAcceptedResponse,
+    JobRecord,
+    SearchRequest,
+    SyncSearchResponse,
+)
+from app.services import engine
+from app.services.images import enrich_search_result
+from app.services.jobs import RETRY_AFTER_SECONDS, store
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+def _has_upgrades(req: SearchRequest) -> bool:
+    if req.upgrades is None:
+        return False
+    if isinstance(req.upgrades, (list, dict)) and len(req.upgrades) == 0:
+        return False
+    return True
+
+
+@router.post("/search")
+async def post_search(
+    req: SearchRequest,
+    response: Response,
+    request: Request,
+    _: None = Depends(require_engine),
+):
+    kwargs = dict(
+        sources=req.sources,
+        upgrades=req.upgrades if req.upgrades is not None else [],
+        upgrade_intensity=req.upgrade_intensity,
+        top_k=req.top_k,
+        filters=req.filters,
+        exclude_sources=req.exclude_sources,
+        seed=req.seed,
+    )
+
+    if not _has_upgrades(req):
+        # Fast path: similarity-only search runs in well under a second.
+        try:
+            result = await engine.run_engine(
+                engine.scouting_engine.search_replacements, **kwargs
+            )
+        except ValueError as e:
+            raise HTTPException(400, detail=str(e))
+        except Exception as e:
+            logger.exception("sync search failed")
+            raise HTTPException(500, detail=str(e))
+        # Attach photo_url + team_logo_url to sources and candidates.
+        return SyncSearchResponse(**enrich_search_result(result, request))
+
+    # Upgrade path: enqueue as a background job.
+    job_id = store.enqueue(kwargs)
+    if job_id is None:
+        response.headers["Retry-After"] = str(RETRY_AFTER_SECONDS)
+        raise HTTPException(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail="Search queue full, retry shortly",
+            headers={
+                "Retry-After": str(RETRY_AFTER_SECONDS),
+            },
+        )
+    return JobAcceptedResponse(job_id=job_id, status="pending")
+
+
+@router.get("/search/{job_id}", response_model=JobRecord)
+def get_job(job_id: str, request: Request) -> JobRecord:
+    # Model-independent: only reads the in-memory job store.
+    record = store.get(job_id)
+    if record is None:
+        raise HTTPException(404, detail=f"Job not found: {job_id}")
+    # If the job is done, enrich its result with per-request image URLs.
+    if record.get("status") == "done" and record.get("result"):
+        record = {
+            **record,
+            "result": enrich_search_result(record["result"], request),
+        }
+    return JobRecord(**record)

backend/app/routes/validations.py

@@ -0,0 +1,251 @@
+"""
+/api/validations/mane — the Mané regression check, surfaced as an API endpoint.
+
+Reproduces the config from src/gp2/evaluation/mane_case_validation.py without
+importing its `validate()` function. Post-filters defenders, re-ranks
+attackers, finds Mané's attacker_rank, returns a verdict.
+
+Cache: deterministic (single variant, seed-fixed), so we cache the response
+in module state after the first successful run. Double-checked-lock pattern
+prevents two simultaneous cold-cache callers from each running the ~30–60 s
+inference.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+
+from app.deps import require_engine
+from app.services import engine
+from app.services.heatmap import NUM_ZONES, aggregate_heatmap, player_heatmap
+from app.services.images import logo_url_for, photo_url_for
+from app.services.mane_preset import (
+    DEFENDER_POSITIONS,
+    KLOPP_UPGRADES_VALIDATED,
+    LIVERPOOL_2015_16_ATTACKERS,
+    MANE_FINAL_TOP_N,
+    MANE_SEED,
+    MANE_TOP_K,
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+_mane_cache: dict[str, Any] | None = None
+_mane_lock = asyncio.Lock()
+
+
+def _verdict_for(rank: int | None) -> tuple[str, str]:
+    if rank is None:
+        return (
+            "FAIL",
+            "Mané did not appear in the post-filtered attacker candidate pool.",
+        )
+    if rank <= 5:
+        return ("EXCELLENT", f"Mané ranked #{rank} among attackers — methodology strongly recovers Liverpool's actual 2016 signing.")
+    if rank <= 10:
+        return ("STRONG", f"Mané ranked #{rank} among attackers — methodology cleanly recovers Liverpool's actual 2016 signing.")
+    if rank <= 20:
+        return ("ACCEPTABLE", f"Mané ranked #{rank} among attackers — methodology recovers Liverpool's actual 2016 signing, with noise.")
+    if rank <= MANE_FINAL_TOP_N:
+        return ("MARGINAL", f"Mané ranked #{rank} among attackers — within the top {MANE_FINAL_TOP_N} but on the edge.")
+    return (
+        "FAIL",
+        f"Mané ranked #{rank} — outside the top {MANE_FINAL_TOP_N} attackers.",
+    )
+
+
+def _build_response(engine_result: dict[str, Any]) -> dict[str, Any]:
+    candidates: list[dict[str, Any]] = engine_result.get("candidates", []) or []
+    warnings: list[str] = engine_result.get("warnings", []) or []
+
+    attackers = [c for c in candidates if c.get("primary_position") not in DEFENDER_POSITIONS]
+    filtered_defender_count = len(candidates) - len(attackers)
+
+    mane_rank: int | None = None
+    for i, c in enumerate(attackers, start=1):
+        c["attacker_rank"] = i
+        if mane_rank is None and "Mané" in (c.get("name") or ""):
+            mane_rank = i
+
+    top_attackers = attackers[:MANE_FINAL_TOP_N]
+    verdict, description = _verdict_for(mane_rank)
+
+    return {
+        "query": engine_result.get("query", {}),
+        "candidates": top_attackers,
+        "mane_rank": mane_rank,
+        "verdict": verdict,
+        "verdict_description": description,
+        "filtered_defender_count": filtered_defender_count,
+        "warnings": warnings,
+    }
+
+
+async def _compute() -> dict[str, Any]:
+    result = await engine.run_engine(
+        engine.scouting_engine.search_replacements,
+        sources=LIVERPOOL_2015_16_ATTACKERS,
+        upgrades=KLOPP_UPGRADES_VALIDATED,
+        top_k=MANE_TOP_K,
+        seed=MANE_SEED,
+    )
+    return _build_response(result)
+
+
+@router.get("/validations/mane")
+async def mane_validation(_: None = Depends(require_engine)) -> dict[str, Any]:
+    global _mane_cache
+    if _mane_cache is not None:
+        return _mane_cache
+    async with _mane_lock:
+        # Double-checked: another coroutine may have populated the cache while we were
+        # waiting on the lock.
+        if _mane_cache is not None:
+            return _mane_cache
+        try:
+            response = await _compute()
+        except ValueError as e:
+            raise HTTPException(400, detail=str(e))
+        except Exception as e:
+            logger.exception("Mané validation failed")
+            raise HTTPException(500, detail=str(e))
+        _mane_cache = response
+        return _mane_cache
+
+
+_mane_heatmap_cache: dict[str, Any] | None = None
+_mane_heatmap_lock = asyncio.Lock()
+
+
+@router.get("/validations/mane/heatmap")
+async def mane_heatmap(
+    request: Request,
+    _: None = Depends(require_engine),
+) -> dict[str, Any]:
+    """
+    Heatmaps for the Mané validation explainer:
+      - `pool`: aggregated zone counts across the 6 Liverpool 2015-16 attackers
+      - `mane`: Mané's own zone counts
+      - `top_candidates`: heatmaps for the top 5 attacking candidates the
+        methodology surfaced (defenders filtered out). Lets the user see
+        that all 5 share a similar spatial profile — visual proof of the
+        ranking.
+
+    Depends on the main /api/validations/mane having been computed (or
+    computes it on demand) so we know who the top-5 attackers are.
+    """
+    global _mane_heatmap_cache
+    if _mane_heatmap_cache is not None:
+        return _enrich_heatmap_response(_mane_heatmap_cache, request)
+    async with _mane_heatmap_lock:
+        if _mane_heatmap_cache is not None:
+            return _enrich_heatmap_response(_mane_heatmap_cache, request)
+
+        # Resolve the 6 source player names → player_ids via the engine's
+        # name lookup (this is cheap — no model inference required, just a
+        # dict scan).
+        try:
+            source_ids: list[str] = []
+            source_names: list[str] = []
+            for name in LIVERPOOL_2015_16_ATTACKERS:
+                pid = await engine.run_engine(engine.scouting_engine.find_player_id, name)
+                if pid is None:
+                    continue
+                summary = await engine.run_engine(
+                    engine.scouting_engine.get_player_summary, pid
+                )
+                source_ids.append(pid)
+                if summary and summary.get("name"):
+                    source_names.append(summary["name"])
+
+            # Find Mané by name. The engine's matcher is plain Unicode substring;
+            # the accented form is required.
+            mane_id = await engine.run_engine(engine.scouting_engine.find_player_id, "Mané")
+
+            pool_counts = await aggregate_heatmap(source_ids)
+            mane_counts = await player_heatmap(mane_id) if mane_id else None
+
+            # Top-5 attacking candidates: reuse the main validation result.
+            # If it hasn't been computed yet, compute it now (single inference,
+            # then cached for both endpoints).
+            global _mane_cache
+            validation = _mane_cache
+            if validation is None:
+                validation = await _compute()
+                _mane_cache = validation
+            top_candidates = []
+            for c in (validation.get("candidates") or [])[:5]:
+                cid = c.get("player_id")
+                if not cid:
+                    continue
+                counts = await player_heatmap(str(cid))
+                if counts is None:
+                    continue
+                # Photo URLs are NOT cached here — they're attached at response
+                # time below because the base URL depends on the current
+                # request (different deploy host, different scheme, etc.).
+                top_candidates.append({
+                    "player_id": cid,
+                    "name": c.get("name"),
+                    "primary_position": c.get("primary_position"),
+                    "team": c.get("team"),
+                    "similarity": c.get("similarity"),
+                    "attacker_rank": c.get("attacker_rank"),
+                    "counts": counts,
+                    "total": sum(counts),
+                    "is_mane": "Mané" in (c.get("name") or ""),
+                })
+
+        except FileNotFoundError as e:
+            raise HTTPException(503, detail=f"Heatmap data unavailable: {e}")
+        except Exception as e:
+            logger.exception("Mané heatmap failed")
+            raise HTTPException(500, detail=str(e))
+
+        _mane_heatmap_cache = {
+            "pool": {
+                "counts": pool_counts,
+                "total": sum(pool_counts),
+                "source_names": source_names,
+                "label": "Liverpool 2015-16 attacking pool",
+            },
+            "mane": {
+                "counts": mane_counts,
+                "total": sum(mane_counts) if mane_counts else 0,
+                "label": "Sadio Mané",
+                "player_id": mane_id,
+            },
+            "top_candidates": top_candidates,
+            "num_x": 6,
+            "num_y": 3,
+            "num_zones": NUM_ZONES,
+        }
+
+    return _enrich_heatmap_response(_mane_heatmap_cache, request)
+
+
+def _enrich_heatmap_response(cached: dict[str, Any], request: Request) -> dict[str, Any]:
+    """Attach per-request image URLs to the cached heatmap response.
+
+    Image URLs include the request's base URL, so they MUST be computed per
+    request (different deploy hosts, schemes, ports). We never mutate the
+    cache itself.
+    """
+    enriched_candidates = []
+    for c in cached.get("top_candidates", []):
+        c2 = dict(c)
+        c2["photo_url"] = photo_url_for(str(c.get("player_id") or ""), request)
+        c2["team_logo_url"] = logo_url_for(c.get("team"), request)
+        enriched_candidates.append(c2)
+    return {
+        **cached,
+        "top_candidates": enriched_candidates,
+        "mane": {
+            **cached.get("mane", {}),
+            "photo_url": photo_url_for(str(cached.get("mane", {}).get("player_id") or ""), request),
+        },
+    }

backend/app/schemas/common.py

@@ -0,0 +1,18 @@
+"""Schemas shared across routes."""
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class HealthResponse(BaseModel):
+    status: Literal["ok"] = "ok"
+    engine_loaded: bool
+    engine_state: Literal["warming", "ready", "unavailable"]
+    engine_message: str | None = None
+    uptime_seconds: float
+
+
+class ErrorResponse(BaseModel):
+    detail: str

backend/app/schemas/player.py

@@ -0,0 +1,36 @@
+"""Player-related schemas. Loose typing on engine-returned fields because
+the engine's dicts include some Optional values we surface as-is."""
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class PlayerSummary(BaseModel):
+    player_id: str
+    name: str
+    primary_position: str
+    team: str
+    versatility_score: float
+    num_matches: int
+    photo_url: str | None = None
+    team_logo_url: str | None = None
+
+
+class PlayerDetail(PlayerSummary):
+    num_distinct_positions: int
+    position_distribution: dict[str, Any]
+
+
+class Candidate(BaseModel):
+    rank: int
+    player_id: str
+    name: str
+    primary_position: str
+    team: str
+    similarity: float
+    versatility_score: float
+    num_matches: int
+    photo_url: str | None = None
+    team_logo_url: str | None = None

backend/app/schemas/search.py

@@ -0,0 +1,47 @@
+"""Search request/response schemas."""
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class SearchRequest(BaseModel):
+    sources: list[str] = Field(..., min_length=1)
+    upgrades: list[str] | dict[str, float] | None = None
+    upgrade_intensity: float = Field(0.5, ge=0.0, le=1.0)
+    top_k: int = Field(30, ge=1, le=100)
+    filters: dict[str, Any] | None = None
+    exclude_sources: bool = True
+    seed: int = 42
+
+    @field_validator("upgrades")
+    @classmethod
+    def _validate_upgrade_probs(cls, v):
+        if isinstance(v, dict):
+            for key, prob in v.items():
+                if not isinstance(prob, (int, float)):
+                    raise ValueError(f"upgrade probability for '{key}' must be numeric")
+                if not (0.0 <= float(prob) <= 1.0):
+                    raise ValueError(f"upgrade probability for '{key}' must be in [0.0, 1.0]")
+        return v
+
+
+class SyncSearchResponse(BaseModel):
+    query: dict[str, Any]
+    candidates: list[dict[str, Any]]
+    warnings: list[str]
+
+
+class JobAcceptedResponse(BaseModel):
+    job_id: str
+    status: Literal["pending"]
+
+
+class JobRecord(BaseModel):
+    job_id: str
+    status: Literal["pending", "running", "done", "error"]
+    created_at: str
+    updated_at: str
+    result: dict[str, Any] | None = None
+    error: str | None = None

backend/app/services/engine.py

@@ -0,0 +1,84 @@
+"""
+Engine wrapper.
+
+Imports the locked GP2 scouting engine via sys.path and exposes a single
+async entry point `run_engine(fn, *args, **kwargs)` that routes every
+CPU-bound engine call through a shared single-worker ThreadPoolExecutor.
+
+The single-worker constraint is structural concurrency control: it means we
+can never run two model inferences in parallel, regardless of which endpoint
+triggered them. The /api/search job queue's "1 running + 3 pending" policy
+is layered on top for upgrade jobs specifically.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import sys
+import traceback
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Callable
+
+from app.config import PROJECT_ROOT
+
+logger = logging.getLogger(__name__)
+
+# Make `from src.gp2.evaluation import scouting_engine` resolvable.
+_project_root_str = str(PROJECT_ROOT)
+if _project_root_str not in sys.path:
+    sys.path.insert(0, _project_root_str)
+
+# State exposed to the rest of the app.
+engine_state: str = "warming"      # "warming" | "ready" | "unavailable"
+engine_message: str | None = None
+
+# Import the engine lazily-friendly: we still import at module load so the
+# rest of the app can reference `scouting_engine.*` directly, but if the
+# import itself fails we mark the engine unavailable and re-raise so the
+# caller sees a clean error.
+try:
+    from src.gp2.evaluation import scouting_engine  # type: ignore
+except Exception as e:  # pragma: no cover — only fires if src/ is missing
+    scouting_engine = None  # type: ignore[assignment]
+    engine_state = "unavailable"
+    engine_message = f"Engine import failed: {e}"
+    logger.error("Engine import failed:\n%s", traceback.format_exc())
+
+
+# Shared single-worker executor. Lazily (re)created so that a shutdown
+# during one app lifespan doesn't permanently kill the executor for a
+# subsequent lifespan in the same process — important for pytest's
+# TestClient pattern, where each test may open a fresh TestClient.
+_executor: ThreadPoolExecutor | None = None
+
+
+def _ensure_executor() -> ThreadPoolExecutor:
+    global _executor
+    if _executor is None:
+        _executor = ThreadPoolExecutor(max_workers=1, thread_name_prefix="engine")
+    return _executor
+
+
+def engine_loaded() -> bool:
+    return engine_state == "ready"
+
+
+def set_state(state: str, message: str | None = None) -> None:
+    global engine_state, engine_message
+    engine_state = state
+    engine_message = message
+
+
+async def run_engine(fn: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
+    """Run a CPU-bound engine function on the shared single-worker executor."""
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(_ensure_executor(), lambda: fn(*args, **kwargs))
+
+
+def shutdown_executor() -> None:
+    """Stop the executor. Safe to call multiple times; a later run_engine
+    call will lazily create a fresh executor."""
+    global _executor
+    if _executor is not None:
+        _executor.shutdown(wait=False, cancel_futures=False)
+        _executor = None

backend/app/services/heatmap.py

@@ -0,0 +1,141 @@
+"""
+Heatmap aggregation service.
+
+Streams `models/gp2/player_match_docs_split.jsonl` and counts pitch-zone
+occurrences per player. The engine's tokens encode locations as zone IDs
+on a 6×3 grid (NUM_X_BINS=6, NUM_Y_BINS=3, row-major from top-left of a
+120×80 StatsBomb pitch — see src/gp2/preprocess/zones.py).
+
+Token shapes we extract zones from:
+  pass|z17_z11|f|r|l|med    -> 17 (start zone)
+  carry|z16_z17|fwd         -> 16
+  shot|z11|on|r|open|xg_l|mid -> 11
+  pressure|z16|reg          -> 16
+  duel|z14|ground|lost      -> 14
+  ... etc.
+
+Tokens that are pure modifiers (e.g. `progressive_pass`, `cut_inside_right`,
+`under_pressure`) have no zone field and are skipped.
+
+We use *start zone only*, which represents "where this player was active."
+This is the right primitive for "show me their pitch footprint." We also
+keep the totals so the heatmap can be normalized to percentages downstream.
+
+The data file is ~132 MB and contains ~49k player-match documents — a full
+scan takes a few seconds. The result for each player is cached in
+process memory; the index `_zone_index` (built lazily on first call) maps
+player_id -> 18-element count array.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+from pathlib import Path
+from typing import Iterable, Optional
+
+from app.config import PROJECT_ROOT
+
+logger = logging.getLogger(__name__)
+
+# Matches `z<digits>` at the start of the second pipe-field, possibly followed
+# by `_z<digits>` (start_end pair) or other field separators. We only care
+# about the first (start) zone.
+_ZONE_RE = re.compile(r"^z(\d+)")
+
+NUM_ZONES = 18  # 6×3 grid
+DOCS_PATH = PROJECT_ROOT / "models" / "gp2" / "player_match_docs_split.jsonl"
+
+# player_id -> [count_z0, count_z1, ..., count_z17]
+_zone_index: Optional[dict[str, list[int]]] = None
+_index_lock = asyncio.Lock()
+
+
+def _extract_zone(token: str) -> Optional[int]:
+    """Return the start-zone id (0-17) for a structured token, or None for modifier-only tokens."""
+    # Tokens look like "<verb>|<zone-or-pair>|<...>" — split once, look at field[1].
+    parts = token.split("|", 2)
+    if len(parts) < 2:
+        return None
+    m = _ZONE_RE.match(parts[1])
+    if not m:
+        return None
+    try:
+        zid = int(m.group(1))
+    except ValueError:
+        return None
+    if 0 <= zid < NUM_ZONES:
+        return zid
+    return None
+
+
+def _build_index_sync() -> dict[str, list[int]]:
+    """Stream the docs jsonl once and tally zones per player. Blocking I/O — caller must offload."""
+    if not DOCS_PATH.exists():
+        raise FileNotFoundError(f"{DOCS_PATH} not found")
+
+    index: dict[str, list[int]] = {}
+    n_docs = 0
+    with open(DOCS_PATH, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                doc = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            pid = doc.get("player_id")
+            if pid is None:
+                continue
+            pid = str(pid)
+            counts = index.get(pid)
+            if counts is None:
+                counts = [0] * NUM_ZONES
+                index[pid] = counts
+            for tok in doc.get("onball_tokens", []) or []:
+                z = _extract_zone(tok)
+                if z is not None:
+                    counts[z] += 1
+            for tok in doc.get("offball_tokens", []) or []:
+                z = _extract_zone(tok)
+                if z is not None:
+                    counts[z] += 1
+            n_docs += 1
+    logger.info("Heatmap index built: %d players from %d documents", len(index), n_docs)
+    return index
+
+
+async def _ensure_index() -> dict[str, list[int]]:
+    global _zone_index
+    if _zone_index is not None:
+        return _zone_index
+    async with _index_lock:
+        if _zone_index is not None:
+            return _zone_index
+        loop = asyncio.get_running_loop()
+        _zone_index = await loop.run_in_executor(None, _build_index_sync)
+        return _zone_index
+
+
+async def player_heatmap(player_id: str) -> Optional[list[int]]:
+    """Return the 18-element zone-count array for a player, or None if unknown."""
+    idx = await _ensure_index()
+    counts = idx.get(str(player_id))
+    if counts is None:
+        return None
+    return list(counts)
+
+
+async def aggregate_heatmap(player_ids: Iterable[str]) -> list[int]:
+    """Sum zone counts across a set of player_ids. Missing IDs contribute zeros."""
+    idx = await _ensure_index()
+    out = [0] * NUM_ZONES
+    for pid in player_ids:
+        counts = idx.get(str(pid))
+        if counts is None:
+            continue
+        for i, c in enumerate(counts):
+            out[i] += c
+    return out

backend/app/services/images.py

@@ -0,0 +1,60 @@
+"""Static image URL resolution. Missing files → None (frontend uses initials fallback)."""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from fastapi import Request
+
+from app.config import PLAYERS_STATIC_DIR, TEAMS_STATIC_DIR
+
+_SLUG_NON_ALNUM = re.compile(r"[^a-z0-9]+")
+
+
+def team_slug(team_name: str) -> str:
+    s = _SLUG_NON_ALNUM.sub("-", team_name.lower()).strip("-")
+    return s or "unknown"
+
+
+def photo_url_for(player_id: str, request: Request) -> str | None:
+    if not player_id:
+        return None
+    if not (PLAYERS_STATIC_DIR / f"{player_id}.jpg").is_file():
+        return None
+    return f"{str(request.base_url).rstrip('/')}/static/players/{player_id}.jpg"
+
+
+def logo_url_for(team_name: str | None, request: Request) -> str | None:
+    if not team_name:
+        return None
+    slug = team_slug(team_name)
+    if not (TEAMS_STATIC_DIR / f"{slug}.png").is_file():
+        return None
+    return f"{str(request.base_url).rstrip('/')}/static/teams/{slug}.png"
+
+
+def attach_images(p: dict[str, Any], request: Request) -> dict[str, Any]:
+    """Return a copy of a player/candidate dict with photo_url + team_logo_url
+    populated using the current request's base URL. Safe to call on engine
+    output (does not mutate the engine's cache)."""
+    out = dict(p)
+    out["photo_url"] = photo_url_for(str(p.get("player_id") or ""), request)
+    out["team_logo_url"] = logo_url_for(p.get("team"), request)
+    return out
+
+
+def enrich_search_result(result: dict[str, Any], request: Request) -> dict[str, Any]:
+    """Add photo_url + team_logo_url to every player in a search-result dict.
+
+    Applies to both `query.sources` (the resolved source players) and the
+    `candidates` array. Returns a new dict — does not mutate the input.
+    """
+    query = dict(result.get("query") or {})
+    sources = [attach_images(s, request) for s in (query.get("sources") or [])]
+    query["sources"] = sources
+    candidates = [attach_images(c, request) for c in (result.get("candidates") or [])]
+    return {
+        **result,
+        "query": query,
+        "candidates": candidates,
+    }

backend/app/services/jobs.py

@@ -0,0 +1,153 @@
+"""
+In-memory async job store for upgrade searches.
+
+Design:
+  - One asyncio.Queue (maxsize=3) of pending job_ids.
+  - One long-running worker task drains it; each job runs through
+    services.engine.run_engine(...), which uses the shared single-worker
+    executor — so heavy work is automatically serialized with any other
+    engine call site (validation endpoint, similar-players, etc.).
+  - Records live in a dict keyed by job_id. Records older than 1 hour are
+    swept on every enqueue and every status lookup.
+
+Lost on restart by design. Acceptable for v1; a Redis/SQLite store is the
+follow-up if production reliability is needed.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import traceback
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from typing import Any, Optional
+
+from app.services import engine
+
+logger = logging.getLogger(__name__)
+
+JOB_TTL = timedelta(hours=1)
+QUEUE_MAXSIZE = 3
+RETRY_AFTER_SECONDS = 30
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+@dataclass
+class Job:
+    job_id: str
+    status: str  # "pending" | "running" | "done" | "error"
+    created_at: str
+    updated_at: str
+    kwargs: dict[str, Any]
+    result: Optional[dict[str, Any]] = None
+    error: Optional[str] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        # kwargs is internal — never expose it
+        return {
+            "job_id": self.job_id,
+            "status": self.status,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "result": self.result,
+            "error": self.error,
+        }
+
+
+class JobStore:
+    def __init__(self) -> None:
+        self._jobs: dict[str, Job] = {}
+        self._queue: asyncio.Queue[str] = asyncio.Queue(maxsize=QUEUE_MAXSIZE)
+        self._worker_task: asyncio.Task | None = None
+        self._running_job_id: str | None = None
+
+    def _sweep(self) -> None:
+        cutoff = datetime.now(timezone.utc) - JOB_TTL
+        stale = [
+            jid for jid, j in self._jobs.items()
+            if datetime.fromisoformat(j.created_at) < cutoff
+        ]
+        for jid in stale:
+            del self._jobs[jid]
+
+    def is_full(self) -> bool:
+        # "Full" = there is currently a running job AND the pending queue is at capacity.
+        return self._running_job_id is not None and self._queue.full()
+
+    def enqueue(self, kwargs: dict[str, Any]) -> str | None:
+        """Enqueue a job. Returns job_id, or None if capacity is exceeded."""
+        self._sweep()
+        if self.is_full():
+            return None
+        job_id = uuid.uuid4().hex
+        now = _now_iso()
+        self._jobs[job_id] = Job(
+            job_id=job_id,
+            status="pending",
+            created_at=now,
+            updated_at=now,
+            kwargs=kwargs,
+        )
+        try:
+            self._queue.put_nowait(job_id)
+        except asyncio.QueueFull:
+            # Shouldn't happen given the is_full() guard, but be defensive.
+            del self._jobs[job_id]
+            return None
+        return job_id
+
+    def get(self, job_id: str) -> dict[str, Any] | None:
+        self._sweep()
+        job = self._jobs.get(job_id)
+        return job.to_dict() if job else None
+
+    async def _worker(self) -> None:
+        from app.services.engine import scouting_engine  # late import; may be None
+
+        while True:
+            try:
+                job_id = await self._queue.get()
+            except asyncio.CancelledError:
+                return
+            job = self._jobs.get(job_id)
+            if job is None:
+                continue
+            self._running_job_id = job_id
+            job.status = "running"
+            job.updated_at = _now_iso()
+            try:
+                if scouting_engine is None:
+                    raise RuntimeError("Engine unavailable")
+                result = await engine.run_engine(
+                    scouting_engine.search_replacements, **job.kwargs
+                )
+                job.result = result
+                job.status = "done"
+            except Exception as e:
+                logger.error("Job %s failed:\n%s", job_id, traceback.format_exc())
+                job.error = f"{type(e).__name__}: {e}"
+                job.status = "error"
+            finally:
+                job.updated_at = _now_iso()
+                self._running_job_id = None
+
+    def start(self, loop: asyncio.AbstractEventLoop | None = None) -> None:
+        if self._worker_task is None or self._worker_task.done():
+            self._worker_task = asyncio.create_task(self._worker(), name="job-worker")
+
+    async def stop(self) -> None:
+        if self._worker_task is not None:
+            self._worker_task.cancel()
+            try:
+                await self._worker_task
+            except (asyncio.CancelledError, Exception):
+                pass
+            self._worker_task = None
+
+
+# Module-level singleton; the FastAPI app touches this via `from app.services.jobs import store`.
+store = JobStore()

backend/app/services/mane_preset.py

@@ -0,0 +1,45 @@
+"""
+Mané-validation preset, reproduced from `src/gp2/evaluation/mane_case_validation.py`.
+
+Reproduced verbatim (not imported) because we don't want to call the
+script's `validate()` function — it has print-heavy reporting side effects
+and a different return contract. The constants here are the regression
+checkpoint; if they drift from the engine's expectations, that's intentional
+breakage to be reviewed.
+"""
+from __future__ import annotations
+
+# Six sources — Coutinho was removed in the engine's regression file
+# (mane_case_validation.py:37, comment "##coutinho removed").
+LIVERPOOL_2015_16_ATTACKERS: list[str] = [
+    "Lallana",
+    "Firmino",
+    "Sturridge",
+    "Origi",
+    "Ibe",
+    "Benteke",
+]
+
+KLOPP_UPGRADES_VALIDATED: dict[str, float] = {
+    "cut_inside": 0.7,
+    "finishing": 0.5,
+    "progression": 0.4,
+    "chance_creation": 0.4,
+    "dribbling": 0.4,
+    "pressing": 0.7,
+}
+
+DEFENDER_POSITIONS: set[str] = {
+    "Goalkeeper",
+    "Center Back",
+    "Left Center Back",
+    "Right Center Back",
+    "Left Back",
+    "Right Back",
+    "Left Wing Back",
+    "Right Wing Back",
+}
+
+MANE_TOP_K: int = 60
+MANE_SEED: int = 42
+MANE_FINAL_TOP_N: int = 30

backend/app/services/player_index.py

@@ -0,0 +1,97 @@
+"""
+In-memory player index with accent-insensitive substring matching.
+
+The locked engine's `list_available_players(query, limit)` does plain
+lower()+substring matching, so `q=mane` does NOT match "Sadio Mané" because
+'e' != 'é'. We can't fix that in the engine (src/gp2/ is locked), so we
+wrap it here:
+
+  1. On first use, fetch the full player list once via
+     `engine.list_available_players("", BIG)` (cheap — just dict
+     construction over cached metadata; no model inference).
+  2. Pre-compute an accent-stripped lowercased name for each player.
+  3. Per request, strip accents from the user's query and substring-match
+     against the pre-computed names. Return canonical (accented) entries.
+
+Cache invalidation: none — the player set is fixed for a given model
+build. If models are reloaded, the engine warmup would discard our cache
+indirectly (we'd need to restart the process to rebuild it). Acceptable.
+"""
+from __future__ import annotations
+
+import asyncio
+import threading
+import unicodedata
+from typing import Any
+
+from app.services import engine
+
+# A bigger limit than any plausible player count; the engine returns at
+# most metadata.size items regardless.
+_FULL_LIST_LIMIT = 100_000
+
+_lock = threading.Lock()
+_full_list: list[dict[str, Any]] | None = None
+_normalized: list[str] | None = None
+
+
+def _strip_accents(s: str) -> str:
+    """NFD decomposition + drop combining marks. 'Mané'→'Mane', 'Bruyne'→'Bruyne'."""
+    return "".join(
+        c for c in unicodedata.normalize("NFD", s)
+        if unicodedata.category(c) != "Mn"
+    ).lower()
+
+
+def _build_sync() -> None:
+    """Synchronous (engine call) — must run on the engine executor."""
+    global _full_list, _normalized
+    if engine.scouting_engine is None:
+        raise RuntimeError("Engine not available")
+    rows = engine.scouting_engine.list_available_players("", _FULL_LIST_LIMIT)
+    _full_list = rows
+    _normalized = [_strip_accents(r.get("name", "")) for r in rows]
+
+
+async def ensure_built() -> None:
+    """Build the index if needed. Safe to call from any request handler."""
+    if _full_list is not None:
+        return
+    # Engine call goes through the shared single-worker executor so we don't
+    # block the event loop and we serialize with other engine work.
+    await engine.run_engine(_acquire_and_build)
+
+
+def _acquire_and_build() -> None:
+    # Runs on the engine thread; the lock guards against the (unlikely)
+    # case where two requests both call ensure_built() and both make it
+    # past the early-return check before either has populated the cache.
+    with _lock:
+        if _full_list is None:
+            _build_sync()
+
+
+def search(query: str, limit: int) -> list[dict[str, Any]]:
+    """Substring-match `query` against accent-stripped names. Caller is
+    expected to have awaited `ensure_built()` first."""
+    if _full_list is None or _normalized is None:
+        return []
+    q = _strip_accents(query).strip()
+    if not q:
+        return list(_full_list[:limit])
+    out: list[dict[str, Any]] = []
+    for row, norm in zip(_full_list, _normalized):
+        if q in norm:
+            out.append(row)
+            if len(out) >= limit:
+                break
+    return out
+
+
+# Test hook — lets tests reset the cache between runs without restarting
+# the process.
+def _reset() -> None:
+    global _full_list, _normalized
+    with _lock:
+        _full_list = None
+        _normalized = None