paperconan

paperconan

paperconan scans paper source-data tables and can register local image assets for external Agent review. Treat every hit as signal, not verdict: report locations and patterns, never intent or personal accusation. PaperConan does not manage model keys or provider SDKs and does not perform autonomous semantic judgment.

Tool repository: https://github.com/zixixr/paperconan

Core Workflow

0. Ensure the CLI is available before scanning: run paperconan --version. If it is missing and pip works, install once with pip install "paperconan[all]" (ask first if a virtualenv or non-global install is preferred; if pip refuses with a PEP 668 externally-managed-environment error, use uv tool install "paperconan[all]" or pipx install "paperconan[all]" instead — see Install And Run). If Python/pip is unavailable, ask the user to install and run locally — never invent output.
1. Confirm what the user supplied:
   • Local source-data directory: run paperconan <input-dir>.
   • DOI or title: run paperconan fetch "<DOI or title>", choose a matched tabular dataset, download it, then scan the downloaded directory.
   • Only an existing audit: read audit/scan.json and use audit/report.html as the evidence browser to triage — then give an adjudicated answer. Do not hand the raw report.html over as "the result" (see Report Positioning below).
2. Prefer the real CLI. Do not invent findings from eyeballing tables.
3. Read the scan in layers — start with paperconan overview, not by parsing the whole scan.json (see Reading A Scan In Layers below). Load the reference file needed for the task.
4. Open the original table when describing a serious finding as worth follow-up. If the original data is unavailable, say the finding is unverified.
5. Answer cautiously: explain the anomaly, plausible benign explanations, and what human context is needed.

Reading A Scan In Layers

One paper's supplement routinely produces hundreds to thousands of findings and a multi-megabyte scan.json. Reading all of it wastes the attention you need for judgement, and the few signals worth acting on get buried among many routine ones.

Detectors deliberately run wide so real signals are not lost to a threshold, so the narrowing happens here, in how you read — not in what was detected. Nothing is filtered; you reach it in stages.

paperconan overview audit/scan.json                    # which locations carry signal
paperconan drill    audit/scan.json 2                  # that location, grouped by kind
paperconan drill    audit/scan.json 2 --kind identical_column
paperconan explain  audit/scan.json seed:17942ad206854a66
paperconan explain  audit/scan.json seed:17942ad206854a66 --full

Add --json to any of them when you need the structure rather than the text.

Evidence windows are bounded, and say so. The scan stores a window around the highlighted cells, not the whole block — on a dense supplement the windows are most of the file's bytes. A trimmed window carries its own scale, e.g. ! this window is 20x30 of a 300x200 block, trimmed by the scan. Read that as "the anomaly is here, and there is more of this block than you are seeing" — not as the block. When the exact cells matter (checking a value against the paper, or judging whether a pattern runs the whole column), explain --full re-reads the block from the source data.

--full refuses rather than guesses. The scan records each input's size and timestamp, so a source that has moved, been edited, or lost the rows or columns the finding covers returns the reason and no rows — reading it blind would hand you a different table under this finding's heading. Two limits worth knowing: a source rewritten to the same byte count with the timestamp restored is undetectable (the check compares size, not content), and a scan produced before this check existed falls back to comparing extents, which catches a shrunk source but not an in-place edit. It also stays inside a cell budget (PAPERCONAN_MAX_FULL_EVIDENCE_CELLS); a window bounded by it says so and names that variable rather than telling you to re-run --full.

Work down, and stop at the shallowest layer that answers the question:

1. overview — which locations, how strong, what families. Often enough to see that a location is one derived relation restated many times.
2. drill <n> — the kinds at that location, with one concrete example each. A kind with a large n and a formulaic example is usually one structure expressed repeatedly; a kind with n=1 may still be the strongest signal there.
3. drill <n> --kind <kind> — the individual findings, each with an id.
4. explain <id> — one finding with its parameters and evidence table. Open the original table before calling anything worth follow-up.

Three things to hold onto while reading:

• detector=high displayed=low means a display profile down-weighted it, not that it is benign. explain prints the recorded reason. Judge that reason — a dense block or a repeated axis is often a fair call, but an exactly duplicated column can be demoted merely for sharing a block with many other relations. Do not skip a finding because its displayed severity is low.

• Read the ! lines — every layer has them. overview and both drill forms carry a coverage block; explain states its own limits inline (an evidence window the scan trimmed, structured parameters only --json shows). They state what was not shown and why: locations beyond the listed count, findings beyond a listing limit, families this layer does not route (digit distributions, decimal endings, image findings), findings the scan's own caps dropped before the layers saw them, and detector-level caps that still reach no channel. Raise --max-locations / --max-findings to reach the remainder; the rest are limits of the scan, not of the view.

• scan: lines carry scan-layer limitations, not just detector ones. The shapes below are the ones you will meet most often, quoted verbatim; the code emits others in the same form (a sheet-scoped line appends the sheet name after the file). Whole-detector skips are the exception — they reach no channel and are never named here at all.

  • scan: file too large in big.xlsx — a file that was not read at all. scan: unreadable in notes.xlsx is the same class: nothing in that file was examined.
  • scan: formula cache missing in m.xlsx Fig 3b (cells=['C4', 'C5', 'C6'], count=812) — count is how many formula cells stored no cached value; cells is a short list of examples, not the whole set. paperconan never saw the numbers those cells compute, so they were not audited and the sheet is partly unread.
  • scan: formula cache unreadable in m.xlsx — the formula-cache inspection itself did not complete, so paperconan cannot say whether that file has unread formula cells. Absence of a formula cache missing line for it proves nothing. formula metadata byte limit and formula metadata sheet limit are the same class, naming which bound stopped the inspection.
  • scan: report block limit in m.xlsx Fig 3b (count=3) — block collection for that sheet stopped at an output budget, so later blocks were never analysed. Two budgets emit this same line: raise PAPERCONAN_MAX_REPORT_BLOCKS, and if that changes nothing raise PAPERCONAN_MAX_TOTAL_FINDINGS.
  • scan: detector candidate pool limit in detect_short_row_reuse (limit=400) — a detector stopped building candidates at its cap, so rows past it were never compared.
  • scan: detector finding limit in detect_row_pair_digit_coupling (limit=25) — a detector stopped emitting at its cap.
  • scan: detector compute budget limit in detect_row_relations — a detector ran out of its work budget.
  • scan: detector row limit in detect_local_pair_runs — a block taller than PAPERCONAN_LOCAL_RUN_MAX_ROWS was not compared row by row by this pass; its columns were, unless the block was also wider than PAPERCONAN_MAX_BLOCK_COLS, where no column pairs are compared either.
  • scan: detector within row folded independent repeat in detect_recurring_row_vectors (count=2) — not a truncation but an omission: the within-row pass folds the overlapping windows one physical repeat produces into a single finding, and this many of the folded candidates also repeated at a place no finding on this page covers at all. The count is all the record holds; finding the place means reading the row.

  Any of these means scan_status is not complete (partial, or failed when nothing could be read at all), so a quiet result on that input is not evidence of a clean one. The rest of this paragraph is about the lines that were CUT SHORT, which is every one above except detector within row folded independent repeat. (Named rather than positioned, so that appending a bullet cannot make this sentence quietly wrong about two of them.) That one reports an omission rather than a truncation: nothing was left unexamined, and reading the row is its remedy. But it is not independent of the caps either — it compares against the findings that were EMITTED, so when detector finding limit appears on the same detector in the same scan, a narrower input can emit more and change whether this line appears at all. Seen on a real supplement. Read the two together when both are present. Detector lines name no file or sheet: the record does not carry one, so the line cannot tell you where the truncation bit — it may have been one block or many. Re-running unchanged proves nothing: the scan is deterministic, so it reproduces the same truncation byte for byte. Re-run with the matching PAPERCONAN_* cap raised (PAPERCONAN_SHORT_ROW_MAX_ROWS, PAPERCONAN_ROW_PAIR_MAX_ROWS, the *_BUDGET vars), or on a narrowed input. Some caps are bare defaults with no knob; for those, narrowing the input is the only remedy. A separate caveat covers whole-detector skips (a block too wide or too tall), which reach no channel at all and so are never named here.

• A quiet overview is not a clean paper. It means these detectors found nothing at these thresholds in the data that was supplied.

Starting From A Specific Claim

overview answers "where is there signal", which is the right first question when nothing else is known. It is the wrong one when you already have a claim -- someone says figure 2j of this paper looks wrong -- because a sheet with no finding never appears there, and "no finding" is exactly what you were asked to check.

paperconan sheets audit/scan.json          # every sheet read, signal or not

Then decide, yourself, which sheet holds that figure. A supplement routinely spreads a few hundred sheets over a dozen files, named Fig. 2j, Fig2J, ED_Fig.7b, Source Data Fig 2, Supplementary Figure 8e, or by content rather than number. No rule maps those to a figure reliably -- reading them is a judgement, which is why the tool lists and does not match.

Names repeat across files, so read the file column too, not just the sheet name.

Then:

• one sheet matches, and it carries signal — drill into it as usual. drill takes an overview ordinal, so a sheet ranked past the default page needs overview --max-locations raised until it appears;
• one sheet matches and carries none — the signal column covers only the families this layer routes. digit_distribution, decimal_endings, decimal_tail_clusters and image_findings are not among them, and the listing says so in its own ! lines without naming which sheet each belongs to. Read those keys in scan.json for your sheet before calling it clean — an empty signal column is not a clean bill of health, the same way an empty image_findings list is not. Once you have, "the data is present and no detector found anything at that location" is an answer worth reporting, and a better one than "the source could not be obtained";
• several could be it — check each. Concluding "present, nothing found" from the one you happened to pick is a more confident wrong answer than "unavailable" was, and costs the reader more;
• none matches — say the figure's data was not among what was fetched, and which files were searched.

The listing also reports what it could NOT read: files that yielded no sheet, and sheets past the size cap (marked not read). A figure whose data sits in one of those has not been checked, and must not be reported as clean.

Do not conclude "source data unavailable" without running sheets first. On this project's own benchmark, 16 claims adjudicated as having no obtainable source had their named figure sitting in a sheet already downloaded -- one of them a sheet in a file of 161 -- and 12 of those sheets carry a finding today. The data was there; nobody had matched the figure to it.

When the sheet genuinely is absent, paperconan fetch may reach a copy the first download missed (see Fetching Data), and the publisher's own label for each supplementary file is recorded to help you tell which one to ask for.

Adaptive Image Review

Use this workflow when the user requests image review or the source directory contains figures that should be reviewed with the numeric material:

1. Run paperconan <input-dir> --images; add --image-diagnostics only when deterministic hints are useful.
2. Read every entry in image_assets; deterministic image_findings are hints and never the complete review set. An empty image_findings list does not mean that every image question was resolved. Deterministic pair hints compare two regions within one registered asset only; they do not compare assets.
3. Confirm the current Agent can open local images.
   • If yes, inspect the whole image first, then use a native-pixel crop for small panels or unresolved detail.
   • If no, set image_review.status to unavailable_no_multimodal, continue numeric review, and state that image semantic review was not completed.
4. For every asset, record exactly one coverage outcome in reviewed_asset_ids, unresolved_asset_ids, unreadable_asset_ids, or deferred_asset_ids. image_review.status: "completed" means coverage accounting is complete; it does not mean every image question was explained.
5. Check figure labels, channels, processing steps, shared controls, insets, before/after layouts, figure legends, and Methods before escalating an image similarity signal.
6. The external multimodal Agent is responsible for cross-asset comparison and may create an image finding using image_refs even when image_findings is empty. Such Agent-only image findings belong in the verdict, not in deterministic scan.json.
7. Put numeric and image findings in the same verdict.json findings[], then generate a single unified report with paperconan report.

PaperConan supplies registered local assets, bounded report previews, and optional deterministic hints. The external multimodal Agent is responsible for capability detection, semantic review, coverage accounting, and cautious contextual interpretation.

Review Modes

Choose the lightest mode that satisfies the user request:

• Single-paper scan: fetch/scan if needed, open the source table for serious findings, check labels/legend/Methods when available, then give a concise answer using references/report-templates.md only if a report is requested.
• Single-paper formal review: after scan and source-table verification, load references/adjudication-tiers.md and references/report-templates.md. Use Tier labels only as review priority / innocent-explanation difficulty, never as author-intent conclusions.
• Batch review: use references/batch-workflow.md. Keep deterministic paperconan output separate from agent judgment. Preserve DROP reasons because repeated false positives can guide future filters.
• Adversarial review: for Tier 1/Tier 2, PubPeer drafts, public-facing claims, or filter changes based on alleged false positives, load references/adversarial-review.md and try to refute the concern before confirming it.

Do not write a full eight-section report for ordinary scan summaries. Use the full report only for Tier 1/Tier 2 KEEP, PubPeer-style drafting, formal research-integrity notes, or when the user explicitly asks for it.

Report Positioning

The pipeline is scan → agent triage/judgment → adjudicated report. Keep the two report artifacts distinct:

• audit/report.html (from the bare CLI) is a deterministic detector / evidence browser — a triage worklist. It is false-positive-heavy by design and represents no judgment. It is an intermediate artifact, not the user-facing deliverable. Never present it as "the audit result".
• The user-facing deliverable is always agent-adjudicated, produced only after you triage scan.json, open the source tables for serious findings, and weigh benign explanations: a short adjudicated summary for ordinary cases, or the eight-section report (paperconan report scan.json --verdict verdict.json --out …) for Tier 1/Tier 2 KEEP and formal/public writing.

So the raw report.html is what you read to triage; the adjudicated summary or eight-section report is what the user receives. A plain CLI user who only runs paperconan <dir> has no agent in the loop, so they see only the raw browser — tell them the findings still need human/agent triage before they mean anything.

Install And Run

pip install paperconan
pip install "paperconan[image]" # image assets, PDF page rendering, optional hints
pip install "paperconan[all]"   # includes PDF / Word table extraction
paperconan --version
paperconan <input-dir>

On systems where pip install is rejected with an externally-managed-environment error (PEP 668 — e.g. Homebrew or Debian Python), install into an isolated environment instead of forcing --break-system-packages:

uv tool install "paperconan[all]"   # or: pipx install "paperconan[all]"
# or a plain virtualenv:
python3 -m venv ~/.venvs/paperconan && ~/.venvs/paperconan/bin/pip install "paperconan[all]"

Default output:

<input-dir>/audit/scan.json
<input-dir>/audit/report.html

Useful variants:

paperconan <input-dir> --out /tmp/audit-X
paperconan <input-dir> --md
paperconan <input-dir> --no-html
paperconan <input-dir> --profile forensic
paperconan <input-dir> --images
paperconan <input-dir> --images --image-diagnostics
paperconan report /tmp/audit-X/scan.json --verdict verdict.json --out adjudication.html

If Python or package access is unavailable, tell the user to run the command locally. A manual review may be offered only as a non-authoritative hint and must not be presented as paperconan output.

Fetching Data

Use fetch only when the user gives a DOI/title instead of local files:

paperconan fetch "<DOI or title>"
paperconan fetch "<DOI or title>" --json
paperconan fetch "<DOI>" --download <id> --out data/
paperconan fetch "<DOI or title>" --auto --images --out data/
paperconan data/
paperconan data/ --images

Prefer candidates with doi_in_related: true. Repository search can return unrelated deposits, so report weak matches honestly and do not imply "no data found" means "paper is clean". Do not bypass paywalls or scrape publisher sites.

Profiles

--profile {review,forensic,triage} changes what you see in scan.json:

• review is the default. It keeps likely false positives visible but may demote them to low.
• forensic preserves raw detector severity. Use it before saying a concerning hit was only low severity under the raw detector.
• triage hides likely false positives.

When a finding has profile_action: "demoted" or profile_action: "hidden", the active profile changed the visible severity. Use prefilter_reason, prefilter_flags, and false_positive_context to explain why, then decide whether the filter reason actually fits the table context.

For deterministic image hints, profile_action: "kept" is informational. Image hints do not pass through the numeric prefilter and are not demoted or hidden by review, forensic, or triage.

Reference Routing

Load references only when needed:

• references/output-schema.md: read before parsing scan.json or explaining fields such as profile_action, prefilter_reason, value_sample, col_a_sample, or cross_sheet_findings.
• references/detectors.md: read when interpreting a detector kind and its common false positives.
• references/judgment-rubric.md: read before ranking findings, judging within-column signals, or drafting PubPeer/research-integrity language.
• references/interpretation.md: read when composing the final user-facing answer or handling requests to accuse, expose, or escalate.
• references/adjudication-tiers.md: read before assigning Tier 1/2/3, KEEP, DROP, NEEDS_HUMAN, or impact_scope.
• references/report-templates.md: read before writing a formal report, PubPeer draft, research-integrity note, or batch verdict JSON.
• references/adversarial-review.md: read before confirming Tier 1/Tier 2, public-facing concerns, or proposed filter changes.
• references/batch-workflow.md: read when reviewing multiple papers or organizing candidate queues.
• references/case-patterns.md: read for synthetic calibration patterns only; do not treat them as real case precedents.

Judgment Discipline

• Never convert severity into an author-intent conclusion. Severity means anomaly strength after the active profile, not author intent.
• Never convert Tier 1/2/3 into an author-intent conclusion. Tier means follow-up priority and difficulty of innocent explanation after context review.
• Inspect cross-sheet reuse and cross-column transforms before weaker single-column patterns.
• Prefer benign structural explanations first: shared controls, re-plots, unit conversions, formulas, indices, ratios, normalized values, model outputs, detection floors, and bounded scoring scales.
• Treat within_col_* findings as false-positive-heavy by default. Do not strongly report n < 10, categorical/index labels, derived columns, fixed-denominator ratios, rounded grids, floors/ceilings, or repeated fill values.
• Use "needs human context" when you cannot confirm row independence, raw measurement status, formula generation, Methods/legend meaning, or original-table provenance.
• For PubPeer-style writing, provide concrete file/sheet/column evidence and questions for the authors; do not accuse authors or state an intent conclusion.
• Do not use real papers as public calibration examples unless the user has explicitly asked to prepare a specific public note and the evidence has been checked against source data and paper context.

Output Shape

A normal scan summary should include:

1. What was scanned and whether any files failed to parse.
2. The highest-priority findings after manual/field-level triage, grouped by file.
3. Concrete evidence snippets: detector kind, location, rule, n, and a small value sample when useful.
4. Plausible benign explanations and what would resolve them.
5. A pointer to report.html for highlighted table context.

For batch or agent-to-agent workflows, an optional verdict JSON may use: verdict, suspicion_tier, impact_scope, tier_why, drop_reason, innocent_explanation, needs_author_data, report_md, review_status, and finding_refs (selectors naming which scan finding(s) the verdict adjudicated, so the rendered report scopes its evidence panel to them). When a paper has more than one distinct finding, use a paper-level object with a findings array (each entry adjudicated on its own tier/status with its own finding_ref); the report then renders one self-contained block per finding. See references/adjudication-tiers.md and references/report-templates.md.

For adaptive image review, scan.json image_assets[] is the complete registered asset inventory while image_findings[] contains only optional deterministic hints. Add Agent conclusions as finding_type: "image" entries with image_refs, and add top-level image_review coverage. Numeric and image entries, including Agent-only cross-asset observations, all remain in the same findings[] and the single unified report; do not create a separate image verdict or a second user-facing report.

When a verdict JSON already exists, paperconan report <scan.json> --verdict <verdict.json> --out <html> renders a separate adjudicated report. Do not confuse this with the default deterministic audit/report.html; the adjudicated report is only as reliable as the human/AI verdict and source context behind it.

If the user asks for an author-intent conclusion, answer that paperconan cannot determine that. The next step is to verify the original data and, if concerns remain, ask for clarification through PubPeer, the journal, or a research integrity office.