pnotp 0.1.0__py3-none-any.whl

pnotp/__init__.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+"""Public entrypoint for the pnotp client library."""
+
+import os
+
+from .client import Client as _Client, DEFAULT_BASE_URL
+
+
+def client(api_key: str | None = None, base_url: str | None = None) -> _Client:
+    """
+    Factory for the PnotP client.
+
+    If no api_key is provided, the loader will pull it from the environment
+    using (in order): PNOTP_API_KEY, pnotp_API_KEY.
+    The base URL defaults to the production endpoint unless explicitly overridden.
+    """
+    resolved_key = api_key or os.getenv("PNOTP_API_KEY") or os.getenv("pnotp_API_KEY")
+    resolved_base = base_url or DEFAULT_BASE_URL
+    return _Client(api_key=resolved_key, base_url=resolved_base)
+
+
+__all__ = ["client"]

pnotp/client.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from typing import List, Optional, Union
+
+import httpx
+
+from .models import RemoteModel
+
+DEFAULT_BASE_URL = "https://api.pnotp.ai/v1"
+
+
+class Client:
+    """
+    Main PnotP client.
+
+    Usage:
+        import pnotp as pnp
+        client = pnp.client(api_key="API_KEY", base_url="http://127.0.0.1:8000/v1")
+        client.models()                      # list models
+        model = client.models("pneumonia_binary_classification")
+        result = model.predict("image.jpg")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required. Pass it explicitly or set PNOTP_API_KEY.")
+        base = base_url.rstrip("/")
+        base_for_httpx = base if base.endswith("/") else f"{base}/"
+
+        self.api_key = api_key
+        self.base_url = base
+        self._http = httpx.Client(
+            base_url=base_for_httpx,
+            timeout=timeout,
+            headers={"X-API-Key": self.api_key},
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def models(
+        self,
+        model: Optional[str] = None,
+    ) -> Union[List[str], RemoteModel]:
+        """
+        - If called with no args: lists all available model ids.
+        - If `model` is provided: returns a RemoteModel handle.
+        """
+        if model is None:
+            resp = self._http.get("models")
+            resp.raise_for_status()
+            data = resp.json()  # {"models": [{...}, ...]}
+
+            model_ids = [m["id"] for m in data.get("models", [])]
+
+            print("You have access to the following models:")
+            for mid in model_ids:
+                print(f"- {mid}")
+
+            return model_ids
+
+        return RemoteModel(name=model, http_client=self._http)
+
+
+__all__ = ["Client", "DEFAULT_BASE_URL"]

pnotp/exceptions.py

@@ -0,0 +1,13 @@
+"""Custom exceptions for the pnotp client."""
+
+
+class PnotPError(Exception):
+    """Base error for all pnotp client exceptions."""
+
+
+class VisionOnlyError(PnotPError):
+    """Raised when attention maps are requested for non-vision models."""
+
+
+__all__ = ["PnotPError", "VisionOnlyError"]
+

pnotp/models.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, IO, Tuple
+
+import httpx
+
+from .exceptions import VisionOnlyError
+
+
+class RemoteModel:
+    """
+    High-level handle for a remote model.
+
+    Example:
+        model = client.models("pneumonia_binary_classification")
+        result = model.predict("image.jpg")
+        heatmap = model.attention_map("image.jpg")
+    """
+
+    def __init__(
+        self,
+        name: str,
+        http_client: httpx.Client,
+        is_vision: bool = True,
+    ) -> None:
+        self.name = name
+        self._http = http_client
+        self.is_vision = is_vision
+
+    # ---------- Internal helpers ----------
+
+    def _normalize_image_input(self, img: Any) -> Tuple[IO[bytes], bool]:
+        """
+        Normalizes supported image inputs to a binary file object and indicates
+        whether the caller should close the file after use.
+        """
+        if isinstance(img, (str, Path)):
+            return open(str(img), "rb"), True
+        if hasattr(img, "read"):
+            return img, False  # type: ignore[return-value]
+        raise TypeError("img must be a file path or file-like object")
+
+    # ---------- Public API ----------
+
+    def predict(self, img: Any):
+        """
+        Sends an image to the remote model and returns the JSON classification report.
+        """
+        file_obj, should_close = self._normalize_image_input(img)
+        try:
+            files = {"file": ("image", file_obj, "application/octet-stream")}
+            resp = self._http.post(f"models/{self.name}:predict", files=files)
+            resp.raise_for_status()
+            return resp.json()
+        finally:
+            if should_close:
+                try:
+                    file_obj.close()
+                except Exception:  # pragma: no cover
+                    pass
+
+    def attention_map(self, img: Any) -> bytes:
+        """
+        Returns an attention/activation map for vision models as raw image bytes.
+        """
+        if not self.is_vision:
+            raise VisionOnlyError(
+                f"Model '{self.name}' does not support attention_map (non-vision model)."
+            )
+
+        file_obj, should_close = self._normalize_image_input(img)
+        try:
+            files = {"file": ("image", file_obj, "application/octet-stream")}
+            resp = self._http.post(f"models/{self.name}:attention-map", files=files)
+            resp.raise_for_status()
+            return resp.content
+        finally:
+            if should_close:
+                try:
+                    file_obj.close()
+                except Exception:  # pragma: no cover
+                    pass
+
+
+__all__ = ["RemoteModel"]
+

pnotp-0.1.0.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: pnotp
+Version: 0.1.0
+Summary: PnotP client and API wrappers for PathoVision models.
+Project-URL: Homepage, https://pnotp.ai
+Author-email: PnotP <support@pnotp.ai>
+Requires-Python: >=3.9
+Requires-Dist: httpx<0.29,>=0.24
+Provides-Extra: server
+Requires-Dist: fastapi<1.0,>=0.110; extra == 'server'
+Requires-Dist: pillow>=9.0; extra == 'server'
+Requires-Dist: pydantic<3.0,>=2.0; extra == 'server'
+Requires-Dist: python-multipart>=0.0.6; extra == 'server'
+Requires-Dist: uvicorn<0.29,>=0.23; extra == 'server'
+Description-Content-Type: text/markdown
+
+# PnotP
+
+Unified API and Python client for PathoVision vision models.
+
+## Packages
+- `pnotp_api`: FastAPI service that wraps PathoVision ensembles under a consistent `/v1` surface with API-key auth.
+- `pnotp`: Python client for calling the PnotP API.
+
+## Install (client only)
+```bash
+pip install pnotp
+```
+
+## Install (client + server extra)
+```bash
+pip install "pnotp[server]"
+```
+
+## Usage (client)
+```python
+import pnotp as pnp
+
+client = pnp.client(api_key="YOUR_KEY")  # default base URL is production
+client.models()
+model = client.models("pneumonia_binary_classification")
+result = model.predict("image.jpg")
+heatmap = model.attention_map("image.jpg")
+```
+
+Set your key once per shell:
+```bash
+export PNOTP_API_KEY="your_api_key_here"
+python your_script.py  # pnp.client() will read the env var automatically
+```
+
+## Run the API locally
+```bash
+export PNOTP_INTERNAL_SECRET="dev-secret"
+export PATHOVISION_ROOT="/absolute/path/to/PathoVision"  # if not default
+uvicorn pnotp_api.main:app --host 0.0.0.0 --port 8000
+```
+
+## Issue an API key (internal)
+```bash
+curl -X POST http://127.0.0.1:8000/internal/api-keys \
+  -H "X-Internal-Secret: $PNOTP_INTERNAL_SECRET" \
+  -H "Content-Type: application/json" \
+  -d '{"user_external_id":"demo-user","plan_code":"pathovision_starter"}'
+```

pnotp-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+pnotp/__init__.py,sha256=HYuvgxR8O1cEKtb_07cz-RrlqQLBEbUKRVu2U4xuWqs,726
+pnotp/client.py,sha256=Sio7xharzWR81g47gu-buZ3_jzNy7q_6qeEbfEJzT4w,2059
+pnotp/exceptions.py,sha256=wyziSTUjI8KIU_8_-foBiLk7jb82CtjCyHSHvvAdYX8,289
+pnotp/models.py,sha256=PQwvBVcV3zCJIhovU1Ex46RFdub3mp3qGgQ29LBB4_Y,2685
+pnotp_api/__init__.py,sha256=hf6hBqS6prZbp0vc3aVQ_hobqh83nj5Ds03uEbIuG5M,114
+pnotp_api/db.py,sha256=K3NIGL3aRecFyoNkHUsEjevHrD8m28Qn9nRJVGKNEpE,3269
+pnotp_api/main.py,sha256=qBCzu4Xw-Awk68y0BMdP6Drrjl8U1qtTa2cGqFPKP2w,5555
+pnotp_api/models_registry.py,sha256=FOA6JCHYugbOe_LI9c0MqeScG_Fd702TYc7Lje01QQg,3556
+pnotp_api/pathovision_bridge.py,sha256=gFRBDLbccDqHj3sYd2mpZ9VSXXOVcVVGZqOb30s9YkM,19412
+pnotp_api/schemas.py,sha256=6Ywf-O0MCuZiRWoalMTu1w99Oub5ymgPXRmKt30IdRI,456
+pnotp_api/security.py,sha256=hUBFvAKaBSjAer6CIKeP4C_kQD6ZfctCgTKBWLxOs9w,1037
+pnotp-0.1.0.dist-info/METADATA,sha256=FvPb7zUILXXnyK4yXNJ9ilK0eu8mYC9lYxm1FRE0oRQ,1866
+pnotp-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pnotp-0.1.0.dist-info/RECORD,,

pnotp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pnotp_api/__init__.py

@@ -0,0 +1,4 @@
+"""PnotP API built on top of PathoVision models."""
+
+# The FastAPI application is exposed in ``pnotp_api.main``.
+

pnotp_api/db.py

@@ -0,0 +1,118 @@
+"""Minimal SQLite-backed API key store for PnotP."""
+from __future__ import annotations
+
+import hashlib
+import secrets
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, Optional
+
+DB_PATH = Path(__file__).resolve().parent.parent / "pnotp_api.db"
+
+
+def _utc_now_iso() -> str:
+    return datetime.now(tz=timezone.utc).isoformat()
+
+
+def _get_conn() -> sqlite3.Connection:
+    conn = sqlite3.connect(DB_PATH)
+    conn.execute("PRAGMA journal_mode=WAL;")
+    conn.execute("PRAGMA foreign_keys=ON;")
+    return conn
+
+
+def init_db() -> None:
+    """Creates the api_keys table if missing."""
+    with _get_conn() as conn:
+        conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS api_keys (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                user_external_id TEXT NOT NULL,
+                plan_code TEXT NOT NULL,
+                key_hash TEXT NOT NULL UNIQUE,
+                key_prefix TEXT NOT NULL,
+                is_active INTEGER NOT NULL DEFAULT 1,
+                created_at TEXT NOT NULL,
+                last_used_at TEXT
+            );
+            """
+        )
+
+
+def _hash_key(raw_key: str) -> str:
+    return hashlib.sha256(raw_key.encode("utf-8")).hexdigest()
+
+
+def generate_api_key(user_external_id: str, plan_code: str) -> str:
+    """
+    Generates and stores a new API key, returning the raw secret.
+    """
+    # Ensure a ~32-character urlsafe suffix.
+    suffix = secrets.token_urlsafe(32)[:32]
+    raw_key = f"pnp_live_{suffix}"
+    key_hash = _hash_key(raw_key)
+    key_prefix = raw_key[:12]
+    created_at = _utc_now_iso()
+
+    with _get_conn() as conn:
+        conn.execute(
+            """
+            INSERT INTO api_keys (user_external_id, plan_code, key_hash, key_prefix, is_active, created_at)
+            VALUES (?, ?, ?, ?, 1, ?)
+            """,
+            (user_external_id, plan_code, key_hash, key_prefix, created_at),
+        )
+
+    return raw_key
+
+
+def get_api_key(key_raw: str) -> Optional[Dict[str, str]]:
+    """
+    Looks up an API key by raw secret. Returns None if missing or inactive.
+    """
+    key_hash = _hash_key(key_raw)
+    with _get_conn() as conn:
+        row = conn.execute(
+            """
+            SELECT user_external_id, plan_code, key_prefix, is_active
+            FROM api_keys
+            WHERE key_hash = ?
+            """,
+            (key_hash,),
+        ).fetchone()
+    if not row:
+        return None
+    user_external_id, plan_code, key_prefix, is_active = row
+    if not is_active:
+        return None
+    return {
+        "user_external_id": user_external_id,
+        "plan_code": plan_code,
+        "key_prefix": key_prefix,
+    }
+
+
+def touch_api_key_usage(key_raw: str) -> None:
+    """Updates last_used_at for an API key; ignores missing keys."""
+    key_hash = _hash_key(key_raw)
+    with _get_conn() as conn:
+        conn.execute(
+            """
+            UPDATE api_keys
+            SET last_used_at = ?
+            WHERE key_hash = ?
+            """,
+            (_utc_now_iso(), key_hash),
+        )
+
+
+# Initialize table eagerly.
+init_db()
+
+
+if __name__ == "__main__":
+    init_db()
+    new_key = generate_api_key("local_dev_user", "pathovision_starter")
+    print(f"Generated API key: {new_key}")

pnotp_api/main.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import os
+
+from fastapi import Depends, FastAPI, File, Header, HTTPException, UploadFile, status
+from fastapi.responses import Response
+from pydantic import BaseModel
+
+from .db import generate_api_key, init_db
+from .models_registry import MODELS_REGISTRY
+from .schemas import PredictionResult
+from .security import require_api_key
+
+app = FastAPI(title="PnotP API", version="0.1.0")
+
+INTERNAL_SECRET = os.getenv("PNOTP_INTERNAL_SECRET", "")
+
+
+def _map_pathovision_report(model_id: str, report: dict) -> PredictionResult:
+    """
+    Normalizes the raw PathoVision report into the PnotP schema.
+    """
+    if report is None:
+        raise ValueError("Inference returned an empty report.")
+
+    positive_prob = report.get("prob")
+    if positive_prob is None:
+        positive_prob = report.get("positive_prob")
+    if positive_prob is None:
+        raise ValueError("Report did not include a probability.")
+
+    class_probabilities = report.get("class_probabilities") or {}
+    if isinstance(class_probabilities, dict) and "notumor" in class_probabilities:
+        neg = float(class_probabilities.get("notumor", 0.0))
+        positive_prob = max(0.0, min(1.0, 1.0 - neg))
+        negative_prob = neg
+    else:
+        negative_prob = max(0.0, 1.0 - float(positive_prob))
+
+    threshold = report.get("threshold", 0.5)
+    decision = report.get("decision")
+    if decision is None:
+        predicted_class = str(report.get("predicted_class", "")).lower()
+        if predicted_class:
+            decision = predicted_class not in {"normal", "notumor", "negative"}
+        else:
+            decision = not bool(report.get("abstain", False))
+
+    model_version = report.get("model_version") or report.get("task") or model_id
+
+    return PredictionResult(
+        task=model_id,
+        positive_prob=float(positive_prob),
+        negative_prob=float(negative_prob),
+        prediction=bool(decision),
+        threshold=float(threshold),
+        model_version=str(model_version),
+        metadata=report,
+    )
+
+
+async def require_internal_secret(x_internal_secret: str = Header(..., alias="X-Internal-Secret")):
+    if not INTERNAL_SECRET or x_internal_secret != INTERNAL_SECRET:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid internal secret")
+
+
+class CreateApiKeyRequest(BaseModel):
+    user_external_id: str
+    plan_code: str
+
+
+@app.on_event("startup")
+async def _startup() -> None:
+    init_db()
+
+
+@app.get("/v1/models")
+async def list_models(api_key_info=Depends(require_api_key)):
+    return {
+        "models": [
+            {
+                "id": m.model_id,
+                "task": m.task,
+                "vertical": m.vertical,
+                "type": "vision" if m.is_vision else "generic",
+            }
+            for m in MODELS_REGISTRY.values()
+        ]
+    }
+
+
+@app.post("/v1/models/{model_id}:predict", response_model=PredictionResult)
+async def predict_model(
+    model_id: str,
+    file: UploadFile = File(...),
+    api_key_info=Depends(require_api_key),
+) -> PredictionResult:
+    model_info = MODELS_REGISTRY.get(model_id)
+    if model_info is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Unknown model_id '{model_id}'",
+        )
+
+    data = await file.read()
+    if not data:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Uploaded file is empty.")
+
+    try:
+        raw_report = await model_info.predict_fn(data)
+        return _map_pathovision_report(model_id, raw_report)
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
+    except HTTPException:
+        raise
+    except Exception as exc:  # pragma: no cover
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Inference failed: {exc}",
+        ) from exc
+
+
+@app.post("/v1/models/{model_id}:attention-map")
+async def attention_map(
+    model_id: str,
+    file: UploadFile = File(...),
+    api_key_info=Depends(require_api_key),
+):
+    model_info = MODELS_REGISTRY.get(model_id)
+    if model_info is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Unknown model_id '{model_id}'",
+        )
+
+    if not model_info.is_vision or model_info.attention_map_fn is None:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Model '{model_id}' does not support attention_map",
+        )
+
+    data = await file.read()
+    if not data:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Uploaded file is empty.")
+
+    try:
+        png_bytes = await model_info.attention_map_fn(data)
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
+    except HTTPException:
+        raise
+    except Exception as exc:  # pragma: no cover
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Attention map generation failed: {exc}",
+        ) from exc
+
+    return Response(content=png_bytes, media_type="image/png")
+
+
+@app.post("/internal/api-keys")
+async def create_api_key(
+    payload: CreateApiKeyRequest,
+    _: None = Depends(require_internal_secret),
+):
+    raw_key = generate_api_key(payload.user_external_id, payload.plan_code)
+    prefix = raw_key[:12]
+    return {"api_key": raw_key, "prefix": prefix}
+
+
+__all__ = ["app"]

pnotp_api/models_registry.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from typing import Awaitable, Callable, Dict, Optional
+
+from .pathovision_bridge import (
+    run_aorticenlargement_attention_map,
+    run_aorticenlargement_inference,
+    run_brainmri_attention_map,
+    run_brainmri_inference,
+    run_cardiomegaly_attention_map,
+    run_cardiomegaly_inference,
+    run_pneumonia_attention_map,
+    run_pneumonia_inference,
+    run_pleuraleffusion_attention_map,
+    run_pleuraleffusion_inference,
+    run_pleuralthickening_attention_map,
+    run_pleuralthickening_inference,
+    run_tuberculosis_attention_map,
+    run_tuberculosis_inference,
+)
+
+
+class ModelInfo:
+    """Metadata and callable hooks for a registered model."""
+
+    def __init__(
+        self,
+        model_id: str,
+        task: str,
+        vertical: str,
+        is_vision: bool,
+        predict_fn: Callable[[bytes], Awaitable[dict]],
+        attention_map_fn: Optional[Callable[[bytes], Awaitable[bytes]]] = None,
+    ) -> None:
+        self.model_id = model_id
+        self.task = task
+        self.vertical = vertical
+        self.is_vision = is_vision
+        self.predict_fn = predict_fn
+        self.attention_map_fn = attention_map_fn
+
+
+MODELS_REGISTRY: Dict[str, ModelInfo] = {
+    "pneumonia_binary_classification": ModelInfo(
+        model_id="pneumonia_binary_classification",
+        task="P_vs_notP",
+        vertical="medical/pathovision/chest-xray",
+        is_vision=True,
+        predict_fn=run_pneumonia_inference,
+        attention_map_fn=run_pneumonia_attention_map,
+    ),
+    "cardiomegaly_binary_classification": ModelInfo(
+        model_id="cardiomegaly_binary_classification",
+        task="P_vs_notP",
+        vertical="medical/pathovision/chest-xray",
+        is_vision=True,
+        predict_fn=run_cardiomegaly_inference,
+        attention_map_fn=run_cardiomegaly_attention_map,
+    ),
+    "pleural_effusion_binary_classification": ModelInfo(
+        model_id="pleural_effusion_binary_classification",
+        task="P_vs_notP",
+        vertical="medical/pathovision/chest-xray",
+        is_vision=True,
+        predict_fn=run_pleuraleffusion_inference,
+        attention_map_fn=run_pleuraleffusion_attention_map,
+    ),
+    "pleural_thickening_binary_classification": ModelInfo(
+        model_id="pleural_thickening_binary_classification",
+        task="P_vs_notP",
+        vertical="medical/pathovision/chest-xray",
+        is_vision=True,
+        predict_fn=run_pleuralthickening_inference,
+        attention_map_fn=run_pleuralthickening_attention_map,
+    ),
+    "aortic_enlargement_binary_classification": ModelInfo(
+        model_id="aortic_enlargement_binary_classification",
+        task="P_vs_notP",
+        vertical="medical/pathovision/chest-xray",
+        is_vision=True,
+        predict_fn=run_aorticenlargement_inference,
+        attention_map_fn=run_aorticenlargement_attention_map,
+    ),
+    "tuberculosis_binary_classification": ModelInfo(
+        model_id="tuberculosis_binary_classification",
+        task="P_vs_notP",
+        vertical="medical/pathovision/chest-xray",
+        is_vision=True,
+        predict_fn=run_tuberculosis_inference,
+        attention_map_fn=run_tuberculosis_attention_map,
+    ),
+    "brain_mri_tumor_binary_classification": ModelInfo(
+        model_id="brain_mri_tumor_binary_classification",
+        task="P_vs_notP",
+        vertical="medical/pathovision/brain-mri",
+        is_vision=True,
+        predict_fn=run_brainmri_inference,
+        attention_map_fn=run_brainmri_attention_map,
+    ),
+}
+
+__all__ = ["MODELS_REGISTRY", "ModelInfo"]

pnotp_api/pathovision_bridge.py

@@ -0,0 +1,463 @@
+"""Thin adapter that reuses PathoVision inference code."""
+from __future__ import annotations
+
+import asyncio
+import base64
+import io
+import os
+import re
+import sys
+from typing import Any, Dict, Optional
+
+from PIL import Image, UnidentifiedImageError
+
+# Location of the existing PathoVision checkout.
+PATHOVISION_ROOT = os.environ.get("PATHOVISION_ROOT", os.path.expanduser("~/Desktop/PathoVision"))
+
+
+def _ensure_pathovision_on_path() -> None:
+    if PATHOVISION_ROOT and PATHOVISION_ROOT not in sys.path:
+        sys.path.insert(0, PATHOVISION_ROOT)
+
+
+_ensure_pathovision_on_path()
+
+# Import PathoVision modules lazily but surface any import issue early.
+_PNEUMONIA_IMPORT_ERROR: Optional[Exception] = None
+_CARDIOMEGALY_IMPORT_ERROR: Optional[Exception] = None
+_PLEURALEFFUSION_IMPORT_ERROR: Optional[Exception] = None
+_PLEURALTHICKENING_IMPORT_ERROR: Optional[Exception] = None
+_AORTICENLARGEMENT_IMPORT_ERROR: Optional[Exception] = None
+_TUBERCULOSIS_IMPORT_ERROR: Optional[Exception] = None
+_BRAINMRI_IMPORT_ERROR: Optional[Exception] = None
+
+try:  # pragma: no cover - depends on local environment
+    from main_chestxray_pneumonia import (  # type: ignore
+        MAX_UPLOAD_BYTES as _PNEUMONIA_MAX_BYTES,
+        TTA_ALLOWED as _PNEUMONIA_TTA_ALLOWED,
+        _PneumoniaEnsembleSingleton,
+    )
+except Exception as exc:  # pragma: no cover
+    _PNEUMONIA_IMPORT_ERROR = exc
+    _PNEUMONIA_MAX_BYTES = 10 * 1024 * 1024  # sensible fallback
+    _PNEUMONIA_TTA_ALLOWED = False
+
+try:  # pragma: no cover
+    from main_chestxray_cardiomegaly import (  # type: ignore
+        MAX_UPLOAD_BYTES as _CARDIOMEGALY_MAX_BYTES,
+        TTA_ALLOWED as _CARDIOMEGALY_TTA_ALLOWED,
+        _CardiomegalyEnsembleSingleton,
+    )
+except Exception as exc:  # pragma: no cover
+    _CARDIOMEGALY_IMPORT_ERROR = exc
+    _CARDIOMEGALY_MAX_BYTES = 10 * 1024 * 1024
+    _CARDIOMEGALY_TTA_ALLOWED = False
+
+try:  # pragma: no cover
+    from main_chestxray_pleuraleffusion import (  # type: ignore
+        MAX_UPLOAD_BYTES as _PLEURALEFFUSION_MAX_BYTES,
+        TTA_ALLOWED as _PLEURALEFFUSION_TTA_ALLOWED,
+        _PleuralEffusionEnsembleSingleton,
+    )
+except Exception as exc:  # pragma: no cover
+    _PLEURALEFFUSION_IMPORT_ERROR = exc
+    _PLEURALEFFUSION_MAX_BYTES = 10 * 1024 * 1024
+    _PLEURALEFFUSION_TTA_ALLOWED = False
+
+try:  # pragma: no cover
+    from main_chestxray_pleuralthickening import (  # type: ignore
+        MAX_UPLOAD_BYTES as _PLEURALTHICKENING_MAX_BYTES,
+        TTA_ALLOWED as _PLEURALTHICKENING_TTA_ALLOWED,
+        _PleuralThickeningEnsembleSingleton,
+    )
+except Exception as exc:  # pragma: no cover
+    _PLEURALTHICKENING_IMPORT_ERROR = exc
+    _PLEURALTHICKENING_MAX_BYTES = 10 * 1024 * 1024
+    _PLEURALTHICKENING_TTA_ALLOWED = False
+
+try:  # pragma: no cover
+    from main_chestxray_aorticenlargement import (  # type: ignore
+        MAX_UPLOAD_BYTES as _AORTICENLARGEMENT_MAX_BYTES,
+        TTA_ALLOWED as _AORTICENLARGEMENT_TTA_ALLOWED,
+        _AorticEnlargementEnsembleSingleton,
+    )
+except Exception as exc:  # pragma: no cover
+    _AORTICENLARGEMENT_IMPORT_ERROR = exc
+    _AORTICENLARGEMENT_MAX_BYTES = 10 * 1024 * 1024
+    _AORTICENLARGEMENT_TTA_ALLOWED = False
+
+try:  # pragma: no cover
+    from main_chestxray_tuberculosis import (  # type: ignore
+        MAX_UPLOAD_BYTES as _TUBERCULOSIS_MAX_BYTES,
+        TTA_ALLOWED as _TUBERCULOSIS_TTA_ALLOWED,
+        _TuberculosisEnsembleSingleton,
+    )
+except Exception as exc:  # pragma: no cover
+    _TUBERCULOSIS_IMPORT_ERROR = exc
+    _TUBERCULOSIS_MAX_BYTES = 10 * 1024 * 1024
+    _TUBERCULOSIS_TTA_ALLOWED = False
+
+try:  # pragma: no cover
+    from main_brainmri import (  # type: ignore
+        MAX_UPLOAD_BYTES as _BRAINMRI_MAX_BYTES,
+        TTA_ALLOWED as _BRAINMRI_TTA_ALLOWED,
+        _BrainMRIEnsembleSingleton,
+    )
+except Exception as exc:  # pragma: no cover
+    _BRAINMRI_IMPORT_ERROR = exc
+    _BRAINMRI_MAX_BYTES = 10 * 1024 * 1024
+    _BRAINMRI_TTA_ALLOWED = False
+
+
+def _ensure_pneumonia_ready() -> None:
+    if _PNEUMONIA_IMPORT_ERROR is not None:
+        raise RuntimeError(
+            "PathoVision pneumonia module could not be imported. "
+            "Set PATHOVISION_ROOT to the PathoVision checkout and ensure dependencies are installed."
+        ) from _PNEUMONIA_IMPORT_ERROR
+
+
+def _ensure_cardiomegaly_ready() -> None:
+    if _CARDIOMEGALY_IMPORT_ERROR is not None:
+        raise RuntimeError("Cardiomegaly module import failed.") from _CARDIOMEGALY_IMPORT_ERROR
+
+
+def _ensure_pleuraleffusion_ready() -> None:
+    if _PLEURALEFFUSION_IMPORT_ERROR is not None:
+        raise RuntimeError("Pleural effusion module import failed.") from _PLEURALEFFUSION_IMPORT_ERROR
+
+
+def _ensure_pleuralthickening_ready() -> None:
+    if _PLEURALTHICKENING_IMPORT_ERROR is not None:
+        raise RuntimeError("Pleural thickening module import failed.") from _PLEURALTHICKENING_IMPORT_ERROR
+
+
+def _ensure_aorticenlargement_ready() -> None:
+    if _AORTICENLARGEMENT_IMPORT_ERROR is not None:
+        raise RuntimeError("Aortic enlargement module import failed.") from _AORTICENLARGEMENT_IMPORT_ERROR
+
+
+def _ensure_tuberculosis_ready() -> None:
+    if _TUBERCULOSIS_IMPORT_ERROR is not None:
+        raise RuntimeError("Tuberculosis module import failed.") from _TUBERCULOSIS_IMPORT_ERROR
+
+
+def _ensure_brainmri_ready() -> None:
+    if _BRAINMRI_IMPORT_ERROR is not None:
+        raise RuntimeError("Brain MRI module import failed.") from _BRAINMRI_IMPORT_ERROR
+
+
+def _decode_data_uri(data_uri: str) -> Optional[bytes]:
+    """Decodes ``data:*;base64`` payloads emitted by PathoVision explainability helpers."""
+    match = re.match(r"^data:(?P<mime>[-\w./+]+);base64,(?P<data>.+)$", data_uri)
+    if not match:
+        return None
+    payload = match.group("data")
+    try:
+        return base64.b64decode(payload, validate=True)
+    except Exception:  # pragma: no cover
+        return None
+
+
+def _load_image_from_bytes(data: bytes) -> Image.Image:
+    if not data:
+        raise ValueError("Uploaded file is empty.")
+    try:
+        return Image.open(io.BytesIO(data)).convert("RGB")
+    except UnidentifiedImageError as exc:
+        raise ValueError("Uploaded file is not a valid image.") from exc
+    except Exception as exc:  # pragma: no cover
+        raise ValueError(f"Failed to read image: {exc}") from exc
+
+
+async def run_pneumonia_inference(
+    image_bytes: bytes,
+    *,
+    use_tta: bool = True,
+    explain: bool = False,
+) -> Dict[str, Any]:
+    """
+    Runs the PathoVision pneumonia ensemble and returns the raw classification report.
+    """
+
+    def _run() -> Dict[str, Any]:
+        _ensure_pneumonia_ready()
+        if len(image_bytes) > _PNEUMONIA_MAX_BYTES:
+            raise ValueError("File too large. Max size is 10MB.")
+        image = _load_image_from_bytes(image_bytes)
+        ensemble = _PneumoniaEnsembleSingleton.get()
+        result = ensemble.predict(image, use_tta=use_tta and _PNEUMONIA_TTA_ALLOWED, explain=explain)
+
+        ctx = getattr(ensemble, "context", {})
+        config = ctx.get("config", {}) if isinstance(ctx, dict) else {}
+        task_id = None
+        if isinstance(config, dict):
+            task_id = config.get("task")
+        model_version = task_id or ctx.get("task") if isinstance(ctx, dict) else None
+
+        enriched: Dict[str, Any] = dict(result)
+        if task_id:
+            enriched.setdefault("task", task_id)
+        enriched.setdefault("model_version", model_version or "pv-chestxray-pneumonia")
+        return enriched
+
+    return await asyncio.to_thread(_run)
+
+
+async def run_pneumonia_attention_map(image_bytes: bytes) -> bytes:
+    """
+    Generates an attention/Grad-CAM style map for pneumonia as PNG bytes.
+    """
+
+    def _run() -> bytes:
+        _ensure_pneumonia_ready()
+        if len(image_bytes) > _PNEUMONIA_MAX_BYTES:
+            raise ValueError("File too large. Max size is 10MB.")
+        image = _load_image_from_bytes(image_bytes)
+        ensemble = _PneumoniaEnsembleSingleton.get()
+        result = ensemble.predict(image, use_tta=False, explain=True)
+
+        data_uri_candidates = []
+        explanation_url = result.get("explanation_url")
+        if explanation_url:
+            data_uri_candidates.append(explanation_url)
+
+        explanations = result.get("explanations")
+        if explanations is not None:
+            primary = getattr(explanations, "primary", None)
+            auxiliary = getattr(explanations, "auxiliary", None)
+            if primary is not None and getattr(primary, "url", None):
+                data_uri_candidates.append(primary.url)
+            if auxiliary is not None and getattr(auxiliary, "url", None):
+                data_uri_candidates.append(auxiliary.url)
+
+        for data_uri in data_uri_candidates:
+            decoded = _decode_data_uri(data_uri)
+            if decoded:
+                return decoded
+
+        raise RuntimeError("Attention map could not be generated for this image.")
+
+    return await asyncio.to_thread(_run)
+
+
+async def run_cardiomegaly_inference(image_bytes: bytes, *, use_tta: bool = True, explain: bool = False) -> Dict[str, Any]:
+    def _run() -> Dict[str, Any]:
+        _ensure_cardiomegaly_ready()
+        if len(image_bytes) > _CARDIOMEGALY_MAX_BYTES:
+            raise ValueError("File too large. Max size is 10MB.")
+        image = _load_image_from_bytes(image_bytes)
+        ensemble = _CardiomegalyEnsembleSingleton.get()
+        result = ensemble.predict(image, use_tta=use_tta and _CARDIOMEGALY_TTA_ALLOWED, explain=explain)
+        result = dict(result)
+        result.setdefault("model_version", "pv-chestxray-cardiomegaly")
+        return result
+
+    return await asyncio.to_thread(_run)
+
+
+async def run_cardiomegaly_attention_map(image_bytes: bytes) -> bytes:
+    def _run() -> bytes:
+        _ensure_cardiomegaly_ready()
+        if len(image_bytes) > _CARDIOMEGALY_MAX_BYTES:
+            raise ValueError("File too large. Max size is 10MB.")
+        image = _load_image_from_bytes(image_bytes)
+        ensemble = _CardiomegalyEnsembleSingleton.get()
+        result = ensemble.predict(image, use_tta=False, explain=True)
+        for candidate in [result.get("explanation_url"), getattr(getattr(result.get("explanations"), "primary", None), "url", None),
+                          getattr(getattr(result.get("explanations"), "auxiliary", None), "url", None)]:
+            if candidate:
+                decoded = _decode_data_uri(candidate)
+                if decoded:
+                    return decoded
+        raise RuntimeError("Attention map could not be generated for this image.")
+
+    return await asyncio.to_thread(_run)
+
+
+async def run_pleuraleffusion_inference(image_bytes: bytes, *, use_tta: bool = True, explain: bool = False) -> Dict[str, Any]:
+    def _run() -> Dict[str, Any]:
+        _ensure_pleuraleffusion_ready()
+        if len(image_bytes) > _PLEURALEFFUSION_MAX_BYTES:
+            raise ValueError("File too large. Max size is 10MB.")
+        image = _load_image_from_bytes(image_bytes)
+        ensemble = _PleuralEffusionEnsembleSingleton.get()
+        result = ensemble.predict(image, use_tta=use_tta and _PLEURALEFFUSION_TTA_ALLOWED, explain=explain)
+        result = dict(result)
+        result.setdefault("model_version", "pv-chestxray-pleuraleffusion")
+        return result
+
+    return await asyncio.to_thread(_run)
+
+
+async def run_pleuraleffusion_attention_map(image_bytes: bytes) -> bytes:
+    def _run() -> bytes:
+        _ensure_pleuraleffusion_ready()
+        if len(image_bytes) > _PLEURALEFFUSION_MAX_BYTES:
+            raise ValueError("File too large. Max size is 10MB.")
+        image = _load_image_from_bytes(image_bytes)
+        ensemble = _PleuralEffusionEnsembleSingleton.get()
+        result = ensemble.predict(image, use_tta=False, explain=True)
+        for candidate in [result.get("explanation_url"), getattr(getattr(result.get("explanations"), "primary", None), "url", None),
+                          getattr(getattr(result.get("explanations"), "auxiliary", None), "url", None)]:
+            if candidate:
+                decoded = _decode_data_uri(candidate)
+                if decoded:
+                    return decoded
+        raise RuntimeError("Attention map could not be generated for this image.")
+
+    return await asyncio.to_thread(_run)
+
+
+async def run_pleuralthickening_inference(image_bytes: bytes, *, use_tta: bool = True, explain: bool = False) -> Dict[str, Any]:
+    def _run() -> Dict[str, Any]:
+        _ensure_pleuralthickening_ready()
+        if len(image_bytes) > _PLEURALTHICKENING_MAX_BYTES:
+            raise ValueError("File too large. Max size is 10MB.")
+        image = _load_image_from_bytes(image_bytes)
+        ensemble = _PleuralThickeningEnsembleSingleton.get()
+        result = ensemble.predict(image, use_tta=use_tta and _PLEURALTHICKENING_TTA_ALLOWED, explain=explain)
+        result = dict(result)
+        result.setdefault("model_version", "pv-chestxray-pleuralthickening")
+        return result
+
+    return await asyncio.to_thread(_run)
+
+
+async def run_pleuralthickening_attention_map(image_bytes: bytes) -> bytes:
+    def _run() -> bytes:
+        _ensure_pleuralthickening_ready()
+        if len(image_bytes) > _PLEURALTHICKENING_MAX_BYTES:
+            raise ValueError("File too large. Max size is 10MB.")
+        image = _load_image_from_bytes(image_bytes)
+        ensemble = _PleuralThickeningEnsembleSingleton.get()
+        result = ensemble.predict(image, use_tta=False, explain=True)
+        for candidate in [result.get("explanation_url"), getattr(getattr(result.get("explanations"), "primary", None), "url", None),
+                          getattr(getattr(result.get("explanations"), "auxiliary", None), "url", None)]:
+            if candidate:
+                decoded = _decode_data_uri(candidate)
+                if decoded:
+                    return decoded
+        raise RuntimeError("Attention map could not be generated for this image.")
+
+    return await asyncio.to_thread(_run)
+
+
+async def run_aorticenlargement_inference(image_bytes: bytes, *, use_tta: bool = True, explain: bool = False) -> Dict[str, Any]:
+    def _run() -> Dict[str, Any]:
+        _ensure_aorticenlargement_ready()
+        if len(image_bytes) > _AORTICENLARGEMENT_MAX_BYTES:
+            raise ValueError("File too large. Max size is 10MB.")
+        image = _load_image_from_bytes(image_bytes)
+        ensemble = _AorticEnlargementEnsembleSingleton.get()
+        result = ensemble.predict(image, use_tta=use_tta and _AORTICENLARGEMENT_TTA_ALLOWED, explain=explain)
+        result = dict(result)
+        result.setdefault("model_version", "pv-chestxray-aorticenlargement")
+        return result
+
+    return await asyncio.to_thread(_run)
+
+
+async def run_aorticenlargement_attention_map(image_bytes: bytes) -> bytes:
+    def _run() -> bytes:
+        _ensure_aorticenlargement_ready()
+        if len(image_bytes) > _AORTICENLARGEMENT_MAX_BYTES:
+            raise ValueError("File too large. Max size is 10MB.")
+        image = _load_image_from_bytes(image_bytes)
+        ensemble = _AorticEnlargementEnsembleSingleton.get()
+        result = ensemble.predict(image, use_tta=False, explain=True)
+        for candidate in [result.get("explanation_url"), getattr(getattr(result.get("explanations"), "primary", None), "url", None),
+                          getattr(getattr(result.get("explanations"), "auxiliary", None), "url", None)]:
+            if candidate:
+                decoded = _decode_data_uri(candidate)
+                if decoded:
+                    return decoded
+        raise RuntimeError("Attention map could not be generated for this image.")
+
+    return await asyncio.to_thread(_run)
+
+
+async def run_tuberculosis_inference(image_bytes: bytes, *, use_tta: bool = True, explain: bool = False) -> Dict[str, Any]:
+    def _run() -> Dict[str, Any]:
+        _ensure_tuberculosis_ready()
+        if len(image_bytes) > _TUBERCULOSIS_MAX_BYTES:
+            raise ValueError("File too large. Max size is 10MB.")
+        image = _load_image_from_bytes(image_bytes)
+        ensemble = _TuberculosisEnsembleSingleton.get()
+        result = ensemble.predict(image, use_tta=use_tta and _TUBERCULOSIS_TTA_ALLOWED, explain=explain)
+        result = dict(result)
+        result.setdefault("model_version", "pv-chestxray-tuberculosis")
+        return result
+
+    return await asyncio.to_thread(_run)
+
+
+async def run_tuberculosis_attention_map(image_bytes: bytes) -> bytes:
+    def _run() -> bytes:
+        _ensure_tuberculosis_ready()
+        if len(image_bytes) > _TUBERCULOSIS_MAX_BYTES:
+            raise ValueError("File too large. Max size is 10MB.")
+        image = _load_image_from_bytes(image_bytes)
+        ensemble = _TuberculosisEnsembleSingleton.get()
+        result = ensemble.predict(image, use_tta=False, explain=True)
+        for candidate in [result.get("explanation_url"), getattr(getattr(result.get("explanations"), "primary", None), "url", None),
+                          getattr(getattr(result.get("explanations"), "auxiliary", None), "url", None)]:
+            if candidate:
+                decoded = _decode_data_uri(candidate)
+                if decoded:
+                    return decoded
+        raise RuntimeError("Attention map could not be generated for this image.")
+
+    return await asyncio.to_thread(_run)
+
+
+async def run_brainmri_inference(image_bytes: bytes, *, use_tta: bool = True, explain: bool = False) -> Dict[str, Any]:
+    def _run() -> Dict[str, Any]:
+        _ensure_brainmri_ready()
+        if len(image_bytes) > _BRAINMRI_MAX_BYTES:
+            raise ValueError("File too large. Max size is 10MB.")
+        image = _load_image_from_bytes(image_bytes)
+        ensemble = _BrainMRIEnsembleSingleton.get()
+        result = ensemble.predict(image, use_tta=use_tta and _BRAINMRI_TTA_ALLOWED, explain=explain)
+        result = dict(result)
+        result.setdefault("model_version", "pv-brainmri-tumorclassification")
+        return result
+
+    return await asyncio.to_thread(_run)
+
+
+async def run_brainmri_attention_map(image_bytes: bytes) -> bytes:
+    def _run() -> bytes:
+        _ensure_brainmri_ready()
+        if len(image_bytes) > _BRAINMRI_MAX_BYTES:
+            raise ValueError("File too large. Max size is 10MB.")
+        image = _load_image_from_bytes(image_bytes)
+        ensemble = _BrainMRIEnsembleSingleton.get()
+        result = ensemble.predict(image, use_tta=False, explain=True)
+        for candidate in [result.get("explanation_url"), getattr(getattr(result.get("explanations"), "primary", None), "url", None),
+                          getattr(getattr(result.get("explanations"), "auxiliary", None), "url", None)]:
+            if candidate:
+                decoded = _decode_data_uri(candidate)
+                if decoded:
+                    return decoded
+        raise RuntimeError("Attention map could not be generated for this image.")
+
+    return await asyncio.to_thread(_run)
+
+
+__all__ = [
+    "run_pneumonia_inference",
+    "run_pneumonia_attention_map",
+    "run_cardiomegaly_inference",
+    "run_cardiomegaly_attention_map",
+    "run_pleuraleffusion_inference",
+    "run_pleuraleffusion_attention_map",
+    "run_pleuralthickening_inference",
+    "run_pleuralthickening_attention_map",
+    "run_aorticenlargement_inference",
+    "run_aorticenlargement_attention_map",
+    "run_tuberculosis_inference",
+    "run_tuberculosis_attention_map",
+    "run_brainmri_inference",
+    "run_brainmri_attention_map",
+]

pnotp_api/schemas.py

@@ -0,0 +1,22 @@
+"""Shared Pydantic schemas for the PnotP API."""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel
+
+
+class PredictionResult(BaseModel):
+    """Normalized binary classification response."""
+
+    task: str
+    positive_prob: float
+    negative_prob: float
+    prediction: bool
+    threshold: float
+    model_version: str
+    metadata: Optional[Dict[str, Any]] = None
+
+
+__all__ = ["PredictionResult"]
+

pnotp_api/security.py

@@ -0,0 +1,40 @@
+"""API-key authentication for the PnotP API."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from fastapi import Header, HTTPException, status
+
+from .db import get_api_key, touch_api_key_usage
+
+
+@dataclass
+class ApiKeyInfo:
+    user_external_id: str
+    plan_code: str
+    key_prefix: str
+
+
+async def require_api_key(x_api_key: str = Header(..., alias="X-API-Key")) -> ApiKeyInfo:
+    """
+    Validates the ``X-API-Key`` header against the DB.
+    """
+    record = get_api_key(x_api_key)
+    if record is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or missing API key",
+        )
+    try:
+        touch_api_key_usage(x_api_key)
+    except Exception:
+        # Best-effort; do not block requests if bookkeeping fails.
+        pass
+    return ApiKeyInfo(
+        user_external_id=record["user_external_id"],
+        plan_code=record["plan_code"],
+        key_prefix=record["key_prefix"],
+    )
+
+
+__all__ = ["require_api_key", "ApiKeyInfo"]