from __future__ import annotations import os from contextlib import asynccontextmanager from dataclasses import dataclass from pathlib import Path from typing import Any, Literal from fastapi import FastAPI, HTTPException, Request from fastapi.responses import JSONResponse from slop_farmer.config import PrSearchRefreshOptions from slop_farmer.data.ghreplica_api import GhReplicaProbeUnavailableError, GhrProbeClient from slop_farmer.data.snapshot_materialize import materialize_hf_dataset_snapshot from slop_farmer.data.snapshot_paths import ( CURRENT_ANALYSIS_MANIFEST_PATH, default_hf_materialize_dir, ) from slop_farmer.reports.analysis_service import ( get_analysis_best, get_analysis_meta_bug, get_analysis_status, get_pr_analysis, list_analysis_duplicate_prs, list_analysis_meta_bugs, ) from slop_farmer.reports.pr_search_service import ( get_pr_search_cluster, get_pr_search_clusters, get_pr_search_contributor_pulls, get_pr_search_pull_contributor, get_pr_search_similar_lookup, get_pr_search_status, list_pr_search_clusters, run_pr_search_refresh, ) from slop_farmer.reports.read_views import ( check_issue_cluster_membership, get_contributor, get_contributor_risk, get_contributor_status, get_issue_best, get_issue_cluster, get_issue_cluster_status, get_issue_clusters_for_pr, get_snapshot_surfaces, list_contributors, list_issue_clusters, list_issue_duplicate_prs, ) @dataclass(slots=True) class PrSearchApiSettings: default_repo: str | None index_path: Path output_dir: Path snapshot_dir: Path | None = None hf_repo_id: str | None = None hf_revision: str | None = None hf_materialize_dir: Path | None = None ghr_base_url: str | None = None http_timeout: int = 180 http_max_retries: int = 5 refresh_if_missing: bool = False rebuild_on_start: bool = False include_drafts: bool = False include_closed: bool = False similar_limit_default: int = 10 similar_limit_max: int = 50 candidate_limit_default: int = 5 candidate_limit_max: int = 20 cluster_list_limit_default: int = 50 cluster_list_limit_max: int = 200 issue_list_limit_default: int = 50 issue_list_limit_max: int = 200 contributor_list_limit_default: int = 50 contributor_list_limit_max: int = 200 probe_limit_default: int = 10 probe_limit_max: int = 25 @classmethod def from_env(cls) -> PrSearchApiSettings: output_dir = Path(os.environ.get("OUTPUT_DIR", "data")).resolve() index_path = Path( os.environ.get("INDEX_PATH", str(output_dir / "state" / "pr-search.duckdb")) ).resolve() snapshot_dir = _env_path("SNAPSHOT_DIR") hf_materialize_dir = _env_path("HF_MATERIALIZE_DIR") return cls( default_repo=os.environ.get("DEFAULT_REPO"), index_path=index_path, output_dir=output_dir, snapshot_dir=snapshot_dir, hf_repo_id=os.environ.get("HF_REPO_ID"), hf_revision=os.environ.get("HF_REVISION"), hf_materialize_dir=hf_materialize_dir, ghr_base_url=os.environ.get("GHR_BASE_URL"), http_timeout=_env_int("HTTP_TIMEOUT", 180), http_max_retries=_env_int("HTTP_MAX_RETRIES", 5), refresh_if_missing=_env_bool("REFRESH_IF_MISSING", False), rebuild_on_start=_env_bool("REBUILD_ON_START", False), include_drafts=_env_bool("INCLUDE_DRAFTS", False), include_closed=_env_bool("INCLUDE_CLOSED", False), similar_limit_default=_env_int("SIMILAR_LIMIT_DEFAULT", 10), similar_limit_max=_env_int("SIMILAR_LIMIT_MAX", 50), candidate_limit_default=_env_int("CANDIDATE_LIMIT_DEFAULT", 5), candidate_limit_max=_env_int("CANDIDATE_LIMIT_MAX", 20), cluster_list_limit_default=_env_int("CLUSTER_LIST_LIMIT_DEFAULT", 50), cluster_list_limit_max=_env_int("CLUSTER_LIST_LIMIT_MAX", 200), issue_list_limit_default=_env_int("ISSUE_LIST_LIMIT_DEFAULT", 50), issue_list_limit_max=_env_int("ISSUE_LIST_LIMIT_MAX", 200), contributor_list_limit_default=_env_int("CONTRIBUTOR_LIST_LIMIT_DEFAULT", 50), contributor_list_limit_max=_env_int("CONTRIBUTOR_LIST_LIMIT_MAX", 200), probe_limit_default=_env_int("PROBE_LIMIT_DEFAULT", 10), probe_limit_max=_env_int("PROBE_LIMIT_MAX", 25), ) def create_app(settings: PrSearchApiSettings | None = None) -> FastAPI: api_settings = settings or PrSearchApiSettings.from_env() @asynccontextmanager async def lifespan(app: FastAPI): app.state.settings = api_settings app.state.ready = False app.state.startup_error = None try: _bootstrap_snapshot_assets(api_settings) _bootstrap_index(api_settings) app.state.ready = _is_ready(api_settings) except Exception as exc: app.state.startup_error = str(exc) yield app = FastAPI(title="slop PR search API", version="0.1.1", lifespan=lifespan) @app.exception_handler(ValueError) async def handle_value_error(_request: Request, exc: ValueError) -> JSONResponse: status_code = 404 if _looks_not_found(exc) else 400 return JSONResponse({"detail": str(exc)}, status_code=status_code) @app.exception_handler(GhReplicaProbeUnavailableError) async def handle_probe_unavailable( _request: Request, exc: GhReplicaProbeUnavailableError ) -> JSONResponse: return JSONResponse({"detail": str(exc)}, status_code=exc.status_code) @app.get("/healthz") async def healthz() -> dict[str, bool]: return {"ok": True} @app.get("/readyz") async def readyz(request: Request) -> JSONResponse: settings = request.app.state.settings error = request.app.state.startup_error ready = request.app.state.ready and _is_ready(settings) if ready: return JSONResponse({"ok": True}) detail = error or _readiness_detail(settings) return JSONResponse({"ok": False, "detail": detail}, status_code=503) @app.get("/v1/repos/{owner}/{repo}/status") async def repo_status(owner: str, repo: str, request: Request) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) status = get_pr_search_status(settings.index_path, repo=repo_slug) issue_snapshot_dir = _surface_snapshot_dir(settings, repo_slug, surface="issues") contributor_snapshot_dir = _surface_snapshot_dir( settings, repo_slug, surface="contributors" ) return { **status, "surfaces": { "issues": get_snapshot_surfaces(issue_snapshot_dir)["issues"], "contributors": get_snapshot_surfaces(contributor_snapshot_dir)["contributors"], }, } @app.get("/v1/repos/{owner}/{repo}/pulls/{number}/similar") async def pr_similar( owner: str, repo: str, number: int, request: Request, limit: int | None = None, mode: Literal["auto", "indexed", "live"] = "auto", ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return get_pr_search_similar_lookup( settings.index_path, repo=repo_slug, pr_number=number, limit=_limit( limit, default=settings.similar_limit_default, maximum=settings.similar_limit_max ), mode=mode, client=_probe_client(settings), ) @app.get("/v1/repos/{owner}/{repo}/pulls/{number}/clusters") async def pr_clusters( owner: str, repo: str, number: int, request: Request, limit: int | None = None, mode: Literal["auto", "indexed", "live"] = "auto", ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return get_pr_search_clusters( settings.index_path, repo=repo_slug, pr_number=number, limit=_limit( limit, default=settings.candidate_limit_default, maximum=settings.candidate_limit_max, ), mode=mode, client=_probe_client(settings), ) @app.get("/v1/repos/{owner}/{repo}/clusters/{cluster_id}") async def cluster_view( owner: str, repo: str, cluster_id: str, request: Request, ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return get_pr_search_cluster(settings.index_path, repo=repo_slug, cluster_id=cluster_id) @app.get("/v1/repos/{owner}/{repo}/clusters") async def cluster_list( owner: str, repo: str, request: Request, limit: int | None = None, ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return list_pr_search_clusters( settings.index_path, repo=repo_slug, limit=_limit( limit, default=settings.cluster_list_limit_default, maximum=settings.cluster_list_limit_max, ), ) @app.get("/v1/repos/{owner}/{repo}/contributors/{login}/pulls") async def contributor_pulls( owner: str, repo: str, login: str, request: Request, limit: int | None = None, ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return get_pr_search_contributor_pulls( settings.index_path, repo=repo_slug, author_login=login, limit=_limit( limit, default=settings.similar_limit_default, maximum=settings.similar_limit_max ), ) @app.get("/v1/repos/{owner}/{repo}/pulls/{number}/contributor") async def pull_contributor( owner: str, repo: str, number: int, request: Request, ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return get_pr_search_pull_contributor(settings.index_path, repo=repo_slug, pr_number=number) @app.get("/v1/repos/{owner}/{repo}/analysis/status") async def analysis_status( owner: str, repo: str, request: Request, variant: Literal["auto", "hybrid", "deterministic"] = "auto", snapshot_id: str | None = None, analysis_id: str | None = None, ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return get_analysis_status( settings.index_path, repo=repo_slug, variant=variant, snapshot_id=snapshot_id, analysis_id=analysis_id, ) @app.get("/v1/repos/{owner}/{repo}/pulls/{number}/analysis") async def pr_analysis( owner: str, repo: str, number: int, request: Request, variant: Literal["auto", "hybrid", "deterministic"] = "auto", snapshot_id: str | None = None, analysis_id: str | None = None, ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return get_pr_analysis( settings.index_path, repo=repo_slug, pr_number=number, variant=variant, snapshot_id=snapshot_id, analysis_id=analysis_id, ) @app.get("/v1/repos/{owner}/{repo}/analysis/meta-bugs") async def analysis_meta_bugs( owner: str, repo: str, request: Request, limit: int | None = None, variant: Literal["auto", "hybrid", "deterministic"] = "auto", snapshot_id: str | None = None, analysis_id: str | None = None, ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return list_analysis_meta_bugs( settings.index_path, repo=repo_slug, variant=variant, limit=_limit( limit, default=settings.cluster_list_limit_default, maximum=settings.cluster_list_limit_max, ), snapshot_id=snapshot_id, analysis_id=analysis_id, ) @app.get("/v1/repos/{owner}/{repo}/analysis/meta-bugs/{cluster_id}") async def analysis_meta_bug( owner: str, repo: str, cluster_id: str, request: Request, variant: Literal["auto", "hybrid", "deterministic"] = "auto", snapshot_id: str | None = None, analysis_id: str | None = None, ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return get_analysis_meta_bug( settings.index_path, repo=repo_slug, cluster_id=cluster_id, variant=variant, snapshot_id=snapshot_id, analysis_id=analysis_id, ) @app.get("/v1/repos/{owner}/{repo}/analysis/duplicate-prs") async def analysis_duplicate_prs( owner: str, repo: str, request: Request, limit: int | None = None, variant: Literal["auto", "hybrid", "deterministic"] = "auto", snapshot_id: str | None = None, analysis_id: str | None = None, ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return list_analysis_duplicate_prs( settings.index_path, repo=repo_slug, variant=variant, limit=_limit( limit, default=settings.cluster_list_limit_default, maximum=settings.cluster_list_limit_max, ), snapshot_id=snapshot_id, analysis_id=analysis_id, ) @app.get("/v1/repos/{owner}/{repo}/analysis/best") async def analysis_best( owner: str, repo: str, request: Request, variant: Literal["auto", "hybrid", "deterministic"] = "auto", snapshot_id: str | None = None, analysis_id: str | None = None, ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return get_analysis_best( settings.index_path, repo=repo_slug, variant=variant, snapshot_id=snapshot_id, analysis_id=analysis_id, ) @app.get("/v1/repos/{owner}/{repo}/issues/status") async def issue_status( owner: str, repo: str, request: Request, variant: Literal["auto", "hybrid", "deterministic"] = "auto", ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return get_issue_cluster_status( _surface_snapshot_dir(settings, repo_slug, surface="issues"), variant=variant, ) @app.get("/v1/repos/{owner}/{repo}/issues/clusters") async def issue_clusters( owner: str, repo: str, request: Request, limit: int | None = None, variant: Literal["auto", "hybrid", "deterministic"] = "auto", ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return list_issue_clusters( _surface_snapshot_dir(settings, repo_slug, surface="issues"), limit=_limit( limit, default=settings.issue_list_limit_default, maximum=settings.issue_list_limit_max, ), variant=variant, ) @app.get("/v1/repos/{owner}/{repo}/issues/clusters/{cluster_id}") async def issue_cluster( owner: str, repo: str, cluster_id: str, request: Request, variant: Literal["auto", "hybrid", "deterministic"] = "auto", ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return get_issue_cluster( _surface_snapshot_dir(settings, repo_slug, surface="issues"), cluster_id=cluster_id, variant=variant, ) @app.get("/v1/repos/{owner}/{repo}/issues/pulls/{number}") async def issue_clusters_for_pr( owner: str, repo: str, number: int, request: Request, variant: Literal["auto", "hybrid", "deterministic"] = "auto", ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return get_issue_clusters_for_pr( _surface_snapshot_dir(settings, repo_slug, surface="issues"), pr_number=number, variant=variant, ) @app.get("/v1/repos/{owner}/{repo}/issues/pulls/{number}/membership") async def issue_membership_for_pr( owner: str, repo: str, number: int, request: Request, cluster_id: str | None = None, variant: Literal["auto", "hybrid", "deterministic"] = "auto", ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return check_issue_cluster_membership( _surface_snapshot_dir(settings, repo_slug, surface="issues"), pr_number=number, cluster_id=cluster_id, variant=variant, ) @app.get("/v1/repos/{owner}/{repo}/issues/duplicate-prs") async def issue_duplicate_prs( owner: str, repo: str, request: Request, limit: int | None = None, variant: Literal["auto", "hybrid", "deterministic"] = "auto", ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return list_issue_duplicate_prs( _surface_snapshot_dir(settings, repo_slug, surface="issues"), limit=_limit( limit, default=settings.issue_list_limit_default, maximum=settings.issue_list_limit_max, ), variant=variant, ) @app.get("/v1/repos/{owner}/{repo}/issues/best") async def issue_best( owner: str, repo: str, request: Request, variant: Literal["auto", "hybrid", "deterministic"] = "auto", ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return get_issue_best( _surface_snapshot_dir(settings, repo_slug, surface="issues"), variant=variant, ) @app.get("/v1/repos/{owner}/{repo}/contributors/status") async def contributor_status( owner: str, repo: str, request: Request, ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return get_contributor_status( _surface_snapshot_dir(settings, repo_slug, surface="contributors") ) @app.get("/v1/repos/{owner}/{repo}/contributors") async def contributors( owner: str, repo: str, request: Request, limit: int | None = None, ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return list_contributors( _surface_snapshot_dir(settings, repo_slug, surface="contributors"), limit=_limit( limit, default=settings.contributor_list_limit_default, maximum=settings.contributor_list_limit_max, ), ) @app.get("/v1/repos/{owner}/{repo}/contributors/{login}") async def contributor( owner: str, repo: str, login: str, request: Request, ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return get_contributor( _surface_snapshot_dir(settings, repo_slug, surface="contributors"), author_login=login, ) @app.get("/v1/repos/{owner}/{repo}/contributors/{login}/risk") async def contributor_risk( owner: str, repo: str, login: str, request: Request, ) -> dict[str, Any]: settings = request.app.state.settings repo_slug = _repo_slug(settings, owner, repo) return get_contributor_risk( _surface_snapshot_dir(settings, repo_slug, surface="contributors"), author_login=login, ) return app def _bootstrap_index(settings: PrSearchApiSettings) -> None: settings.output_dir.mkdir(parents=True, exist_ok=True) settings.index_path.parent.mkdir(parents=True, exist_ok=True) if not _needs_refresh(settings): return if settings.snapshot_dir is None and settings.hf_repo_id is None: return run_pr_search_refresh( PrSearchRefreshOptions( snapshot_dir=settings.snapshot_dir, output_dir=settings.output_dir, db=settings.index_path, hf_repo_id=settings.hf_repo_id, hf_revision=settings.hf_revision, hf_materialize_dir=settings.hf_materialize_dir, include_drafts=settings.include_drafts, include_closed=settings.include_closed, ) ) def _bootstrap_snapshot_assets(settings: PrSearchApiSettings) -> None: if settings.snapshot_dir is not None or settings.hf_repo_id is None: return materialize_dir = settings.hf_materialize_dir or default_hf_materialize_dir( settings.output_dir, settings.hf_repo_id, settings.hf_revision, ) materialize_hf_dataset_snapshot( repo_id=settings.hf_repo_id, local_dir=materialize_dir, revision=settings.hf_revision, ) def _needs_refresh(settings: PrSearchApiSettings) -> bool: if settings.rebuild_on_start: return True if not settings.refresh_if_missing: return False return not _is_ready(settings) def _is_ready(settings: PrSearchApiSettings) -> bool: if not settings.index_path.exists(): return False try: get_pr_search_status(settings.index_path, repo=settings.default_repo) except Exception: return False return True def _readiness_detail(settings: PrSearchApiSettings) -> str: if not settings.index_path.exists(): return f"index not found at {settings.index_path}" try: get_pr_search_status(settings.index_path, repo=settings.default_repo) except Exception as exc: return str(exc) return "ready" def _repo_slug(settings: PrSearchApiSettings, owner: str, repo: str) -> str: repo_slug = f"{owner}/{repo}" if settings.default_repo and repo_slug != settings.default_repo: raise HTTPException( status_code=400, detail=f"repo {settings.default_repo} is the only configured repo for this deployment", ) return repo_slug def _active_snapshot_dir(settings: PrSearchApiSettings, repo_slug: str) -> Path: return _status_snapshot_dir(get_pr_search_status(settings.index_path, repo=repo_slug)) def _surface_snapshot_dir( settings: PrSearchApiSettings, repo_slug: str, *, surface: Literal["issues", "contributors"], ) -> Path: active_snapshot_dir = _active_snapshot_dir(settings, repo_slug) if _surface_available(active_snapshot_dir, surface=surface): return active_snapshot_dir materialized_snapshot_dir = _materialized_snapshot_dir(settings) if materialized_snapshot_dir is not None and _surface_available( materialized_snapshot_dir, surface=surface ): return materialized_snapshot_dir return active_snapshot_dir def _status_snapshot_dir(status: dict[str, Any]) -> Path: snapshot_dir = status.get("snapshot_dir") if not snapshot_dir: raise HTTPException(status_code=503, detail="active snapshot directory is unavailable") return Path(str(snapshot_dir)) def _materialized_snapshot_dir(settings: PrSearchApiSettings) -> Path | None: if settings.hf_repo_id is None: return None return settings.hf_materialize_dir or default_hf_materialize_dir( settings.output_dir, settings.hf_repo_id, settings.hf_revision, ) def _surface_available(snapshot_dir: Path, *, surface: Literal["issues", "contributors"]) -> bool: if not snapshot_dir.exists(): return False if surface == "issues": return (snapshot_dir / CURRENT_ANALYSIS_MANIFEST_PATH).exists() or any( snapshot_dir.glob("analysis-report*.json") ) return (snapshot_dir / "new-contributors-report.json").exists() def _limit(value: int | None, *, default: int, maximum: int) -> int: limit = default if value is None else value if limit < 1: raise HTTPException(status_code=400, detail="limit must be at least 1") if limit > maximum: raise HTTPException(status_code=400, detail=f"limit must be at most {maximum}") return limit def _probe_client(settings: PrSearchApiSettings) -> Any: if not settings.ghr_base_url: return None return GhrProbeClient( base_url=settings.ghr_base_url, timeout=settings.http_timeout, max_retries=settings.http_max_retries, ) def _looks_not_found(exc: ValueError) -> bool: message = str(exc).lower() return ( "not found" in message or "analysis report was not found" in message or "no analysis report was found" in message or "published analysis" in message or "materialized snapshot" in message or "no active pr search run" in message or "was not found in the active indexed universe" in message ) def _env_bool(name: str, default: bool) -> bool: raw = os.environ.get(name) if raw is None: return default return raw.strip().lower() in {"1", "true", "yes", "on"} def _env_int(name: str, default: int) -> int: raw = os.environ.get(name) return default if raw is None else int(raw) def _env_path(name: str) -> Path | None: raw = os.environ.get(name) return None if raw is None else Path(raw).resolve() app = create_app()