puremethod 0.1.0__py3-none-any.whl

puretrace/client.py

@@ -0,0 +1,320 @@
+"""PureTrace REST v1 adapter (02-puretrace.md).
+
+Routes used, all under `/v1`: rubrics, papers (list, submit, get, report) and paper-type
+detection. There is deliberately no code path to the certification or author-response
+routes (INV-1, INV-2): the client can only send the requests built below.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import time
+import uuid
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime
+from typing import Any
+
+import httpx
+
+from .types import (
+    ASSESSED_STATUSES,
+    PAPER_TYPES,
+    TERMINAL_STATUSES,
+    USES,
+    Artifacts,
+    Assessment,
+    AssessmentFailed,
+    AssessmentTimeout,
+    AuthError,
+    CallRecord,
+    Dimension,
+    Fact,
+    NotApplicable,
+    NotFound,
+    PureTraceError,
+    Question,
+    QuotaExhausted,
+    RateLimited,
+    RequestRejected,
+    Rubric,
+    ServiceUnavailable,
+    TypeGuess,
+    Use,
+    UseNotEnabled,
+)
+
+
+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)
+
+
+class PureTrace:
+    """Built from the configuration, the run id and the uses the run enables (KB-015).
+
+    The HTTP client is created here: use one instance from one event loop, and `aclose` it.
+    """
+
+    def __init__(self, api_base: str, api_key: str, run_id: str, enabled_uses: list[str], *,
+                 poll_interval_s: float = 10.0, poll_max_s: float = 60.0,
+                 assessment_timeout_s: float = 1800.0, request_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:
+        unknown = set(enabled_uses) - set(USES)
+        if unknown:
+            raise ValueError(f"unknown uses: {sorted(unknown)}")
+        if not api_key:
+            raise ValueError("an API key is required")
+        self._base = api_base.rstrip("/")
+        self._key = api_key
+        self._run_id = run_id
+        self._uses = frozenset(enabled_uses)
+        self._poll = poll_interval_s
+        self._poll_max = poll_max_s
+        self._timeout = assessment_timeout_s
+        self._retries = retries
+        self._sleep = sleep
+        self._monotonic = monotonic
+        self._client = httpx.AsyncClient(base_url=self._base, transport=transport,
+                                         timeout=request_timeout_s,
+                                         headers={"Authorization": f"Bearer {api_key}"})
+        self._rubrics: list[Rubric] | None = None
+
+    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, path: str, records: list[CallRecord], *,
+                       json_body: Any = None, files: Any = None, data: Any = None,
+                       params: dict[str, Any] | None = None,
+                       headers: dict[str, str] | None = None,
+                       described_body: Any = None) -> Any:
+        """One logical request with retries. Every attempt appends a CallRecord."""
+        if not path.startswith("/v1/"):
+            raise ValueError("only /v1 routes are called (INV-7)")
+        body_text = _canonical(described_body if described_body is not None
+                               else {"json": json_body, "params": params})
+        delay = 1.0
+        for attempt in range(self._retries + 1):
+            started, t0 = _now(), self._monotonic()
+            response: httpx.Response | None = None
+            error_type: str | None = None
+            try:
+                response = await self._client.request(method, path, json=json_body,
+                                                      files=files, data=data, params=params,
+                                                      headers=headers)
+            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 = None
+            if response is not None and response.status_code >= 400:
+                try:
+                    code = response.json().get("error", {}).get("code")
+                except (ValueError, AttributeError):
+                    code = None
+                error_type = f"http_{response.status_code}:{code or 'unknown'}"
+            records.append(CallRecord(
+                call_id=uuid.uuid4().hex, 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-API-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:
+                    return response.json()
+                except ValueError:
+                    raise ServiceUnavailable(f"PureTrace {path} returned a non-JSON body",
+                                             list(records)) from None
+            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
+        status = response.status_code
+        if status == 429 and code != "quota_exceeded":
+            try:
+                return True, float(response.headers.get("Retry-After", ""))
+            except ValueError:
+                return True, None
+        if status == 409 and code == "idempotency_in_progress":
+            return True, None
+        return status >= 500, None
+
+    def _error(self, response: httpx.Response | None, code: str | None,
+               records: list[CallRecord]) -> PureTraceError:
+        if response is None:
+            return ServiceUnavailable("PureTrace unreachable", list(records))
+        status = response.status_code
+        msg = f"PureTrace {status} {code or ''}".strip()
+        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 == "quota_exceeded":
+                return QuotaExhausted(msg, list(records), code)
+            return RateLimited(msg, list(records), code)
+        if status >= 500 or (status == 409 and code == "idempotency_in_progress"):
+            return ServiceUnavailable(msg, list(records), code)
+        return RequestRejected(msg, list(records), code)
+
+    # ---- interface ---------------------------------------------------------------------
+
+    async def preflight(self) -> list[CallRecord]:
+        """Checks the key reads rubrics and papers. `papers:write` cannot be checked
+        without submitting; a missing write scope surfaces on the first submit."""
+        records: list[CallRecord] = []
+        await self._request("GET", "/v1/rubrics", records)
+        await self._request("GET", "/v1/papers", records, params={"limit": 1})
+        return records
+
+    async def rubrics(self) -> tuple[list[Rubric], list[CallRecord]]:
+        records: list[CallRecord] = []
+        if self._rubrics is None:
+            page = await self._request("GET", "/v1/rubrics", records)
+            out = []
+            for summary in page["data"]:
+                detail = await self._request("GET", f"/v1/rubrics/{summary['paper_type']}",
+                                             records)
+                out.append(Rubric(paper_type=detail["paper_type"], label=detail["label"],
+                                  rubric_version=detail.get("rubric_version"),
+                                  total_weight=float(detail["total_weight"]),
+                                  dimensions=list(detail["dimensions"])))
+            self._rubrics = out
+        return list(self._rubrics), records
+
+    async def detect_type(self, title: str, abstract: str | None = None
+                          ) -> TypeGuess | NotApplicable:
+        records: list[CallRecord] = []
+        body: dict[str, Any] = {"title": title}
+        if abstract:
+            body["abstract"] = abstract
+        resp = await self._request("POST", "/v1/paper-types/detect", records, json_body=body)
+        guess = str(resp["paper_type"])
+        if guess not in PAPER_TYPES:
+            return NotApplicable(reason="detected type is not one of the five PureTrace types",
+                                 detected=guess, records=records)
+        return TypeGuess(paper_type=guess, confidence=float(resp["confidence"]),
+                         records=records)
+
+    async def assess(self, pdf: bytes, title: str, authors: str, artifacts: Artifacts,
+                     paper_type: str | None, *, use: Use) -> Assessment | NotApplicable:
+        if use not in self._uses:
+            raise UseNotEnabled(f"the run did not enable PureTrace {use}")
+        records: list[CallRecord] = []
+        if paper_type is None:
+            guess = await self.detect_type(title)
+            records.extend(guess.records)
+            if isinstance(guess, NotApplicable):
+                guess.records = records
+                return guess
+            paper_type = guess.paper_type
+        elif paper_type not in PAPER_TYPES:
+            return NotApplicable(reason="paper type is not one of the five PureTrace types",
+                                 detected=paper_type, records=records)
+
+        pdf_hash = _sha256(pdf)
+        fields = {"title": title, "authors": authors, "paper_type": paper_type,
+                  **{k: v for k, v in artifacts.__dict__.items() if v is not None}}
+        idempotency_key = _sha256(f"{self._run_id}:{pdf_hash}".encode())
+        try:
+            paper = await self._request(
+                "POST", "/v1/papers", records, data=fields,
+                files={"file": ("paper.pdf", pdf, "application/pdf")},
+                headers={"Idempotency-Key": idempotency_key},
+                described_body={"form": fields, "pdf_sha256": pdf_hash,
+                                "idempotency_key": idempotency_key, "use": use})
+            paper = await self._poll_until_done(paper, records)
+            return await self._assessment(paper, records)
+        except PureTraceError as exc:
+            exc.records = list(records)
+            raise
+
+    async def report(self, paper_id: str) -> Assessment:
+        records: list[CallRecord] = []
+        try:
+            paper = await self._request("GET", f"/v1/papers/{paper_id}", records)
+            if paper["status"] == "failed":
+                raise AssessmentFailed(f"paper {paper_id} failed", list(records))
+            if paper["status"] not in ASSESSED_STATUSES:
+                raise RequestRejected(f"paper {paper_id} is still {paper['status']}",
+                                      list(records), "not_assessed")
+            return await self._assessment(paper, records)
+        except PureTraceError as exc:
+            exc.records = list(records)
+            raise
+
+    # ---- internals ---------------------------------------------------------------------
+
+    async def _poll_until_done(self, paper: dict[str, Any],
+                               records: list[CallRecord]) -> dict[str, Any]:
+        deadline = self._monotonic() + self._timeout
+        interval = self._poll
+        while paper["status"] not in TERMINAL_STATUSES:
+            if self._monotonic() >= deadline:
+                raise AssessmentTimeout(f"paper {paper['id']} still {paper['status']}")
+            await self._sleep(interval)
+            interval = min(interval * 1.5, self._poll_max)
+            paper = await self._request("GET", f"/v1/papers/{paper['id']}", records)
+        if paper["status"] == "failed":
+            raise AssessmentFailed(f"paper {paper['id']} failed")
+        return paper
+
+    async def _assessment(self, paper: dict[str, Any],
+                          records: list[CallRecord]) -> Assessment:
+        rep = await self._request("GET", f"/v1/papers/{paper['id']}/report", records)
+        try:
+            return self._parse_assessment(paper, rep, records)
+        except (KeyError, TypeError, ValueError) as exc:
+            # A response missing the §4 fields is an upstream fault, never a partial score.
+            raise ServiceUnavailable(f"unexpected report shape: {type(exc).__name__} {exc}",
+                                     list(records)) from None
+
+    @staticmethod
+    def _parse_assessment(paper: dict[str, Any], rep: dict[str, Any],
+                          records: list[CallRecord]) -> Assessment:
+        score = rep["score"]
+        return Assessment(
+            paper_id=paper["id"], status=paper["status"], paper_type=score["paper_type"],
+            rubric_version=score.get("rubric_version"), overall=float(score["overall"]),
+            provisional=bool(score.get("provisional", False)),
+            dimensions=[Dimension(key=d["key"], label=d["label"], score=float(d["score"]),
+                                  weight=float(d["weight"]),
+                                  confidence=float(d["confidence"]),
+                                  rationale=d.get("rationale"),
+                                  needs_author_input=bool(d.get("needs_author_input", False)))
+                        for d in score["dimensions"]],
+            facts=[Fact(key=f["key"], label=f["label"], value=str(f["value"]),
+                        confidence=f.get("confidence"), source_excerpt=f.get("source_excerpt"))
+                   for f in rep["facts"]],
+            open_questions=[Question(question_id=q["question_id"], fact_key=q["fact_key"],
+                                     label=q["label"], prompt=q["prompt"],
+                                     required=bool(q.get("required", False)))
+                            for q in rep.get("questions", [])],
+            paper_hash=rep.get("paper_hash") or paper.get("paper_hash"),
+            records=list(records))

puretrace/types.py

@@ -0,0 +1,166 @@
+"""PureTrace adapter types (02-puretrace.md §3, §4)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+PaperType = Literal["vision", "llm_finetune", "llm_pretrain", "rl", "graph_ml"]
+PAPER_TYPES: tuple[str, ...] = ("vision", "llm_finetune", "llm_pretrain", "rl", "graph_ml")
+Use = Literal["screening", "selfcheck"]
+USES: tuple[str, ...] = ("screening", "selfcheck")
+
+# Polling stops on these. `anchoring` and `certified` can come back when PureTrace returns an
+# existing paper for a PDF the organization already holds (deduplication); the adapter never
+# certifies anything itself (INV-1).
+ASSESSED_STATUSES = ("needs_author_input", "ready_to_certify", "anchoring", "certified")
+TERMINAL_STATUSES = (*ASSESSED_STATUSES, "failed")
+
+
+@dataclass
+class CallRecord:
+    """One HTTP call (01-purescholar.md §4 shape, 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 Artifacts:
+    code_repository_url: str | None = None
+    dataset_url: str | None = None
+    model_weights_url: str | None = None
+    environment_url: str | None = None
+    evaluation_url: str | None = None
+    notes: str | None = None
+
+
+@dataclass(frozen=True)
+class Dimension:
+    key: str
+    label: str
+    score: float
+    weight: float
+    confidence: float
+    rationale: str | None
+    needs_author_input: bool
+
+
+@dataclass(frozen=True)
+class Fact:
+    key: str
+    label: str
+    value: str
+    confidence: float | None
+    source_excerpt: str | None
+
+
+@dataclass(frozen=True)
+class Question:
+    question_id: str
+    fact_key: str
+    label: str
+    prompt: str
+    required: bool
+
+
+@dataclass
+class Assessment:
+    """A PureTrace result. The score always travels with its type, rubric version and
+    provisional flag (INV-4); scores are not comparable across paper types."""
+
+    paper_id: str
+    status: str
+    paper_type: str
+    rubric_version: str | None
+    overall: float
+    provisional: bool
+    dimensions: list[Dimension]
+    facts: list[Fact]
+    open_questions: list[Question]
+    paper_hash: str | None
+    records: list[CallRecord] = field(default_factory=list)
+
+
+@dataclass
+class TypeGuess:
+    paper_type: str
+    confidence: float
+    records: list[CallRecord] = field(default_factory=list)
+
+
+@dataclass
+class NotApplicable:
+    """The paper is outside the five PureTrace types (INV-5). Nothing was submitted."""
+
+    reason: str
+    detected: str | None = None
+    records: list[CallRecord] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class Rubric:
+    paper_type: str
+    label: str
+    rubric_version: str | None
+    total_weight: float
+    dimensions: list[dict[str, Any]]
+
+
+# ---- errors (KB-015) --------------------------------------------------------------------
+
+class PureTraceError(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(PureTraceError):
+    """401, or 403 (for example `insufficient_scope`)."""
+
+
+class NotFound(PureTraceError):
+    """404: does not exist, or belongs to another organization."""
+
+
+class RequestRejected(PureTraceError):
+    """400, 409 (other than `idempotency_in_progress`), 422."""
+
+
+class RateLimited(PureTraceError):
+    """`429 rate_limit_exceeded` after the retries."""
+
+
+class QuotaExhausted(PureTraceError):
+    """`429 quota_exceeded`: the monthly allowance is spent; not retried (KB-016)."""
+
+
+class ServiceUnavailable(PureTraceError):
+    """5xx, timeouts or connection failures after the retries."""
+
+
+class AssessmentFailed(PureTraceError):
+    """PureTrace marked the paper `failed`."""
+
+
+class AssessmentTimeout(PureTraceError):
+    """The assessment did not finish within the configured timeout."""
+
+
+class UseNotEnabled(PureTraceError):
+    """The run did not enable this use; nothing was submitted (INV-3)."""

writer/__init__.py

@@ -0,0 +1,8 @@
+"""writer: the paper and the run bundle, built from the ledger
+(docs/knowledge_base/06-writer.md)."""
+
+from .core import Writer
+from .types import BuildResult, CompilerUnavailable, PaperOptions, RunContext, WriterError
+
+__all__ = ["BuildResult", "CompilerUnavailable", "PaperOptions", "RunContext", "Writer",
+           "WriterError"]