feat(uniprot,domains): reviewed/organism search filters + ScanProsite raw-sequence motif scan (3c,3d)

app/routers/domains.py

@@ -15,7 +15,8 @@ Provides comprehensive protein feature analysis:
   - Combined analysis endpoint
 """
 from fastapi import APIRouter, HTTPException
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
+from app.config import settings
 from app.tools.domain_analysis import (
     _sanitize,
     fetch_interpro_domains,
@@ -31,6 +32,7 @@ from app.tools.domain_analysis import (
     extract_go_terms,
     extract_pathways,
     full_analysis,
+    scan_prosite_sequence,
 )
 
 router = APIRouter(prefix="/api/domains", tags=["domains"])
@@ -278,6 +280,38 @@ async def get_all_features(accession: str):
     return FullAnalysisResponse(**result)
 
 
+# ---------------------------------------------------------------------------
+# ScanProsite — raw-sequence motif scanning
+# ---------------------------------------------------------------------------
+
+class ScanPrositeRequest(BaseModel):
+    sequence: str = Field(..., min_length=1, description="Raw protein sequence (no FASTA header required)")
+
+
+class ScanPrositeMatch(BaseModel):
+    signature_ac: str
+    name: str = ""
+    start: int
+    stop: int
+    level_tag: str = ""
+
+
+class ScanPrositeResponse(BaseModel):
+    sequence_length: int
+    count: int
+    matches: list[ScanPrositeMatch]
+
+
+@router.post("/scan", response_model=ScanPrositeResponse)
+async def scan_prosite(req: ScanPrositeRequest):
+    """Scan a raw protein sequence against PROSITE signatures (best-effort)."""
+    email = settings.NCBI_EMAIL or ""
+    result = await scan_prosite_sequence(req.sequence, email)
+    if "error" in result:
+        raise HTTPException(status_code=400, detail=result["error"])
+    return ScanPrositeResponse(**result)
+
+
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------

app/routers/uniprot.py

@@ -14,6 +14,8 @@ ncbi_service = NCBIService()
 class UniprotSearchRequest(BaseModel):
     query: str = Field(..., min_length=2, description="Free-text search (gene name, protein name, keyword)")
     max_results: int = Field(20, ge=1, le=50)
+    reviewed: bool = Field(False, description="Only Swiss-Prot (reviewed) entries")
+    organism: str = Field("", description="Restrict results to an organism (e.g. Homo sapiens)")
 
 
 class UniprotAccessionRequest(BaseModel):
@@ -27,7 +29,12 @@ class UniprotCDSRequest(BaseModel):
 @router.post("/search")
 async def search_uniprot(req: UniprotSearchRequest):
     url = f"{settings.UNIPROT_BASE_URL}/search"
-    params = {"query": req.query, "format": "json", "size": req.max_results}
+    query = req.query.strip()
+    if req.organism.strip():
+        query = f'{query} AND organism_name:"{req.organism.strip()}"'
+    if req.reviewed:
+        query = f"{query} AND reviewed:true"
+    params = {"query": query, "format": "json", "size": req.max_results}
     async with httpx.AsyncClient(timeout=15) as client:
         resp = await client.get(url, params=params)
         if resp.status_code != 200:
@@ -36,12 +43,14 @@ async def search_uniprot(req: UniprotSearchRequest):
     results = data.get("results", [])
     out = []
     for r in results:
+        entry_type = (r.get("entryType", "") or "").lower()
         out.append({
             "accession": r.get("primaryAccession", ""),
             "name": ((r.get("proteinDescription", {}) or {}).get("recommendedName", {}) or {}).get("fullName", {}).get("value", ""),
             "gene_names": [g.get("geneName", {}).get("value", "") for g in (r.get("genes") or []) if g.get("geneName")],
             "organism": (r.get("organism", {}) or {}).get("scientificName", ""),
             "length": ((r.get("sequence", {}) or {}).get("length", 0)),
+            "reviewed": "reviewed" in entry_type and "unreviewed" not in entry_type,
         })
     return {"results": out, "count": len(out)}
 

app/tools/domain_analysis.py

@@ -7,19 +7,28 @@ functional sites, PTMs, topology, motifs, variants, GO terms, pathways).
 Provides the shared analysis functions used by both the standalone router
 and the pipeline_v2 orchestrator.
 """
+import hashlib
 import re
 import httpx
 from typing import Any
 
+from app.config import settings
+from app.services.cache import cache_get, cache_set
 
 INTERPRO_API = "https://www.ebi.ac.uk/interpro/api/entry/all/protein/UniProt/{accession}/?format=json&page_size=50"
 UNIPROT_API = "https://rest.uniprot.org/uniprotkb/{accession}.json"
+SCANPROSITE_URL = "https://prosite.expasy.org/cgi-bin/prosite/scanprosite/PSScan.cgi"
+INTERPRO_ENTRY_API = "https://www.ebi.ac.uk/interpro/api/entry/prosite/{signature}/"
 
 
 def _sanitize(s: str) -> str:
     return re.sub(r'[\x00-\x1f\x7f-\x9f]', '', s).strip().upper()
 
 
+def _clean_sequence(sequence: str) -> str:
+    return "".join(c for c in _sanitize(sequence) if c.isalpha())
+
+
 async def fetch_uniprot_raw(accession: str) -> dict:
     """Fetch raw UniProt JSON for an accession."""
     accession = _sanitize(accession)
@@ -384,7 +393,6 @@ def extract_pathways(raw: dict) -> list[dict]:
 # ---------------------------------------------------------------------------
 # 12. Combined Analysis (all features at once)
 # ---------------------------------------------------------------------------
-
 async def full_analysis(accession: str) -> dict:
     """Run all domain/motif analyses for a UniProt accession."""
     accession = _sanitize(accession)
@@ -430,3 +438,71 @@ async def full_analysis(accession: str) -> dict:
             cat: len(items) for cat, items in features.items() if items
         },
     }
+
+
+# ---------------------------------------------------------------------------
+# 13. ScanProsite — raw-sequence motif scan
+# ---------------------------------------------------------------------------
+
+def _signature_cache_key(signature_ac: str) -> str:
+    return f"prosite_signature_name:{hashlib.sha256(signature_ac.encode()).hexdigest()[:16]}"
+
+
+async def _prosite_signature_name(signature_ac: str) -> str:
+    """Best-effort PROSITE signature name resolution via InterPro (cached)."""
+    cached = cache_get(_signature_cache_key(signature_ac))
+    if cached is not None:
+        return cached
+    name = ""
+    try:
+        async with httpx.AsyncClient(timeout=15) as client:
+            resp = await client.get(INTERPRO_ENTRY_API.format(signature=signature_ac))
+            if resp.status_code == 200:
+                md = resp.json().get("metadata") or {}
+                nm = md.get("name") or {}
+                name = str(nm.get("name") or "")
+    except Exception:
+        pass
+    if name:
+        cache_set(_signature_cache_key(signature_ac), name, ttl=86400)
+    return name
+
+
+async def scan_prosite_sequence(sequence: str, email: str = "") -> dict:
+    """Scan a raw protein sequence against PROSITE signatures.
+
+    Contract verified live (2026-08-03): POST the sequence to ScanProsite with
+    ``output=json``; the response is ``{"n_match", "n_seq", "matchset": [...]}``
+    where each match has ``sequence_ac``/``start``/``stop``/``signature_ac``/
+    ``level_tag``. Returns ``{"sequence_length", "count", "matches"}``.
+    """
+    clean = _clean_sequence(sequence)
+    if len(clean) < 10:
+        return {"error": "Sequence too short (min 10 amino acids)"}
+
+    async with httpx.AsyncClient(timeout=60) as client:
+        resp = await client.post(
+            SCANPROSITE_URL,
+            data={"seq": clean, "output": "json", "email": email or "bioflow@example.com"},
+        )
+        if resp.status_code != 200:
+            return {"error": f"ScanProsite returned HTTP {resp.status_code}"}
+        data = resp.json()
+
+    matchset = data.get("matchset") or []
+    matches: list[dict] = []
+    for m in matchset:
+        signature_ac = str(m.get("signature_ac", ""))
+        matches.append({
+            "signature_ac": signature_ac,
+            "name": await _prosite_signature_name(signature_ac),
+            "start": int(m.get("start", 0)),
+            "stop": int(m.get("stop", 0)),
+            "level_tag": str(m.get("level_tag", "")),
+        })
+
+    return {
+        "sequence_length": len(clean),
+        "count": len(matches),
+        "matches": matches,
+    }

app/tools/uniprot.py

@@ -21,6 +21,7 @@ class UniprotTool(BaseTool):
 
         return {
             "accession": data.get("primaryAccession", ""),
+            "reviewed": "reviewed" in (data.get("entryType", "") or "").lower() and "unreviewed" not in (data.get("entryType", "") or "").lower(),
             "full_name": self._extract_name(data),
             "ec_number": (data.get("proteinDescription", {}) or {}).get("ecNumbers", [{}])[0].get("ecNumber", "") if data.get("proteinDescription") else "",
             "gene_names": [g.get("geneName", {}).get("value", "") for g in (data.get("genes") or []) if g.get("geneName")],

tests/test_scanprosite.py

@@ -0,0 +1,127 @@
+"""
+Tests for 3d ScanProsite raw-sequence motif scanning:
+
+- scan_prosite_sequence parses the verified ScanProsite JSON contract
+- short sequences return a clear error
+- empty matchset -> count 0
+- POST /api/domains/scan router: success + 400 on short sequence
+
+Network calls are mocked; these run fully offline.
+"""
+
+import pytest
+from fastapi import HTTPException
+
+from app.tools import domain_analysis as da
+from app.routers import domains as domains_router
+from app.routers.domains import ScanPrositeRequest, scan_prosite
+
+
+class FakeResp:
+    def __init__(self, status_code, json_data):
+        self.status_code = status_code
+        self._json = json_data
+
+    def json(self):
+        return self._json
+
+
+class FakeClient:
+    def __init__(self, *args, **kwargs):
+        self.calls = []
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        return None
+
+    async def post(self, url, data=None, **kwargs):
+        self.calls.append((url, data))
+        return FakeResp(200, {
+            "n_match": 1,
+            "n_seq": 1,
+            "matchset": [
+                {"sequence_ac": "USERSEQ1", "start": 237, "stop": 249,
+                 "signature_ac": "PS00348", "level_tag": "(0)"},
+            ],
+        })
+
+
+class TestScanPrositeSequence:
+    @pytest.mark.asyncio
+    async def test_parses_json_contract(self, monkeypatch):
+        fake = FakeClient()
+        monkeypatch.setattr(da.httpx, "AsyncClient", lambda *a, **k: fake)
+        monkeypatch.setattr(da, "_prosite_signature_name",
+                            lambda sig: _fake_name(sig))
+
+        seq = "M" * 250
+        result = await da.scan_prosite_sequence(seq)
+        assert result["sequence_length"] == 250
+        assert result["count"] == 1
+        m = result["matches"][0]
+        assert m["signature_ac"] == "PS00348"
+        assert m["start"] == 237 and m["stop"] == 249
+        assert m["name"] == "p53 family signature"
+
+    @pytest.mark.asyncio
+    async def test_empty_matchset(self, monkeypatch):
+        class FakeClientEmpty(FakeClient):
+            async def post(self, url, data=None, **kwargs):
+                self.calls.append((url, data))
+                return FakeResp(200, {"n_match": 0, "n_seq": 1})
+
+        monkeypatch.setattr(da.httpx, "AsyncClient", lambda *a, **k: FakeClientEmpty())
+        result = await da.scan_prosite_sequence("M" * 50)
+        assert result["count"] == 0
+        assert result["matches"] == []
+
+    @pytest.mark.asyncio
+    async def test_short_sequence_rejected(self):
+        result = await da.scan_prosite_sequence("MEEPQ")
+        assert "error" in result
+        assert "too short" in result["error"]
+
+    @pytest.mark.asyncio
+    async def test_http_error(self, monkeypatch):
+        class FakeClientFail(FakeClient):
+            async def post(self, url, data=None, **kwargs):
+                return FakeResp(500, {})
+
+        monkeypatch.setattr(da.httpx, "AsyncClient", lambda *a, **k: FakeClientFail())
+        result = await da.scan_prosite_sequence("M" * 50)
+        assert "error" in result
+        assert "HTTP 500" in result["error"]
+
+
+class TestScanPrositeEndpoint:
+    @pytest.mark.asyncio
+    async def test_success(self, monkeypatch):
+        async def fake_scan(sequence, email=""):
+            assert email == "bioflow@example.com"
+            return {"sequence_length": 10, "count": 1, "matches": [
+                {"signature_ac": "PS00001", "name": "N-glycosylation site",
+                 "start": 2, "stop": 5, "level_tag": "(0)"},
+            ]}
+
+        monkeypatch.setattr(domains_router, "scan_prosite_sequence", fake_scan)
+        resp = await scan_prosite(ScanPrositeRequest(sequence="MEEPQSDPSV"))
+        assert resp.sequence_length == 10
+        assert resp.count == 1
+        assert resp.matches[0].name == "N-glycosylation site"
+
+    @pytest.mark.asyncio
+    async def test_short_sequence_400(self, monkeypatch):
+        async def fake_scan(sequence, email=""):
+            return {"error": "Sequence too short (min 10 amino acids)"}
+
+        monkeypatch.setattr(domains_router, "scan_prosite_sequence", fake_scan)
+        with pytest.raises(HTTPException) as exc:
+            await scan_prosite(ScanPrositeRequest(sequence="MEEPQ"))
+        assert exc.value.status_code == 400
+        assert "too short" in exc.value.detail
+
+
+async def _fake_name(sig: str) -> str:
+    return "p53 family signature"

tests/test_uniprot_search.py

@@ -0,0 +1,107 @@
+"""
+Tests for 3c UniProt search polish:
+
+- reviewed/organism filters are folded into the UniProt query string
+- search results carry a `reviewed` flag derived from entryType
+
+Network calls are mocked; these run fully offline.
+"""
+
+import pytest
+from fastapi import HTTPException
+
+from app.routers import uniprot as uniprot_router
+from app.routers.uniprot import UniprotSearchRequest, search_uniprot
+
+
+class FakeResp:
+    def __init__(self, status_code, json_data):
+        self.status_code = status_code
+        self._json = json_data
+
+    def json(self):
+        return self._json
+
+
+class FakeClient:
+    def __init__(self, *args, **kwargs):
+        self.calls = []
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        return None
+
+    async def get(self, url, params=None, **kwargs):
+        self.calls.append((url, params))
+        results = []
+        for i in range(params.get("size", 1)):
+            results.append({
+                "primaryAccession": f"P{i:05d}",
+                "proteinDescription": {"recommendedName": {"fullName": {"value": "Test protein"}}},
+                "genes": [{"geneName": {"value": "TP53"}}],
+                "organism": {"scientificName": "Homo sapiens"},
+                "sequence": {"length": 100},
+                "entryType": "UniProtKB reviewed (Swiss-Prot)",
+            })
+        return FakeResp(200, {"results": results})
+
+
+@pytest.mark.asyncio
+async def test_reviewed_and_organism_fold_into_query(monkeypatch):
+    fake = FakeClient()
+    monkeypatch.setattr(uniprot_router.httpx, "AsyncClient", lambda *a, **k: fake)
+    req = UniprotSearchRequest(query="p53", max_results=1, reviewed=True, organism="Homo sapiens")
+    res = await search_uniprot(req)
+    assert res["count"] == 1
+    assert res["results"][0]["reviewed"] is True
+    _, params = fake.calls[0]
+    assert "AND organism_name:\"Homo sapiens\"" in params["query"]
+    assert "AND reviewed:true" in params["query"]
+
+
+@pytest.mark.asyncio
+async def test_no_filters_query_unchanged(monkeypatch):
+    fake = FakeClient()
+    monkeypatch.setattr(uniprot_router.httpx, "AsyncClient", lambda *a, **k: fake)
+    req = UniprotSearchRequest(query="BRCA1")
+    res = await search_uniprot(req)
+    assert res["results"][0]["reviewed"] is True
+    _, params = fake.calls[0]
+    assert params["query"] == "BRCA1"
+
+
+@pytest.mark.asyncio
+async def test_reviewed_flag_false_for_trembl(monkeypatch):
+    class FakeClientTrEmbl(FakeClient):
+        async def get(self, url, params=None, **kwargs):
+            self.calls.append((url, params))
+            return FakeResp(200, {"results": [{
+                "primaryAccession": "A0A1111111",
+                "proteinDescription": {},
+                "genes": [],
+                "organism": {"scientificName": "Unknown"},
+                "sequence": {"length": 50},
+                "entryType": "UniProtKB unreviewed (TrEMBL)",
+            }]})
+
+    fake = FakeClientTrEmbl()
+    monkeypatch.setattr(uniprot_router.httpx, "AsyncClient", lambda *a, **k: fake)
+    req = UniprotSearchRequest(query="hypothetical")
+    res = await search_uniprot(req)
+    assert res["results"][0]["reviewed"] is False
+
+
+@pytest.mark.asyncio
+async def test_search_failure_raises_502(monkeypatch):
+    class FakeClientFail(FakeClient):
+        async def get(self, url, params=None, **kwargs):
+            self.calls.append((url, params))
+            return FakeResp(500, {})
+
+    fake = FakeClientFail()
+    monkeypatch.setattr(uniprot_router.httpx, "AsyncClient", lambda *a, **k: fake)
+    with pytest.raises(HTTPException) as exc:
+        await search_uniprot(UniprotSearchRequest(query="p53"))
+    assert exc.value.status_code == 502