@inflexa-ai/harness 0.16.0 → 0.18.0

package/dist/tools/lib/monarch-client.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure async client functions for the Monarch Initiative association API.
+ *
+ * Monarch curates human gene→phenotype annotations (HPO, from HPOA/OMIM/
+ * Orphanet): *human* loss-of-function evidence, meaning what is observed in
+ * people carrying variation in the gene, as opposed to a mouse knockout's
+ * phenotype or an aggregate gene-disease association score.
+ *
+ * Each phenotype association carries its HPO ancestor closure, which is what
+ * lets a consumer resolve the phenotype onto an organ system by identifier
+ * rather than by matching prose.
+ *
+ * The API is keyless and public.
+ */
+/** A curated human phenotype attributed to variation in the gene. */
+export interface MonarchPhenotypeAssociation {
+    /** HPO term id, e.g. `HP:0001392`. */
+    readonly hpoId: string;
+    readonly label: string;
+    /** The term's HPO ancestor closure, for identifier-based organ resolution. */
+    readonly ancestorIds: string[];
+    /** PMIDs (as `PMID:…` curies) cited by the annotation. */
+    readonly publications: string[];
+    /** The disease the phenotype was annotated under, when the annotation names one. */
+    readonly diseaseContext: string | null;
+    /** Share of affected individuals showing the phenotype, when annotated. */
+    readonly frequencyPercent: number | null;
+    readonly primaryKnowledgeSource: string | null;
+}
+export interface MonarchGeneProfile {
+    /** The curie the gene was queried by, e.g. `HGNC:1097`. */
+    readonly geneCurie: string;
+    readonly phenotypes: MonarchPhenotypeAssociation[];
+}
+/**
+ * Curated human phenotype associations for one gene.
+ *
+ * `geneCurie` is a prefixed identifier Monarch resolves — an HGNC id
+ * (`HGNC:1097`) or an NCBI gene id (`NCBIGene:673`). A gene Monarch does not
+ * hold returns an empty profile rather than an error.
+ */
+export declare function getGenePhenotypeProfile(geneCurie: string): Promise<MonarchGeneProfile>;

package/dist/tools/lib/monarch-client.js

@@ -0,0 +1,100 @@
+/**
+ * Pure async client functions for the Monarch Initiative association API.
+ *
+ * Monarch curates human gene→phenotype annotations (HPO, from HPOA/OMIM/
+ * Orphanet): *human* loss-of-function evidence, meaning what is observed in
+ * people carrying variation in the gene, as opposed to a mouse knockout's
+ * phenotype or an aggregate gene-disease association score.
+ *
+ * Each phenotype association carries its HPO ancestor closure, which is what
+ * lets a consumer resolve the phenotype onto an organ system by identifier
+ * rather than by matching prose.
+ *
+ * The API is keyless and public.
+ */
+import { z } from "zod";
+import { apiFetchValidated, describeApiError, isUnexpectedApiError } from "./api-utils.js";
+const MONARCH_BASE = "https://api-v3.monarchinitiative.org/v3/api";
+/** Row cap per association category — a well-annotated gene carries a few hundred. */
+const ASSOCIATION_ROW_CAP = 300;
+/** The closure arrays make these responses large; the default timeout is short for them. */
+const REQUEST_TIMEOUT_MS = 120_000;
+const HUMAN_TAXON = "NCBITaxon:9606";
+/** Phenotype terms live in the HPO namespace; a model-organism term would not. */
+const HPO_NAMESPACE = "HP";
+/**
+ * One association row. Every field is optional because Monarch returns the same
+ * envelope for every category and populates only what applies; the reader below
+ * treats a missing field as absent rather than trusting the wire.
+ */
+const MonarchAssociationSchema = z.object({
+    subject_taxon: z.string().nullish(),
+    object: z.string().optional(),
+    object_label: z.string().nullish(),
+    object_closure: z.array(z.string()).nullish(),
+    publications: z.array(z.string()).nullish(),
+    primary_knowledge_source: z.string().nullish(),
+    disease_context_qualifier: z.string().nullish(),
+    has_percentage: z.number().nullish(),
+});
+const MonarchAssociationPageSchema = z.object({
+    items: z.array(MonarchAssociationSchema).optional(),
+});
+async function fetchAssociations(geneCurie, category) {
+    const params = new URLSearchParams({
+        subject: geneCurie,
+        category,
+        limit: String(ASSOCIATION_ROW_CAP),
+    });
+    const res = await apiFetchValidated(`${MONARCH_BASE}/association?${params.toString()}`, MonarchAssociationPageSchema, {
+        timeoutMs: REQUEST_TIMEOUT_MS,
+    });
+    if (res.isErr()) {
+        // A 4xx means the gene curie is not one Monarch holds — an expected
+        // "not found", returned as an empty page. Anything else is a real
+        // failure and surfaces.
+        if (isUnexpectedApiError(res.error))
+            throw new Error(describeApiError(res.error));
+        return [];
+    }
+    return res.value.items ?? [];
+}
+/**
+ * Human phenotype annotations only.
+ *
+ * Monarch serves a gene's phenotype edges from several annotation sets; the
+ * filter keeps the rows whose subject is the human gene and whose object is an
+ * HPO term, so model-organism phenotypes stay with the collector that owns them.
+ */
+function toPhenotype(row) {
+    if (!row.object || !row.object.startsWith(`${HPO_NAMESPACE}:`))
+        return null;
+    if (row.subject_taxon != null && row.subject_taxon !== HUMAN_TAXON)
+        return null;
+    return {
+        hpoId: row.object,
+        label: row.object_label ?? "",
+        ancestorIds: row.object_closure ?? [],
+        publications: row.publications ?? [],
+        diseaseContext: row.disease_context_qualifier ?? null,
+        frequencyPercent: row.has_percentage ?? null,
+        primaryKnowledgeSource: row.primary_knowledge_source ?? null,
+    };
+}
+/**
+ * Curated human phenotype associations for one gene.
+ *
+ * `geneCurie` is a prefixed identifier Monarch resolves — an HGNC id
+ * (`HGNC:1097`) or an NCBI gene id (`NCBIGene:673`). A gene Monarch does not
+ * hold returns an empty profile rather than an error.
+ */
+export async function getGenePhenotypeProfile(geneCurie) {
+    const rows = await fetchAssociations(geneCurie, "biolink:GeneToPhenotypicFeatureAssociation");
+    const phenotypes = [];
+    for (const row of rows) {
+        const p = toPhenotype(row);
+        if (p)
+            phenotypes.push(p);
+    }
+    return { geneCurie, phenotypes };
+}

package/dist/tools/lib/ncbi-utils.d.ts

@@ -1,58 +1,3 @@
-/**
- * Shared NCBI E-utilities helpers for PubMed/PMC tools.
- *
- * Provides base URL constants, API key injection, and XML-to-article
- * mapping functions for PubMed and PMC DTD structures.
- */
-export declare const NCBI_BASE = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils";
-export declare const NCBI_IDCONV = "https://www.ncbi.nlm.nih.gov/pmc/utils/idconv/v1.0";
-/**
- * Append `api_key` and optional extra params to a base URL.
- * Omits the key when `apiKey` is undefined.
- */
-export declare function ncbiUrl(apiKey: string | undefined, base: string, params: Record<string, string | number | undefined>): string;
-export interface PubMedSummary {
-    pmid: string;
-    title: string;
-    journal: string;
-    year: string;
-    authors: string;
-}
-/**
- * Parse esummary XML into PubMedSummary records.
- */
-export declare function parseEsummary(xml: string): PubMedSummary[];
-export interface ArticleDetail {
-    pmid: string;
-    title: string;
-    abstract: string;
-    authors: string[];
-    journal: string;
-    year: string;
-    doi: string;
-    meshTerms: string[];
-    pmcId: string | null;
-}
-/**
- * Parse efetch PubMed XML into ArticleDetail records.
- * `pmcId` is left null here — resolved separately via ID Converter.
- */
-export declare function parseEfetch(xml: string): ArticleDetail[];
-/**
- * Parse ID Converter JSON response into a PMID → PMC ID map.
- * Returns only entries that have a PMC ID.
- */
-export declare function parseIdConvResponse(data: unknown): Map<string, string>;
-export interface ArticleSection {
-    heading: string;
-    text: string;
-}
-export interface FullTextResult {
-    fullText: string;
-    sections: ArticleSection[];
-}
-/**
- * Parse PMC efetch XML into plain text with section structure.
- * Omits figures, tables, and supplementary material markup.
- */
-export declare function parsePmcFullText(xml: string): FullTextResult | null;
+/** @deprecated Import NCBI authority contracts from literature/sources/pubmed. */
+export { NCBI_BASE, NCBI_IDCONV, ncbiUrl, parseEfetch, parseEsummary, parseIdConvResponse, parsePmcFullText } from "../../literature/sources/pubmed.js";
+export type { ArticleDetail, ArticleSection, FullTextResult, PubMedSummary } from "../../literature/sources/pubmed.js";

package/dist/tools/lib/ncbi-utils.js

@@ -1,286 +1,2 @@
-/**
- * Shared NCBI E-utilities helpers for PubMed/PMC tools.
- *
- * Provides base URL constants, API key injection, and XML-to-article
- * mapping functions for PubMed and PMC DTD structures.
- */
-import { XMLParser } from "fast-xml-parser";
-// ── NCBI E-utilities base URLs ──────────────────────────────────────
-export const NCBI_BASE = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils";
-export const NCBI_IDCONV = "https://www.ncbi.nlm.nih.gov/pmc/utils/idconv/v1.0";
-// ── API key injection ───────────────────────────────────────────────
-/**
- * Append `api_key` and optional extra params to a base URL.
- * Omits the key when `apiKey` is undefined.
- */
-export function ncbiUrl(apiKey, base, params) {
-    const url = new URL(base);
-    if (apiKey) {
-        url.searchParams.set("api_key", apiKey);
-    }
-    for (const [k, v] of Object.entries(params)) {
-        if (v !== undefined) {
-            url.searchParams.set(k, String(v));
-        }
-    }
-    return url.toString();
-}
-// ── XML parser (shared, configured once) ────────────────────────────
-const xmlParser = new XMLParser({
-    ignoreAttributes: false,
-    attributeNamePrefix: "@_",
-    isArray: (name) => ["PubmedArticle", "Author", "MeshHeading", "AbstractText", "sec", "p", "record"].includes(name),
-    textNodeName: "#text",
-});
-function getItemValue(items, name) {
-    if (!items)
-        return "";
-    const arr = Array.isArray(items) ? items : [items];
-    const item = arr.find((i) => i["@_Name"] === name);
-    return item?.["#text"] ?? "";
-}
-function getAuthorsFromDocSum(items) {
-    if (!items)
-        return "";
-    const arr = Array.isArray(items) ? items : [items];
-    const authorList = arr.find((i) => i["@_Name"] === "AuthorList");
-    if (!authorList?.Item)
-        return "";
-    const authors = Array.isArray(authorList.Item) ? authorList.Item : [authorList.Item];
-    const names = authors.map((a) => a["#text"] ?? "").filter(Boolean);
-    if (names.length === 0)
-        return "";
-    if (names.length <= 3)
-        return names.join(", ");
-    return `${names[0]} et al.`;
-}
-/**
- * Parse esummary XML into PubMedSummary records.
- */
-export function parseEsummary(xml) {
-    const parsed = xmlParser.parse(xml);
-    const result = parsed?.eSummaryResult ?? parsed;
-    const docSums = result?.DocSum;
-    if (!docSums)
-        return [];
-    const docs = Array.isArray(docSums) ? docSums : [docSums];
-    return docs.map((doc) => {
-        const items = doc.Item;
-        const pubDate = getItemValue(items, "PubDate");
-        return {
-            pmid: String(doc.Id ?? ""),
-            title: getItemValue(items, "Title"),
-            journal: getItemValue(items, "FullJournalName") || getItemValue(items, "Source"),
-            year: pubDate ? String(pubDate).slice(0, 4) : "",
-            authors: getAuthorsFromDocSum(items),
-        };
-    });
-}
-/**
- * Parse efetch PubMed XML into ArticleDetail records.
- * `pmcId` is left null here — resolved separately via ID Converter.
- */
-export function parseEfetch(xml) {
-    const parsed = xmlParser.parse(xml);
-    const articleSet = parsed?.PubmedArticleSet;
-    if (!articleSet)
-        return [];
-    const articles = Array.isArray(articleSet.PubmedArticle) ? articleSet.PubmedArticle : articleSet.PubmedArticle ? [articleSet.PubmedArticle] : [];
-    return articles.map((entry) => {
-        const article = entry;
-        const medlineCitation = article.MedlineCitation;
-        const articleData = medlineCitation?.Article;
-        // PMID
-        const pmidObj = medlineCitation?.PMID;
-        const pmid = typeof pmidObj === "object" && pmidObj !== null ? String(pmidObj["#text"] ?? "") : String(pmidObj ?? "");
-        // Title
-        const title = String(articleData?.ArticleTitle ?? "");
-        // Abstract
-        const abstractObj = articleData?.Abstract;
-        let abstract = "";
-        if (abstractObj?.AbstractText) {
-            const texts = Array.isArray(abstractObj.AbstractText) ? abstractObj.AbstractText : [abstractObj.AbstractText];
-            abstract = texts
-                .map((t) => {
-                if (typeof t === "string")
-                    return t;
-                if (typeof t === "object" && t !== null) {
-                    const label = t["@_Label"];
-                    const text = t["#text"] ?? "";
-                    return label ? `${label}: ${text}` : String(text);
-                }
-                return String(t);
-            })
-                .join("\n\n");
-        }
-        // Authors
-        const authorListObj = articleData?.AuthorList;
-        const rawAuthors = authorListObj?.Author;
-        const authorArr = Array.isArray(rawAuthors) ? rawAuthors : rawAuthors ? [rawAuthors] : [];
-        const authors = authorArr.map((a) => {
-            if (a.CollectiveName)
-                return a.CollectiveName;
-            return [a.ForeName ?? a.Initials, a.LastName].filter(Boolean).join(" ");
-        });
-        // Journal + year
-        const journalObj = articleData?.Journal;
-        const journal = String(journalObj?.Title ?? journalObj?.ISOAbbreviation ?? "");
-        const journalIssue = journalObj?.JournalIssue;
-        const pubDate = journalIssue?.PubDate;
-        const year = String(pubDate?.Year ?? "");
-        // DOI
-        let doi = "";
-        const articleIdList = article.PubmedData?.ArticleIdList;
-        if (articleIdList?.ArticleId) {
-            const ids = Array.isArray(articleIdList.ArticleId) ? articleIdList.ArticleId : [articleIdList.ArticleId];
-            for (const idObj of ids) {
-                if (typeof idObj === "object" && idObj !== null) {
-                    const typed = idObj;
-                    if (typed["@_IdType"] === "doi") {
-                        doi = String(typed["#text"] ?? "");
-                    }
-                }
-            }
-        }
-        // MeSH terms
-        const meshList = medlineCitation?.MeshHeadingList;
-        const meshHeadings = meshList?.MeshHeading
-            ? Array.isArray(meshList.MeshHeading)
-                ? meshList.MeshHeading
-                : [meshList.MeshHeading]
-            : [];
-        const meshTerms = meshHeadings
-            .map((h) => {
-            const desc = h.DescriptorName;
-            if (typeof desc === "string")
-                return desc;
-            if (typeof desc === "object" && desc !== null)
-                return desc["#text"] ?? "";
-            return "";
-        })
-            .filter(Boolean);
-        return {
-            pmid,
-            title,
-            abstract,
-            authors,
-            journal,
-            year,
-            doi,
-            meshTerms,
-            pmcId: null, // resolved separately via ID Converter
-        };
-    });
-}
-// ── NCBI ID Converter mapping ───────────────────────────────────────
-/**
- * Parse ID Converter JSON response into a PMID → PMC ID map.
- * Returns only entries that have a PMC ID.
- */
-export function parseIdConvResponse(data) {
-    const map = new Map();
-    const typed = data;
-    if (!typed?.records)
-        return map;
-    for (const rec of typed.records) {
-        if (rec.pmid && rec.pmcid) {
-            map.set(rec.pmid, rec.pmcid);
-        }
-    }
-    return map;
-}
-/**
- * Parse PMC efetch XML into plain text with section structure.
- * Omits figures, tables, and supplementary material markup.
- */
-export function parsePmcFullText(xml) {
-    const parsed = xmlParser.parse(xml);
-    const articleSet = parsed?.["pmc-articleset"];
-    const article = articleSet?.article;
-    if (!article)
-        return null;
-    const body = article.body;
-    if (!body)
-        return null;
-    const sections = [];
-    const rawSecs = body.sec ? (Array.isArray(body.sec) ? body.sec : [body.sec]) : [];
-    for (const sec of rawSecs) {
-        extractSection(sec, sections);
-    }
-    // If no sections found, try to extract body text directly
-    if (sections.length === 0) {
-        const bodyText = extractParagraphs(body);
-        if (bodyText) {
-            sections.push({ heading: "", text: bodyText });
-        }
-    }
-    const fullText = sections.map((s) => (s.heading ? `## ${s.heading}\n\n${s.text}` : s.text)).join("\n\n");
-    return { fullText, sections };
-}
-function extractSection(sec, out) {
-    if (!sec || typeof sec !== "object")
-        return;
-    const s = sec;
-    const heading = typeof s.title === "string" ? s.title : "";
-    const text = extractParagraphs(s);
-    if (text) {
-        out.push({ heading, text });
-    }
-    // Recurse into nested sections
-    if (s.sec) {
-        const nested = Array.isArray(s.sec) ? s.sec : [s.sec];
-        for (const sub of nested) {
-            extractSection(sub, out);
-        }
-    }
-}
-function extractParagraphs(container) {
-    const paragraphs = container.p;
-    if (!paragraphs)
-        return "";
-    const pArr = Array.isArray(paragraphs) ? paragraphs : [paragraphs];
-    return pArr
-        .map((p) => {
-        if (typeof p === "string")
-            return p;
-        if (typeof p === "object" && p !== null) {
-            return flattenTextContent(p);
-        }
-        return String(p);
-    })
-        .filter(Boolean)
-        .join("\n\n");
-}
-/**
- * Recursively extract text content from a parsed XML node,
- * ignoring markup like <fig>, <table-wrap>, <xref>, etc.
- */
-function flattenTextContent(node) {
-    if (typeof node === "string")
-        return node;
-    if (typeof node === "number")
-        return String(node);
-    if (!node || typeof node !== "object")
-        return "";
-    const obj = node;
-    const parts = [];
-    for (const [key, value] of Object.entries(obj)) {
-        // Skip attributes and figure/table elements
-        if (key.startsWith("@_"))
-            continue;
-        if (key === "fig" || key === "table-wrap" || key === "supplementary-material")
-            continue;
-        if (key === "#text") {
-            parts.push(String(value));
-        }
-        else if (Array.isArray(value)) {
-            for (const item of value) {
-                parts.push(flattenTextContent(item));
-            }
-        }
-        else {
-            parts.push(flattenTextContent(value));
-        }
-    }
-    return parts.filter(Boolean).join("");
-}
+/** @deprecated Import NCBI authority contracts from literature/sources/pubmed. */
+export { NCBI_BASE, NCBI_IDCONV, ncbiUrl, parseEfetch, parseEsummary, parseIdConvResponse, parsePmcFullText } from "../../literature/sources/pubmed.js";

package/dist/tools/lib/pubmed-client.d.ts

@@ -4,18 +4,11 @@
  * Used by §3.11 (Key Papers), §3.10.4 (Preclinical literature), and the
  * pubmed-index Phase-1 collector.
  */
-import { type ArticleDetail, type ArticleSection, type PubMedSummary, type FullTextResult } from "./ncbi-utils.js";
+import { type ArticleDetail, type ArticleSection, type FullTextResult, type PubmedSearchOptions, type PubMedSummary } from "../../literature/sources/pubmed.js";
 export type { PubMedSummary, ArticleDetail, ArticleSection, FullTextResult };
-export interface SearchOptions {
-    maxResults?: number;
-    sort?: "relevance" | "date";
-    dateRange?: {
-        from: string;
-        to: string;
-    };
-}
+export type SearchOptions = PubmedSearchOptions;
 /** PubMed search via esearch + esummary. */
-export declare function searchPubmed(ncbiApiKey: string | undefined, query: string, options?: SearchOptions): Promise<{
+export declare function searchPubmed(ncbiApiKey: string | undefined, query: string, options?: SearchOptions, signal?: AbortSignal): Promise<{
     totalFound: number;
     results: PubMedSummary[];
 }>;
@@ -36,7 +29,7 @@ export interface BoundedArticleDetail extends ArticleDetail {
     meshTermCount: number;
 }
 /** Fetch full PubMed article details (efetch + ID Converter for PMC). */
-export declare function getArticleDetails(ncbiApiKey: string | undefined, pmids: string[]): Promise<{
+export declare function getArticleDetails(ncbiApiKey: string | undefined, pmids: string[], signal?: AbortSignal): Promise<{
     articles: ArticleDetail[];
     notFound: string[];
 }>;
@@ -76,6 +69,6 @@ export interface BoundedFullText {
  * Methods is worse than none) and admitted in document order until the budget
  * would be exceeded.
  */
-export declare function getArticleFullText(ncbiApiKey: string | undefined, pmcId: string, options?: FullTextOptions): Promise<BoundedFullText | null>;
+export declare function getArticleFullText(ncbiApiKey: string | undefined, pmcId: string, options?: FullTextOptions, signal?: AbortSignal): Promise<BoundedFullText | null>;
 /** Apply the section filter and character budget to a parsed full text. */
 export declare function boundFullText(parsed: FullTextResult, options?: FullTextOptions): BoundedFullText;

package/dist/tools/lib/pubmed-client.js

@@ -4,76 +4,27 @@
  * Used by §3.11 (Key Papers), §3.10.4 (Preclinical literature), and the
  * pubmed-index Phase-1 collector.
  */
-import { z } from "zod";
-import { apiFetch, apiFetchValidated, describeApiError } from "./api-utils.js";
-import { NCBI_BASE, NCBI_IDCONV, ncbiUrl, parseEsummary, parseEfetch, parseIdConvResponse, parsePmcFullText, } from "./ncbi-utils.js";
-// NCBI E-utilities JSON payloads, validated at the fetch boundary. Every field
-// is optional because the API omits absent values.
-const EsearchResponseSchema = z.object({
-    esearchresult: z.object({ idlist: z.array(z.string()).optional(), count: z.string().optional() }).optional(),
-});
-const IdConvResponseSchema = z.object({
-    records: z.array(z.object({ pmid: z.string().optional(), pmcid: z.string().optional() })).optional(),
-});
-/** PubMed search via esearch + esummary. */
-export async function searchPubmed(ncbiApiKey, query, options = {}) {
-    const maxResults = options.maxResults ?? 10;
-    const sort = options.sort ?? "relevance";
-    const esearchParams = {
-        db: "pubmed",
-        term: query,
-        retmax: maxResults,
-        retmode: "json",
-        sort: sort === "date" ? "pub+date" : "relevance",
-    };
-    if (options.dateRange) {
-        esearchParams.mindate = options.dateRange.from;
-        esearchParams.maxdate = options.dateRange.to;
-        esearchParams.datetype = "pdat";
-    }
-    const searchUrl = ncbiUrl(ncbiApiKey, `${NCBI_BASE}/esearch.fcgi`, esearchParams);
-    const searchResult = await apiFetchValidated(searchUrl, EsearchResponseSchema);
-    if (searchResult.isErr())
-        throw new Error(describeApiError(searchResult.error));
-    const idList = searchResult.value.esearchresult?.idlist ?? [];
-    const totalFound = parseInt(searchResult.value.esearchresult?.count ?? "0", 10);
-    if (idList.length === 0)
-        return { totalFound, results: [] };
-    const summaryUrl = ncbiUrl(ncbiApiKey, `${NCBI_BASE}/esummary.fcgi`, {
-        db: "pubmed",
-        id: idList.join(","),
-        retmode: "xml",
+import { createPubmedSource, } from "../../literature/sources/pubmed.js";
+function pubmedSource(ncbiApiKey) {
+    return createPubmedSource({
+        ...(ncbiApiKey === undefined ? {} : { apiKey: ncbiApiKey }),
+        maxRetries: 3,
+        retryDelayMs: 1_000,
+        timeoutMs: 90_000,
     });
-    const summaryResult = await apiFetch(summaryUrl, { parseAs: "text" });
-    if (summaryResult.isErr())
-        throw new Error(describeApiError(summaryResult.error));
-    return { totalFound, results: parseEsummary(summaryResult.value) };
+}
+function unwrap(result) {
+    if (result.status !== "ok")
+        throw new Error(result.detail);
+    return result.value;
+}
+/** PubMed search via esearch + esummary. */
+export async function searchPubmed(ncbiApiKey, query, options = {}, signal) {
+    return unwrap(await pubmedSource(ncbiApiKey).search(query, options, signal));
 }
 /** Fetch full PubMed article details (efetch + ID Converter for PMC). */
-export async function getArticleDetails(ncbiApiKey, pmids) {
-    const idString = pmids.join(",");
-    const efetchAsync = apiFetch(ncbiUrl(ncbiApiKey, `${NCBI_BASE}/efetch.fcgi`, {
-        db: "pubmed",
-        id: idString,
-        rettype: "xml",
-        retmode: "xml",
-    }), { parseAs: "text" });
-    const idConvAsync = apiFetchValidated(ncbiUrl(ncbiApiKey, NCBI_IDCONV, { ids: idString, format: "json" }), IdConvResponseSchema);
-    // Both requests run concurrently; each Result is awaited and handled below.
-    const efetchResult = await efetchAsync;
-    const idConvResult = await idConvAsync;
-    if (efetchResult.isErr())
-        throw new Error(describeApiError(efetchResult.error));
-    const articles = parseEfetch(efetchResult.value);
-    if (idConvResult.isOk()) {
-        const pmcMap = parseIdConvResponse(idConvResult.value);
-        for (const article of articles) {
-            article.pmcId = pmcMap.get(article.pmid) ?? null;
-        }
-    }
-    const foundPmids = new Set(articles.map((a) => a.pmid));
-    const notFound = pmids.filter((id) => !foundPmids.has(id));
-    return { articles, notFound };
+export async function getArticleDetails(ncbiApiKey, pmids, signal) {
+    return unwrap(await pubmedSource(ncbiApiKey).articleDetails(pmids, signal));
 }
 /** Trim the two unbounded list fields on each article, recording their true sizes. */
 export function boundArticleDetails(articles, options = {}) {
@@ -97,18 +48,8 @@ export function boundArticleDetails(articles, options = {}) {
  * Methods is worse than none) and admitted in document order until the budget
  * would be exceeded.
  */
-export async function getArticleFullText(ncbiApiKey, pmcId, options = {}) {
-    const numericId = pmcId.replace(/^PMC/i, "");
-    const url = ncbiUrl(ncbiApiKey, `${NCBI_BASE}/efetch.fcgi`, {
-        db: "pmc",
-        id: numericId,
-        rettype: "xml",
-        retmode: "xml",
-    });
-    const result = await apiFetch(url, { parseAs: "text" });
-    if (result.isErr())
-        throw new Error(describeApiError(result.error));
-    const parsed = parsePmcFullText(result.value);
+export async function getArticleFullText(ncbiApiKey, pmcId, options = {}, signal) {
+    const parsed = unwrap(await pubmedSource(ncbiApiKey).fetchFullText(pmcId, signal));
     if (!parsed)
         return null;
     return boundFullText(parsed, options);

package/dist/tools/report/build-report.js

@@ -16,6 +16,7 @@ export function createBuildReportTool(state) {
             "Always use this — never invoke a build script directly. Returns " +
             "structured errors with line numbers when the template is broken.",
         inputSchema: z.object({}),
+        describeCall: "none",
         execute: async () => {
             return ok(await renderReport({
                 versionDir: state.versionDir,

package/dist/tools/report/mint-preview-url.js

@@ -24,6 +24,7 @@ export function createMintPreviewUrlTool(state) {
         inputSchema: z.object({
             version: z.number().optional().describe("Version to mint for. Defaults to the iteration's current version."),
         }),
+        describeCall: "none",
         execute: async (input) => {
             const version = input.version ?? state.currentVersion;
             const result = await state.previews.mintPreviewAccess(state.resourceId, state.previewId);

package/dist/tools/report/preview-snapshot.js

@@ -47,6 +47,7 @@ export function createPreviewSnapshotTool(state) {
                 .optional()
                 .describe("Optional extra wait in ms after the theme-ready event (e.g., for chart paint). Capped at 30s."),
         }),
+        describeCall: "none",
         execute: async (input) => {
             let url = state.urlCell.url;
             const expiresAt = state.urlCell.expiresAt;