puremethod 0.1.0__py3-none-any.whl

purescholar/client.py

@@ -0,0 +1,380 @@
+"""PureScholar REST v1 adapter (01-purescholar.md).
+
+Read-only (INV-5): the client builds only the GET and POST requests below, none of which
+writes to a corpus. Only `/api/v1/*` routes are called, with the API key (INV-4).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import re
+import time
+import uuid
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime
+from typing import Any
+
+import httpx
+
+from .types import (
+    REQUIRED_SCOPES,
+    AuthError,
+    CallRecord,
+    Citation,
+    CitationRecord,
+    Evidence,
+    Grounded,
+    Identity,
+    NotCitable,
+    NotFound,
+    NoveltyEvidence,
+    PaperRef,
+    PureScholarError,
+    QuotaExhausted,
+    RateLimited,
+    RequestRejected,
+    ServiceUnavailable,
+)
+
+_ENVELOPE = {"citations", "invalid_citations", "insufficient_evidence", "external_added",
+             "lab_evidence", "external_evidence", "notice", "error", "sub_questions",
+             "reasoning_trace", "grounding"}
+_SORTS = ("relevance", "cited", "recent")
+_DOI_RE = re.compile(r"^(?:https?://(?:dx\.)?doi\.org/)?(10\.\d{4,9}/\S+)$", re.IGNORECASE)
+_OPENALEX_RE = re.compile(r"(?:openalex\.org/)?(W\d+)$")
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def _sha256(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _canonical(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def _error_code(response: httpx.Response) -> str | None:
+    """Both shapes: FastAPI `{"detail": {"error": code}}` and `{"error": code}` (API.md)."""
+    try:
+        body = response.json()
+    except ValueError:
+        return None
+    if not isinstance(body, dict):
+        return None
+    detail = body.get("detail")
+    if isinstance(detail, dict) and isinstance(detail.get("error"), str):
+        return str(detail["error"])
+    if isinstance(body.get("error"), str):
+        return str(body["error"])
+    return None
+
+
+class PureScholar:
+    """Built from the configuration (§3, KB-015). Use one instance from one event loop."""
+
+    def __init__(self, api_base: str, api_key: str, *, timeout_s: float = 120.0,
+                 retries: int = 3, transport: httpx.AsyncBaseTransport | None = None,
+                 sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+                 monotonic: Callable[[], float] = time.monotonic) -> None:
+        if not api_key:
+            raise ValueError("an API key is required")
+        self._key = api_key
+        self._retries = retries
+        self._sleep = sleep
+        self._monotonic = monotonic
+        # PURESCHOLAR_API_BASE is an origin; the adapter appends /api/v1 (§3).
+        self._client = httpx.AsyncClient(base_url=api_base.rstrip("/"), transport=transport,
+                                         timeout=timeout_s,
+                                         headers={"Authorization": f"Bearer {api_key}"})
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    # ---- transport ---------------------------------------------------------------------
+
+    def _scrub(self, text: str) -> str:
+        return text.replace(self._key, "[REDACTED]")
+
+    async def _request(self, method: str, route: str, records: list[CallRecord],
+                       body: dict[str, Any] | None = None) -> tuple[dict[str, Any], str]:
+        """One logical request with retries. Returns the JSON body and the final call id."""
+        path = "/api/v1" + route
+        body_text = _canonical(body)
+        delay = 1.0
+        for attempt in range(self._retries + 1):
+            started, t0 = _now(), self._monotonic()
+            call_id = uuid.uuid4().hex
+            response: httpx.Response | None = None
+            error_type: str | None = None
+            try:
+                response = await self._client.request(method, path, json=body)
+            except httpx.TransportError as exc:
+                error_type = f"transport:{type(exc).__name__}"
+            text = self._scrub(response.text) if response is not None else None
+            code = _error_code(response) if response is not None and response.status_code >= 400 \
+                else None
+            if response is not None and response.status_code >= 400:
+                error_type = f"http_{response.status_code}:{code or 'unknown'}"
+            records.append(CallRecord(
+                call_id=call_id, endpoint=f"{method} {path}",
+                request_digest=_sha256(body_text.encode()),
+                response_digest=_sha256(text.encode()) if text is not None else None,
+                status=response.status_code if response is not None else None,
+                started_at=started, duration_ms=int((self._monotonic() - t0) * 1000),
+                service_version=response.headers.get("X-Service-Version") if response else None,
+                quota_remaining=response.headers.get("RateLimit-Remaining") if response else None,
+                error_type=error_type, request_body=body_text, response_body=text))
+            if response is not None and response.status_code < 400:
+                try:
+                    data = response.json()
+                except ValueError:
+                    raise ServiceUnavailable(f"PureScholar {route} returned a non-JSON body",
+                                             list(records)) from None
+                if not isinstance(data, dict):
+                    raise ServiceUnavailable(f"PureScholar {route} returned a non-object body",
+                                             list(records))
+                return data, call_id
+            retryable, wait = self._retry_decision(response, code)
+            if retryable and attempt < self._retries:
+                await self._sleep(wait if wait is not None else delay)
+                delay *= 2
+                continue
+            raise self._error(response, code, records)
+        raise AssertionError("unreachable")
+
+    @staticmethod
+    def _retry_decision(response: httpx.Response | None,
+                        code: str | None) -> tuple[bool, float | None]:
+        if response is None:
+            return True, None
+        if response.status_code == 429 and code != "monthly_quota_exhausted":
+            try:
+                return True, float(response.headers.get("Retry-After", ""))
+            except ValueError:
+                return True, None
+        return response.status_code >= 500, None
+
+    @staticmethod
+    def _error(response: httpx.Response | None, code: str | None,
+               records: list[CallRecord]) -> PureScholarError:
+        if response is None:
+            return ServiceUnavailable("PureScholar unreachable", list(records))
+        status = response.status_code
+        msg = f"PureScholar {status} {code or ''}".strip()
+        if code == "key_orphaned":
+            msg += ": the key's creator left the lab; a lab owner must mint a new key"
+        if status in (401, 403):
+            return AuthError(msg, list(records), code)
+        if status == 404:
+            return NotFound(msg, list(records), code)
+        if status == 429:
+            if code == "monthly_quota_exhausted":
+                return QuotaExhausted(msg, list(records), code)
+            return RateLimited(msg, list(records), code)
+        if status >= 500:
+            return ServiceUnavailable(msg, list(records), code)
+        return RequestRejected(msg, list(records), code)
+
+    async def _call(self, method: str, route: str, body: dict[str, Any] | None,
+                    records: list[CallRecord]) -> tuple[dict[str, Any], str]:
+        try:
+            return await self._request(method, route, records, body)
+        except PureScholarError as exc:
+            exc.records = list(records)
+            raise
+
+    # ---- parsing -----------------------------------------------------------------------
+
+    @staticmethod
+    def _evidence(ch: dict[str, Any]) -> Evidence:
+        return Evidence(marker=str(ch["id"]), paper_id=ch.get("paper_id"),
+                        title=ch.get("title"), authors=list(ch.get("authors") or []),
+                        year=ch.get("year"), venue=ch.get("venue"), section=ch.get("section"),
+                        content=str(ch.get("content") or ""),
+                        source=str(ch.get("source") or "external"), url=ch.get("url"))
+
+    def _grounded(self, data: dict[str, Any], call_id: str,
+                  records: list[CallRecord]) -> Grounded:
+        if data.get("notice"):
+            raise ServiceUnavailable(f"generation disabled upstream: {data['notice']}",
+                                     list(records), "notice")
+        if data.get("error"):
+            raise ServiceUnavailable(f"upstream error: {data['error']}", list(records),
+                                     "upstream_error")
+        try:
+            evidence = [self._evidence(ch) for key in ("lab_evidence", "external_evidence")
+                        for ch in data.get(key) or []]
+            by_marker = {e.marker: e for e in evidence}
+            citations = [Citation(marker=str(c["marker"]), paper_id=c.get("paper_id"),
+                                  title=c.get("title"), url=c.get("url"),
+                                  quartile=c.get("quartile"), conf_rank=c.get("conf_rank"),
+                                  doc_type=c.get("doc_type"), valid=bool(c["valid"]),
+                                  evidence=by_marker.get(str(c["marker"])), call_id=call_id)
+                         for c in data.get("citations") or []]
+            return Grounded(
+                body={k: v for k, v in data.items() if k not in _ENVELOPE},
+                citations=citations,
+                invalid_citations=[str(m) for m in data.get("invalid_citations") or []],
+                insufficient_evidence=bool(data.get("insufficient_evidence", False)),
+                evidence=evidence, grounding=data.get("grounding"),
+                sub_questions=[str(q) for q in data.get("sub_questions") or []],
+                records=list(records))
+        except (KeyError, TypeError, ValueError) as exc:
+            raise ServiceUnavailable(f"unexpected response shape: {type(exc).__name__} {exc}",
+                                     list(records)) from None
+
+    @staticmethod
+    def _paper(w: dict[str, Any], call_id: str) -> PaperRef:
+        return PaperRef(title=w.get("title"), authors=list(w.get("authors") or []),
+                        year=w.get("year"), venue=w.get("venue"), doi=w.get("doi"),
+                        url=w.get("url"), abstract=w.get("abstract"),
+                        cited_by_count=w.get("cited_by_count"), quartile=w.get("quartile"),
+                        conf_rank=w.get("conf_rank"), call_id=call_id)
+
+    # ---- interface ---------------------------------------------------------------------
+
+    async def preflight(self) -> Identity:
+        records: list[CallRecord] = []
+        data, _ = await self._call("GET", "/me", None, records)
+        scopes = [str(s) for s in data.get("scopes") or []]
+        missing = [s for s in REQUIRED_SCOPES if s not in scopes]
+        if missing:
+            raise AuthError(f"the PureScholar key lacks required scopes: {missing}",
+                            list(records), "missing_scope")
+        return Identity(auth=str(data.get("auth")), lab_id=data.get("lab_id"),
+                        lab_name=data.get("lab_name"), scopes=scopes, quota=data.get("quota"),
+                        records=records)
+
+    async def _tool(self, tool: str, text: str) -> Grounded:
+        if not text.strip():
+            raise ValueError("input must not be empty")
+        records: list[CallRecord] = []
+        data, call_id = await self._call("POST", f"/tools/{tool}", {"input": text}, records)
+        return self._grounded(data, call_id, records)
+
+    async def literature_map(self, topic: str) -> Grounded:
+        return await self._tool("literature-map", topic)
+
+    async def find_gaps(self, topic: str) -> Grounded:
+        return await self._tool("gaps", topic)
+
+    async def critique(self, idea: str) -> Grounded:
+        return await self._tool("fixit", idea)
+
+    async def ask(self, question: str, deep: bool = True,
+                  balance: float | None = None) -> Grounded:
+        if not question.strip():
+            raise ValueError("question must not be empty")
+        if balance is not None and not 0.0 <= balance <= 1.0:
+            raise ValueError("balance must be between 0 and 1")
+        body: dict[str, Any] = {"question": question, "deep": deep}
+        if balance is not None:
+            body["balance"] = balance
+        records: list[CallRecord] = []
+        data, call_id = await self._call("POST", "/ask", body, records)
+        return self._grounded(data, call_id, records)
+
+    async def retrieve(self, query: str, k: int = 10) -> tuple[list[Evidence], list[CallRecord]]:
+        if not 1 <= k <= 50:
+            raise ValueError("k must be between 1 and 50")
+        records: list[CallRecord] = []
+        data, _ = await self._call("POST", "/search", {"query": query, "k": k}, records)
+        try:
+            return [self._evidence(ch) for ch in data.get("chunks") or []], records
+        except (KeyError, TypeError) as exc:
+            raise ServiceUnavailable(f"unexpected response shape: {exc}", records) from None
+
+    async def search_papers(self, query: str, from_year: int | None = None,
+                            sort: str = "relevance", limit: int = 15
+                            ) -> tuple[list[PaperRef], list[CallRecord]]:
+        if sort not in _SORTS:
+            raise ValueError(f"sort must be one of {_SORTS}")
+        if not 1 <= limit <= 50:
+            raise ValueError("limit must be between 1 and 50")
+        body: dict[str, Any] = {"query": query, "sort": sort, "limit": limit}
+        if from_year is not None:
+            body["from_year"] = from_year
+        records: list[CallRecord] = []
+        data, call_id = await self._call("POST", "/papers/search", body, records)
+        return [self._paper(w, call_id) for w in data.get("works") or []], records
+
+    async def novelty_evidence(self, hypothesis: str, limit: int = 10) -> NoveltyEvidence:
+        """§5 step 6: papers by relevance, then by citations, then a grounded `ask` on
+        whether those works already test the hypothesis. `loop` makes the judgement."""
+        records: list[CallRecord] = []
+        closest: list[PaperRef] = []
+        seen: set[str] = set()
+        for sort in ("relevance", "cited"):
+            works, recs = await self.search_papers(hypothesis, sort=sort, limit=limit)
+            records.extend(recs)
+            for w in works:
+                ident = (w.doi or w.url or w.title or "").lower()
+                if ident and ident not in seen:
+                    seen.add(ident)
+                    closest.append(w)
+        titles = "; ".join(w.title for w in closest[:limit] if w.title)
+        question = ("Has prior work already tested this hypothesis, or one very close to it? "
+                    f"Hypothesis: {hypothesis}. Candidate prior works: {titles or 'none found'}.")
+        answer = await self.ask(question, deep=True)
+        records.extend(answer.records)
+        return NoveltyEvidence(hypothesis=hypothesis, closest=closest, answer=answer,
+                               records=records)
+
+    @staticmethod
+    def citation_for(item: Citation | PaperRef) -> CitationRecord | NotCitable:
+        """INV-1: only a valid citation matching retrieved evidence, or a paper-search
+        result, and only with a DOI, an OpenAlex ID or a URL."""
+        if isinstance(item, Citation):
+            if not item.valid:
+                return NotCitable("the citation is marked invalid (never retrieved)")
+            if item.evidence is None:
+                return NotCitable("the citation's marker is not in the response's evidence")
+            ev = item.evidence
+            ident = _identifier(item.paper_id, item.url or ev.url)
+            if ident is None:
+                return NotCitable("no DOI, OpenAlex ID or URL (an uploaded file is not "
+                                  "resolvable outside the lab)")
+            kind, value = ident
+            return CitationRecord(
+                key=_cite_key(ev.authors, ev.year, value), id_kind=kind, id=value,
+                title=item.title or ev.title, authors=list(ev.authors), year=ev.year,
+                venue=ev.venue, url=item.url or ev.url, source=ev.source,
+                evidence_markers=[item.marker], excerpts=[ev.content] if ev.content else [],
+                call_id=item.call_id)
+        ident = _identifier(item.doi, item.url)
+        if ident is None:
+            return NotCitable("the paper has no DOI, OpenAlex ID or URL")
+        kind, value = ident
+        return CitationRecord(key=_cite_key(item.authors, item.year, value), id_kind=kind,
+                              id=value, title=item.title, authors=list(item.authors),
+                              year=item.year, venue=item.venue, url=item.url,
+                              source="external", evidence_markers=[], excerpts=[],
+                              call_id=item.call_id)
+
+
+def _identifier(primary: str | None, url: str | None) -> tuple[Any, str] | None:
+    """DOI if there is one, otherwise an OpenAlex ID, otherwise the URL (§5 step 7)."""
+    for candidate in (primary, url):
+        if candidate:
+            m = _DOI_RE.match(candidate.strip())
+            if m:
+                return "doi", m.group(1).lower()
+    for candidate in (primary, url):
+        if candidate and "openalex" in candidate.lower():
+            m = _OPENALEX_RE.search(candidate.strip())
+            if m:
+                return "openalex", m.group(1)
+    if url and url.lower().startswith(("http://", "https://")):
+        return "url", url
+    return None
+
+
+def _cite_key(authors: list[str], year: int | None, ident: str) -> str:
+    """Stable per identifier, so the same source always gets the same key in a run."""
+    surname = re.sub(r"[^a-z]", "", (authors[0].split()[-1] if authors else "anon").lower())
+    return f"{surname or 'anon'}{year or 'nd'}{_sha256(ident.encode())[:6]}"

purescholar/types.py

@@ -0,0 +1,164 @@
+"""PureScholar adapter types (01-purescholar.md §3, §4)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+REQUIRED_SCOPES: tuple[str, ...] = ("ask", "search", "papers.read", "tools.run")
+
+
+@dataclass
+class CallRecord:
+    """One HTTP call (§4, KB-015). Never contains the key."""
+
+    call_id: str
+    endpoint: str
+    request_digest: str
+    response_digest: str | None
+    status: int | None  # HTTP status, or None when no response arrived
+    started_at: str
+    duration_ms: int
+    service_version: str | None
+    quota_remaining: str | None
+    error_type: str | None
+    request_body: str
+    response_body: str | None
+
+    def to_dict(self) -> dict[str, Any]:
+        return dict(self.__dict__)
+
+
+@dataclass(frozen=True)
+class Evidence:
+    marker: str
+    paper_id: str | None
+    title: str | None
+    authors: list[str]
+    year: int | None
+    venue: str | None
+    section: str | None
+    content: str
+    source: str  # lab | personal | external
+    url: str | None = None
+
+
+@dataclass(frozen=True)
+class Citation:
+    """A `[cID]` marker as PureScholar resolved it. `evidence` is the retrieved chunk the
+    marker points to, when the response carried it; `call_id` is the call it came from."""
+
+    marker: str
+    paper_id: str | None
+    title: str | None
+    url: str | None
+    quartile: str | None
+    conf_rank: str | None
+    doc_type: str | None
+    valid: bool
+    evidence: Evidence | None
+    call_id: str
+
+
+@dataclass(frozen=True)
+class PaperRef:
+    title: str | None
+    authors: list[str]
+    year: int | None
+    venue: str | None
+    doi: str | None
+    url: str | None
+    abstract: str | None
+    cited_by_count: int | None
+    quartile: str | None
+    conf_rank: str | None
+    call_id: str
+
+
+@dataclass
+class Grounded:
+    """A grounded envelope. The signals pass through exactly as they arrived (INV-2)."""
+
+    body: dict[str, Any]
+    citations: list[Citation]
+    invalid_citations: list[str]
+    insufficient_evidence: bool
+    evidence: list[Evidence]
+    grounding: dict[str, Any] | None
+    sub_questions: list[str] = field(default_factory=list)
+    records: list[CallRecord] = field(default_factory=list)
+
+
+@dataclass
+class Identity:
+    auth: str
+    lab_id: int | None
+    lab_name: str | None
+    scopes: list[str]
+    quota: dict[str, Any] | None
+    records: list[CallRecord] = field(default_factory=list)
+
+
+@dataclass
+class NoveltyEvidence:
+    """The closest prior works found, and a grounded answer on overlap. `loop` judges."""
+
+    hypothesis: str
+    closest: list[PaperRef]
+    answer: Grounded
+    records: list[CallRecord] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class CitationRecord:
+    key: str
+    id_kind: Literal["doi", "openalex", "url"]
+    id: str
+    title: str | None
+    authors: list[str]
+    year: int | None
+    venue: str | None
+    url: str | None
+    source: str
+    evidence_markers: list[str]
+    excerpts: list[str]
+    call_id: str
+
+
+@dataclass(frozen=True)
+class NotCitable:
+    reason: str
+
+
+# ---- errors (KB-015) --------------------------------------------------------------------
+
+class PureScholarError(Exception):
+    def __init__(self, message: str, records: list[CallRecord] | None = None,
+                 code: str | None = None) -> None:
+        super().__init__(message)
+        self.records: list[CallRecord] = records or []
+        self.code = code
+
+
+class AuthError(PureScholarError):
+    """401, or 403 with its code (`missing_scope`, `key_orphaned`, ...)."""
+
+
+class NotFound(PureScholarError):
+    """404."""
+
+
+class RequestRejected(PureScholarError):
+    """400, 409, 413, 415, 422."""
+
+
+class RateLimited(PureScholarError):
+    """`429 rate_limited` after the retries."""
+
+
+class QuotaExhausted(PureScholarError):
+    """`429 monthly_quota_exhausted`. The run pauses until the user acts."""
+
+
+class ServiceUnavailable(PureScholarError):
+    """5xx, timeouts, connection failures, or generation disabled (`notice`)."""

puretrace/__init__.py

@@ -0,0 +1,49 @@
+"""puretrace: adapter to the PureTrace service (docs/knowledge_base/02-puretrace.md)."""
+
+from .client import PureTrace
+from .types import (
+    PAPER_TYPES,
+    Artifacts,
+    Assessment,
+    AssessmentFailed,
+    AssessmentTimeout,
+    AuthError,
+    CallRecord,
+    Dimension,
+    Fact,
+    NotApplicable,
+    NotFound,
+    PureTraceError,
+    Question,
+    QuotaExhausted,
+    RateLimited,
+    RequestRejected,
+    Rubric,
+    ServiceUnavailable,
+    TypeGuess,
+    UseNotEnabled,
+)
+
+__all__ = [
+    "PAPER_TYPES",
+    "Artifacts",
+    "Assessment",
+    "AssessmentFailed",
+    "AssessmentTimeout",
+    "AuthError",
+    "CallRecord",
+    "Dimension",
+    "Fact",
+    "NotApplicable",
+    "NotFound",
+    "PureTrace",
+    "PureTraceError",
+    "Question",
+    "QuotaExhausted",
+    "RateLimited",
+    "RequestRejected",
+    "Rubric",
+    "ServiceUnavailable",
+    "TypeGuess",
+    "UseNotEnabled",
+]