@mantra-ai/core 0.1.5 → 0.2.0

package/dist/discovery/ranking.d.ts

@@ -0,0 +1,31 @@
+import type { DiscoverCandidateCore, DiscoverSourceKind } from "./types";
+/**
+ * Normalize a raw source-specific score to 0–1 (lower = better).
+ *
+ * Each source uses a different scoring system:
+ * - Mantra FTS: BM25 rank (negative float, lower = better match)
+ * - Zotero: match-location score (negative int, e.g. -15 for title match)
+ * - Semantic Scholar: position in relevance-ordered results (0-based index)
+ * - null score: treated as 0.5 (neutral)
+ */
+export declare function normalizeScore(raw: number | null, sourceKind: DiscoverSourceKind, opts?: {
+    resultCount?: number;
+}): number;
+/**
+ * Merge candidates from multiple sources.
+ * Primary key: normalized DOI.
+ * Secondary key: normalized title (for DOI-less papers, min 10 chars).
+ */
+export declare function mergeCandidates(candidates: DiscoverCandidateCore[]): DiscoverCandidateCore[];
+export interface RankOpts {
+    /** Limit output to top N candidates. */
+    limit?: number;
+}
+/**
+ * Unified ranking pipeline:
+ * 1. Normalize each candidate's raw score to 0–1.
+ * 2. Apply boosts for locality, citations, and recency.
+ * 3. Sort ascending (lower = better). Deterministic tiebreak by title.
+ */
+export declare function rankCandidates(candidates: DiscoverCandidateCore[], opts?: RankOpts): DiscoverCandidateCore[];
+//# sourceMappingURL=ranking.d.ts.map

package/dist/discovery/ranking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ranking.d.ts","sourceRoot":"","sources":["../../src/discovery/ranking.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAkBzE;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,UAAU,EAAE,kBAAkB,EAC9B,IAAI,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9B,MAAM,CA+BR;AA4ED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,qBAAqB,EAAE,GAClC,qBAAqB,EAAE,CAiDzB;AAID,MAAM,WAAW,QAAQ;IACvB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,qBAAqB,EAAE,EACnC,IAAI,CAAC,EAAE,QAAQ,GACd,qBAAqB,EAAE,CA0BzB"}

package/dist/discovery/ranking.js

@@ -0,0 +1,195 @@
+// ── Boost weights (tunable) ──────────────────────────────────────────
+/** Boost applied when the paper exists in a local source. */
+const LOCAL_BOOST = 0.15;
+/** Max boost for highly-cited papers (log-scaled). */
+const CITATION_BOOST_MAX = 0.15;
+/** Max boost for recent papers (< 3 years old). */
+const RECENCY_BOOST_MAX = 0.10;
+/** Citation count at which the citation boost saturates. */
+const CITATION_SATURATION = 10_000;
+// ── Score normalization ──────────────────────────────────────────────
+/**
+ * Normalize a raw source-specific score to 0–1 (lower = better).
+ *
+ * Each source uses a different scoring system:
+ * - Mantra FTS: BM25 rank (negative float, lower = better match)
+ * - Zotero: match-location score (negative int, e.g. -15 for title match)
+ * - Semantic Scholar: position in relevance-ordered results (0-based index)
+ * - null score: treated as 0.5 (neutral)
+ */
+export function normalizeScore(raw, sourceKind, opts) {
+    if (raw === null)
+        return 0.5;
+    switch (sourceKind) {
+        case "mantra": {
+            // BM25 rank: typically -20 (best) to 0 (worst).
+            // Clamp to [-30, 0] then map to [0, 1].
+            const clamped = Math.max(-30, Math.min(0, raw));
+            return (clamped + 30) / 30;
+        }
+        case "zotero": {
+            // Zotero scores: -15 (title match) to -2 (author match).
+            // Map [-20, 0] → [0, 1].
+            const clamped = Math.max(-20, Math.min(0, raw));
+            return (clamped + 20) / 20;
+        }
+        case "semantic-scholar": {
+            // S2 results are ordered by relevance (position 0 = best).
+            // Normalize by result count, fallback to 20 if unknown.
+            const count = opts?.resultCount ?? 20;
+            return Math.min(1, raw / Math.max(1, count));
+        }
+        default: {
+            // Unknown source: assume raw is already roughly 0–1 or treat as neutral.
+            if (raw >= 0 && raw <= 1)
+                return raw;
+            return 0.5;
+        }
+    }
+}
+// ── Boost functions ──────────────────────────────────────────────────
+function localBoost(candidate) {
+    const hasLocal = candidate.sources.some((s) => s === "mantra" || s === "zotero" || s === "pdf-index");
+    return hasLocal ? LOCAL_BOOST : 0;
+}
+function citationBoost(candidate) {
+    const count = candidate.citationCount;
+    if (count == null || count <= 0)
+        return 0;
+    // Log-scaled: log(1 + count) / log(1 + SATURATION), capped at max.
+    return Math.min(CITATION_BOOST_MAX, (Math.log(1 + count) / Math.log(1 + CITATION_SATURATION)) * CITATION_BOOST_MAX);
+}
+function recencyBoost(candidate) {
+    if (candidate.year == null)
+        return 0;
+    const currentYear = new Date().getFullYear();
+    const age = currentYear - candidate.year;
+    if (age < 0)
+        return RECENCY_BOOST_MAX; // future-dated = very recent
+    if (age >= 3)
+        return 0;
+    // Linear decay: 0 years → full boost, 3 years → 0.
+    return RECENCY_BOOST_MAX * (1 - age / 3);
+}
+// ── Dedup ────────────────────────────────────────────────────────────
+/**
+ * Normalize a title for dedup comparison:
+ * lowercase, strip punctuation and extra whitespace.
+ */
+function normalizeTitle(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^\w\s]/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function mergeTwo(a, b) {
+    return {
+        doi: a.doi ?? b.doi,
+        title: a.title ?? b.title,
+        authors: a.authors ?? b.authors,
+        year: a.year ?? b.year,
+        sources: [...new Set([...a.sources, ...b.sources])],
+        score: bestRawScore(a.score, b.score),
+        // Merge materialization metadata (prefer non-null)
+        mantraId: a.mantraId ?? b.mantraId,
+        zoteroKey: a.zoteroKey ?? b.zoteroKey,
+        pdfPath: a.pdfPath ?? b.pdfPath,
+        // Merge remote metadata (prefer non-null)
+        semanticScholarId: a.semanticScholarId ?? b.semanticScholarId,
+        citationCount: a.citationCount ?? b.citationCount,
+        influentialCitationCount: a.influentialCitationCount ?? b.influentialCitationCount,
+        abstractSnippet: a.abstractSnippet ?? b.abstractSnippet,
+        venue: a.venue ?? b.venue,
+        url: a.url ?? b.url,
+    };
+}
+function bestRawScore(a, b) {
+    if (a === null)
+        return b;
+    if (b === null)
+        return a;
+    return Math.min(a, b);
+}
+/**
+ * Merge candidates from multiple sources.
+ * Primary key: normalized DOI.
+ * Secondary key: normalized title (for DOI-less papers, min 10 chars).
+ */
+export function mergeCandidates(candidates) {
+    const byDoi = new Map();
+    const byTitle = new Map();
+    const unkeyed = [];
+    for (const c of candidates) {
+        if (c.doi) {
+            const key = c.doi.toLowerCase();
+            const existing = byDoi.get(key);
+            if (existing) {
+                byDoi.set(key, mergeTwo(existing, c));
+            }
+            else {
+                byDoi.set(key, { ...c });
+            }
+            continue;
+        }
+        if (c.title) {
+            const key = normalizeTitle(c.title);
+            if (key.length >= 10) {
+                const existing = byTitle.get(key);
+                if (existing) {
+                    byTitle.set(key, mergeTwo(existing, c));
+                }
+                else {
+                    byTitle.set(key, { ...c });
+                }
+                continue;
+            }
+        }
+        unkeyed.push(c);
+    }
+    // Cross-check: title-keyed entries that also match a DOI-keyed entry
+    for (const [titleKey, titleCandidate] of byTitle) {
+        let merged = false;
+        for (const [, doiCandidate] of byDoi) {
+            if (doiCandidate.title && normalizeTitle(doiCandidate.title) === titleKey) {
+                byDoi.set(doiCandidate.doi.toLowerCase(), mergeTwo(doiCandidate, titleCandidate));
+                merged = true;
+                break;
+            }
+        }
+        if (!merged) {
+            unkeyed.push(titleCandidate);
+        }
+    }
+    return [...byDoi.values(), ...unkeyed];
+}
+/**
+ * Unified ranking pipeline:
+ * 1. Normalize each candidate's raw score to 0–1.
+ * 2. Apply boosts for locality, citations, and recency.
+ * 3. Sort ascending (lower = better). Deterministic tiebreak by title.
+ */
+export function rankCandidates(candidates, opts) {
+    const scored = candidates.map((c) => {
+        // Use the first source for normalization context
+        const primarySource = c.sources[0] ?? "unknown";
+        const normalized = normalizeScore(c.score, primarySource);
+        // Boosts are subtracted (lower = better)
+        const finalScore = normalized -
+            localBoost(c) -
+            citationBoost(c) -
+            recencyBoost(c);
+        return { candidate: c, finalScore };
+    });
+    // Sort: lower finalScore = better. Tiebreak by title.
+    scored.sort((a, b) => {
+        if (a.finalScore !== b.finalScore)
+            return a.finalScore - b.finalScore;
+        const aTitle = (a.candidate.title ?? "").toLowerCase();
+        const bTitle = (b.candidate.title ?? "").toLowerCase();
+        return aTitle.localeCompare(bTitle);
+    });
+    const limit = opts?.limit ?? scored.length;
+    return scored.slice(0, limit).map((s) => s.candidate);
+}
+//# sourceMappingURL=ranking.js.map

package/dist/discovery/ranking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ranking.js","sourceRoot":"","sources":["../../src/discovery/ranking.ts"],"names":[],"mappings":"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"}

package/dist/discovery/registry.d.ts

@@ -0,0 +1,32 @@
+import type { DiscoverCapability, DiscoverCandidateCore, DiscoverProvider, ProviderError, RegistrySearchOpts, RegistrySearchResult } from "./types";
+/**
+ * Holds registered discovery providers, runs searches in parallel,
+ * and isolates per-provider failures.
+ */
+export declare class ProviderRegistry {
+    private providers;
+    register(provider: DiscoverProvider): void;
+    /** Get providers filtered by capability and/or locality. */
+    getProviders(filter?: {
+        capability?: DiscoverCapability;
+        local?: boolean;
+    }): DiscoverProvider[];
+    /**
+     * Run all search-capable providers in parallel.
+     *
+     * Returns results split by local vs remote. A failure in one
+     * provider does not abort the others — it is captured in `errors`.
+     */
+    searchAll(query: string, opts?: RegistrySearchOpts): Promise<RegistrySearchResult>;
+    /**
+     * Run all augment-capable providers on a candidate list.
+     *
+     * Augmenters run sequentially (each may depend on prior enrichment).
+     * Failures are captured but do not abort the chain.
+     */
+    augmentAll(candidates: DiscoverCandidateCore[]): Promise<{
+        candidates: DiscoverCandidateCore[];
+        errors: ProviderError[];
+    }>;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/discovery/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/discovery/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,oBAAoB,EACrB,MAAM,SAAS,CAAC;AAEjB;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,SAAS,CAA0B;IAE3C,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAI1C,4DAA4D;IAC5D,YAAY,CAAC,MAAM,CAAC,EAAE;QACpB,UAAU,CAAC,EAAE,kBAAkB,CAAC;QAChC,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,GAAG,gBAAgB,EAAE;IAetB;;;;;OAKG;IACG,SAAS,CACb,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,kBAAkB,GACxB,OAAO,CAAC,oBAAoB,CAAC;IA0ChC;;;;;OAKG;IACG,UAAU,CACd,UAAU,EAAE,qBAAqB,EAAE,GAClC,OAAO,CAAC;QAAE,UAAU,EAAE,qBAAqB,EAAE,CAAC;QAAC,MAAM,EAAE,aAAa,EAAE,CAAA;KAAE,CAAC;CAoB7E"}

package/dist/discovery/registry.js

@@ -0,0 +1,90 @@
+/**
+ * Holds registered discovery providers, runs searches in parallel,
+ * and isolates per-provider failures.
+ */
+export class ProviderRegistry {
+    providers = [];
+    register(provider) {
+        this.providers.push(provider);
+    }
+    /** Get providers filtered by capability and/or locality. */
+    getProviders(filter) {
+        let list = this.providers;
+        if (filter?.capability) {
+            const cap = filter.capability;
+            list = list.filter((p) => p.capabilities.includes(cap));
+        }
+        if (filter?.local !== undefined) {
+            const local = filter.local;
+            list = list.filter((p) => p.isLocal === local);
+        }
+        return list;
+    }
+    /**
+     * Run all search-capable providers in parallel.
+     *
+     * Returns results split by local vs remote. A failure in one
+     * provider does not abort the others — it is captured in `errors`.
+     */
+    async searchAll(query, opts) {
+        const searchProviders = this.getProviders({ capability: "search" });
+        const active = opts?.localOnly
+            ? searchProviders.filter((p) => p.isLocal)
+            : searchProviders;
+        const local = [];
+        const remote = [];
+        const errors = [];
+        const settled = await Promise.allSettled(active.map(async (provider) => {
+            const results = await provider.search(query, { limit: opts?.limit });
+            return { provider, results };
+        }));
+        for (const outcome of settled) {
+            if (outcome.status === "fulfilled") {
+                const { provider, results } = outcome.value;
+                const bucket = provider.isLocal ? local : remote;
+                bucket.push(...results);
+            }
+            else {
+                // Extract provider info from the rejected promise
+                // Promise.allSettled doesn't give us the input, so we match by index
+                const idx = settled.indexOf(outcome);
+                const provider = active[idx];
+                errors.push({
+                    provider: provider?.name ?? "unknown",
+                    sourceKind: provider?.sourceKind ?? "unknown",
+                    error: outcome.reason instanceof Error
+                        ? outcome.reason.message
+                        : String(outcome.reason),
+                });
+            }
+        }
+        return { local, remote, errors };
+    }
+    /**
+     * Run all augment-capable providers on a candidate list.
+     *
+     * Augmenters run sequentially (each may depend on prior enrichment).
+     * Failures are captured but do not abort the chain.
+     */
+    async augmentAll(candidates) {
+        const augmenters = this.getProviders({ capability: "augment" });
+        const errors = [];
+        let result = candidates;
+        for (const provider of augmenters) {
+            if (!provider.augment)
+                continue;
+            try {
+                result = await provider.augment(result);
+            }
+            catch (e) {
+                errors.push({
+                    provider: provider.name,
+                    sourceKind: provider.sourceKind,
+                    error: e instanceof Error ? e.message : String(e),
+                });
+            }
+        }
+        return { candidates: result, errors };
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/discovery/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/discovery/registry.ts"],"names":[],"mappings":"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"}

package/dist/discovery/types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Core discovery contracts.
+ *
+ * Every discovery source (local or remote) implements DiscoverProvider.
+ * The registry orchestrates providers by capability and phase.
+ */
+/** What a provider can do. */
+export type DiscoverCapability = "search" | "augment";
+/**
+ * Extensible source identifier.
+ * Built-in kinds are listed here; providers may add new ones.
+ */
+export type DiscoverSourceKind = "mantra" | "zotero" | "pdf-index" | "semantic-scholar" | (string & {});
+/**
+ * A paper found during discovery, before materialization.
+ *
+ * Core fields are source-agnostic. Optional fields carry richer
+ * metadata from remote sources (citation counts, venue, etc.).
+ */
+export interface DiscoverCandidateCore {
+    doi: string | null;
+    title: string | null;
+    authors: string | null;
+    year: number | null;
+    /** Which sources contributed to this candidate. */
+    sources: DiscoverSourceKind[];
+    /** Raw relevance score from the source (interpretation varies). */
+    score: number | null;
+    /** Mantra store paper ID — set by MantraProvider when the paper is already ingested. */
+    mantraId?: number | null;
+    /** Zotero item key — set by ZoteroProvider for materialization. */
+    zoteroKey?: string | null;
+    /** Resolved local PDF path — set by PDF index augmenter or Zotero. */
+    pdfPath?: string | null;
+    /** Semantic Scholar paper ID. */
+    semanticScholarId?: string | null;
+    /** Total citation count. */
+    citationCount?: number | null;
+    /** Influential citation count (Semantic Scholar). */
+    influentialCitationCount?: number | null;
+    /** Short abstract or snippet. */
+    abstractSnippet?: string | null;
+    /** Publication venue name. */
+    venue?: string | null;
+    /** Canonical URL to the paper. */
+    url?: string | null;
+}
+export interface DiscoverSearchOpts {
+    limit?: number;
+}
+/**
+ * Contract every discovery source implements.
+ *
+ * - `search` providers return candidates for a text query.
+ * - `augment` providers enrich an existing candidate list (e.g. attach PDF paths).
+ */
+export interface DiscoverProvider {
+    /** Human-readable name (e.g. "Semantic Scholar"). */
+    readonly name: string;
+    /** Machine identifier for this source. */
+    readonly sourceKind: DiscoverSourceKind;
+    /** What this provider can do. */
+    readonly capabilities: readonly DiscoverCapability[];
+    /** True for sources backed by local data (store, Zotero, PDF dirs). */
+    readonly isLocal: boolean;
+    /**
+     * Search for papers matching a query.
+     * Only called on providers with the "search" capability.
+     */
+    search(query: string, opts?: DiscoverSearchOpts): Promise<DiscoverCandidateCore[]>;
+    /**
+     * Enrich candidates with additional metadata.
+     * Only called on providers with the "augment" capability.
+     * Mutates candidates in-place and returns the same array.
+     */
+    augment?(candidates: DiscoverCandidateCore[]): Promise<DiscoverCandidateCore[]>;
+}
+export interface RegistrySearchOpts {
+    limit?: number;
+    localOnly?: boolean;
+}
+export interface RegistrySearchResult {
+    local: DiscoverCandidateCore[];
+    remote: DiscoverCandidateCore[];
+    errors: ProviderError[];
+}
+export interface ProviderError {
+    provider: string;
+    sourceKind: DiscoverSourceKind;
+    error: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/discovery/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/discovery/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,8BAA8B;AAC9B,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,SAAS,CAAC;AAItD;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B,QAAQ,GACR,QAAQ,GACR,WAAW,GACX,kBAAkB,GAClB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAIlB;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAEpB,mDAAmD;IACnD,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAE9B,mEAAmE;IACnE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAIrB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAIxB,iCAAiC;IACjC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,4BAA4B;IAC5B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,qDAAqD;IACrD,wBAAwB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,iCAAiC;IACjC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAID,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IAExC,iCAAiC;IACjC,QAAQ,CAAC,YAAY,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAErD,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAAC;IAEnF;;;;OAIG;IACH,OAAO,CAAC,CAAC,UAAU,EAAE,qBAAqB,EAAE,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAAC;CACjF;AAID,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAID,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,qBAAqB,EAAE,CAAC;IAC/B,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAChC,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,kBAAkB,CAAC;IAC/B,KAAK,EAAE,MAAM,CAAC;CACf"}

package/dist/discovery/types.js

@@ -0,0 +1,8 @@
+/**
+ * Core discovery contracts.
+ *
+ * Every discovery source (local or remote) implements DiscoverProvider.
+ * The registry orchestrates providers by capability and phase.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/discovery/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/discovery/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/index.d.ts

@@ -18,6 +18,13 @@ export { pickFirstString, parseArxivIdFromUrl, parseArxivIdFromDoi, parseBiorxiv
 export { createWorkId } from "./works/util/work-id";
 export { NormalizedDocSchema, SectionCategoryEnum, } from "./normalization/normalized-doc-schema";
 export type { NormalizedDoc } from "./normalization/normalized-doc-schema";
+export type { DiscoverCapability, DiscoverSourceKind, DiscoverCandidateCore, DiscoverProvider, DiscoverSearchOpts, RegistrySearchOpts, RegistrySearchResult, ProviderError, } from "./discovery/types";
+export { ProviderRegistry } from "./discovery/registry";
+export { normalizeScore, mergeCandidates, rankCandidates, } from "./discovery/ranking";
+export type { RankOpts } from "./discovery/ranking";
+export { SemanticScholarProvider } from "./sources/semantic-scholar/provider";
+export { searchPapers as s2SearchPapers, getPaperDetails as s2GetPaperDetails, } from "./sources/semantic-scholar/client";
+export type { S2Paper, S2Author, S2ExternalIds, S2SearchResponse, S2ClientOpts, } from "./sources/semantic-scholar/client";
 export type { PaperDigest, HypothesisSet, Hypothesis } from "./analysis/schemas";
 export { PaperDigestSchema, HypothesisSetSchema } from "./analysis/schemas";
 export { extractFindings } from "./analysis/extract-findings";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACrE,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGxD,YAAY,EACV,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,YAAY,EACZ,UAAU,EACV,cAAc,EACd,aAAa,EACb,aAAa,EACb,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,IAAI,EACJ,eAAe,EACf,YAAY,EACZ,eAAe,EACf,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,WAAW,GACZ,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGzC,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EACL,YAAY,EACZ,SAAS,EACT,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,6BAA6B,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AACvE,YAAY,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,YAAY,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAGvE,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGpD,OAAO,EACL,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,uCAAuC,CAAC;AAC/C,YAAY,EAAE,aAAa,EAAE,MAAM,uCAAuC,CAAC;AAG3E,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -18,6 +18,11 @@ export { pickFirstString, parseArxivIdFromUrl, parseArxivIdFromDoi, parseBiorxiv
 export { createWorkId } from "./works/util/work-id";
 // ── Normalization ──────────────────────────────────────────────────
 export { NormalizedDocSchema, SectionCategoryEnum, } from "./normalization/normalized-doc-schema";
+export { ProviderRegistry } from "./discovery/registry";
+export { normalizeScore, mergeCandidates, rankCandidates, } from "./discovery/ranking";
+// ── Sources: Semantic Scholar ────────────────────────────────────
+export { SemanticScholarProvider } from "./sources/semantic-scholar/provider";
+export { searchPapers as s2SearchPapers, getPaperDetails as s2GetPaperDetails, } from "./sources/semantic-scholar/client";
 export { PaperDigestSchema, HypothesisSetSchema } from "./analysis/schemas";
 export { extractFindings } from "./analysis/extract-findings";
 export { generateHypotheses } from "./analysis/generate-hypotheses";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iCAAiC;AAEjC,sEAAsE;AACtE,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AAEjC,sEAAsE;AACtE,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAsCrE,sEAAsE;AACtE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAIzC,OAAO,EACL,YAAY,EACZ,SAAS,EACT,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,6BAA6B,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAEvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAGhE,sEAAsE;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,sEAAsE;AACtE,OAAO,EACL,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,uCAAuC,CAAC;AAK/C,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iCAAiC;AAEjC,sEAAsE;AACtE,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AAEjC,sEAAsE;AACtE,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAsCrE,sEAAsE;AACtE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAIzC,OAAO,EACL,YAAY,EACZ,SAAS,EACT,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,6BAA6B,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAEvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAGhE,sEAAsE;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,sEAAsE;AACtE,OAAO,EACL,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,uCAAuC,CAAC;AAc/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EACL,cAAc,EACd,eAAe,EACf,cAAc,GACf,MAAM,qBAAqB,CAAC;AAG7B,oEAAoE;AACpE,OAAO,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AAC9E,OAAO,EACL,YAAY,IAAI,cAAc,EAC9B,eAAe,IAAI,iBAAiB,GACrC,MAAM,mCAAmC,CAAC;AAW3C,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC"}

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

@@ -0,0 +1,69 @@
+/**
+ * Typed client for the Semantic Scholar Academic Graph API.
+ *
+ * Unauthenticated: 100 requests per 5 minutes.
+ * Authenticated (x-api-key header): higher limits.
+ *
+ * @see https://api.semanticscholar.org/api-docs/graph
+ */
+import type { AdapterResult } from "../../works/types";
+export interface S2Author {
+    authorId: string | null;
+    name: string | null;
+}
+export interface S2ExternalIds {
+    DOI?: string | null;
+    ArXiv?: string | null;
+    PubMed?: string | null;
+    PMCID?: string | null;
+    MAG?: string | null;
+    CorpusId?: number | null;
+}
+export interface S2Paper {
+    paperId: string;
+    title: string | null;
+    abstract: string | null;
+    year: number | null;
+    authors: S2Author[];
+    citationCount: number | null;
+    influentialCitationCount: number | null;
+    venue: string | null;
+    externalIds: S2ExternalIds | null;
+    url: string | null;
+    referenceCount?: number | null;
+    isOpenAccess?: boolean | null;
+    openAccessPdf?: {
+        url: string;
+    } | null;
+    publicationDate?: string | null;
+    journal?: {
+        name: string | null;
+    } | null;
+}
+export interface S2SearchResponse {
+    total: number;
+    offset: number;
+    next?: number;
+    data: S2Paper[];
+}
+export interface S2ClientOpts {
+    apiKey?: string;
+}
+/**
+ * Search for papers by keyword query.
+ *
+ * @see https://api.semanticscholar.org/api-docs/graph#tag/Paper-Data/operation/post_graph_get_papers_search
+ */
+export declare function searchPapers(query: string, opts?: S2ClientOpts & {
+    limit?: number;
+    offset?: number;
+}): Promise<AdapterResult<S2SearchResponse>>;
+/**
+ * Get detailed information about a single paper.
+ *
+ * Accepts S2 paper ID, DOI (prefixed with "DOI:"), ArXiv ID ("ARXIV:"), etc.
+ *
+ * @see https://api.semanticscholar.org/api-docs/graph#tag/Paper-Data/operation/post_graph_get_paper
+ */
+export declare function getPaperDetails(paperId: string, opts?: S2ClientOpts): Promise<AdapterResult<S2Paper>>;
+//# sourceMappingURL=client.d.ts.map

package/dist/sources/semantic-scholar/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/sources/semantic-scholar/client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAkCvD,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,wBAAwB,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,EAAE,aAAa,GAAG,IAAI,CAAC;IAClC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,YAAY,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,aAAa,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACvC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CAC1C;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAiDD;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,YAAY,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACxD,OAAO,CAAC,aAAa,CAAC,gBAAgB,CAAC,CAAC,CA4B1C;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,YAAY,GAClB,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAkBjC"}