@zenalexa/unicli 0.225.1 → 0.225.3

package/src/adapters/pmlr/proceedings.ts

@@ -1,12 +1,12 @@
 /**
  * @owner       src::adapters::pmlr::proceedings
- * @does        Registers Proceedings of Machine Learning Research volume search using official citeproc.yaml metadata.
- * @needs       proceedings.mlr.press citeproc.yaml files, js-yaml, src/registry.ts
- * @feeds       src/commands/scholar.ts via scholar.search, scholar.get, scholar.pdf, and scholar.venue
- * @breaks      Missing volume metadata or citeproc drift surfaces as explicit adapter errors.
+ * @does        Registers Proceedings of Machine Learning Research volume search, paper lookup, and PDF text reading using official citeproc.yaml metadata.
+ * @needs       proceedings.mlr.press citeproc.yaml/PDF assets, js-yaml, src/adapters/scholar-artifacts/pdf-read.ts, src/registry.ts
+ * @feeds       src/commands/scholar.ts via scholar.search, scholar.get, scholar.pdf, scholar.fulltext, and scholar.venue
+ * @breaks      Missing volume metadata, citeproc/PDF drift, denied downloads, or missing pdftotext surfaces as explicit adapter errors.
  * @invariants  Volume is explicit; rows are filtered locally from official YAML metadata, not scraped from rendered cards.
- * @side-effects HTTPS egress to proceedings.mlr.press only
- * @perf        O(N) over one proceedings volume
+ * @side-effects HTTPS egress to proceedings.mlr.press/raw.githubusercontent.com; read writes one PDF artifact and executes pdftotext.
+ * @perf        O(N) over one proceedings volume; read is O(PDF bytes + selected pages)
  * @concurrency safe
  * @test        tests/unit/adapters/scholar-sources.test.ts
  * @stability   experimental
@@ -16,6 +16,7 @@
 import yaml from "js-yaml";
 import { cli, Strategy } from "../../registry.js";
 import type { ScholarlyWorkRecord } from "../../types/scholarly.js";
+import { readScholarPdf } from "../scholar-artifacts/pdf-read.js";
 
 interface PmlrEntry {
   title?: unknown;
@@ -102,6 +103,44 @@ async function fetchVolume(volume: string): Promise<PmlrEntry[]> {
   return parsePmlrCiteproc(await response.text());
 }
 
+async function findPmlrPaper(
+  volume: string,
+  id: string,
+): Promise<ScholarlyWorkRecord> {
+  const row = (await fetchVolume(volume))
+    .map((entry) => mapPmlrEntry(entry, "pmlr"))
+    .find((entry) => entry.id === id);
+  if (!row) throw new Error(`No PMLR v${volume} paper found with id "${id}".`);
+  return row;
+}
+
+async function readPmlrPaperPdf(
+  row: ScholarlyWorkRecord,
+  kwargs: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  if (!row.pdf_url) throw new Error(`PMLR paper ${row.id} has no PDF URL.`);
+  return readScholarPdf(
+    {
+      id: row.id,
+      title: row.title,
+      source_adapter: "pmlr",
+      source_url: row.source_url,
+      pdf_url: row.pdf_url,
+      output: kwargs.output,
+      filename: kwargs.filename,
+      "first-page": kwargs["first-page"] ?? kwargs.firstPage,
+      "last-page": kwargs["last-page"] ?? kwargs.lastPage,
+      "max-chars": kwargs["max-chars"] ?? kwargs.maxChars,
+    },
+    {
+      site: "pmlr",
+      command: "read",
+      defaultOutput: "./pmlr-downloads",
+      userAgent: "unicli-pmlr/1.0 (https://github.com/olo-dot-io/Uni-CLI)",
+    },
+  );
+}
+
 cli({
   site: "pmlr",
   name: "search",
@@ -157,11 +196,62 @@ cli({
     const id = String(kwargs.id ?? kwargs.ref ?? "").trim();
     if (!id) throw new Error("pmlr paper id is required.");
     const volume = requireVolume(kwargs.volume);
-    const row = (await fetchVolume(volume))
-      .map((entry) => mapPmlrEntry(entry, "pmlr"))
-      .find((entry) => entry.id === id);
-    if (!row)
-      throw new Error(`No PMLR v${volume} paper found with id "${id}".`);
-    return [row];
+    return [await findPmlrPaper(volume, id)];
+  },
+});
+
+cli({
+  site: "pmlr",
+  name: "read",
+  description:
+    "Download a PMLR paper PDF by id inside a proceedings volume and extract text",
+  domain: "proceedings.mlr.press",
+  strategy: Strategy.PUBLIC,
+  args: [
+    { name: "id", type: "str", required: true, positional: true },
+    { name: "volume", type: "str", default: "235" },
+    {
+      name: "output",
+      type: "str",
+      default: "./pmlr-downloads",
+      description: "Output directory for the downloaded PDF",
+      "x-unicli-kind": "path",
+    },
+    { name: "filename", type: "str", description: "Output PDF filename" },
+    { name: "first-page", type: "int", default: 1, description: "First page" },
+    { name: "last-page", type: "int", default: 20, description: "Last page" },
+    {
+      name: "max-chars",
+      type: "int",
+      default: 40000,
+      description: "Maximum extracted text characters",
+    },
+  ],
+  columns: [
+    "id",
+    "title",
+    "source_adapter",
+    "source_url",
+    "pdf_url",
+    "path",
+    "text_source",
+    "text",
+    "text_chars",
+    "text_truncated",
+  ],
+  capabilities: [
+    "http.fetch",
+    "http.download",
+    "subprocess.exec",
+    "scholar.fulltext",
+    "scholar.pdf",
+  ],
+  executables: ["pdftotext"],
+  minimum_capability: "subprocess.exec",
+  func: async (_page, kwargs) => {
+    const id = String(kwargs.id ?? kwargs.ref ?? "").trim();
+    if (!id) throw new Error("pmlr paper id is required.");
+    const volume = requireVolume(kwargs.volume);
+    return [await readPmlrPaperPdf(await findPmlrPaper(volume, id), kwargs)];
   },
 });

package/src/adapters/pubmed/articles.test.ts

@@ -1,9 +1,13 @@
 import { describe, expect, it } from "vitest";
 import {
+  mapPmcFullTextRow,
+  mapPubMedArticleRecord,
   mapPubMedArticleRows,
   mapPubMedSummaryRows,
+  normalizePmcId,
   requirePmid,
   requirePubMedLimit,
+  requirePubMedMaxChars,
   requirePubMedText,
 } from "./articles.js";
 
@@ -13,9 +17,15 @@ describe("pubmed agent-facing commands", () => {
     expect(() => requirePubMedText("", "query")).toThrow("cannot be empty");
     expect(requirePmid("37780221")).toBe("37780221");
     expect(() => requirePmid("PMID:1")).toThrow("numeric PMID");
+    expect(normalizePmcId("8938715")).toBe("PMC8938715");
+    expect(normalizePmcId("PMC8938715")).toBe("PMC8938715");
+    expect(() => normalizePmcId("pmc:8938715")).toThrow("not valid");
     expect(requirePubMedLimit(undefined)).toBe(20);
     expect(requirePubMedLimit("100")).toBe(100);
     expect(() => requirePubMedLimit("0")).toThrow("pubmed limit must");
+    expect(requirePubMedMaxChars(undefined)).toBe(40000);
+    expect(requirePubMedMaxChars("1000")).toBe(1000);
+    expect(() => requirePubMedMaxChars("999")).toThrow("max-chars");
   });
 
   it("maps PubMed summary rows in PMID order", () => {
@@ -34,7 +44,10 @@ describe("pubmed agent-facing commands", () => {
             source: "Journal",
             pubdate: "2026 May",
             pubtype: ["Journal Article"],
-            articleids: [{ idtype: "doi", value: "10.1/example" }],
+            articleids: [
+              { idtype: "doi", value: "10.1/example" },
+              { idtype: "pmc", value: "PMC123456" },
+            ],
           },
           {
             uid: "1",
@@ -51,6 +64,7 @@ describe("pubmed agent-facing commands", () => {
     ).toMatchObject([
       {
         rank: 1,
+        id: "1",
         pmid: "1",
         title: "First",
         authors: "Hopper G",
@@ -59,9 +73,12 @@ describe("pubmed agent-facing commands", () => {
       },
       {
         rank: 2,
+        id: "2",
         pmid: "2",
         authors: "Ada, Grace, Linus, et al.",
         doi: "10.1/example",
+        pmc_id: "PMC123456",
+        source_adapter: "pubmed",
       },
     ]);
   });
@@ -77,12 +94,14 @@ describe("pubmed agent-facing commands", () => {
         <PubDate><Year>2026</Year></PubDate>
         <PublicationType>Journal Article</PublicationType>
         <Language>eng</Language>
+        <ArticleId IdType="pmc">PMC123456</ArticleId>
         <ArticleId IdType="doi">10.1/example</ArticleId>
       </PubmedArticle>
       `,
       "123",
     );
     expect(rows).toContainEqual({ field: "PMID", value: "123" });
+    expect(rows).toContainEqual({ field: "PMCID", value: "PMC123456" });
     expect(rows).toContainEqual({ field: "Title", value: "Test & Treat" });
     expect(rows).toContainEqual({ field: "DOI", value: "10.1/example" });
     expect(rows).toContainEqual({
@@ -93,4 +112,72 @@ describe("pubmed agent-facing commands", () => {
       "did not include a title",
     );
   });
+
+  it("maps normalized PubMed article metadata rows", () => {
+    const row = mapPubMedArticleRecord(
+      `
+      <PubmedArticle>
+        <ArticleTitle>Normalized Article</ArticleTitle>
+        <Abstract><AbstractText>Abstract text</AbstractText></Abstract>
+        <Author><LastName>Ada</LastName><Initials>L</Initials></Author>
+        <Journal><Title>Journal</Title></Journal>
+        <PubDate><Year>2026</Year></PubDate>
+        <PublicationType>Journal Article</PublicationType>
+        <Language>eng</Language>
+        <ArticleId IdType="pmc">PMC123456</ArticleId>
+        <ArticleId IdType="doi">10.1/example</ArticleId>
+      </PubmedArticle>
+      `,
+      "123",
+    );
+
+    expect(row).toMatchObject({
+      id: "123",
+      pmid: "123",
+      title: "Normalized Article",
+      authors: ["Ada L"],
+      doi: "10.1/example",
+      pmc_id: "PMC123456",
+      source_adapter: "pubmed",
+      source_url: "https://pubmed.ncbi.nlm.nih.gov/123/",
+    });
+  });
+
+  it("maps PMC JATS XML into source-direct full text", () => {
+    const row = mapPmcFullTextRow(
+      `
+      <article>
+        <front>
+          <article-meta>
+            <article-id pub-id-type="pmcid">PMC123456</article-id>
+            <article-id pub-id-type="pmid">123</article-id>
+            <article-id pub-id-type="doi">10.1/example</article-id>
+            <title-group><article-title>Full Text Article</article-title></title-group>
+          </article-meta>
+        </front>
+        <abstract><p>Abstract paragraph.</p></abstract>
+        <body>
+          <sec><title>Introduction</title><p>First body paragraph.</p></sec>
+          <sec><title>Methods</title><p>Second body paragraph.</p></sec>
+        </body>
+      </article>
+      `,
+      "PMC123456",
+      1000,
+    );
+
+    expect(row).toMatchObject({
+      id: "123",
+      title: "Full Text Article",
+      pmid: "123",
+      pmc_id: "PMC123456",
+      doi: "10.1/example",
+      source_adapter: "pubmed",
+      source_url: "https://pmc.ncbi.nlm.nih.gov/articles/PMC123456/",
+      text_truncated: false,
+    });
+    expect(row.text).toContain("## Abstract");
+    expect(row.text).toContain("## Introduction");
+    expect(row.text).toContain("First body paragraph.");
+  });
 });