@fbraza/pi-cite 0.2.0 → 0.3.1

package/src/rendering.ts

@@ -2,7 +2,7 @@ import { Text } from "@earendil-works/pi-tui";
 import type { PaperRecord } from "./types.ts";
 
 export const MAX_STREAMED_PAPERS_PER_QUERY = 5;
-export const MAX_FINAL_MERGED_PAPERS = 20;
+export const MAX_EXPANDED_PAPER_PREVIEW = 5;
 
 type ThemeLike = {
   fg?: (color: string, text: string) => string;
@@ -16,37 +16,35 @@ export type CompactPaperForDisplay = {
   source: string;
   year?: number;
   journal?: string;
-  citation_count?: number;
 };
 
 export type LiteratureSearchDisplayEvent =
   | { phase: "start" }
   | {
       phase: "query_start";
-      provider: "pubmed" | "semantic_scholar";
+      provider: "pubmed";
       query_index: number;
       query: string;
     }
   | {
       phase: "query_results";
-      provider: "pubmed" | "semantic_scholar";
+      provider: "pubmed";
       query_index: number;
       query: string;
       count: number;
-      papers: CompactPaperForDisplay[];
     }
   | {
       phase: "query_error";
-      provider: "pubmed" | "semantic_scholar";
+      provider: "pubmed";
       query_index: number;
       query: string;
       error: string;
     }
   | { phase: "dedupe" }
-  | { phase: "complete"; count: number; papers: CompactPaperForDisplay[] };
+  | { phase: "complete"; count: number };
 
 export type LiteratureSearchDisplaySearch = {
-  provider: "pubmed" | "semantic_scholar";
+  provider: "pubmed";
   query_index: number;
   query: string;
   count: number;
@@ -107,7 +105,6 @@ export function authorRange(paper: PaperRecord): string {
 export function paperIdentifier(paper: PaperRecord): string {
   if (paper.doi) return `DOI:${paper.doi}`;
   if (paper.pmid) return `PMID:${paper.pmid}`;
-  if (paper.s2_id) return `S2:${paper.s2_id}`;
   return "—";
 }
 
@@ -120,12 +117,8 @@ export function sourceLabel(paper: PaperRecord): string {
       .map((source) => source.trim())
       .filter(Boolean),
   );
-  const hasPubmed = sources.has("pubmed");
-  const hasS2 = sources.has("semantic_scholar");
-  if (hasPubmed && hasS2) return "PM+S2";
-  if (hasPubmed) return "PM";
-  if (hasS2) return "S2";
-  return paper.source ?? "—";
+  if (sources.has("pubmed")) return "PM";
+  return "—";
 }
 
 export function compactPaperForDisplay(paper: PaperRecord): CompactPaperForDisplay {
@@ -136,7 +129,6 @@ export function compactPaperForDisplay(paper: PaperRecord): CompactPaperForDispl
     source: sourceLabel(paper),
     year: paper.year,
     journal: paper.journal,
-    citation_count: paper.citation_count,
   };
 }
 
@@ -144,12 +136,16 @@ export function compactPapersForDisplay(papers: PaperRecord[]): CompactPaperForD
   return papers.map(compactPaperForDisplay);
 }
 
-function providerLabel(provider: "pubmed" | "semantic_scholar"): string {
-  return provider === "pubmed" ? "PubMed" : "Semantic Scholar";
+function providerLabel(provider: "pubmed"): string {
+  return "PubMed";
+}
+
+function providerColor(provider: "pubmed"): string {
+  return "success";
 }
 
-function providerColor(provider: "pubmed" | "semantic_scholar"): string {
-  return provider === "pubmed" ? "success" : "accent";
+function pluralize(count: number, singular: string, plural = `${singular}s`): string {
+  return count === 1 ? singular : plural;
 }
 
 export function formatFoundLine(
@@ -162,60 +158,14 @@ export function formatFoundLine(
   return `  ${color(theme, "success", "✓ found:")} ${author}  ${title}  ${color(theme, "muted", id)}`;
 }
 
-export function formatMergedLine(
+export function formatPaperPreviewLine(
   paper: CompactPaperForDisplay,
   index: number,
   theme?: ThemeLike,
 ): string {
-  const title = truncateText(paper.title, 72);
-  const source = color(theme, paper.source.includes("S2") ? "accent" : "success", `(${paper.source})`);
-  return `  ${color(theme, "success", "+")} ${index + 1}. ${title} ${source}`;
-}
-
-function renderEvent(
-  event: LiteratureSearchDisplayEvent,
-  theme?: ThemeLike,
-): string[] {
-  if (event.phase === "start") {
-    return [`${color(theme, "accent", "●")} ${color(theme, "toolTitle", "literature_search")} starting`];
-  }
-  if (event.phase === "query_start") {
-    return [
-      `${color(theme, providerColor(event.provider), "→")} ${color(theme, providerColor(event.provider), providerLabel(event.provider))} q${event.query_index}: ${event.query}`,
-    ];
-  }
-  if (event.phase === "query_results") {
-    const lines = event.papers
-      .slice(0, MAX_STREAMED_PAPERS_PER_QUERY)
-      .map((paper) => formatFoundLine(paper, theme));
-    const hidden = event.count - Math.min(event.count, MAX_STREAMED_PAPERS_PER_QUERY);
-    if (hidden > 0) lines.push(`  ${color(theme, "dim", "…")} ${hidden} more candidate papers`);
-    if (event.count === 0) lines.push(`  ${color(theme, "muted", "no candidate papers found")}`);
-    return lines;
-  }
-  if (event.phase === "query_error") {
-    return [
-      `  ${color(theme, "error", "! failed:")} ${providerLabel(event.provider)} q${event.query_index}: ${truncateText(event.error, 96)}`,
-    ];
-  }
-  if (event.phase === "dedupe") {
-    return [`${color(theme, "warning", "→")} deduplicating by DOI / PMID / title-year`];
-  }
-  const lines = event.papers
-    .slice(0, MAX_FINAL_MERGED_PAPERS)
-    .map((paper, index) => formatMergedLine(paper, index, theme));
-  const hidden = event.count - Math.min(event.count, MAX_FINAL_MERGED_PAPERS);
-  if (hidden > 0) lines.push(`  ${color(theme, "dim", "…")} ${hidden} more merged papers`);
-  lines.push(`${color(theme, "success", "✓")} done: ${event.count} merged papers`);
-  return lines;
-}
-
-export function renderLiteratureEventTranscript(
-  events: LiteratureSearchDisplayEvent[] | undefined,
-  theme?: ThemeLike,
-): string {
-  if (!events?.length) return "";
-  return events.flatMap((event) => renderEvent(event, theme)).join("\n");
+  const year = paper.year ? ` ${paper.year}` : "";
+  const title = truncateText(paper.title, 88);
+  return `  ${color(theme, "success", `${index + 1}.`)} ${paper.first_author}${year} — ${title}`;
 }
 
 type RenderOptions = { expanded?: boolean; isPartial?: boolean };
@@ -230,6 +180,7 @@ type ToolRenderResult<TDetails> = {
 type ProviderSearchSummary = {
   searched?: boolean;
   count?: number;
+  query?: string;
 };
 
 type LiteratureResultDetails = {
@@ -237,7 +188,6 @@ type LiteratureResultDetails = {
   papers?: PaperRecord[];
   providers?: {
     pubmed?: ProviderSearchSummary;
-    semantic_scholar?: ProviderSearchSummary;
   };
   events?: LiteratureSearchDisplayEvent[];
 };
@@ -249,12 +199,40 @@ type ProviderResultDetails = {
 };
 
 function renderCollapsedLiteratureResult(details: LiteratureResultDetails, theme?: ThemeLike): string {
-  const pubmed = details?.providers?.pubmed;
-  const s2 = details?.providers?.semantic_scholar;
-  const pubmedText = pubmed?.searched ? `PubMed: ${pubmed.count}` : "PubMed: —";
-  const s2Text = s2?.searched ? `S2: ${s2.count}` : "S2: skipped";
-  const count = details?.count ?? details?.papers?.length ?? 0;
-  return `${color(theme, "success", "✓")} ${color(theme, "toolTitle", "literature_search")} ${color(theme, "success", pubmedText)} | ${color(theme, "accent", s2Text)} | merged: ${count}`;
+  const count = details.count ?? details.papers?.length ?? details.providers?.pubmed?.count;
+  const prefix = `${color(theme, "success", "✓")} ${color(theme, "toolTitle", "literature_search")}`;
+  if (count === undefined) return `${prefix} PubMed papers`;
+  if (count === 0) return `${prefix} no PubMed papers found`;
+  return `${prefix} ${count} PubMed ${pluralize(count, "paper")}`;
+}
+
+function renderLiteratureStreamingStatus(details: LiteratureResultDetails, theme?: ThemeLike): string {
+  const event = details.events?.at(-1);
+  const prefix = `${color(theme, "accent", "●")} ${color(theme, "toolTitle", "literature_search")}`;
+  if (!event || event.phase === "start" || event.phase === "query_start" || event.phase === "dedupe") {
+    return `${prefix} searching PubMed…`;
+  }
+  if (event.phase === "query_error") {
+    return `${color(theme, "error", "!")} ${color(theme, "toolTitle", "literature_search")} PubMed failed: ${truncateText(event.error, 96)}`;
+  }
+  const count = event.count;
+  if (count === 0) return `${prefix} no PubMed papers found`;
+  return `${prefix} found ${count} PubMed ${pluralize(count, "paper")}`;
+}
+
+function renderExpandedLiteratureResult(details: LiteratureResultDetails, theme?: ThemeLike): string {
+  const papers = compactPapersForDisplay(details.papers ?? []);
+  const lines = [renderCollapsedLiteratureResult(details, theme)];
+  const query = details.providers?.pubmed?.query;
+  if (query) lines.push(`${color(theme, "muted", "query:")} ${truncateText(query, 96)}`);
+  lines.push(
+    ...papers
+      .slice(0, MAX_EXPANDED_PAPER_PREVIEW)
+      .map((paper, index) => formatPaperPreviewLine(paper, index, theme)),
+  );
+  const hidden = papers.length - Math.min(papers.length, MAX_EXPANDED_PAPER_PREVIEW);
+  if (hidden > 0) lines.push(`  ${color(theme, "dim", "…")} ${hidden} more ${pluralize(hidden, "paper")} in tool result`);
+  return lines.join("\n");
 }
 
 export function renderLiteratureSearchResult(
@@ -263,28 +241,17 @@ export function renderLiteratureSearchResult(
   theme?: ThemeLike,
 ): Text {
   const details = result.details ?? {};
-  const transcript = renderLiteratureEventTranscript(details.events, theme);
   if (options.isPartial) {
-    return terminalText(transcript || color(theme, "warning", "Searching literature..."));
+    return terminalText(renderLiteratureStreamingStatus(details, theme));
   }
   if (!options.expanded) {
     return terminalText(renderCollapsedLiteratureResult(details, theme));
   }
-  if (transcript) return terminalText(transcript);
-
-  const papers = compactPapersForDisplay(details.papers ?? []);
-  const lines = [
-    `${color(theme, "accent", "●")} ${color(theme, "toolTitle", "literature_search")} result`,
-    renderCollapsedLiteratureResult(details, theme),
-    `${color(theme, "warning", "→")} deduplicating by DOI / PMID / title-year`,
-    ...papers.slice(0, MAX_FINAL_MERGED_PAPERS).map((paper, index) => formatMergedLine(paper, index, theme)),
-    `${color(theme, "success", "✓")} done: ${papers.length} merged papers`,
-  ];
-  return terminalText(lines.join("\n"));
+  return terminalText(renderExpandedLiteratureResult(details, theme));
 }
 
 export function renderProviderSearchResult(
-  provider: "pubmed" | "semantic_scholar",
+  provider: "pubmed",
   result: ToolRenderResult<ProviderResultDetails>,
   options: RenderOptions,
   theme?: ThemeLike,
@@ -298,7 +265,7 @@ export function renderProviderSearchResult(
     return terminalText(color(theme, "warning", text));
   }
   if (!options.expanded) {
-    return terminalText(`${color(theme, "success", "✓")} ${color(theme, "toolTitle", provider === "pubmed" ? "pubmed_search" : "semantic_scholar_search")} ${papers.length} papers`);
+    return terminalText(`${color(theme, "success", "✓")} ${color(theme, "toolTitle", "pubmed_search")} ${papers.length} papers`);
   }
   const lines = [
     `${color(theme, providerColor(provider), "→")} ${color(theme, providerColor(provider), providerName)} q1: ${query}`,

package/src/shared.ts

@@ -1,5 +1,3 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import path from "node:path";
 import type { PaperRecord } from "./types.ts";
 
 export const USER_AGENT = "research-skills-literature-tools/0.1 (+https://github.com/fbraza/research-skills)";
@@ -82,22 +80,3 @@ export async function fetchJson<T>(url: string, signal?: AbortSignal, headers?:
 export function formatPaperText(papers: PaperRecord[]): string {
 	return JSON.stringify(papers, null, 2);
 }
-
-export function sanitizeFilename(value: string): string {
-	return value.replace(/[^a-z0-9._-]+/gi, "_").replace(/^_+|_+$/g, "") || "paper";
-}
-
-export async function savePdf(pdfUrl: string, outputDir: string, preferredId: string, signal?: AbortSignal): Promise<string> {
-	await mkdir(outputDir, { recursive: true });
-	const response = await fetch(pdfUrl, {
-		method: "GET",
-		signal,
-		headers: { "user-agent": USER_AGENT, accept: "application/pdf,*/*" },
-		redirect: "follow",
-	});
-	if (!response.ok) throw new Error(`Failed to download PDF (${response.status})`);
-	const bytes = Buffer.from(await response.arrayBuffer());
-	const filePath = path.resolve(outputDir, `${sanitizeFilename(preferredId)}.pdf`);
-	await writeFile(filePath, bytes);
-	return filePath;
-}

package/src/types.ts

@@ -1,7 +1,6 @@
 export type PaperRecord = {
 	pmid?: string;
 	doi?: string;
-	s2_id?: string;
 	title: string;
 	abstract?: string;
 	authors?: string[];
@@ -9,22 +8,10 @@ export type PaperRecord = {
 	year?: number;
 	publication_types?: string[];
 	mesh_terms?: string[];
-	citation_count?: number;
-	tldr?: string;
-	open_access_pdf?: string;
-	external_ids?: Record<string, string>;
 	source?: string;
 	sources?: string[];
 	date?: string;
 	category?: string;
 	version?: string;
 	license?: string;
-	pdf_url?: string;
-};
-
-export type FullTextRouteResult = {
-	source: string;
-	pdf_url?: string;
-	access_note: string;
-	is_preprint?: boolean;
 };

package/skills/literature/references/full-text-access-guide.md

@@ -1,34 +0,0 @@
-# Full-Text Access Guide
-
-**Workflow:** literature
-**Purpose:** Retrieve PDFs for prioritised papers using a consistent fallback chain.
-
-## Access order
-
-1. **PubMed Central (PMC)**
-   - Preferred for PubMed-indexed papers with open full text.
-   - Use PubMed/PMC linking first when a PMID is available.
-
-2. **Publisher open-access page**
-   - Resolve DOI at `https://doi.org/<doi>`.
-   - Look for `citation_pdf_url`, explicit PDF links, or embedded PDF viewers.
-
-3. **Sci-Hub fallback**
-   - Use only as the final fallback after OA routes are exhausted.
-   - Record that Sci-Hub was used.
-
-## Per-paper logging
-
-For each paper, record:
-- PMID
-- DOI
-- source used: `pmc`, `publisher_oa`, `scihub`, or `not_found`
-- direct PDF URL if found
-- local saved path if downloaded
-- access note
-
-## Notes
-
-- PMC and publisher OA should always be attempted before Sci-Hub.
-- If no DOI is known but PMID exists, try resolving identifiers from PubMed metadata first.
-- If no PDF is found, keep the paper in the synthesis and note `not_found`.

package/skills/literature/references/scihub_routine.md

@@ -1,40 +0,0 @@
-# Sci-Hub PDF Resolver — Routine Quick-Reference
-
-Resolves DOIs to direct PDF URLs via Sci-Hub mirrors. **Always check institutional access and open-access sources first** (PubMed Central, publisher OA). Use Sci-Hub only as a last resort.
-
-**Script:** `scripts/scihub_pdf_resolver.py` — zero-dependency Python script.
-
-## CLI Usage
-
-```bash
-python scripts/scihub_pdf_resolver.py "10.1038/s41586-024-07000-0"
-```
-
-## Output Codes
-
-| Output | Meaning |
-|---|---|
-| Prints a URL | Direct PDF link, ready to download |
-| `NOT_FOUND` | Sci-Hub does not have this paper. Check for `OA_LINK <url>` for open-access alternatives. |
-| `MIRROR_ERROR` | Sci-Hub mirrors could not be reached reliably |
-| `INVALID_INPUT` | The DOI is malformed |
-
-## Exit Codes
-
-`0` = found, `1` = not found, `2` = mirror error, `3` = invalid input.
-
-## Python API
-
-```python
-from scripts.scihub_pdf_resolver import resolve_pdf
-
-status, url = resolve_pdf("10.1038/s41586-024-07000-0")
-if status == "FOUND":
-    print(f"PDF available at: {url}")
-elif status == "NOT_FOUND" and url:
-    print(f"Open-access link: {url}")
-```
-
-## Mirror Configuration
-
-Set `SCIHUB_MIRRORS` environment variable (comma-separated URLs) to override defaults. Defaults: `sci-hub.st`, `sci-hub.ru`, `sci-hub.se`.

package/skills/literature/references/semanticscholar_routine.md

@@ -1,50 +0,0 @@
-# Semantic Scholar — Routine Quick-Reference
-
-Quick-start for paper search, paper lookup, and author search. For citation network analysis or bulk queries → consult the full API documentation.
-
-## Paper Search
-
-```
-GET https://api.semanticscholar.org/graph/v1/paper/search
-```
-
-**Parameters:**
-| Parameter | Value |
-|---|---|
-| `query` | Search terms |
-| `limit` | Max results (default 10, max 100) |
-| `offset` | Pagination offset |
-| `fields` | Comma-separated fields to return |
-| `year` | `<YYYY>` or `<YYYY-YYYY>` range |
-| `fieldsOfStudy` | Field of study filter |
-
-**Useful fields:** `paperId`, `title`, `abstract`, `year`, `referenceCount`, `citationCount`, `authors`, `journal`, `publicationTypes`, `tldr`, `openAccessPdf`, `externalIds`
-
-**Example:**
-```
-https://api.semanticscholar.org/graph/v1/paper/search?query=CRISPR+off-target&limit=20&fields=title,abstract,year,citationCount,openAccessPdf
-```
-
-## Paper Details (by ID)
-
-```
-GET https://api.semanticscholar.org/graph/v1/paper/{paper_id}
-```
-
-`paper_id` accepts: S2 ID, DOI (`DOI:10.xxx`), PMID (`PMID:12345`), ArXiv ID.
-
-**Example:**
-```
-https://api.semanticscholar.org/graph/v1/paper/DOI:10.1038/s41586-024-07000-0?fields=title,abstract,year,citationCount,references,citations
-```
-
-## Author Search
-
-```
-GET https://api.semanticscholar.org/graph/v1/author/search?query=<name>
-GET https://api.semanticscholar.org/graph/v1/author/{author_id}/papers
-```
-
-## Rate Limits
-
-100 requests / 5 min (unauthenticated). Higher limits available with an API key.