GXL Paperclip Python SDK and HTTP contracts

Reviewed on 2026-09-30 against gxl_paperclip 0.7.92 installed client/source, request-construction smoke tests with fake HTTP responses, and the public OpenAPI 3.1 schema. Public metadata/unauthenticated probes were checked; authenticated retrieval, LLM execution, account permissions, uploads, and repository mutations were not exercised. Remote examples below are illustrative.

Install and connect

Install the official wheel in an environment you control; the managed CLI's private library is not on an arbitrary Python interpreter's path. See installation.md.

uv pip install https://paperclip.gxl.ai/paperclip.whl

import gxl_paperclip
from gxl_paperclip import PaperclipClient

print(gxl_paperclip.__version__)
client = PaperclipClient.from_env(no_color=True)

Ordinary from_env() precedence is PAPERCLIP_BEARER_TOKEN, PAPERCLIP_API_KEY, then stored OAuth. It also accepts base_url, timeout, user_agent, session, and no_color. API keys use X-API-Key; bearer auth uses Authorization. FileCredentialsAuth can refresh stored OAuth on 401 and retry once. Do not print credentials, authorization headers, or a complete private config.

Explicit auth is useful when a notebook must select exactly one configured identity:

import os
from gxl_paperclip import APIKeyAuth, PaperclipClient

client = PaperclipClient(auth=APIKeyAuth(os.environ["PAPERCLIP_API_KEY"]), no_color=True)

The ordinary request timeout is 120 seconds. In this version map defaults to 1,500 seconds, structured/exhaustive maps have separate longer defaults, and reduce/ask-image default to 300. These can be environment-configured. Pass a per-call timeout to override a slow command; setting the constructor timeout alone does not override every command-specific default.

Structured search and lookup

result = client.search("CRISPR delivery", source="pmc", limit=5)
if result.exit_code != 0 or result.output.lstrip().startswith("ERR:"):
    raise RuntimeError(result.output)
for paper in result.papers:
    doc_id = paper.get("document_id") or paper.get("id") or paper.get("paper_id")
    if not doc_id:
        raise ValueError("Search hit has no document identifier")
    print(doc_id, paper.get("title"), paper.get("doi"))
print(result.result_id)

ExecuteResult has output, exit_code, elapsed_ms, result_id, result_data, raw, cwd, download_url, and download_filename. Newer papers and count properties expose structured search/lookup hits. papers reads the papers or results array in result_data; count uses its length when nonempty, otherwise a declared count. It is not an independent completeness check. Search/lookup attempt saved-result hydration if data is absent/truncated; hydration failures can leave a preview. Compare declared counts/truncation with retrieved rows before calling a cohort complete. Do not parse ANSI-colored terminal titles to reconstruct IDs.

Supported search keyword arguments in 0.7.92:

limit, source, exact, since, sort, author, journal, year, type, category,
mode, min_embedding_similarity, min_bm25_score, all, timeout

The wrapper serializes mode as -m; the CLI's documented spelling is --ranking. The score floors also exist as CLI flags and affect only their respective retrieval legs. Source/date/ranking caveats are in search-and-retrieval.md.

identified = client.lookup("doi", "10.1073/pnas.2307796121", limit=1)
counts = client.sql("SELECT source, COUNT(*) AS n FROM documents GROUP BY source")
protein_count = client.sql("SELECT COUNT(*) FROM uniprot_v.proteins", source="proteins")

Load the current protein domain reference before constructing protein queries. SQL output remains an ExecuteResult, not a guaranteed pandas table.

Reading and arbitrary commands

import json

path = "/papers/PMC10945750"
metadata_result = client.papers.cat(f"{path}/meta.json")
if metadata_result.exit_code != 0 or metadata_result.output.lstrip().startswith("ERR:"):
    raise RuntimeError(metadata_result.output)
meta = json.loads(metadata_result.output)
opening = client.papers.head(f"{path}/content.lines", lines=40)
ending = client.papers.tail(f"{path}/content.lines", lines=20)
sections = client.papers.ls(f"{path}/sections/")
hits = client.papers.grep("lipid nanoparticle", f"{path}/content.lines", ignore_case=True)
scanned = client.papers.scan(f"{path}/content.lines", ["IC50", "EC50", "dose"])

These typed methods preserve argument boundaries and support per-call timeout. papers.grep also accepts extended=True. Do not assume every metadata source has journal or pub_year; inspect keys and use optional access for nullable source-specific fields. L<n> prefixes in text are the source for line citations.

client.execute("grep", ["-n", "-C", "3", "IC50", "/papers/PMC10945750/content.lines"])

Use execute(command, args) for commands without a wrapper. bash(script) exists for server-side pipelines, but old versions failed on this path and current authenticated behavior was not tested. Prefer argument lists and local Python composition. ask_image(path, question=None, fn=None) returns an ExecuteResult; list the figure directory first. pull(target, dest=None) returns textual metadata and any server-provided download URL; **the SDK does not stream image bytes to dest**. Never interpret exit_code == 0 as proof that a local image was written.

Map events and schemas

from gxl_paperclip import MapProgressEvent, MapResultEvent

schema = {
    "type": "object",
    "required": ["effect"],
    "additionalProperties": False,
    "properties": {"effect": {"type": ["number", "null"]}},
}
for event in client.map_(
    "Extract the reported effect; use null when absent.",
    from_results="s_ID", output_schema=schema, timeout=1500.0,
):
    if isinstance(event, MapProgressEvent):
        print(event.completed, event.failed, event.total)
    elif isinstance(event, MapResultEvent):
        if event.exit_code:
            raise RuntimeError(event.output)
        print(event.result_id, event.output)

Use isinstance; these dataclasses do not provide the event.type used in an old website example. map_ returns an iterator. On the unified paperclip.gxl.ai host, API-key and OAuth maps use the streaming REST route; a direct mcp.* host with API-key auth emits only a final result event. The typed wrapper accepts from_results, output_schema, and timeout, not worker/repo parameters; use stream("map", argv) for specialized options after inspecting the relevant workflow.

summary = client.reduce("Compare the effects", from_map="m_ID", strategy="table", columns=["paper", "effect"])

A schema validates JSON shape; source evidence still needs scientific checks. See map-reduce.md.

Results and pagination

recent = client.results.list(limit=10)
saved = client.results.get("s_ID")
page = client.results.page("s_ID", cursor=0, limit=500)
sample = client.results.sample("s_ID", count=10, seed=42)

list() returns ResultRow objects (recent results, not hit pages); get() returns ResultData with output and raw. page() returns a dict with papers, total count, and next_cursor. The initial cursor is integer 0, page size is 1–500, and next_cursor is None terminates. These contracts are taken from the SDK and bundled cohort exporter, not an authenticated page. A 404 can mean missing results or a server lacking cohort-page support.

Bound traversal and reject a nonadvancing cursor or an inconsistent count:

def saved_papers(client, result_id, max_pages=20):
    cursor = 0
    rows = []
    expected = None
    for _ in range(max_pages):
        page = client.results.page(result_id, cursor=cursor, limit=500)
        batch = page.get("papers")
        count = page.get("count")
        if not isinstance(batch, list) or isinstance(count, bool) or not isinstance(count, int) or count < 0:
            raise ValueError("Invalid saved-cohort page")
        if expected is None:
            expected = count
        if count != expected:
            raise ValueError("Cohort changed during pagination")
        rows.extend(batch)
        next_cursor = page.get("next_cursor")
        if next_cursor is None:
            if len(rows) != expected:
                raise ValueError("Incomplete saved cohort")
            return rows
        if isinstance(next_cursor, bool) or not isinstance(next_cursor, int) or next_cursor <= cursor:
            raise ValueError("Invalid cohort cursor")
        cursor = next_cursor
    raise ValueError("Saved cohort exceeded the page budget")

This retrieves a saved cohort; it does not extend the original search into unsaved hits. results.sample accepts 1–100 papers and an integer seed. The CLI portable bundle exporter uses these pages, verifies count/cursor advancement, and caps exports at 10,000 rows in 0.7.92.

SDK transport and workspace contracts

The SDK is not a wrapper around the newer /api/v1/search API. Inspected 0.7.92 routing:

The legacy MCP text parser can report exit_code=0 even when returned text contains a virtual-shell error; this is still visible in the 0.7.92 implementation. HTTP status, typed exceptions, command status, and expected result content all matter. The SDK health() dispatches authenticated status; it is not the public /health probe used by CLI config.

Repo/library methods return mostly raw dicts and accept internal repo/entry IDs rather than CLI names. Examples are mutations and require the corresponding user task:

repo = client.repos.create_repo("my-review", "Delivery vectors")
client.repos.add_papers(repo["id"], [{"paper_id": "PMC10945750"}])

The item key is paper_id, not the old example's document_id. Resolve an existing repo with get_repo_by_name() and handle None before use. The route mapping for the formerly documented SDK operations is:

SDK repos.commit() only sends the commit request; it does not run the CLI's client-side verifier or its scientific gates. Do not substitute it for paperclip repo commit and claim equivalent verification. Permissions are not established merely because a method exists: client.list_paper_repos() explicitly rejects API-key auth, while client.repos.list_repos() dispatches directly. This inconsistency was not resolved with live account tests. Library and repo history paging are separate one-based APIs; do not reuse the cohort's zero-based cursor.

Public JSON API

For stable search/metadata JSON without the CLI transport, the current public contract is based at https://paperclip.gxl.ai/api/v1 and accepts X-API-Key or an API key as Authorization: Bearer .... The OpenAPI security declaration lists HTTPBearer; both key forms are described in its info and the official HTTP guide. These endpoints are distinct from SDK command transport.

/search defaults to abstracts, not PMC. The schema describes that default index as residual PubMed/Crossref title/abstract content; do not assume the CLI's broader -s abstracts wording. analogical is not a v1 ranking enum even though the CLI supports it. Neither search nor lookup exposes a page, cursor, or offset in this schema: increasing num_results is bounded retrieval, not arbitrary pagination. Year bounds are inclusive; records with unknown year are retained by the published filter contract. published_after/before are year-granular aliases, not day precision.

Illustrative request, schema-checked locally but not submitted with credentials:

import os
import requests

response = requests.post(
    "https://paperclip.gxl.ai/api/v1/search",
    headers={"X-API-Key": os.environ["PAPERCLIP_API_KEY"]},
    json={"query": "CRISPR delivery", "sources": ["pmc"], "num_results": 5, "ranking": "hybrid"},
    timeout=120,
)
response.raise_for_status()
papers = response.json()["papers"]

Public schema and health reads returned 200 during review; unauthenticated document/results reads returned 401. That verifies authentication boundaries, not successful retrieval or billing behavior.

Errors

Catch PaperclipError and its subclasses: AuthError (401), ForbiddenError (403), RateLimitError (429), NotFoundError, ServerError, RequestTimeoutError, and NetworkError. Do not retry bad credentials or forbidden operations automatically. Bound retries for transient failures; do not restart a mutation whose outcome is unknown without reconciling server state. Inspect typed command status and returned content as well as exceptions. Never log request headers or credential-bearing diagnostics when reporting an error.