@marinoscar/kvox-eval 0.0.0-bootstrap → 0.1.0-next.0

package/dist/kg/scorer.js

@@ -0,0 +1,463 @@
+"use strict";
+// =============================================================================
+// The kg:eval scorer (issue #362) — pure, deterministic, no I/O.
+//
+// Matching rules (the issue's contract, restated only where a choice was made):
+//   - Entities: a candidate pair needs equal types and either the normalized
+//     predicted label ∈ normalized {gold label ∪ gold aliases} (similarity 1)
+//     or a token-set Jaccard ≥ 0.8 against one of those names. Assignment is
+//     one-to-one, greedy by descending similarity — never double-counted.
+//   - Entity coverage uses the same matcher with the type check dropped.
+//   - A relation/item endpoint is compared by CANONICAL identity: a gold
+//     entity is its `existingId` when it has one, else `key:<key>`; a
+//     `knownEntities` id is itself; a predicted ref maps to the gold entity it
+//     matched (or, unmatched, to the id its resolution linked, else nothing).
+//   - Items: equal kind, subject matched, statement token-set F1 ≥ 0.5, and a
+//     commitment's owner matched when the label names one.
+//   - Temporal accuracy: over matched relations of a temporal type (from the
+//     ontology registry, never a hand list): equal precision and both bounds
+//     equal after truncation to it (`unknown` matches only `unknown`); over
+//     matched items that carry a date: `occurredAt`/`dueAt` equal to the day.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ratio = exports.BASE_REPORT_TYPES = exports.ITEM_REPORT_TYPES = exports.ENTITY_REPORT_TYPES = exports.ITEM_STATEMENT_F1 = exports.ENTITY_MATCH_JACCARD = exports.normalizeName = void 0;
+exports.nameSimilarity = nameSimilarity;
+exports.matchEntities = matchEntities;
+exports.temporalEqual = temporalEqual;
+exports.scoreFixture = scoreFixture;
+exports.scoreRun = scoreRun;
+exports.precisionOf = precisionOf;
+exports.recallOf = recallOf;
+exports.f1Of = f1Of;
+exports.entityCoverage = entityCoverage;
+exports.commitmentRecall = commitmentRecall;
+exports.autoLinkPrecision = autoLinkPrecision;
+const ontology_1 = require("@marinoscar/kvox-contract/ontology");
+const text_js_1 = require("./text.js");
+var text_js_2 = require("./text.js");
+Object.defineProperty(exports, "normalizeName", { enumerable: true, get: function () { return text_js_2.normalizeName; } });
+/**
+ * The token-set Jaccard a predicted label needs against a gold name to be a match candidate.
+ *
+ * @stability experimental
+ */
+exports.ENTITY_MATCH_JACCARD = 0.8;
+/**
+ * The token-set F1 a predicted item statement needs against the gold statement.
+ *
+ * @stability experimental
+ */
+exports.ITEM_STATEMENT_F1 = 0.5;
+/**
+ * Report rows, fixed order. Relation rows (`relation:<TYPE>`) follow, sorted.
+ *
+ * @stability experimental
+ */
+exports.ENTITY_REPORT_TYPES = [
+    'Person',
+    'Organization',
+    'Project',
+    'Meeting',
+    // #383: the `personal` domain's entity types (only `personal`-tagged fixtures label them).
+    'Interest',
+    'Trip',
+    'Milestone',
+];
+/**
+ * The report row of each item kind.
+ *
+ * @stability experimental
+ */
+exports.ITEM_REPORT_TYPES = {
+    commitment: 'Commitment',
+    decision: 'Decision',
+    claim: 'Claim',
+    person_fact: 'PersonFact',
+};
+/**
+ * Every fixed report row: the entity types, then the item kinds.
+ *
+ * @stability experimental
+ */
+exports.BASE_REPORT_TYPES = [...exports.ENTITY_REPORT_TYPES, ...Object.values(exports.ITEM_REPORT_TYPES)];
+function bump(types, type, key, by = 1) {
+    const c = types[type] ?? (types[type] = { tp: 0, fp: 0, fn: 0 });
+    c[key] += by;
+}
+function goldNames(label, aliases) {
+    return new Set([label, ...aliases].map(text_js_1.normalizeName).filter((n) => n.length > 0));
+}
+/**
+ * Similarity of one predicted label to one gold name set; 0 when not a candidate.
+ *
+ * @stability experimental
+ */
+function nameSimilarity(predLabel, gold) {
+    const n = (0, text_js_1.normalizeName)(predLabel);
+    if (gold.names.has(n))
+        return 1;
+    const toks = (0, text_js_1.tokenSet)(predLabel);
+    let best = 0;
+    for (const g of gold.tokenSets)
+        best = Math.max(best, (0, text_js_1.jaccard)(toks, g));
+    return best >= exports.ENTITY_MATCH_JACCARD ? best : 0;
+}
+/** Greedy one-to-one assignment; returns predIdx → goldIdx. */
+function greedyAssign(candidates) {
+    const sorted = [...candidates].sort((a, b) => b.sim - a.sim || a.p - b.p || a.g - b.g);
+    const usedP = new Set();
+    const usedG = new Set();
+    const out = new Map();
+    for (const c of sorted) {
+        if (usedP.has(c.p) || usedG.has(c.g))
+            continue;
+        usedP.add(c.p);
+        usedG.add(c.g);
+        out.set(c.p, c.g);
+    }
+    return out;
+}
+/**
+ * The one-to-one assignment of predicted to gold entities (greedy by descending similarity).
+ *
+ * @param gold - the gold entities (label and aliases).
+ * @param preds - the predicted entities.
+ * @param opts - `typed`: candidates must share a type (entity coverage drops the check).
+ * @returns predicted index to gold index.
+ *
+ * @stability experimental
+ */
+function matchEntities(gold, preds, opts) {
+    const g = gold.map((e) => {
+        const names = goldNames(e.label, e.aliases);
+        return { type: e.type, names, tokenSets: [...names].map((n) => (0, text_js_1.tokenSet)(n)) };
+    });
+    const candidates = [];
+    preds.forEach((p, pi) => {
+        g.forEach((ge, gi) => {
+            if (opts.typed && ge.type !== p.type)
+                return;
+            const sim = nameSimilarity(p.label, ge);
+            if (sim > 0)
+                candidates.push({ p: pi, g: gi, sim });
+        });
+    });
+    return greedyAssign(candidates);
+}
+const TRUNC = { day: 10, month: 7, year: 4 };
+/**
+ * Whether two temporal ranges are equal at the gold precision (`unknown` matches only `unknown`).
+ *
+ * @param gold - the gold bounds and precision.
+ * @param pred - the predicted bounds and precision.
+ * @returns `true` when equal.
+ *
+ * @stability experimental
+ */
+function temporalEqual(gold, pred) {
+    if (gold.precision !== pred.precision)
+        return false;
+    if (gold.precision === 'unknown')
+        return true;
+    const n = TRUNC[gold.precision];
+    const t = (d) => (d === null ? null : d.slice(0, n));
+    return t(gold.validFrom) === t(pred.validFrom) && t(gold.validTo) === t(pred.validTo);
+}
+const day = (d) => (d ? d.slice(0, 10) : null);
+function evidenceValid(fixture, ev) {
+    // A note citation may quote the body (`N`) or the note's Context (`C`, #440).
+    if (ev.source === 'note') {
+        return (0, text_js_1.quoteFoundIn)(ev.quote, fixture.note.body) || (fixture.contextText !== null && (0, text_js_1.quoteFoundIn)(ev.quote, fixture.contextText));
+    }
+    const seg = fixture.segments.find((s) => s.id === ev.segmentId);
+    return seg !== undefined && (0, text_js_1.quoteFoundIn)(ev.quote, seg.text);
+}
+/**
+ * Scores one fixture's prediction. Pure and deterministic.
+ *
+ * @param fixture - the fixture and its labels.
+ * @param prediction - what a run predicted for it.
+ * @returns the fixture's score.
+ *
+ * @stability experimental
+ */
+function scoreFixture(fixture, prediction) {
+    const types = {};
+    for (const t of exports.BASE_REPORT_TYPES)
+        types[t] = { tp: 0, fp: 0, fn: 0 };
+    const goldEntities = fixture.labels.entities;
+    const knownIds = new Set(fixture.knownEntities.map((k) => k.id));
+    // --- entities -------------------------------------------------------------
+    const typedMatch = matchEntities(goldEntities, prediction.entities, { typed: true });
+    const matchedGold = new Set(typedMatch.values());
+    prediction.entities.forEach((p, pi) => {
+        if (typedMatch.has(pi))
+            bump(types, p.type, 'tp');
+        else
+            bump(types, p.type, 'fp');
+    });
+    goldEntities.forEach((g, gi) => {
+        if (!matchedGold.has(gi))
+            bump(types, g.type, 'fn');
+    });
+    const anyTypeMatch = matchEntities(goldEntities, prediction.entities, { typed: false });
+    const coverage = { matched: new Set(anyTypeMatch.values()).size, total: goldEntities.length };
+    // --- canonical identities -------------------------------------------------
+    const goldCanon = new Map();
+    for (const g of goldEntities)
+        goldCanon.set(g.key, g.existingId ?? `key:${g.key}`);
+    const canonGold = (s) => {
+        if (s === null)
+            return null;
+        return goldCanon.get(s) ?? (knownIds.has(s) ? s : `unresolved:${s}`);
+    };
+    const predCanon = new Map();
+    prediction.entities.forEach((p, pi) => {
+        const gi = typedMatch.get(pi);
+        if (gi !== undefined) {
+            predCanon.set(p.ref, canonGold(goldEntities[gi].key));
+        }
+        else if (p.resolution?.outcome === 'linked' && p.resolution.entityId) {
+            predCanon.set(p.ref, p.resolution.entityId);
+        }
+        else {
+            predCanon.set(p.ref, `pred:${p.ref}`);
+        }
+    });
+    const canonPred = (s) => {
+        if (s === null)
+            return null;
+        return predCanon.get(s) ?? (knownIds.has(s) ? s : `pred:${s}`);
+    };
+    // --- auto-link precision --------------------------------------------------
+    const autoLink = { correct: 0, total: 0, anyResolution: false };
+    prediction.entities.forEach((p, pi) => {
+        if (p.resolution)
+            autoLink.anyResolution = true;
+        if (!p.resolution || !p.resolution.prechecked || p.resolution.outcome !== 'linked')
+            return;
+        autoLink.total += 1;
+        const gi = typedMatch.get(pi);
+        const expected = gi === undefined ? undefined : goldEntities[gi].existingId;
+        if (expected && p.resolution.entityId === expected)
+            autoLink.correct += 1;
+    });
+    const temporal = { accurate: 0, total: 0 };
+    // --- relations ------------------------------------------------------------
+    const goldRels = fixture.labels.relations;
+    const usedGoldRel = new Set();
+    for (const p of prediction.relations) {
+        const pf = canonPred(p.from);
+        const pt = canonPred(p.to);
+        // #383: a symmetric relation (SPOUSE_OF, FRIEND_OF) matches either way round.
+        const symmetric = ontology_1.ONTOLOGY.relationType(p.type)?.symmetric === true;
+        const gi = goldRels.findIndex((g, i) => !usedGoldRel.has(i) &&
+            g.type === p.type &&
+            ((canonGold(g.from) === pf && canonGold(g.to) === pt) ||
+                (symmetric && canonGold(g.from) === pt && canonGold(g.to) === pf)));
+        const row = `relation:${p.type}`;
+        if (gi === -1) {
+            bump(types, row, 'fp');
+            continue;
+        }
+        usedGoldRel.add(gi);
+        bump(types, row, 'tp');
+        const g = goldRels[gi];
+        if (ontology_1.ONTOLOGY.relationType(g.type)?.temporal) {
+            temporal.total += 1;
+            if (temporalEqual(g, p))
+                temporal.accurate += 1;
+        }
+    }
+    goldRels.forEach((g, i) => {
+        if (!usedGoldRel.has(i))
+            bump(types, `relation:${g.type}`, 'fn');
+    });
+    // --- items ----------------------------------------------------------------
+    const goldItems = fixture.labels.items;
+    const itemCandidates = [];
+    prediction.items.forEach((p, pi) => {
+        goldItems.forEach((g, gi) => {
+            if (g.kind !== p.kind)
+                return;
+            if (canonGold(g.subject) !== canonPred(p.subject))
+                return;
+            if (g.kind === 'commitment' && g.owner !== null && canonGold(g.owner) !== canonPred(p.owner))
+                return;
+            const f1 = (0, text_js_1.tokenF1)(g.statement, p.statement);
+            if (f1 >= exports.ITEM_STATEMENT_F1)
+                itemCandidates.push({ p: pi, g: gi, sim: f1 });
+        });
+    });
+    const itemMatch = greedyAssign(itemCandidates);
+    const matchedGoldItems = new Set(itemMatch.values());
+    prediction.items.forEach((p, pi) => {
+        const row = exports.ITEM_REPORT_TYPES[p.kind];
+        const gi = itemMatch.get(pi);
+        if (gi === undefined) {
+            bump(types, row, 'fp');
+            return;
+        }
+        bump(types, row, 'tp');
+        const g = goldItems[gi];
+        if (g.occurredAt !== null || g.dueAt !== null) {
+            temporal.total += 1;
+            if (day(p.occurredAt) === g.occurredAt && day(p.dueAt) === g.dueAt)
+                temporal.accurate += 1;
+        }
+    });
+    goldItems.forEach((g, gi) => {
+        if (!matchedGoldItems.has(gi))
+            bump(types, exports.ITEM_REPORT_TYPES[g.kind], 'fn');
+    });
+    // --- evidence validity ----------------------------------------------------
+    const evidence = { valid: 0, total: 0 };
+    const allEvidence = [
+        ...prediction.entities.flatMap((e) => e.evidence),
+        ...prediction.relations.flatMap((r) => r.evidence),
+        ...prediction.items.flatMap((i) => i.evidence),
+    ];
+    for (const ev of allEvidence) {
+        evidence.total += 1;
+        if (evidenceValid(fixture, ev))
+            evidence.valid += 1;
+    }
+    return {
+        fixtureId: fixture.id,
+        types,
+        coverage,
+        autoLink,
+        evidence,
+        temporal,
+        stats: { ...prediction.stats },
+    };
+}
+/**
+ * Scores every fixture of a run (a fixture with no prediction scores as empty).
+ *
+ * @param fixtures - the fixtures.
+ * @param predictions - the predictions by fixture id.
+ * @returns the run's score.
+ *
+ * @stability experimental
+ */
+function scoreRun(fixtures, predictions) {
+    const run = {
+        fixtures: fixtures.length,
+        types: {},
+        coverage: { matched: 0, total: 0 },
+        autoLink: { correct: 0, total: 0, anyResolution: false },
+        evidence: { valid: 0, total: 0 },
+        temporal: { accurate: 0, total: 0 },
+        stats: {},
+        perFixture: [],
+    };
+    for (const t of exports.BASE_REPORT_TYPES)
+        run.types[t] = { tp: 0, fp: 0, fn: 0 };
+    for (const f of fixtures) {
+        const pred = predictions.get(f.id) ?? {
+            fixtureId: f.id,
+            model: null,
+            entities: [],
+            relations: [],
+            items: [],
+            stats: {},
+        };
+        const s = scoreFixture(f, pred);
+        run.perFixture.push(s);
+        for (const [type, c] of Object.entries(s.types)) {
+            bump(run.types, type, 'tp', c.tp);
+            bump(run.types, type, 'fp', c.fp);
+            bump(run.types, type, 'fn', c.fn);
+        }
+        run.coverage.matched += s.coverage.matched;
+        run.coverage.total += s.coverage.total;
+        run.autoLink.correct += s.autoLink.correct;
+        run.autoLink.total += s.autoLink.total;
+        run.autoLink.anyResolution ||= s.autoLink.anyResolution;
+        run.evidence.valid += s.evidence.valid;
+        run.evidence.total += s.evidence.total;
+        run.temporal.accurate += s.temporal.accurate;
+        run.temporal.total += s.temporal.total;
+        for (const [k, v] of Object.entries(s.stats))
+            run.stats[k] = (run.stats[k] ?? 0) + v;
+    }
+    return run;
+}
+// --- ratios -----------------------------------------------------------------
+/**
+ * `num / den`, or `null` (printed `n/a`) when `den` is 0.
+ *
+ * @stability experimental
+ */
+const ratio = (num, den) => (den === 0 ? null : num / den);
+exports.ratio = ratio;
+/**
+ * Precision of one row, or `null` with nothing predicted.
+ *
+ * @param c - the row's counts.
+ * @returns the ratio or `null`.
+ *
+ * @stability experimental
+ */
+function precisionOf(c) {
+    return (0, exports.ratio)(c.tp, c.tp + c.fp);
+}
+/**
+ * Recall of one row, or `null` with nothing labelled.
+ *
+ * @param c - the row's counts.
+ * @returns the ratio or `null`.
+ *
+ * @stability experimental
+ */
+function recallOf(c) {
+    return (0, exports.ratio)(c.tp, c.tp + c.fn);
+}
+/**
+ * F1 of one row, or `null` when precision or recall is.
+ *
+ * @param c - the row's counts.
+ * @returns the ratio or `null`.
+ *
+ * @stability experimental
+ */
+function f1Of(c) {
+    const p = precisionOf(c);
+    const r = recallOf(c);
+    if (p === null || r === null)
+        return null;
+    return p + r === 0 ? 0 : (2 * p * r) / (p + r);
+}
+/**
+ * Gold entities matched by any prediction, type ignored, over all gold entities (the §6 entity-coverage target).
+ *
+ * @param run - the run's coverage counts.
+ * @returns the ratio or `null`.
+ *
+ * @stability experimental
+ */
+function entityCoverage(run) {
+    return (0, exports.ratio)(run.coverage.matched, run.coverage.total);
+}
+/**
+ * Recall of the Commitment row (the §6 commitment-recall target).
+ *
+ * @param run - the run's per-type counts.
+ * @returns the ratio or `null`.
+ *
+ * @stability experimental
+ */
+function commitmentRecall(run) {
+    return recallOf(run.types.Commitment ?? { tp: 0, fp: 0, fn: 0 });
+}
+/**
+ * `null` (printed `n/a`) when no prediction carries a resolution, or none was a prechecked link.
+ *
+ * @stability experimental
+ */
+function autoLinkPrecision(run) {
+    if (!run.autoLink.anyResolution)
+        return null;
+    return (0, exports.ratio)(run.autoLink.correct, run.autoLink.total);
+}

package/dist/kg/targets.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The §6 quality bar (docs/specs/ontology.md). Gates on relaxing §7's resolution
+ * thresholds, not on shipping: CI reports, `--enforce` fails.
+ *
+ * @stability experimental
+ */
+export declare const KG_EVAL_TARGETS: {
+    readonly autoLinkPrecision: 0.95;
+    readonly commitmentRecall: 0.85;
+    readonly entityCoverage: 0.9;
+};
+/**
+ * One of the {@link KG_EVAL_TARGETS} keys.
+ *
+ * @stability experimental
+ */
+export type KgEvalTargetKey = keyof typeof KG_EVAL_TARGETS;

package/dist/kg/targets.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KG_EVAL_TARGETS = void 0;
+// The §6 quality bar (docs/specs/ontology.md). Gates on relaxing §7's
+// resolution thresholds — NOT gates on shipping; CI reports, `--enforce` fails.
+/**
+ * The §6 quality bar (docs/specs/ontology.md). Gates on relaxing §7's resolution
+ * thresholds, not on shipping: CI reports, `--enforce` fails.
+ *
+ * @stability experimental
+ */
+exports.KG_EVAL_TARGETS = {
+    autoLinkPrecision: 0.95,
+    commitmentRecall: 0.85,
+    entityCoverage: 0.9,
+};

package/dist/kg/text.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Collapse every whitespace run to one space and trim.
+ *
+ * @stability experimental
+ */
+export declare function collapseWhitespace(s: string): string;
+/**
+ * Whether `quote` occurs verbatim in `haystack`, after whitespace collapse on both.
+ *
+ * @stability experimental
+ */
+export declare function quoteFoundIn(quote: string, haystack: string): boolean;
+/**
+ * NFKC → lower-case → strip punctuation except an inner `'`/`-` (one joining
+ * two letters/digits) → collapse whitespace. "Sarah  Chen," → "sarah chen";
+ * "O'Neil-Smith" keeps both joiners.
+  *
+  * @stability experimental
+ */
+export declare function normalizeName(s: string): string;
+/**
+ * The set of normalized tokens of a string.
+ *
+ * @param s - the string.
+ * @returns its tokens.
+ *
+ * @stability experimental
+ */
+export declare function tokenSet(s: string): Set<string>;
+/**
+ * Jaccard similarity of two token sets.
+ *
+ * @param a - one set.
+ * @param b - the other.
+ * @returns |A∩B| / |A∪B| (1 for two empty sets).
+ *
+ * @stability experimental
+ */
+export declare function jaccard(a: Set<string>, b: Set<string>): number;
+/**
+ * Token-set F1: 2·|A∩B| / (|A|+|B|).
+ *
+ * @stability experimental
+ */
+export declare function tokenF1(a: string, b: string): number;

package/dist/kg/text.js

@@ -0,0 +1,100 @@
+"use strict";
+// Pure text helpers shared by the scorer, the loader and the fixture test.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collapseWhitespace = collapseWhitespace;
+exports.quoteFoundIn = quoteFoundIn;
+exports.normalizeName = normalizeName;
+exports.tokenSet = tokenSet;
+exports.jaccard = jaccard;
+exports.tokenF1 = tokenF1;
+/**
+ * Collapse every whitespace run to one space and trim.
+ *
+ * @stability experimental
+ */
+function collapseWhitespace(s) {
+    return s.replace(/\s+/g, ' ').trim();
+}
+/**
+ * Whether `quote` occurs verbatim in `haystack`, after whitespace collapse on both.
+ *
+ * @stability experimental
+ */
+function quoteFoundIn(quote, haystack) {
+    const q = collapseWhitespace(quote);
+    return q.length > 0 && collapseWhitespace(haystack).includes(q);
+}
+/**
+ * NFKC → lower-case → strip punctuation except an inner `'`/`-` (one joining
+ * two letters/digits) → collapse whitespace. "Sarah  Chen," → "sarah chen";
+ * "O'Neil-Smith" keeps both joiners.
+  *
+  * @stability experimental
+ */
+function normalizeName(s) {
+    const lowered = s.normalize('NFKC').toLowerCase().replace(/[‘’]/g, "'");
+    let out = '';
+    for (let i = 0; i < lowered.length; i += 1) {
+        const ch = lowered[i];
+        if (/[\p{L}\p{N}\s]/u.test(ch)) {
+            out += ch;
+            continue;
+        }
+        if ((ch === "'" || ch === '-') && i > 0 && i < lowered.length - 1) {
+            const prev = lowered[i - 1];
+            const next = lowered[i + 1];
+            if (/[\p{L}\p{N}]/u.test(prev) && /[\p{L}\p{N}]/u.test(next)) {
+                out += ch;
+                continue;
+            }
+        }
+        out += ' ';
+    }
+    return out.replace(/\s+/g, ' ').trim();
+}
+/**
+ * The set of normalized tokens of a string.
+ *
+ * @param s - the string.
+ * @returns its tokens.
+ *
+ * @stability experimental
+ */
+function tokenSet(s) {
+    const n = normalizeName(s);
+    return new Set(n.length === 0 ? [] : n.split(' '));
+}
+/**
+ * Jaccard similarity of two token sets.
+ *
+ * @param a - one set.
+ * @param b - the other.
+ * @returns |A∩B| / |A∪B| (1 for two empty sets).
+ *
+ * @stability experimental
+ */
+function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    let inter = 0;
+    for (const t of a)
+        if (b.has(t))
+            inter += 1;
+    return inter / (a.size + b.size - inter);
+}
+/**
+ * Token-set F1: 2·|A∩B| / (|A|+|B|).
+ *
+ * @stability experimental
+ */
+function tokenF1(a, b) {
+    const A = tokenSet(a);
+    const B = tokenSet(b);
+    if (A.size === 0 && B.size === 0)
+        return 1;
+    let inter = 0;
+    for (const t of A)
+        if (B.has(t))
+            inter += 1;
+    return (2 * inter) / (A.size + B.size);
+}

package/dist/live/adapters.d.ts

@@ -0,0 +1,16 @@
+import type { AiProviderAdapter } from '@marinoscar/platform-api/ai';
+/**
+ * A provider id {@link platformAdapter} can build.
+ *
+ * @stability experimental
+ */
+export type PlatformAdapterProvider = 'openai' | 'openai-compatible';
+/**
+ * The platform's adapter for a provider, constructed outside Nest.
+ *
+ * @param provider - `openai` or `openai-compatible`.
+ * @returns the adapter (`responses`, `embeddings`, ...).
+ * @throws Error when the installed platform no longer carries the adapter where this shim looks.
+ * @stability experimental
+ */
+export declare function platformAdapter(provider: PlatformAdapterProvider): AiProviderAdapter;