Submit a paper request. Resolves metadata, checks dedup, queues for fetch.

Args: ref: The paper identifier. Any subset of: {doi, arxiv, pmid, title, authors, year, raw}. raw is a free-form citation string — Quest will try to extract a DOI or arXiv id from it. dry_run: If True, resolve and return candidates but do not persist. source: Provenance — e.g. {"document": "ch02.tex", "line": 147}. priority: Higher = served first by the runner. Default 0. created_by: Agent slug or user id. Used for per-agent rate-limiting.

Returns: The full request record, including resolved metadata, candidates, and misconceptions. Status will be one of: found_in_store (already have it), queued (waiting for runner), needs_user (disambiguation or bad DOI required manual action).

Idempotent: calling submit twice with the same DOI while the first request is still open returns the same request id.

Do not fabricate quotes from a paper whose status is not ingested or found_in_store.

Read one or many paper requests.

Args: id: A request id (uuid string). If given, filter is ignored. filter: Narrow the list of rows returned. Supported keys: status, created_by, has_misconception (bool), source_document, limit.

Returns: A single card (when id is set) or a list of cards.

Mutate a request. Single verb with an explicit mode (see precis.put for the same pattern).

Modes: confirm: pick one of candidates by index. Requires choice. repoint: replace the DOI (user-corrected) and re-resolve. Requires doi. flag: attach a misconception. Requires code; optional severity, evidence. priority: change the runner priority. Requires priority. cancel: terminate the request.

Attach a user-supplied PDF to a paper request.

Use this when a user drops a PDF (e.g. a Discord attachment) for a paper that Quest could not fetch automatically, or to pre-load a PDF you already have on disk.

Args: url: A direct HTTP(S) link to the PDF. Must resolve to a fresh file (follow-redirects is enabled, so short-lived Discord CDN URLs work). Mutually exclusive with content_base64. content_base64: Base64-encoded PDF bytes, for agents that already have the file in memory. Prefer url when available so the provenance URL is recorded on the request. filename: Optional filename hint, used when naming the file written to the inbox. Falls back to the request's author/year. request_id: Attach to an existing request (preferred). Reopens failed, extract_failed, or needs_user requests. Refuses to overwrite already-closed or cancelled requests. ref: Create a new request from this reference (same shape as :func:submit) and attach the PDF. Use this when the paper isn't already being tracked. created_by: Agent or user id, used when ref is given.

Returns: The full request record, flipped to ingesting. The background runner reconciles with acatome-store once acatome-extract has done its work.

Exactly one of url / content_base64 is required, and exactly one of request_id / ref.