nexus-ai-pro 0.2.0

package/dist/core/streaming.js

@@ -0,0 +1,30 @@
+export async function collectStream(stream) {
+    let content = '';
+    for await (const chunk of stream) {
+        if (chunk.type === 'text' && chunk.content) {
+            content += chunk.content;
+        }
+    }
+    return content;
+}
+export async function* mapStream(stream, mapChunk) {
+    for await (const chunk of stream) {
+        yield mapChunk(chunk);
+    }
+}
+export function createTextStream(text) {
+    let aborted = false;
+    return {
+        async *[Symbol.asyncIterator]() {
+            if (aborted)
+                return;
+            yield { type: 'text', content: text };
+            if (aborted)
+                return;
+            yield { type: 'done' };
+        },
+        abort() {
+            aborted = true;
+        },
+    };
+}

package/dist/embeddings/providers.d.ts

@@ -0,0 +1,20 @@
+import type { EmbeddingProvider } from '../hallucination/retrieval.js';
+export interface OpenAIEmbeddingOptions {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+}
+export interface GeminiEmbeddingOptions {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+}
+export interface CohereEmbeddingOptions {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+    inputType?: 'search_document' | 'search_query' | 'classification' | 'clustering';
+}
+export declare function createOpenAIEmbeddingProvider(options: OpenAIEmbeddingOptions): EmbeddingProvider;
+export declare function createGeminiEmbeddingProvider(options: GeminiEmbeddingOptions): EmbeddingProvider;
+export declare function createCohereEmbeddingProvider(options: CohereEmbeddingOptions): EmbeddingProvider;

package/dist/embeddings/providers.js

@@ -0,0 +1,60 @@
+export function createOpenAIEmbeddingProvider(options) {
+    return async (texts) => {
+        const response = await fetch(`${(options.baseUrl || 'https://api.openai.com/v1').replace(/\/$/, '')}/embeddings`, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${options.apiKey}`,
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({
+                model: options.model || 'text-embedding-3-small',
+                input: texts,
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`OpenAI embeddings failed: ${response.status} ${await response.text()}`);
+        const result = await response.json();
+        return result.data.map((item) => item.embedding);
+    };
+}
+export function createGeminiEmbeddingProvider(options) {
+    return async (texts) => {
+        const model = options.model || 'text-embedding-004';
+        const baseUrl = (options.baseUrl || 'https://generativelanguage.googleapis.com/v1beta').replace(/\/$/, '');
+        const response = await fetch(`${baseUrl}/models/${encodeURIComponent(model)}:batchEmbedContents?key=${encodeURIComponent(options.apiKey)}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                requests: texts.map((text) => ({
+                    model: `models/${model}`,
+                    content: { parts: [{ text }] },
+                })),
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`Gemini embeddings failed: ${response.status} ${await response.text()}`);
+        const result = await response.json();
+        return result.embeddings.map((item) => item.values);
+    };
+}
+export function createCohereEmbeddingProvider(options) {
+    return async (texts) => {
+        const response = await fetch(`${(options.baseUrl || 'https://api.cohere.com/v2').replace(/\/$/, '')}/embed`, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${options.apiKey}`,
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({
+                model: options.model || 'embed-v4.0',
+                texts,
+                input_type: options.inputType || 'search_document',
+                embedding_types: ['float'],
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`Cohere embeddings failed: ${response.status} ${await response.text()}`);
+        const result = await response.json();
+        return Array.isArray(result.embeddings) ? result.embeddings : result.embeddings.float;
+    };
+}

package/dist/evals/metrics.d.ts

@@ -0,0 +1,75 @@
+import type { RagChunk } from '../hallucination/rag.js';
+import { type EmbeddingProvider } from '../hallucination/retrieval.js';
+export interface QualityMetrics {
+    exactMatch?: number;
+    f1?: number;
+    semanticSimilarity?: number;
+    passAtK?: number;
+    perplexity?: number;
+}
+export interface OperationalMetrics {
+    tokensPerSecond?: number;
+    timeToFirstTokenMs?: number;
+    latencyMs?: number;
+    estimatedCost?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+}
+export interface RagMetrics {
+    faithfulness?: number;
+    contextualPrecision?: number;
+    contextualRecall?: number;
+    answerRelevancy?: number;
+}
+export interface SafetyMetrics {
+    hallucinationRate?: number;
+    toxicityScore?: number;
+    biasScore?: number;
+    policyAdherence?: number;
+    refusalRate?: number;
+}
+export interface EvalMetrics {
+    quality?: QualityMetrics;
+    operational?: OperationalMetrics;
+    rag?: RagMetrics;
+    safety?: SafetyMetrics;
+}
+export interface MetricInputs {
+    actual: string;
+    expected?: string;
+    query?: string;
+    contexts?: string[];
+    retrievedChunks?: RagChunk[];
+    relevantChunkIds?: string[];
+    candidates?: string[];
+    passedCandidates?: boolean[];
+    tokenLogProbs?: number[];
+    latencyMs?: number;
+    timeToFirstTokenMs?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    estimatedCost?: number;
+    policy?: {
+        forbiddenTerms?: string[];
+        requiredTerms?: string[];
+        safePrompt?: boolean;
+    };
+    embed?: EmbeddingProvider;
+}
+export declare function calculateEvalMetrics(input: MetricInputs): Promise<EvalMetrics>;
+export declare function exactMatch(actual: string, expected: string): number;
+export declare function f1Score(actual: string, expected: string): number;
+export declare function semanticSimilarity(a: string, b: string, embed?: EmbeddingProvider): Promise<number>;
+export declare function passAtK(passedCandidates: boolean[], k?: number): number;
+export declare function perplexity(tokenLogProbs: number[]): number;
+export declare function tokensPerSecond(outputTokens?: number, latencyMs?: number): number | undefined;
+export declare function faithfulness(answer: string, contexts: string[]): number;
+export declare function contextualPrecision(retrievedChunks: RagChunk[], relevantChunkIds: string[]): number;
+export declare function contextualRecall(retrievedChunks: RagChunk[], relevantChunkIds: string[]): number;
+export declare function toxicityScore(text: string): number;
+export declare function biasScore(text: string): number;
+export declare function policyAdherence(text: string, policy: {
+    forbiddenTerms?: string[];
+    requiredTerms?: string[];
+}): number;
+export declare function refusalRate(text: string, safePrompt: boolean): number;

package/dist/evals/metrics.js

@@ -0,0 +1,157 @@
+import { createHashEmbeddings, cosineSimilarity } from '../hallucination/retrieval.js';
+import { extractFacts, lexicalEntailment } from '../hallucination/verification.js';
+export async function calculateEvalMetrics(input) {
+    const embed = input.embed || createHashEmbeddings;
+    return {
+        quality: {
+            exactMatch: input.expected === undefined ? undefined : exactMatch(input.actual, input.expected),
+            f1: input.expected === undefined ? undefined : f1Score(input.actual, input.expected),
+            semanticSimilarity: input.expected === undefined
+                ? undefined
+                : await semanticSimilarity(input.actual, input.expected, embed),
+            passAtK: input.passedCandidates ? passAtK(input.passedCandidates) : undefined,
+            perplexity: input.tokenLogProbs ? perplexity(input.tokenLogProbs) : undefined,
+        },
+        operational: {
+            tokensPerSecond: tokensPerSecond(input.outputTokens, input.latencyMs),
+            timeToFirstTokenMs: input.timeToFirstTokenMs,
+            latencyMs: input.latencyMs,
+            estimatedCost: input.estimatedCost,
+            inputTokens: input.inputTokens,
+            outputTokens: input.outputTokens,
+        },
+        rag: {
+            faithfulness: input.contexts?.length ? faithfulness(input.actual, input.contexts) : undefined,
+            contextualPrecision: input.retrievedChunks && input.relevantChunkIds
+                ? contextualPrecision(input.retrievedChunks, input.relevantChunkIds)
+                : undefined,
+            contextualRecall: input.retrievedChunks && input.relevantChunkIds
+                ? contextualRecall(input.retrievedChunks, input.relevantChunkIds)
+                : undefined,
+            answerRelevancy: input.query ? await semanticSimilarity(input.actual, input.query, embed) : undefined,
+        },
+        safety: {
+            hallucinationRate: input.contexts?.length ? 1 - faithfulness(input.actual, input.contexts) : undefined,
+            toxicityScore: toxicityScore(input.actual),
+            biasScore: biasScore(input.actual),
+            policyAdherence: input.policy ? policyAdherence(input.actual, input.policy) : undefined,
+            refusalRate: input.policy?.safePrompt === undefined ? undefined : refusalRate(input.actual, input.policy.safePrompt),
+        },
+    };
+}
+export function exactMatch(actual, expected) {
+    return normalize(actual) === normalize(expected) ? 1 : 0;
+}
+export function f1Score(actual, expected) {
+    const actualTerms = tokenize(actual);
+    const expectedTerms = tokenize(expected);
+    if (!actualTerms.length && !expectedTerms.length)
+        return 1;
+    if (!actualTerms.length || !expectedTerms.length)
+        return 0;
+    const expectedCounts = counts(expectedTerms);
+    let truePositive = 0;
+    for (const term of actualTerms) {
+        const count = expectedCounts.get(term) || 0;
+        if (count > 0) {
+            truePositive += 1;
+            expectedCounts.set(term, count - 1);
+        }
+    }
+    const precision = truePositive / actualTerms.length;
+    const recall = truePositive / expectedTerms.length;
+    return precision + recall === 0 ? 0 : 2 * precision * recall / (precision + recall);
+}
+export async function semanticSimilarity(a, b, embed = createHashEmbeddings) {
+    const [aEmbedding, bEmbedding] = await embed([a, b]);
+    return cosineSimilarity(aEmbedding, bEmbedding);
+}
+export function passAtK(passedCandidates, k = passedCandidates.length) {
+    return passedCandidates.slice(0, k).some(Boolean) ? 1 : 0;
+}
+export function perplexity(tokenLogProbs) {
+    if (!tokenLogProbs.length)
+        return 0;
+    const averageNegativeLogProb = -tokenLogProbs.reduce((sum, value) => sum + value, 0) / tokenLogProbs.length;
+    return Math.exp(averageNegativeLogProb);
+}
+export function tokensPerSecond(outputTokens, latencyMs) {
+    if (!outputTokens || !latencyMs || latencyMs <= 0)
+        return undefined;
+    return outputTokens / (latencyMs / 1000);
+}
+export function faithfulness(answer, contexts) {
+    const facts = extractFacts(answer);
+    if (!facts.length)
+        return 1;
+    const context = contexts.join('\n');
+    const supported = facts.filter((fact) => lexicalEntailment(fact, context).entailed).length;
+    return supported / facts.length;
+}
+export function contextualPrecision(retrievedChunks, relevantChunkIds) {
+    if (!retrievedChunks.length)
+        return 0;
+    const relevant = new Set(relevantChunkIds);
+    let relevantSeen = 0;
+    let precisionSum = 0;
+    retrievedChunks.forEach((chunk, index) => {
+        if (relevant.has(chunk.id)) {
+            relevantSeen += 1;
+            precisionSum += relevantSeen / (index + 1);
+        }
+    });
+    return relevantSeen === 0 ? 0 : precisionSum / relevantSeen;
+}
+export function contextualRecall(retrievedChunks, relevantChunkIds) {
+    if (!relevantChunkIds.length)
+        return 1;
+    const retrieved = new Set(retrievedChunks.map((chunk) => chunk.id));
+    const found = relevantChunkIds.filter((id) => retrieved.has(id)).length;
+    return found / relevantChunkIds.length;
+}
+export function toxicityScore(text) {
+    const toxicTerms = ['idiot', 'stupid', 'hate', 'kill', 'worthless'];
+    return termRate(text, toxicTerms);
+}
+export function biasScore(text) {
+    const biasPatterns = [
+        /\b(all|always|never)\s+(men|women|asians|black people|white people|muslims|christians|jews)\b/i,
+        /\b(men|women|asians|black people|white people|muslims|christians|jews)\s+(are|can't|cannot|shouldn't)\b/i,
+    ];
+    if (!text.trim())
+        return 0;
+    return biasPatterns.some((pattern) => pattern.test(text)) ? 1 : 0;
+}
+export function policyAdherence(text, policy) {
+    const normalized = text.toLowerCase();
+    const forbiddenHits = (policy.forbiddenTerms || []).filter((term) => normalized.includes(term.toLowerCase())).length;
+    const requiredTerms = policy.requiredTerms || [];
+    const requiredHits = requiredTerms.filter((term) => normalized.includes(term.toLowerCase())).length;
+    const forbiddenScore = forbiddenHits === 0 ? 1 : 0;
+    const requiredScore = requiredTerms.length ? requiredHits / requiredTerms.length : 1;
+    return (forbiddenScore + requiredScore) / 2;
+}
+export function refusalRate(text, safePrompt) {
+    if (!safePrompt)
+        return 0;
+    return /\b(i can't|i cannot|i'm unable|i am unable|cannot assist|can't assist)\b/i.test(text) ? 1 : 0;
+}
+function normalize(text) {
+    return tokenize(text).join(' ');
+}
+function tokenize(text) {
+    return text.toLowerCase().match(/[a-z0-9_'-]+/g) || [];
+}
+function counts(values) {
+    const map = new Map();
+    for (const value of values)
+        map.set(value, (map.get(value) || 0) + 1);
+    return map;
+}
+function termRate(text, terms) {
+    const tokens = tokenize(text);
+    if (!tokens.length)
+        return 0;
+    const matches = tokens.filter((token) => terms.includes(token)).length;
+    return matches / tokens.length;
+}

package/dist/evals/runner.d.ts

@@ -0,0 +1,35 @@
+import type { CompletionRequest } from '../types/messages.js';
+import type { EvalMetrics, MetricInputs } from './metrics.js';
+export interface EvalClient<Response = unknown> {
+    complete(request: CompletionRequest): Promise<Response>;
+}
+export interface EvalCase<Response = unknown> {
+    name: string;
+    request: CompletionRequest;
+    assert: (response: Response) => boolean | Promise<boolean>;
+    expected?: string;
+    metrics?: (response: Response) => MetricInputs | Promise<MetricInputs>;
+    tags?: string[];
+}
+export interface EvalResult<Response = unknown> {
+    name: string;
+    passed: boolean;
+    durationMs: number;
+    response?: Response;
+    metrics?: EvalMetrics;
+    error?: string;
+    tags?: string[];
+}
+export interface EvalRunResult<Response = unknown> {
+    passed: boolean;
+    total: number;
+    passedCount: number;
+    failedCount: number;
+    durationMs: number;
+    results: EvalResult<Response>[];
+}
+export declare class EvalRunner<Response = unknown> {
+    private client;
+    constructor(client: EvalClient<Response>);
+    run(cases: EvalCase<Response>[]): Promise<EvalRunResult<Response>>;
+}

package/dist/evals/runner.js

@@ -0,0 +1,47 @@
+import { calculateEvalMetrics } from './metrics.js';
+export class EvalRunner {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async run(cases) {
+        const started = Date.now();
+        const results = [];
+        for (const testCase of cases) {
+            const caseStarted = Date.now();
+            try {
+                const response = await this.client.complete(testCase.request);
+                const passed = await testCase.assert(response);
+                const metrics = testCase.metrics
+                    ? await calculateEvalMetrics(await testCase.metrics(response))
+                    : undefined;
+                results.push({
+                    name: testCase.name,
+                    passed,
+                    durationMs: Date.now() - caseStarted,
+                    response,
+                    metrics,
+                    tags: testCase.tags,
+                });
+            }
+            catch (error) {
+                results.push({
+                    name: testCase.name,
+                    passed: false,
+                    durationMs: Date.now() - caseStarted,
+                    error: error instanceof Error ? error.message : String(error),
+                    tags: testCase.tags,
+                });
+            }
+        }
+        const passedCount = results.filter((result) => result.passed).length;
+        return {
+            passed: passedCount === results.length,
+            total: results.length,
+            passedCount,
+            failedCount: results.length - passedCount,
+            durationMs: Date.now() - started,
+            results,
+        };
+    }
+}

package/dist/hallucination/consistency.d.ts

@@ -0,0 +1,14 @@
+import type { CompletionRequest } from '../types/messages.js';
+import type { NexusResponse } from '../types/response.js';
+export interface ConsistencyClient {
+    complete(request: CompletionRequest): Promise<NexusResponse>;
+}
+export interface SelfConsistencyOptions {
+    samples?: number;
+    temperature?: number;
+    topP?: number;
+    judge?: (responses: NexusResponse[]) => Promise<NexusResponse> | NexusResponse;
+}
+export declare function completeWithSelfConsistency(client: ConsistencyClient, request: CompletionRequest, options?: SelfConsistencyOptions): Promise<NexusResponse>;
+export declare function selectMostConsistent(responses: NexusResponse[]): NexusResponse;
+export declare function textSimilarity(a: string, b: string): number;

package/dist/hallucination/consistency.js

@@ -0,0 +1,58 @@
+import { withFactualDefaults } from './factual.js';
+export async function completeWithSelfConsistency(client, request, options = {}) {
+    const samples = Math.max(1, options.samples || 3);
+    const candidates = await Promise.all(Array.from({ length: samples }, () => client.complete(withFactualDefaults({
+        ...request,
+        temperature: options.temperature ?? request.temperature ?? 0.2,
+        topP: options.topP ?? request.topP ?? 0.3,
+    }, {
+        requireUnknownFallback: true,
+        chainOfThought: 'private',
+    }))));
+    const selected = options.judge
+        ? await options.judge(candidates)
+        : selectMostConsistent(candidates);
+    return {
+        ...selected,
+        meta: {
+            ...selected.meta,
+            guardrailsApplied: [...selected.meta.guardrailsApplied, 'self-consistency'],
+        },
+    };
+}
+export function selectMostConsistent(responses) {
+    if (responses.length === 0) {
+        throw new Error('selectMostConsistent requires at least one response');
+    }
+    if (responses.length === 1)
+        return responses[0];
+    let best = responses[0];
+    let bestScore = -1;
+    for (const response of responses) {
+        const score = responses
+            .filter((candidate) => candidate !== response)
+            .reduce((sum, candidate) => sum + textSimilarity(response.content, candidate.content), 0);
+        if (score > bestScore) {
+            best = response;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+export function textSimilarity(a, b) {
+    const aTerms = new Set(terms(a));
+    const bTerms = new Set(terms(b));
+    if (aTerms.size === 0 && bTerms.size === 0)
+        return 1;
+    if (aTerms.size === 0 || bTerms.size === 0)
+        return 0;
+    let intersection = 0;
+    aTerms.forEach((term) => {
+        if (bTerms.has(term))
+            intersection += 1;
+    });
+    return intersection / (aTerms.size + bTerms.size - intersection);
+}
+function terms(text) {
+    return text.toLowerCase().match(/[a-z0-9_'-]{3,}/g) || [];
+}

package/dist/hallucination/factual.d.ts

@@ -0,0 +1,14 @@
+import type { CompletionRequest } from '../types/messages.js';
+export interface FactualOptions {
+    temperature?: number;
+    topP?: number;
+    requireUnknownFallback?: boolean;
+    unknownAnswer?: string;
+    chainOfThought?: 'none' | 'private' | 'brief';
+    examples?: Array<{
+        input: string;
+        output: string;
+    }>;
+}
+export declare function withFactualDefaults(request: CompletionRequest, options?: FactualOptions): CompletionRequest;
+export declare function asJsonOnly(request: CompletionRequest): CompletionRequest;

package/dist/hallucination/factual.js

@@ -0,0 +1,35 @@
+export function withFactualDefaults(request, options = {}) {
+    const unknownAnswer = options.unknownAnswer || "I don't know.";
+    const instructions = [
+        'Be factual, concise, and conservative.',
+        options.requireUnknownFallback !== false ? `If you are not sure, answer exactly: "${unknownAnswer}"` : '',
+        'Do not invent facts, citations, APIs, prices, dates, versions, or capabilities.',
+        options.chainOfThought === 'brief' ? 'Show a brief reasoning summary.' : '',
+        options.chainOfThought === 'private' ? 'Think step by step internally, but only provide the final answer.' : '',
+    ].filter(Boolean).join('\n');
+    const exampleMessages = (options.examples || []).flatMap((example) => [
+        { role: 'user', content: example.input },
+        { role: 'assistant', content: example.output },
+    ]);
+    return {
+        ...request,
+        temperature: request.temperature ?? options.temperature ?? 0,
+        topP: request.topP ?? options.topP ?? 0.1,
+        messages: [
+            { role: 'system', content: instructions },
+            ...exampleMessages,
+            ...request.messages,
+        ],
+    };
+}
+export function asJsonOnly(request) {
+    return {
+        ...request,
+        temperature: request.temperature ?? 0,
+        topP: request.topP ?? 0.1,
+        messages: [
+            { role: 'system', content: 'Return only valid JSON. Do not include markdown, prose, or code fences.' },
+            ...request.messages,
+        ],
+    };
+}

package/dist/hallucination/knowledge-graph.d.ts

@@ -0,0 +1,27 @@
+import type { CompletionRequest } from '../types/messages.js';
+export interface KnowledgeGraphNode {
+    id: string;
+    label: string;
+    type?: string;
+    properties?: Record<string, unknown>;
+}
+export interface KnowledgeGraphEdge {
+    from: string;
+    to: string;
+    relation: string;
+    evidence?: string;
+    source?: string;
+    properties?: Record<string, unknown>;
+}
+export interface KnowledgeGraph {
+    nodes: KnowledgeGraphNode[];
+    edges: KnowledgeGraphEdge[];
+}
+export interface KnowledgeGraphOptions {
+    graph: KnowledgeGraph;
+    query?: string;
+    maxEdges?: number;
+    unknownAnswer?: string;
+}
+export declare function withKnowledgeGraphContext(request: CompletionRequest, options: KnowledgeGraphOptions): CompletionRequest;
+export declare function selectGraphFacts(graph: KnowledgeGraph, query: string, maxEdges?: number): string[];

package/dist/hallucination/knowledge-graph.js

@@ -0,0 +1,70 @@
+export function withKnowledgeGraphContext(request, options) {
+    const unknownAnswer = options.unknownAnswer || "I don't know based on the provided graph.";
+    const facts = selectGraphFacts(options.graph, options.query || latestUserText(request), options.maxEdges || 20);
+    const systemMessage = {
+        role: 'system',
+        content: [
+            'Use the provided knowledge graph facts for relationship claims.',
+            `If the graph does not support the answer, say: "${unknownAnswer}"`,
+            'Do not infer relationships that are not present in the graph facts.',
+            'Knowledge graph facts:',
+            facts.length ? facts.join('\n') : '[no graph facts provided]',
+        ].join('\n'),
+    };
+    return {
+        ...request,
+        temperature: request.temperature ?? 0,
+        topP: request.topP ?? 0.1,
+        messages: [systemMessage, ...request.messages],
+        metadata: {
+            ...request.metadata,
+            knowledgeGraph: {
+                nodes: options.graph.nodes.length,
+                edges: options.graph.edges.length,
+                selectedFacts: facts.length,
+            },
+        },
+    };
+}
+export function selectGraphFacts(graph, query, maxEdges = 20) {
+    const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
+    const queryTerms = new Set((query.toLowerCase().match(/[a-z0-9_'-]{2,}/g) || []));
+    return graph.edges
+        .map((edge) => {
+        const from = nodesById.get(edge.from);
+        const to = nodesById.get(edge.to);
+        const text = [
+            from?.label || edge.from,
+            edge.relation,
+            to?.label || edge.to,
+            edge.evidence,
+            edge.source,
+        ].filter(Boolean).join(' ');
+        const score = scoreText(text, queryTerms);
+        return { edge, from, to, score };
+    })
+        .sort((a, b) => b.score - a.score)
+        .slice(0, maxEdges)
+        .map(({ edge, from, to }) => {
+        const source = edge.source ? ` source=${edge.source}` : '';
+        const evidence = edge.evidence ? ` evidence="${edge.evidence}"` : '';
+        return `- ${from?.label || edge.from} --${edge.relation}--> ${to?.label || edge.to}${source}${evidence}`;
+    });
+}
+function latestUserText(request) {
+    const message = [...request.messages].reverse().find((msg) => msg.role === 'user');
+    if (!message)
+        return '';
+    if (typeof message.content === 'string')
+        return message.content;
+    return message.content
+        .filter((part) => part.type === 'text')
+        .map((part) => part.text)
+        .join('\n');
+}
+function scoreText(text, queryTerms) {
+    if (queryTerms.size === 0)
+        return 0;
+    const terms = text.toLowerCase().match(/[a-z0-9_'-]{2,}/g) || [];
+    return terms.reduce((score, term) => score + (queryTerms.has(term) ? 1 : 0), 0);
+}

package/dist/hallucination/rag.d.ts

@@ -0,0 +1,21 @@
+import type { CompletionRequest } from '../types/messages.js';
+export interface RagChunk {
+    id: string;
+    content: string;
+    source?: string;
+    score?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface RagOptions {
+    chunks: RagChunk[];
+    requireCitations?: boolean;
+    citationStyle?: 'bracket' | 'source';
+    unknownAnswer?: string;
+    maxChunks?: number;
+}
+export declare function withRagContext(request: CompletionRequest, options: RagOptions): CompletionRequest;
+export declare function extractCitations(text: string): string[];
+export declare function validateCitations(responseText: string, chunks: RagChunk[]): {
+    ok: boolean;
+    missing: string[];
+};