@inflexa-ai/harness 0.16.0 → 0.17.0

package/dist/literature/sources/arxiv.js

@@ -0,0 +1,103 @@
+import { requestText } from "./http.js";
+const BASE_URL = "https://export.arxiv.org/api/query";
+const stripCdata = (value) => value.replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, "$1");
+const decodeXmlEntities = (value) => value
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#x([0-9a-fA-F]+);/g, (_, hexadecimal) => String.fromCodePoint(parseInt(hexadecimal, 16)))
+    .replace(/&#(\d+);/g, (_, decimal) => String.fromCodePoint(parseInt(decimal, 10)))
+    .replace(/&amp;/g, "&");
+const collapseWhitespace = (value) => decodeXmlEntities(stripCdata(value)).replace(/\s+/g, " ").trim();
+function extractEntries(xml) {
+    const expression = /<entry\b[^>]*>([\s\S]*?)<\/entry>/g;
+    const entries = [];
+    let match;
+    while ((match = expression.exec(xml)) !== null)
+        entries.push(match[1]);
+    return entries;
+}
+function firstMatch(entry, tag) {
+    return entry.match(new RegExp(`<${tag}\\b[^>]*>([\\s\\S]*?)</${tag}>`))?.[1];
+}
+function allMatches(entry, tag) {
+    const expression = new RegExp(`<${tag}\\b[^>]*>([\\s\\S]*?)</${tag}>`, "g");
+    const values = [];
+    let match;
+    while ((match = expression.exec(entry)) !== null)
+        values.push(match[1]);
+    return values;
+}
+function linkAttribute(entry, predicate) {
+    const expression = /<link\b([^>]*)\/>/g;
+    let match;
+    while ((match = expression.exec(entry)) !== null) {
+        const attributes = match[1];
+        if (predicate(attributes))
+            return attributes.match(/href="([^"]+)"/)?.[1];
+    }
+    return undefined;
+}
+function categoryTerms(entry) {
+    const expression = /<category\b([^>]*)\/>/g;
+    const terms = [];
+    let match;
+    while ((match = expression.exec(entry)) !== null) {
+        const term = match[1].match(/term="([^"]+)"/)?.[1];
+        if (term !== undefined)
+            terms.push(term);
+    }
+    return terms;
+}
+export function parseArxivAtom(xml) {
+    return extractEntries(xml).flatMap((entry) => {
+        const rawId = firstMatch(entry, "id");
+        const title = firstMatch(entry, "title");
+        if (rawId === undefined || title === undefined)
+            return [];
+        const idMatch = rawId.match(/abs\/(.+)$/);
+        const authors = allMatches(entry, "author")
+            .map((author) => firstMatch(author, "name"))
+            .filter((name) => name !== undefined)
+            .map(collapseWhitespace);
+        const htmlUrl = linkAttribute(entry, (attributes) => /rel="alternate"/.test(attributes) && /type="text\/html"/.test(attributes));
+        const pdfUrl = linkAttribute(entry, (attributes) => /title="pdf"/.test(attributes));
+        return [
+            {
+                id: idMatch?.[1] ?? collapseWhitespace(rawId),
+                title: collapseWhitespace(title),
+                abstract: collapseWhitespace(firstMatch(entry, "summary") ?? ""),
+                authors,
+                published: collapseWhitespace(firstMatch(entry, "published") ?? ""),
+                categories: categoryTerms(entry),
+                url: htmlUrl ?? collapseWhitespace(rawId),
+                ...(pdfUrl === undefined ? {} : { pdfUrl }),
+            },
+        ];
+    });
+}
+export function createArxivSource(options = {}) {
+    async function fetchPapers(params, signal) {
+        const result = await requestText(`${BASE_URL}?${params}`, options, signal);
+        if (result.status !== "ok")
+            return result;
+        if (!/<feed\b/.test(result.value))
+            return { status: "unavailable", detail: "response schema mismatch: missing Atom feed" };
+        return { status: "ok", value: parseArxivAtom(result.value) };
+    }
+    return {
+        search: (input, signal) => {
+            const categoryQuery = input.categories !== undefined && input.categories.length > 0
+                ? ` AND (${input.categories.map((category) => `cat:${category}`).join(" OR ")})`
+                : "";
+            return fetchPapers(new URLSearchParams({
+                search_query: `all:${input.query}${categoryQuery}`,
+                max_results: String(input.limit),
+                sortBy: "relevance",
+                sortOrder: "descending",
+            }), signal);
+        },
+        lookupExact: (id, limit, signal) => fetchPapers(new URLSearchParams({ id_list: id, max_results: String(limit) }), signal),
+    };
+}

package/dist/literature/sources/http.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+export interface SourceHttpOptions {
+    readonly fetch?: typeof globalThis.fetch;
+    /**
+     * Admission gate wrapped around each network attempt — a rate limiter, a
+     * concurrency semaphore, or both. The request timeout is armed *inside* it,
+     * so time an attempt spends queueing is never charged against the timeout.
+     */
+    readonly schedule?: <T>(operation: () => Promise<T>, signal?: AbortSignal) => Promise<T>;
+    readonly timeoutMs?: number;
+    readonly maxRetries?: number;
+    readonly retryDelayMs?: number;
+    /** Ceiling on any single retry wait, including one a server asks for via `Retry-After`. */
+    readonly maxRetryDelayMs?: number;
+    readonly sleep?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+}
+export type SourceHttpResult<T> = {
+    readonly status: "ok";
+    readonly value: T;
+} | {
+    readonly status: "no_data";
+    readonly detail: string;
+} | {
+    readonly status: "unavailable";
+    readonly detail: string;
+};
+export declare function requestJson<S extends z.ZodType>(url: string, schema: S, options: SourceHttpOptions, signal?: AbortSignal, init?: RequestInit): Promise<SourceHttpResult<z.infer<S>>>;
+export declare function requestText(url: string, options: SourceHttpOptions, signal?: AbortSignal, init?: RequestInit): Promise<SourceHttpResult<string>>;

package/dist/literature/sources/http.js

@@ -0,0 +1,97 @@
+const RETRYABLE_STATUSES = new Set([429, 503]);
+function cancellationReason(signal) {
+    return signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted", "AbortError");
+}
+async function delay(ms, signal) {
+    if (signal?.aborted)
+        throw cancellationReason(signal);
+    await new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timeout);
+            reject(cancellationReason(signal));
+        };
+        const timeout = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function retryAfterMilliseconds(response) {
+    const value = response.headers.get("retry-after")?.trim();
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1000;
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : undefined;
+}
+async function request(url, options, signal, init) {
+    if (signal?.aborted)
+        throw cancellationReason(signal);
+    const timeoutMs = options.timeoutMs ?? 15_000;
+    const maxRetries = options.maxRetries ?? 0;
+    const retryDelayMs = options.retryDelayMs ?? 1_000;
+    const maxRetryDelayMs = options.maxRetryDelayMs ?? Number.POSITIVE_INFINITY;
+    const schedule = options.schedule ?? ((operation) => operation());
+    const sleep = options.sleep ?? delay;
+    const fetcher = options.fetch ?? globalThis.fetch;
+    const backoff = (attempt) => Math.min(maxRetryDelayMs, retryDelayMs * 2 ** attempt);
+    for (let attempt = 0;; attempt += 1) {
+        let timeout;
+        try {
+            const response = await schedule(async () => {
+                timeout = AbortSignal.timeout(timeoutMs);
+                const combined = signal === undefined ? timeout : AbortSignal.any([signal, timeout]);
+                return await fetcher(url, { ...init, signal: combined });
+            }, signal);
+            if (RETRYABLE_STATUSES.has(response.status) && attempt < maxRetries) {
+                await sleep(Math.min(maxRetryDelayMs, retryAfterMilliseconds(response) ?? backoff(attempt)), signal);
+                continue;
+            }
+            if (response.status === 404 || response.status === 400 || response.status === 406) {
+                return { status: "no_data", detail: `HTTP ${response.status}` };
+            }
+            if (!response.ok)
+                return { status: "unavailable", detail: `HTTP ${response.status}` };
+            return { status: "ok", value: response };
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw cancellationReason(signal);
+            if (timeout?.aborted)
+                return { status: "unavailable", detail: `request timed out after ${timeoutMs}ms` };
+            if (attempt < maxRetries) {
+                await sleep(backoff(attempt), signal);
+                continue;
+            }
+            return { status: "unavailable", detail: error instanceof Error ? error.message : String(error) };
+        }
+    }
+}
+export async function requestJson(url, schema, options, signal, init = {}) {
+    const response = await request(url, options, signal, init);
+    if (response.status !== "ok")
+        return response;
+    try {
+        const parsed = schema.safeParse(await response.value.json());
+        if (!parsed.success)
+            return { status: "unavailable", detail: `response schema mismatch: ${parsed.error.issues[0]?.message ?? "unknown"}` };
+        return { status: "ok", value: parsed.data };
+    }
+    catch (error) {
+        return { status: "unavailable", detail: `invalid JSON response: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}
+export async function requestText(url, options, signal, init = {}) {
+    const response = await request(url, options, signal, init);
+    if (response.status !== "ok")
+        return response;
+    try {
+        return { status: "ok", value: await response.value.text() };
+    }
+    catch (error) {
+        return { status: "unavailable", detail: `invalid text response: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}

package/dist/literature/sources/pubmed.d.ts

@@ -0,0 +1,68 @@
+import { type SourceHttpOptions, type SourceHttpResult } from "./http.js";
+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";
+export interface PubmedSourceOptions extends SourceHttpOptions {
+    readonly apiKey?: string;
+}
+export interface PubmedSearchOptions {
+    readonly maxResults?: number;
+    readonly sort?: "relevance" | "date";
+    readonly dateRange?: {
+        readonly from: string;
+        readonly to: string;
+    };
+}
+export interface PubmedCitationFields {
+    readonly venue?: string;
+    readonly year?: string | number;
+    readonly volume?: string;
+    readonly firstPage?: string;
+    readonly firstAuthor?: string;
+    readonly key: string;
+}
+export interface PubMedSummary {
+    pmid: string;
+    title: string;
+    journal: string;
+    year: string;
+    authors: string;
+}
+export interface ArticleDetail {
+    pmid: string;
+    title: string;
+    abstract: string;
+    authors: string[];
+    journal: string;
+    year: string;
+    doi: string;
+    meshTerms: string[];
+    pmcId: string | null;
+}
+export interface ArticleSection {
+    heading: string;
+    text: string;
+}
+export interface FullTextResult {
+    fullText: string;
+    sections: ArticleSection[];
+}
+export interface PubmedSource {
+    search(query: string, options?: PubmedSearchOptions, signal?: AbortSignal): Promise<SourceHttpResult<{
+        totalFound: number;
+        results: PubMedSummary[];
+    }>>;
+    searchIds(query: string, maxResults: number, signal?: AbortSignal): Promise<SourceHttpResult<string[]>>;
+    matchCitation(fields: PubmedCitationFields, signal?: AbortSignal): Promise<SourceHttpResult<string[]>>;
+    fetchArticles(pmids: readonly string[], signal?: AbortSignal): Promise<SourceHttpResult<ArticleDetail[]>>;
+    articleDetails(pmids: readonly string[], signal?: AbortSignal): Promise<SourceHttpResult<{
+        articles: ArticleDetail[];
+        notFound: string[];
+    }>>;
+    fetchFullText(pmcId: string, signal?: AbortSignal): Promise<SourceHttpResult<FullTextResult | null>>;
+}
+export declare function ncbiUrl(apiKey: string | undefined, base: string, params: Record<string, string | number | undefined>): string;
+export declare function parseEsummary(xml: string): PubMedSummary[];
+export declare function parseEfetch(xml: string): ArticleDetail[];
+export declare function parseIdConvResponse(data: unknown): Map<string, string>;
+export declare function parsePmcFullText(xml: string): FullTextResult | null;
+export declare function createPubmedSource(options?: PubmedSourceOptions): PubmedSource;

package/dist/literature/sources/pubmed.js

@@ -0,0 +1,266 @@
+import { XMLParser } from "fast-xml-parser";
+import { z } from "zod";
+import { requestJson, requestText } from "./http.js";
+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";
+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(),
+});
+export function ncbiUrl(apiKey, base, params) {
+    const url = new URL(base);
+    if (apiKey !== undefined)
+        url.searchParams.set("api_key", apiKey);
+    for (const [key, value] of Object.entries(params))
+        if (value !== undefined)
+            url.searchParams.set(key, String(value));
+    return url.toString();
+}
+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 === undefined)
+        return "";
+    const item = (Array.isArray(items) ? items : [items]).find((candidate) => candidate["@_Name"] === name);
+    return item?.["#text"] ?? "";
+}
+function getAuthorsFromDocSum(items) {
+    if (items === undefined)
+        return "";
+    const authorList = (Array.isArray(items) ? items : [items]).find((item) => item["@_Name"] === "AuthorList");
+    if (authorList?.Item === undefined)
+        return "";
+    const names = (Array.isArray(authorList.Item) ? authorList.Item : [authorList.Item]).map((author) => author["#text"] ?? "").filter(Boolean);
+    if (names.length <= 3)
+        return names.join(", ");
+    return `${names[0]} et al.`;
+}
+export function parseEsummary(xml) {
+    const parsed = xmlParser.parse(xml);
+    const docSums = (parsed?.eSummaryResult ?? parsed)?.DocSum;
+    if (docSums === undefined)
+        return [];
+    const documents = Array.isArray(docSums) ? docSums : [docSums];
+    return documents.map((document) => {
+        const publicationDate = getItemValue(document.Item, "PubDate");
+        return {
+            pmid: String(document.Id ?? ""),
+            title: getItemValue(document.Item, "Title"),
+            journal: getItemValue(document.Item, "FullJournalName") || getItemValue(document.Item, "Source"),
+            year: publicationDate.slice(0, 4),
+            authors: getAuthorsFromDocSum(document.Item),
+        };
+    });
+}
+export function parseEfetch(xml) {
+    const articleSet = xmlParser.parse(xml)?.PubmedArticleSet;
+    if (articleSet === undefined)
+        return [];
+    const entries = Array.isArray(articleSet.PubmedArticle)
+        ? articleSet.PubmedArticle
+        : articleSet.PubmedArticle === undefined
+            ? []
+            : [articleSet.PubmedArticle];
+    return entries.map((entry) => {
+        const article = entry;
+        const citation = article.MedlineCitation;
+        const articleData = citation?.Article;
+        const pmidValue = citation?.PMID;
+        const pmid = typeof pmidValue === "object" && pmidValue !== null ? String(pmidValue["#text"] ?? "") : String(pmidValue ?? "");
+        const abstractValue = articleData?.Abstract?.AbstractText;
+        const abstract = (abstractValue === undefined ? [] : Array.isArray(abstractValue) ? abstractValue : [abstractValue])
+            .map((value) => {
+            if (typeof value === "string")
+                return value;
+            if (typeof value !== "object" || value === null)
+                return String(value);
+            const object = value;
+            const text = String(object["#text"] ?? "");
+            return object["@_Label"] === undefined ? text : `${String(object["@_Label"])}: ${text}`;
+        })
+            .join("\n\n");
+        const authorValue = articleData?.AuthorList?.Author;
+        const authors = (authorValue === undefined ? [] : Array.isArray(authorValue) ? authorValue : [authorValue]).map((author) => author.CollectiveName ?? [author.ForeName ?? author.Initials, author.LastName].filter(Boolean).join(" "));
+        const journalData = articleData?.Journal;
+        const publicationDate = journalData?.JournalIssue?.PubDate;
+        let doi = "";
+        const articleIds = article.PubmedData?.ArticleIdList?.ArticleId;
+        for (const id of articleIds === undefined ? [] : Array.isArray(articleIds) ? articleIds : [articleIds]) {
+            if (typeof id === "object" && id !== null && id["@_IdType"] === "doi") {
+                doi = String(id["#text"] ?? "");
+            }
+        }
+        const meshValue = citation?.MeshHeadingList?.MeshHeading;
+        const meshTerms = (meshValue === undefined ? [] : Array.isArray(meshValue) ? meshValue : [meshValue])
+            .map((heading) => {
+            const descriptor = heading.DescriptorName;
+            return typeof descriptor === "string" ? descriptor : (descriptor?.["#text"] ?? "");
+        })
+            .filter(Boolean);
+        return {
+            pmid,
+            title: String(articleData?.ArticleTitle ?? ""),
+            abstract,
+            authors,
+            journal: String(journalData?.Title ?? journalData?.ISOAbbreviation ?? ""),
+            year: String(publicationDate?.Year ?? ""),
+            doi,
+            meshTerms,
+            pmcId: null,
+        };
+    });
+}
+export function parseIdConvResponse(data) {
+    const result = new Map();
+    const records = data?.records ?? [];
+    for (const record of records)
+        if (record.pmid !== undefined && record.pmcid !== undefined)
+            result.set(record.pmid, record.pmcid);
+    return result;
+}
+function flattenTextContent(node) {
+    if (typeof node === "string" || typeof node === "number")
+        return String(node);
+    if (node === null || typeof node !== "object")
+        return "";
+    return Object.entries(node)
+        .flatMap(([key, value]) => {
+        if (key.startsWith("@_") || key === "fig" || key === "table-wrap" || key === "supplementary-material")
+            return [];
+        if (key === "#text")
+            return [String(value)];
+        return Array.isArray(value) ? value.map(flattenTextContent) : [flattenTextContent(value)];
+    })
+        .filter(Boolean)
+        .join("");
+}
+function extractParagraphs(container) {
+    const paragraphs = container.p;
+    if (paragraphs === undefined)
+        return "";
+    return (Array.isArray(paragraphs) ? paragraphs : [paragraphs])
+        .map((paragraph) => (typeof paragraph === "string" ? paragraph : flattenTextContent(paragraph)))
+        .filter(Boolean)
+        .join("\n\n");
+}
+function extractSection(section, output) {
+    if (section === null || typeof section !== "object")
+        return;
+    const object = section;
+    const text = extractParagraphs(object);
+    if (text)
+        output.push({ heading: typeof object.title === "string" ? object.title : "", text });
+    const nested = object.sec;
+    for (const child of nested === undefined ? [] : Array.isArray(nested) ? nested : [nested])
+        extractSection(child, output);
+}
+export function parsePmcFullText(xml) {
+    const article = xmlParser.parse(xml)?.["pmc-articleset"]?.article;
+    const body = article?.body;
+    if (body === undefined)
+        return null;
+    const sections = [];
+    for (const section of body.sec === undefined ? [] : Array.isArray(body.sec) ? body.sec : [body.sec])
+        extractSection(section, sections);
+    if (sections.length === 0) {
+        const text = extractParagraphs(body);
+        if (text)
+            sections.push({ heading: "", text });
+    }
+    return {
+        fullText: sections.map((section) => (section.heading ? `## ${section.heading}\n\n${section.text}` : section.text)).join("\n\n"),
+        sections,
+    };
+}
+export function createPubmedSource(options = {}) {
+    const url = (endpoint, params) => ncbiUrl(options.apiKey, endpoint, params);
+    async function searchIdsWithTotal(query, searchOptions, signal) {
+        const params = {
+            db: "pubmed",
+            term: query,
+            retmax: searchOptions.maxResults ?? 10,
+            retmode: "json",
+            sort: searchOptions.sort === "date" ? "pub+date" : "relevance",
+        };
+        if (searchOptions.dateRange !== undefined) {
+            params.mindate = searchOptions.dateRange.from;
+            params.maxdate = searchOptions.dateRange.to;
+            params.datetype = "pdat";
+        }
+        const result = await requestJson(url(`${NCBI_BASE}/esearch.fcgi`, params), EsearchResponseSchema, options, signal);
+        if (result.status !== "ok")
+            return result;
+        return {
+            status: "ok",
+            value: {
+                totalFound: parseInt(result.value.esearchresult?.count ?? "0", 10),
+                ids: result.value.esearchresult?.idlist ?? [],
+            },
+        };
+    }
+    async function fetchArticles(pmids, signal) {
+        const result = await requestText(url(`${NCBI_BASE}/efetch.fcgi`, { db: "pubmed", id: pmids.join(","), rettype: "xml", retmode: "xml" }), options, signal);
+        if (result.status !== "ok")
+            return result;
+        if (!/<PubmedArticleSet\b/.test(result.value))
+            return { status: "unavailable", detail: "response schema mismatch: missing PubmedArticleSet" };
+        return { status: "ok", value: parseEfetch(result.value) };
+    }
+    return {
+        async search(query, searchOptions = {}, signal) {
+            const search = await searchIdsWithTotal(query, searchOptions, signal);
+            if (search.status !== "ok")
+                return search;
+            if (search.value.ids.length === 0)
+                return { status: "ok", value: { totalFound: search.value.totalFound, results: [] } };
+            const summary = await requestText(url(`${NCBI_BASE}/esummary.fcgi`, { db: "pubmed", id: search.value.ids.join(","), retmode: "xml" }), options, signal);
+            if (summary.status !== "ok")
+                return summary;
+            return { status: "ok", value: { totalFound: search.value.totalFound, results: parseEsummary(summary.value) } };
+        },
+        async searchIds(query, maxResults, signal) {
+            const result = await searchIdsWithTotal(query, { maxResults }, signal);
+            return result.status === "ok" ? { status: "ok", value: result.value.ids } : result;
+        },
+        async matchCitation(fields, signal) {
+            const bdata = [fields.venue ?? "", fields.year ?? "", fields.volume ?? "", fields.firstPage ?? "", fields.firstAuthor ?? "", fields.key, ""].join("|");
+            const result = await requestText(url(`${NCBI_BASE}/ecitmatch.cgi`, { db: "pubmed", rettype: "xml", bdata }), options, signal);
+            if (result.status !== "ok")
+                return result;
+            const pmids = result.value
+                .trim()
+                .split(/\r?\n/)
+                .flatMap((line) => {
+                const value = line.split("|").at(-1)?.trim();
+                return value !== undefined && /^\d+$/.test(value) ? [value] : [];
+            });
+            return { status: "ok", value: pmids };
+        },
+        fetchArticles,
+        async articleDetails(pmids, signal) {
+            const [articlesResult, conversionResult] = await Promise.all([
+                fetchArticles(pmids, signal),
+                requestJson(url(NCBI_IDCONV, { ids: pmids.join(","), format: "json" }), IdConvResponseSchema, options, signal),
+            ]);
+            if (articlesResult.status !== "ok")
+                return articlesResult;
+            if (conversionResult.status === "ok") {
+                const conversions = parseIdConvResponse(conversionResult.value);
+                for (const article of articlesResult.value)
+                    article.pmcId = conversions.get(article.pmid) ?? null;
+            }
+            const found = new Set(articlesResult.value.map((article) => article.pmid));
+            return { status: "ok", value: { articles: articlesResult.value, notFound: pmids.filter((pmid) => !found.has(pmid)) } };
+        },
+        async fetchFullText(pmcId, signal) {
+            const result = await requestText(url(`${NCBI_BASE}/efetch.fcgi`, { db: "pmc", id: pmcId.replace(/^PMC/i, ""), rettype: "xml", retmode: "xml" }), options, signal);
+            return result.status === "ok" ? { status: "ok", value: parsePmcFullText(result.value) } : result;
+        },
+    };
+}

package/dist/literature/sources/semantic-scholar.d.ts

@@ -0,0 +1,24 @@
+import { type SourceHttpOptions, type SourceHttpResult } from "./http.js";
+export interface SemanticScholarPaper {
+    id: string;
+    title?: string;
+    abstract?: string;
+    year?: number;
+    venue?: string;
+    citationCount?: number;
+    url?: string;
+    authors: string[];
+    externalIds?: Record<string, string>;
+}
+export interface SemanticScholarSearchPaper extends SemanticScholarPaper {
+    title: string;
+}
+export interface SemanticScholarSourceOptions extends SourceHttpOptions {
+    readonly apiKey?: string;
+}
+export interface SemanticScholarSource {
+    search(query: string, limit: number, signal?: AbortSignal): Promise<SourceHttpResult<SemanticScholarSearchPaper[]>>;
+    lookupIdentifier(identifier: string, signal?: AbortSignal): Promise<SourceHttpResult<SemanticScholarPaper>>;
+}
+export declare function parseSemanticScholarResponse(raw: unknown): SemanticScholarSearchPaper[];
+export declare function createSemanticScholarSource(options?: SemanticScholarSourceOptions): SemanticScholarSource;

package/dist/literature/sources/semantic-scholar.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { requestJson } from "./http.js";
+const BASE_URL = "https://api.semanticscholar.org/graph/v1";
+const FIELDS = "paperId,title,abstract,year,venue,citationCount,url,authors,externalIds";
+const WirePaperSchema = z
+    .object({
+    paperId: z.string().optional(),
+    title: z.string().nullable().optional(),
+    abstract: z.string().nullable().optional(),
+    year: z.number().nullable().optional(),
+    venue: z.string().nullable().optional(),
+    citationCount: z.number().nullable().optional(),
+    url: z.string().nullable().optional(),
+    authors: z.array(z.object({ name: z.string().nullable().optional() })).optional(),
+    externalIds: z.record(z.string(), z.unknown()).nullable().optional(),
+})
+    .passthrough();
+const ExactPaperSchema = WirePaperSchema.extend({ paperId: z.string() });
+const SearchResponseSchema = z.object({ data: z.array(WirePaperSchema).optional() });
+function stringExternalIds(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    const entries = Object.entries(value).filter((entry) => typeof entry[1] === "string");
+    return entries.length === 0 ? undefined : Object.fromEntries(entries);
+}
+function mapPaper(raw) {
+    if (raw.paperId === undefined || raw.paperId.trim() === "")
+        return undefined;
+    const authors = raw.authors?.flatMap((author) => (typeof author.name === "string" && author.name.trim() ? [author.name] : [])) ?? [];
+    const externalIds = stringExternalIds(raw.externalIds);
+    return {
+        id: raw.paperId,
+        ...(typeof raw.title === "string" ? { title: raw.title } : {}),
+        ...(typeof raw.abstract === "string" ? { abstract: raw.abstract } : {}),
+        ...(typeof raw.year === "number" ? { year: raw.year } : {}),
+        ...(typeof raw.venue === "string" ? { venue: raw.venue } : {}),
+        ...(typeof raw.citationCount === "number" ? { citationCount: raw.citationCount } : {}),
+        ...(typeof raw.url === "string" ? { url: raw.url } : {}),
+        authors,
+        ...(externalIds === undefined ? {} : { externalIds }),
+    };
+}
+export function parseSemanticScholarResponse(raw) {
+    const parsed = SearchResponseSchema.safeParse(raw);
+    if (!parsed.success)
+        return [];
+    return (parsed.data.data ?? []).flatMap((paper) => {
+        const mapped = mapPaper(paper);
+        return mapped?.title === undefined ? [] : [mapped];
+    });
+}
+export function createSemanticScholarSource(options = {}) {
+    const headers = options.apiKey === undefined ? {} : { "x-api-key": options.apiKey };
+    return {
+        async search(query, limit, signal) {
+            const params = new URLSearchParams({ query, limit: String(limit), fields: FIELDS });
+            const result = await requestJson(`${BASE_URL}/paper/search?${params}`, SearchResponseSchema, options, signal, { headers });
+            if (result.status !== "ok")
+                return result;
+            return { status: "ok", value: parseSemanticScholarResponse(result.value) };
+        },
+        async lookupIdentifier(identifier, signal) {
+            const url = `${BASE_URL}/paper/${encodeURIComponent(identifier)}?fields=${encodeURIComponent(FIELDS)}`;
+            const result = await requestJson(url, ExactPaperSchema, options, signal, { headers });
+            if (result.status !== "ok")
+                return result;
+            const paper = mapPaper(result.value);
+            return paper === undefined ? { status: "unavailable", detail: "response schema mismatch: missing paperId" } : { status: "ok", value: paper };
+        },
+    };
+}