Acquire Research Papers

简体中文

Acquire Research Papers is an agent skill and deterministic CLI for paper acquisition and library management. Codex, Claude Code, Kiro IDE, and Kiro CLI share the same skill:

• fetch a known paper from its DOI or official publisher page;
• build an auditable corpus for specified venues, years, topics, and quotas;
• prepare and carry out literature research for nearest work, claim evidence, Related Work, or gap analysis;
• audit, update, import, and organize local PDF/BibTeX libraries with reviewable plans and backups;
• discover an author's publications with explicit identity, date, and source-coverage evidence.

Documentation · Latest release · Changelog · Contributing · Help and feedback · Security

A completed acquisition is an identity-verified pair: the official publisher PDF and the publisher's raw BibTeX export. Crossref, OpenAlex, and Semantic Scholar can discover and enrich candidates, but they never replace those official artifacts. The project does not use mirrors, generate citations with an LLM, or bypass publisher access controls.

This README is a summary. The documentation site (English and 简体中文) has the complete guides, specification examples, and output reference.

Contents

• Start: choose the workflow · install · first use · quick start
• How it works: corpus discovery · literature research · sources
• Scope and project: trust boundaries · limitations · roadmap · development · citation

Choose the workflow

The executing agent is part of the workflow. The CLI validates, checkpoints, freezes, and acquires deterministic artifacts; the agent translates the user's request into explicit inputs and makes the recorded semantic review decisions.

Install

Install the skill with the standard Skills installer (Node.js/npm required); no developer clone or development dependency sync is needed:

npx skills add EnosElinsa/acquire-research-papers --skill acquire-research-papers -a codex -g

Use Python 3.11+ and uv. Resolve the actual directory returned by the installer; the shared default is normally ~/.agents/skills/acquire-research-papers:

$skill = Join-Path $env:USERPROFILE ".agents/skills/acquire-research-papers"
python "$skill/scripts/arp.py" --help
python "$skill/scripts/arp.py" config status

The standard-library launcher reads runtime.json, downloads the fixed release wheel, verifies SHA-256, and installs it with uv into a separate cache. File configuration and core commands support Windows/macOS/Linux. Current IEEE browser access and legacy DPAPI require Windows, PowerShell, and Node.js; on macOS and Linux, IEEE papers join the manual-download queue. Update by rerunning the same install command. From v0.16.0, the CLI alone also installs from PyPI with uv tool install acquire-research-papers. Install covers other hosts, arp doctor, release verification with gh attestation verify, and migrating from a developer checkout.

Release downloads and manual installation

The v0.17.0 release provides:

Do not copy the source archive or a developer checkout into the skill directory. See SUPPORT.md for bootstrap and migration troubleshooting.

First use: configure only what this task needs

Start by asking which optional capabilities are already configured:

python "$skill/scripts/arp.py" config status

The command returns capability booleans only and never prints secret values. A true result means local configuration exists; it does not prove live API or publisher entitlement. Configure only a capability required by this task, then test it with a representative operation.

Secret prompts are interactive and non-echoing. Never paste a password, API key, token, or cookie into chat, an agent message, a command argument, or a repository file. Configuration explains the editable credential files and named institution profiles.

Quick start

Fetch one known paper:

python "$skill/scripts/arp.py" fetch `
  --input "https://aclanthology.org/2024.acl-long.1/" `
  --output "C:\Research\papers"

Use the output only when the JSON status is delivered. A title alone must first be resolved through discovery; the fetch command will not guess between similarly named papers.

Corpus and research runs start from a specification or brief that the executing agent writes from your request. arp is shorthand for python "$skill/scripts/arp.py":

arp discover corpus --progress --spec corpus.yaml --output <corpus-run>
arp review corpus --run <corpus-run> --decisions <review-decisions.jsonl>
arp acquire corpus --selection <corpus-run>/selection-manifest.json --output <delivery>

arp discover research --brief research-brief.yaml --output <research-run>
arp review research --run <research-run> --decisions <research-review.jsonl>
arp acquire research --run <research-run>
arp evidence research --run <research-run> --records <evidence-review.jsonl>

The quick start has a complete corpus specification and research brief to copy.

How corpus discovery actually works

Corpus discovery is designed for bounded requests such as “papers from these venues, during these years, about these topics.” It records the boundary, enumerates official indexes (ACL, IJCAI, NeurIPS, ICLR, PMLR, CVF, USENIX) or Crossref by ISSN, collection DOI, venue, and year, and marks every venue/year slice complete, partial, or failed. Records are deduplicated by DOI and enriched with abstracts. Keywords only nominate candidates: acceptance requires the executing agent to judge both title and abstract and record a reason. The selection is hashed and frozen before acquisition, which cannot add, remove, or replace papers.

Two pending states are expected:

• pending_abstract means no trustworthy abstract was obtained. The paper is kept for later enrichment and cannot be automatically accepted from its title alone.
• ready_unreviewed (often seen as decision_missing) means the candidate has sufficient metadata but was not semantically reviewed, commonly because the preferred total and every quota were already satisfied. It cannot enter the selection.

An inaccessible paper stays in the frozen selection and is written to manual-download.csv; a transient failure goes to retryable-downloads.csv. Reruns resume from checkpoints. See corpus discovery and acquisition.

How literature research actually works

A defensible literature investigation needs more than one keyword query. The skill searches with four complementary passes (direct terminology, mechanism decomposition, citation expansion, and falsification) in an explicit, resumable pipeline:

• discover research searches Crossref plus configured Semantic Scholar/OpenAlex sources and expands a bounded citation graph into citation-graph.json. search-saturation.json records whether the last query passes and graph steps were still adding new papers, and its signals say whether to broaden the brief or widen the graph. Discovery returns status: review_required.
• review research requires one explicit agent include/exclude decision for every hash-bound candidate, then freezes the closest papers for full-text checking.
• acquire research reuses the official publisher workflow and parses verified PDFs through the MinerU cache.
• evidence research verifies paper IDs, hashes, claims, locations, and excerpts before writing the report; --export-csv adds papers.csv and claim-coverage.csv.

Title and abstract only nominate candidates. Direct support and contradiction require a full-text excerpt with a section or page, and gap conclusions are bounded to the searched scope. See literature research.

Source support and maturity

The IEEE flow is generic and profile-driven; it has been live-tested end to end with one CARSI institution, and every additional institution requires first-use adaptation. Run arp sources --spec <corpus.yaml> for offline per-venue/year gaps. Source support has the full table with live-test results and the venue presets.

Accuracy and trust boundaries

The project improves reliability in three different ways:

• Coverage accountability: venue/year enumeration and a coverage ledger are stronger than trusting the first page of keyword results. They still cannot guarantee that upstream indexes contain every paper.
• Relevance accountability: deterministic hard gates and prefiltering reduce noise, but an accepted paper requires a recorded agent judgment over title and abstract. This is more auditable than keyword-only acceptance, not a proof of universal semantic accuracy.
• Artifact identity: official-host boundaries, raw publisher BibTeX, metadata comparison, provenance, and hashes give the strongest guarantee in the system: the delivered files correspond to the frozen paper.

The repository has regression tests for its contracts and has completed real multi-venue corpus runs. It does not yet have a large, independently labeled cross-domain benchmark, so it must not advertise a measured precision/recall score. Missing abstracts, incomplete current-year indexes, ambiguous records, and boundary relevance judgments are reported rather than guessed.

Current limitations

• The full IEEE/CARSI path has been live-validated with one CARSI institution; IEEE browser integration is Windows-only.
• ACM and ScienceDirect papers are manual downloads; the project does not automate organization login.
• Research mode is staged and requires explicit agent decisions; it is not an unattended one-command systematic review.
• Citation-graph coverage is bounded by seeds, neighbor limits, and provider coverage; neither the graph nor the saturation record proves universal recall.
• New proceedings and inconsistent upstream metadata can leave coverage incomplete.
• arp config status: true confirms stored configuration shape, not live credentials, quota, subscription, or API entitlement.
• Claude Code and Kiro interactive execution have not been live verified.

Trust and limitations lists every known limitation.

Roadmap

Near-term priorities, not claims about current support: follow-up discovery that reuses a finished research run, clearer IEEE institution diagnostics, a dedicated ACM authorized-access contract, safe delta acquisition into existing libraries, and more composition guidance. See the roadmap.

Development

See CONTRIBUTING.md for development setup, Python/Node/PowerShell checks, wheel/skill builds, isolated installation, release validation, and the documentation site. Participation is governed by the Code of Conduct; questions and bug reports go through SUPPORT.md, and vulnerabilities through SECURITY.md.

Citation

If this tool supports published research, cite the release you used. CITATION.cff holds the citation metadata; GitHub shows it as "Cite this repository" on the repository page.

Responsible use

Use institutional access only within the account and license terms that authorize the requested material. The project does not bypass publisher controls, redistribute acquired papers, automate prohibited publisher interactions, or weaken an institution's authentication flow.

Licensed under the MIT License.