paperread

name	paperread
description	Read surface-research PDFs or JSON records and extract structured reaction, material, and modeling information for downstream agent workflows.
metadata	{"tools":["run_skill_script"],"dependent_skills":["ptomodel"],"tags":["paperread","pdf","extraction","surface","literature"]}

Paperread

Use this skill when the task starts from a paper PDF or a prepared JSON text record and the agent needs structured outputs instead of a free-form summary.

This skill is the entrypoint for the local paperread/surface pipeline and its reusable surface-paper experience loop:

paper PDF or JSON text
-> paperread extraction
-> table / time / relations / summary / ptomodel json
-> optional experience collection
-> unknown-term export / parameter registry update
-> downstream ptomodel / surface-modeling or later skill updates

Script

Script:

scripts/paperread_tools.py

Run it with run_skill_script:

run_skill_script(
  skill_name="paperread",
  script_name="paperread_tools.py",
  args="surface-pipeline --input /abs/path/to/paper.pdf --output-dir ./paperread_output --collect-experience"
)

Main Commands

Surface Pipeline

Default command for a surface-material reaction paper:

python scripts/paperread_tools.py surface-pipeline \
  --input /abs/path/to/paper.pdf \
  --output-dir ./paperread_output \
  --collect-experience

Supported input:

• PDF paper
• JSON file containing paper text records

Main outputs:

• *_table.csv
• *_time.csv
• *_surface_relations.jsonl
• *_summary.txt
• *_ptomodel.json

Optional intermediate outputs:

• *_text.txt
• *_sections.json
• *_conditions_input.json
• *_relations_input.json
• *_raw.csv

Use --keep-intermediate when debugging extraction quality. Use --save-raw when raw condition rows are needed.

The pipeline now also writes *_ptomodel.json, but the preferred downstream entrypoint for this bridge step is the separate ptomodel skill.

Collect Experience From Existing Outputs

python scripts/paperread_tools.py collect-experience \
  --relations ./paperread_output/paper_surface_relations.jsonl \
  --table ./paperread_output/paper_table.csv \
  --write-run-file \
  --write-markdown

Use this when extraction has already run and you only want to accumulate useful or unfamiliar material/modeling information for later review.

Initialize Experience Store

python scripts/paperread_tools.py init-material-classes \
  --output-dir paperread/surface/experience

Export Unknown Terms

Use this when extraction finds unfamiliar surface-research terms, unsupported modeling cues, or concepts that cannot yet be mapped to a supported workflow.

python scripts/paperread_tools.py export-unknown-terms \
  --relations ./paperread_output/paper_surface_relations.jsonl \
  --table ./paperread_output/paper_table.csv

Default outputs:

• agents/Agent/skills/paperread/experience/unrecognized_surface_terms.jsonl
• agents/Agent/skills/paperread/experience/unrecognized_surface_terms.md

Add A Manual Term

Use this when the researcher sees an unfamiliar paper term directly:

python scripts/paperread_tools.py add-term \
  --term "exsolved nanoparticle" \
  --category "surface modifier" \
  --context "Appears in a catalyst paper but is not mapped to a workflow yet." \
  --suggested-action "Decide whether this maps to cluster generation or a new exsolution workflow."

Build Parameter Registry

Build the reusable surface vocabulary from material-class experience:

python scripts/paperread_tools.py build-parameter-registry

Default outputs:

• agents/Agent/skills/paperread/experience/surface_parameter_registry.json
• agents/Agent/skills/paperread/experience/surface_parameter_registry.md

Recommended Usage Policy

• Use surface-pipeline as the default paperread entrypoint.
• Read *_summary.txt first for a quick modeling-oriented overview.
• Read *_surface_relations.jsonl when the task needs structured entities, surfaces, facets, adsorbates, defects, single atoms, clusters, or suggested modeling tasks.
• Read *_ptomodel.json when the task should directly continue into surface-modeling rather than stopping at literature extraction.
• Read *_table.csv when the task needs preparation or reaction conditions.
• If paperread extracts unfamiliar terms or unsupported modeling cues, use export-unknown-terms or add-term inside this skill.
• If the extracted paper clearly maps to a supported modeling workflow, follow with surface-modeling.

Knowledge Loop Policy

This skill must participate in the Agent knowledge loop:

paper PDF / JSON
-> structured extraction
-> experience collection
-> material-class keyword statistics
-> parameter registry
-> ptomodel / surface-modeling reuse
-> repeated evidence promoted into durable knowledge

Before reading a new batch of papers, prefer existing reusable knowledge over starting from a blank prompt:

• Check paperread/surface/experience/material_classes/*.json for known material classes, active sites, adsorbates, dopants, defects, reactions, and modeling keywords.
• Check agents/Agent/skills/paperread/experience/surface_parameter_registry.json for vocabulary that should guide extraction.
• Use agent knowledge stats when the user wants to inspect the graph state before a large paper-reading run.

During extraction, preserve structured evidence that can be reused later:

• Keep *_surface_relations.jsonl as the main entity and relation record.
• Keep *_table.csv for preparation, reaction, amount, and condition evidence.
• Keep *_ptomodel.json for downstream task mapping.
• Use --collect-experience whenever the output should improve future paper-reading or modeling.

After extraction, do not treat the paper summary as the final knowledge store. Run experience collection so repeated terms become statistics:

• Collect material identity, element composition, material class, surface, facet, termination, defect, dopant, active site, adsorbate, coverage, cluster, single atom, modifier, reaction, and modeling task keywords.
• Keep surface-site associations explicit when a paper ties a facet to a site role; metal surfaces often use top/bridge/hollow language, while oxides often use facet plus active-site wording.
• Store only compact source/context examples; the goal is keyword statistics and reusable parameter cues, not a long source list.
• Send unfamiliar or unmapped terms to this skill's unknown-term experience store with export-unknown-terms or add-term.

Class-specific reuse rules:

• Treat mineral or structure-prototype names as crystal-structure cues, not generic material names. Reuse the surface crystal-structure dictionary for terms such as rutile, anatase, brookite, spinel, normal spinel, inverse spinel, perovskite, fluorite, wurtzite, rocksalt, pyrochlore, delafossite, brucite, and corundum. These terms often imply crystal system, likely space group family, and which facet notation may be meaningful.
• Treat repeated composite material names, variable compositions, and adsorbed intermediate formulae through the surface material vocabulary before adding them to unknown terms. Examples include graphitic carbon nitride (g-C3N4), layered double hydroxides (LDH, NiFe LDH, NiCo LDH/CC), black phosphorus, BSCF-type perovskites, NixPy, single-atom/support shorthand, electrolyte concentrations, and adsorbed species notation such as *OH, *O, *OOH, Hads, and OHads.
• supported_catalysts: track support, loaded species, loading amount, nanoparticle or cluster identity, exposed support facet, and any adsorption site naming that reuses the support surface.
• carbon_materials: track 2D carbon host, doped element, N/O/S coordination, vacancy or defect motif, and single-atom center.
• metals_alloys: track alloy elements, high-entropy composition, element ratios, exposed crystal face, and top/bridge/hollow adsorption-site cues.
• oxides: track oxide formula, polymorph, space group, surface facet, termination, oxygen vacancy, dopant, and active-site wording tied to the facet.
• perovskites_spinels: track A/B-site species, substitution, oxygen vacancy, space group, exposed facet, and site/facet coupling if the paper names both.

When enough repeated evidence exists, use the Agent graph commands to turn working memory into durable knowledge:

• agent knowledge seed after skill or guide updates.
• agent knowledge distill --min-evidence 3 after repeated successful extraction patterns appear.
• agent knowledge migrate only when old memory stores need to be unified into know_do_graph.db.