@devilsdev/rag-core 3.3.0 → 3.5.0

package/README.md

@@ -8,7 +8,7 @@ Part of [@devilsdev/rag-pipeline-utils](https://www.npmjs.com/package/@devilsdev
 npm install @devilsdev/rag-core
 ```
 
-Exports: `createRagPipeline`, `createPipeline`, `packContext`, `createError`, `wrapError`, `ERROR_CODES`, `retry`, `withRetry`, `ChunkingEngine`, `BM25Search`, `reciprocalRankFusion`, `HybridRetriever`, `ScoringReranker`, `EmbeddingReranker`, `CascadeReranker`, `MemoryCache`, `RedisCache`, `CostCalculator`, `PRICING_METADATA`, `CostTracker`, `TokenBudget`, `createModelRouter`, `classifyQuery`, `MemoryRetriever`, `BaseConnector`.
+Exports: `createRagPipeline`, `createPipeline`, `evaluationScores`, `toLangfuseScores`, `packContext`, `createError`, `wrapError`, `ERROR_CODES`, `retry`, `withRetry`, `ChunkingEngine`, `BM25Search`, `reciprocalRankFusion`, `HybridRetriever`, `ScoringReranker`, `EmbeddingReranker`, `CascadeReranker`, `MemoryCache`, `RedisCache`, `CostCalculator`, `PRICING_METADATA`, `CostTracker`, `TokenBudget`, `createModelRouter`, `classifyQuery`, `MemoryRetriever`, `BaseConnector`.
 
 Documentation: https://devilsdev.github.io/rag-pipeline-utils/
 

package/dist/all.d.ts

@@ -50,10 +50,26 @@ export interface TelemetryOptions {
   tracer?: TelemetryTracer;
   /** The @opentelemetry/api module, for @devilsdev/rag-pipeline-utils/edge, which cannot load it itself. */
   api?: any;
+  /**
+   * The @opentelemetry/api-logs module, for evaluation events when your SDK registers its
+   * LoggerProvider there (before sdk-logs 3). With @opentelemetry/api 1.10+ its own logs API is used.
+   */
+  logs?: any;
+  /** A Logger (`emit(logRecord)`) for the gen_ai.evaluation.result events. */
+  logger?: { emit(logRecord: any): void };
   /** Also record the query text and the retrieved document ids and scores. Default false. */
   recordContent?: boolean;
 }
 
+/** A run's OpenTelemetry ids, on its result when `telemetry` is on. */
+export interface RunTelemetry {
+  traceId: string;
+  /** The `rag.pipeline.run` span. */
+  spanId: string;
+  /** The stage spans, when the stage ran (not served from the cache). */
+  spans: { retrieval?: string; generation?: string };
+}
+
 /** A cache store: get / set / delete, optionally stats. */
 export interface CacheBackend {
   /** Resolves the stored value, or undefined when the key is missing or expired. */
@@ -151,6 +167,8 @@ export interface PipelineRunResult {
   timing?: { totalMs: number };
   /** The model router's decision, when the llm is a createModelRouter() and was called. */
   route?: RouteDecision;
+  /** The run's trace and span ids, when `telemetry` is on. */
+  telemetry?: RunTelemetry;
 }
 
 /** Which model a createModelRouter() chose for a run. */
@@ -202,6 +220,8 @@ export interface StreamChunk {
   timing?: StreamTiming;
   /** On the last chunk, when the llm is a createModelRouter(). */
   route?: RouteDecision;
+  /** On the last chunk, the run's trace and span ids, when `telemetry` is on. */
+  telemetry?: RunTelemetry;
 }
 
 /** A pipeline returned by {@link createRagPipeline}. */
@@ -307,6 +327,33 @@ export interface RerankerPlugin {
   rerank(query: string, documents: SearchResult[], options?: { topK?: number; signal?: AbortSignal }): SearchResult[] | Promise<SearchResult[]>;
 }
 
+/** Where a guard runs a detector, with the document for retrieval guards. */
+export interface DetectorContext {
+  stage: "query" | "document" | "output";
+  document?: any;
+  /** The request's AbortSignal, when the caller passed one to checkAsync() / filterAsync(). */
+  signal?: AbortSignal;
+}
+
+/** What a detector found. PII detectors must give each match's exact `text`, which is redacted. */
+export interface DetectorResult {
+  flagged: boolean;
+  score?: number;
+  labels?: string[];
+  matches?: Array<{ label?: string; text: string; start?: number; end?: number }>;
+}
+
+/**
+ * A detector for the guards' `detectors` option: prompt injection
+ * (PreRetrievalGuard, RetrievalGuard) or PII (PostGenerationGuard). Async
+ * detectors need the guards' checkAsync() / filterAsync().
+ */
+export interface GuardDetector {
+  name: string;
+  kind: "injection" | "pii";
+  detect(text: string, context: DetectorContext): DetectorResult | Promise<DetectorResult>;
+}
+
 /** The interface of {@link pluginRegistry}. */
 export interface PluginRegistry {
   /**
@@ -428,6 +475,11 @@ export { PipelineEvaluator } from "./types/evaluate/pipeline-evaluator";
 export { ChunkingEngine } from "./types/chunking/chunking-engine";
 export { CitationTracker } from "./types/citation/citation-tracker";
 export { checkAnswer } from "./types/grounding/check-answer";
+export { fromAnthropicCitations } from "./types/grounding/provider-citations";
+export { fromOpenAIFileCitations } from "./types/grounding/provider-citations";
+export { verifyCitations } from "./types/grounding/provider-citations";
+export { evaluationScores } from "./types/observability/scores";
+export { toLangfuseScores } from "./types/observability/scores";
 export { normalizeSources } from "./types/grounding/check-answer";
 export { createAiSdkAdapter } from "./types/adapters/ai-sdk";
 export { createMastraScorer } from "./types/adapters/mastra";
@@ -445,6 +497,12 @@ export { HybridRetriever } from "./types/retrieval/hybrid-retriever";
 export { FileVectorStore } from "./types/retrieval/file-vector-store";
 export { PreRetrievalGuard } from "./types/guardrails/pre-retrieval-guard";
 export { detectInjection } from "./types/guardrails/injection-detector";
+export { patternInjectionDetector } from "./types/guardrails/detectors";
+export { patternPIIDetector } from "./types/guardrails/detectors";
+export { detectedText } from "./types/guardrails/detectors";
+export { evaluateDetectors } from "./types/guardrails/evaluate-detectors";
+export { detectorVerdict } from "./types/guardrails/evaluate-detectors";
+export { renderDetectorReport } from "./types/guardrails/evaluate-detectors";
 export { RetrievalGuard } from "./types/guardrails/retrieval-guard";
 export { PostGenerationGuard } from "./types/guardrails/post-generation-guard";
 export { GuardrailsPipeline } from "./types/guardrails/guardrails-pipeline";

package/dist/index.cjs

@@ -1291,12 +1291,74 @@ var require_context_packing = __commonJS({
   }
 });
 
+// src/observability/scores.js
+var require_scores = __commonJS({
+  "src/observability/scores.js"(exports2, module2) {
+    "use strict";
+    var RETRIEVAL_METRICS = /* @__PURE__ */ new Set(["contextPrecision", "contextRecall"]);
+    var isScore = (v) => typeof v === "number" && Number.isFinite(v);
+    function evaluationScores(result, { explanations = false } = {}) {
+      if (!result || typeof result !== "object") return [];
+      const out = [];
+      const scores = result.evaluation && result.evaluation.scores ? result.evaluation.scores : {};
+      for (const [name, value] of Object.entries(scores)) {
+        if (!isScore(value)) continue;
+        out.push({
+          name,
+          value,
+          target: RETRIEVAL_METRICS.has(name) ? "retrieval" : "generation"
+        });
+      }
+      if (result.citations && isScore(result.citations.groundednessScore)) {
+        out.push({
+          name: "citationCoverage",
+          value: result.citations.groundednessScore,
+          target: "generation"
+        });
+      }
+      if (typeof result.grounded === "boolean" && isScore(result.groundedness)) {
+        const unsupported = Array.isArray(result.unsupported) ? result.unsupported : [];
+        out.push({
+          name: "groundedSentences",
+          value: result.groundedness,
+          target: "generation",
+          label: result.grounded ? "grounded" : "ungrounded",
+          ...explanations && unsupported.length > 0 && {
+            explanation: `Unsupported: ${unsupported.map((s) => JSON.stringify(s)).join(" ")}`
+          }
+        });
+      }
+      return out;
+    }
+    function toLangfuseScores(result, options = {}) {
+      const { observationId, sessionId, comments = false } = options;
+      const tel = result && result.telemetry || {};
+      const traceId = options.traceId || tel.traceId;
+      const fromSameTrace = !options.traceId || options.traceId === tel.traceId;
+      return evaluationScores(result, { explanations: comments }).map((s) => {
+        const observation = observationId || (fromSameTrace && tel.spans ? tel.spans[s.target] : void 0);
+        return {
+          name: s.name,
+          value: s.value,
+          dataType: "NUMERIC",
+          ...traceId && { traceId },
+          ...observation && { observationId: observation },
+          ...sessionId && { sessionId },
+          ...s.explanation && { comment: s.explanation },
+          ...s.label && { metadata: { label: s.label } }
+        };
+      });
+    }
+    module2.exports = { evaluationScores, toLangfuseScores };
+  }
+});
+
 // package.json
 var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@devilsdev/rag-pipeline-utils",
-      version: "3.3.0",
+      version: "3.5.0",
       description: "Composable retrieval-augmented generation (RAG) for Node.js: grounded citations, evaluation, guardrails, hybrid retrieval and a CLI.",
       main: "dist/index.cjs",
       type: "commonjs",
@@ -1392,6 +1454,11 @@ var require_package = __commonJS({
         "benchmark:full": "node scripts/benchmark.js --iterations=500 --verbose",
         "bench:speed": "node benchmarks/speed.js",
         "bench:quality": "node benchmarks/quality.js",
+        "bench:guardrails": "node benchmarks/guardrails.js",
+        "bench:judge": "node benchmarks/judge.js",
+        "bench:claude-citations": "node benchmarks/claude-citations.js",
+        "bench:judge-more": "node benchmarks/judge-more.js",
+        "bench:claude-latency": "node benchmarks/claude-latency.js",
         dev: "node scripts/dev-tools.js menu",
         "dev:health": "node scripts/dev-tools.js health",
         "dev:setup": "node scripts/dev-tools.js setup",
@@ -1410,6 +1477,7 @@ var require_package = __commonJS({
         "tests:ci": "jest --maxWorkers=50% --reporters=default --json --outputFile=test-results-current.json",
         "test:unit": "jest __tests__/unit",
         "test:integration": "jest __tests__/integration",
+        "test:live": "jest --config jest.live.config.js --runInBand",
         "test:simple": "jest --maxWorkers=1 --no-coverage",
         "verify:pack": "node scripts/verify-npm-pack.js",
         "smoke:pack": "node scripts/smoke-test-pack.js",
@@ -1489,6 +1557,8 @@ var require_package = __commonJS({
         "**/*.{json,md,mdx,yml,yaml,css,scss,html}": "prettier --write --ignore-unknown"
       },
       devDependencies: {
+        "@ai-sdk/anthropic": "3.0.138",
+        "@ai-sdk/anthropic-v4": "npm:@ai-sdk/anthropic@4.0.97",
         "@babel/core": "^7.26.10",
         "@babel/preset-env": "^7.26.9",
         "@docusaurus/core": "3.10.2",
@@ -1499,12 +1569,14 @@ var require_package = __commonJS({
         "@fontsource/jetbrains-mono": "5.3.0",
         "@octokit/rest": "^21.1.1",
         "@opentelemetry/api": "^1.9.1",
+        "@opentelemetry/api-logs": "^0.223.0",
         "@opentelemetry/auto-instrumentations-node": "^0.52.1",
         "@opentelemetry/context-async-hooks": "^2.12.0",
         "@opentelemetry/exporter-jaeger": "^1.26.0",
         "@opentelemetry/exporter-prometheus": "^0.53.0",
         "@opentelemetry/exporter-trace-otlp-http": "^0.53.0",
         "@opentelemetry/resources": "^1.26.0",
+        "@opentelemetry/sdk-logs": "^0.223.0",
         "@opentelemetry/sdk-metrics": "^1.26.0",
         "@opentelemetry/sdk-node": "^0.53.0",
         "@opentelemetry/sdk-trace-base": "^2.12.0",
@@ -1550,10 +1622,10 @@ var require_package = __commonJS({
         "why-is-node-running": "^3.2.2"
       },
       dependencies: {
-        "@devilsdev/rag-connectors": "3.3.0",
-        "@devilsdev/rag-core": "3.3.0",
-        "@devilsdev/rag-eval": "3.3.0",
-        "@devilsdev/rag-guardrails": "3.3.0",
+        "@devilsdev/rag-connectors": "3.5.0",
+        "@devilsdev/rag-core": "3.5.0",
+        "@devilsdev/rag-eval": "3.5.0",
+        "@devilsdev/rag-guardrails": "3.5.0",
         ajv: "^8.17.1",
         axios: "^1.21.0",
         chokidar: "^4.0.3",
@@ -1636,6 +1708,7 @@ var require_optional_peer = __commonJS({
 var require_otel = __commonJS({
   "src/observability/otel.js"(exports2, module2) {
     "use strict";
+    var { evaluationScores } = require_scores();
     var { version: LIBRARY_VERSION } = require_package();
     var { loadOptionalPeer } = require_optional_peer();
     var TRACER_NAME = "@devilsdev/rag-pipeline-utils";
@@ -1653,7 +1726,7 @@ var require_otel = __commonJS({
       const opts = option === true ? {} : option;
       if (typeof opts !== "object") {
         throw new TypeError(
-          "telemetry must be true or { tracer?, api?, recordContent? }"
+          "telemetry must be true or { tracer?, api?, logs?, logger?, recordContent? }"
         );
       }
       const api = opts.api || loadOtelApi();
@@ -1666,7 +1739,33 @@ var require_otel = __commonJS({
       if (!tracer || typeof tracer.startActiveSpan !== "function") {
         throw new TypeError("telemetry.tracer must be an OpenTelemetry Tracer");
       }
-      return { api, tracer, recordContent: Boolean(opts.recordContent) };
+      let logger = opts.logger || null;
+      if (logger && typeof logger.emit !== "function") {
+        throw new TypeError("telemetry.logger must be an OpenTelemetry Logger");
+      }
+      if (!logger) {
+        if (opts.logs && !(opts.logs.logs && typeof opts.logs.logs.getLogger === "function")) {
+          throw new TypeError(
+            'telemetry.logs must be the @opentelemetry/api-logs module (import * as logs from "@opentelemetry/api-logs")'
+          );
+        }
+        const source = [opts.logs, api].find(
+          (m) => m && m.logs && typeof m.logs.getLogger === "function"
+        );
+        if (source) logger = source.logs.getLogger(TRACER_NAME, LIBRARY_VERSION);
+      }
+      return {
+        api,
+        tracer,
+        logger,
+        // Holds the spans of one run, so its scores find them under concurrency
+        runKey: api.createContextKey("rag.pipeline.run"),
+        recordContent: Boolean(opts.recordContent)
+      };
+    }
+    function recordStage(tel, stage, span) {
+      const run = tel.api.context.active().getValue(tel.runKey);
+      if (run) run[stage] = span.spanContext();
     }
     function providerOf(component) {
       const name = component && component.name;
@@ -1749,8 +1848,8 @@ var require_otel = __commonJS({
         retriever(method, [params = {}]) {
           const source = component.collection || (typeof component.table === "string" ? component.table.replace(/"/g, "") : void 0);
           return {
-            name: source ? `retrieval ${source}` : "retrieval",
-            kind: SpanKind.CLIENT,
+            name: "retrieval",
+            kind: SpanKind.INTERNAL,
             attributes: clean({
               "gen_ai.operation.name": "retrieval",
               "gen_ai.data_source.id": source,
@@ -1808,6 +1907,7 @@ var require_otel = __commonJS({
           };
         }
       };
+      const STAGES = { retriever: "retrieval", llm: "generation" };
       const METHODS = {
         embedder: ["embed", "embedQuery"],
         retriever: ["retrieve"],
@@ -1821,8 +1921,10 @@ var require_otel = __commonJS({
           return (...args) => {
             const spec = spanFor[kind](prop, args);
             const options = { kind: spec.kind, attributes: spec.attributes };
+            const stage = STAGES[kind];
             if (prop === "generateStream") {
               return tel.tracer.startActiveSpan(spec.name, options, (span) => {
+                if (stage) recordStage(tel, stage, span);
                 const startedAt = performance.now();
                 let source;
                 try {
@@ -1836,6 +1938,7 @@ var require_otel = __commonJS({
               });
             }
             return inSpan(tel, spec.name, options, async (span) => {
+              if (stage) recordStage(tel, stage, span);
               const out = await value.apply(target, args);
               spec.after(span, out);
               return out;
@@ -1890,32 +1993,49 @@ var require_otel = __commonJS({
           "rag.pipeline.run",
           { kind: SpanKind.INTERNAL, attributes },
           async (span) => {
+            const stages = {};
+            const runContext = tel.api.context.active().setValue(tel.runKey, stages);
             let result;
             try {
-              result = await run(params);
+              result = await tel.api.context.with(runContext, () => run(params));
             } catch (error) {
               markError(tel, span, error);
               span.end();
               throw error;
             }
             if (result && typeof result[Symbol.asyncIterator] === "function") {
+              const iterator = result[Symbol.asyncIterator]();
               return (async function* tracedStream() {
+                let finished = false;
                 try {
-                  for await (const chunk of result) {
+                  for (; ; ) {
+                    const step = await tel.api.context.with(
+                      runContext,
+                      () => iterator.next()
+                    );
+                    if (step.done) break;
+                    const chunk = step.value;
                     if (chunk && chunk.done) {
                       span.setAttributes(runAttributes(tel, chunk));
+                      finishRun(tel, span, stages, chunk);
                     }
                     yield chunk;
                   }
+                  finished = true;
                 } catch (error) {
+                  finished = true;
                   markError(tel, span, error);
                   throw error;
                 } finally {
+                  if (!finished && typeof iterator.return === "function") {
+                    await iterator.return();
+                  }
                   span.end();
                 }
               })();
             }
             span.setAttributes(runAttributes(tel, result));
+            finishRun(tel, span, stages, result);
             if (!result || result.success === false) {
               const message = result && result.error || "run failed";
               span.setAttribute("error.type", errorType(message));
@@ -1927,6 +2047,33 @@ var require_otel = __commonJS({
         );
       };
     }
+    function finishRun(tel, span, stages, result) {
+      if (!result || typeof result !== "object") return;
+      const own = span.spanContext();
+      result.telemetry = {
+        traceId: own.traceId,
+        spanId: own.spanId,
+        spans: Object.fromEntries(
+          Object.entries(stages).map(([stage, ctx]) => [stage, ctx.spanId])
+        )
+      };
+      if (!tel.logger) return;
+      for (const score of evaluationScores(result, {
+        explanations: tel.recordContent
+      })) {
+        const parent = stages[score.target] || own;
+        tel.logger.emit({
+          eventName: "gen_ai.evaluation.result",
+          context: tel.api.trace.setSpanContext(tel.api.context.active(), parent),
+          attributes: clean({
+            "gen_ai.evaluation.name": score.name,
+            "gen_ai.evaluation.score.value": score.value,
+            "gen_ai.evaluation.score.label": score.label,
+            "gen_ai.evaluation.explanation": score.explanation
+          })
+        });
+      }
+    }
     function errorType(message) {
       if (message === "Execution timeout") return "timeout";
       if (message === "Execution aborted") return "aborted";
@@ -5101,7 +5248,79 @@ var require_connector_utils = __commonJS({
         reader.releaseLock();
       }
     }
+    function toConnectorError(err, provider) {
+      if (!err || typeof err !== "object" || err.isAxiosError !== true) {
+        return err;
+      }
+      if (isAbortError(err)) {
+        const aborted = new Error("The operation was aborted");
+        aborted.name = "AbortError";
+        aborted.code = "ABORT_ERR";
+        return aborted;
+      }
+      const response = err.response;
+      let message;
+      if (response) {
+        const data = response.data;
+        const apiError = data && typeof data === "object" && typeof data.pipe !== "function" ? data.error : void 0;
+        let detail = "";
+        if (apiError && typeof apiError === "object") {
+          detail = [apiError.type, apiError.message].filter(Boolean).join(": ");
+        } else if (typeof apiError === "string") {
+          detail = apiError;
+        } else if (data && typeof data === "object" && typeof data.message === "string") {
+          detail = data.message;
+        }
+        message = `${provider} API error ${response.status}${detail ? `: ${detail}` : ""}`;
+      } else {
+        message = `${provider} request failed: ${err.message}`;
+      }
+      const error = new Error(message);
+      if (err.code) error.code = err.code;
+      if (response) {
+        error.status = response.status;
+        error.response = {
+          status: response.status,
+          statusText: response.statusText,
+          headers: response.headers,
+          data: response.data
+        };
+      }
+      return error;
+    }
+    async function readErrorBody(stream) {
+      const chunks = [];
+      let size = 0;
+      try {
+        for await (const chunk of stream) {
+          size += chunk.length;
+          if (size > 65536) break;
+          chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+        }
+      } catch {
+      } finally {
+        if (typeof stream.destroy === "function") stream.destroy();
+      }
+      const text = Buffer.concat(chunks).toString("utf8");
+      try {
+        return JSON.parse(text);
+      } catch {
+        return text || void 0;
+      }
+    }
+    function cleanAxiosErrors(client, provider) {
+      client.interceptors.response.use(void 0, async (err) => {
+        const data = err && err.response && err.response.data;
+        if (data && typeof data.pipe === "function") {
+          err.response.data = await readErrorBody(data);
+        }
+        throw toConnectorError(err, provider);
+      });
+      return client;
+    }
     module2.exports = {
+      toConnectorError,
+      cleanAxiosErrors,
       textChunks,
       createAbortError,
       isAbortError,
@@ -5640,6 +5859,23 @@ var require_cost_calculator = __commonJS({
         source: "https://platform.claude.com/docs/en/about-claude/pricing",
         asOf: "2026-11-01"
       },
+      // $0.10 / $0.50 per million input / output tokens, for prompts up to
+      // 100,000 tokens ($0.50 / $2.50 above; this table has one price per model).
+      "claude-haiku-5.5": {
+        input: 1e-4,
+        output: 5e-4,
+        unit: 1e3,
+        source: "https://platform.claude.com/docs/en/about-claude/pricing",
+        asOf: "2026-11-05"
+      },
+      // $10 / $50 per million input / output tokens.
+      "claude-fable-5.1": {
+        input: 0.01,
+        output: 0.05,
+        unit: 1e3,
+        source: "https://platform.claude.com/docs/en/about-claude/pricing",
+        asOf: "2026-11-05"
+      },
       "cohere-command": {
         input: 1e-3,
         output: 2e-3,
@@ -6032,6 +6268,8 @@ var require_cost_tracker = __commonJS({
       budgetOptions: {}
     };
     var CHARS_PER_TOKEN = 4;
+    var PROMPT_OVERHEAD_CHARS = 600;
+    var PASSAGE_WRAPPER_CHARS = 40;
     var CostTracker = class extends EventEmitter {
       /**
        * @param {object} [options]
@@ -6071,9 +6309,18 @@ var require_cost_tracker = __commonJS({
         }
         const inputText = result.input || result.query || result.prompt || "";
         const outputText = result.output || result.answer || result.response || "";
+        const passages = Array.isArray(result.results) ? result.results : [];
+        const passageChars = passages.reduce((n, doc) => {
+          const text = typeof doc === "string" ? doc : doc && (doc.content || doc.text) || "";
+          return n + String(text).length + PASSAGE_WRAPPER_CHARS;
+        }, 0);
+        const promptChars = passages.length > 0 ? PROMPT_OVERHEAD_CHARS : 0;
         return {
-          inputTokens: Math.ceil(String(inputText).length / CHARS_PER_TOKEN),
-          outputTokens: Math.ceil(String(outputText).length / CHARS_PER_TOKEN)
+          inputTokens: Math.ceil(
+            (String(inputText).length + passageChars + promptChars) / CHARS_PER_TOKEN
+          ),
+          outputTokens: Math.ceil(String(outputText).length / CHARS_PER_TOKEN),
+          estimated: true
         };
       }
       /**
@@ -6096,7 +6343,7 @@ var require_cost_tracker = __commonJS({
               tracker.startSession({ autoStarted: true });
             }
             const result = await pipeline.run(...args);
-            const { inputTokens, outputTokens } = tracker._extractUsage(result);
+            const { inputTokens, outputTokens, estimated } = tracker._extractUsage(result);
             const model = result.model || result.route && result.route.model || tracker.config.model;
             const costEstimate = tracker.calculator.estimate(
               model,
@@ -6123,8 +6370,14 @@ var require_cost_tracker = __commonJS({
               inputTokens,
               outputTokens,
               estimatedCost: costEstimate.totalCost,
+              // The price-table entry used (as before), and the model the run
+              // asked for, which can differ in form (claude-haiku-4-5 is priced
+              // as claude-haiku-4.5)
               model: costEstimate.model,
-              currency: "USD"
+              requestedModel: model,
+              currency: "USD",
+              // Token counts estimated from text length (no usage reported)
+              ...estimated && { tokensEstimated: true }
             };
             const entry = {
               timestamp: Date.now(),
@@ -6811,9 +7064,15 @@ var require_core = __commonJS({
     var { createModelRouter, classifyQuery } = require_model_router();
     var { MemoryRetriever } = require_memory_retriever();
     var { BaseConnector } = require_base_connector();
+    var {
+      evaluationScores,
+      toLangfuseScores
+    } = require_scores();
     module2.exports = {
       createRagPipeline,
       createPipeline: createRagPipeline,
+      evaluationScores,
+      toLangfuseScores,
       packContext,
       createError: errorFormatter.createError,
       wrapError: errorFormatter.wrapError,
@@ -6873,6 +7132,7 @@ var modules = {
   "evaluate/relevance.js": () => require_relevance(),
   "evaluate/scoring.js": () => require_scoring(),
   "observability/otel.js": () => require_otel(),
+  "observability/scores.js": () => require_scores(),
   "packages/core.js": () => require_core(),
   "reranker/cascade-reranker.js": () => require_cascade_reranker(),
   "reranker/embedding-reranker.js": () => require_embedding_reranker(),

package/dist/index.d.ts

@@ -1 +1 @@
-export { createRagPipeline, createPipeline, packContext, createError, wrapError, ERROR_CODES, retry, withRetry, ChunkingEngine, BM25Search, reciprocalRankFusion, HybridRetriever, ScoringReranker, EmbeddingReranker, CascadeReranker, MemoryCache, RedisCache, CostCalculator, PRICING_METADATA, CostTracker, TokenBudget, createModelRouter, classifyQuery, MemoryRetriever, BaseConnector } from "./all";
+export { createRagPipeline, createPipeline, evaluationScores, toLangfuseScores, packContext, createError, wrapError, ERROR_CODES, retry, withRetry, ChunkingEngine, BM25Search, reciprocalRankFusion, HybridRetriever, ScoringReranker, EmbeddingReranker, CascadeReranker, MemoryCache, RedisCache, CostCalculator, PRICING_METADATA, CostTracker, TokenBudget, createModelRouter, classifyQuery, MemoryRetriever, BaseConnector } from "./all";

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
 const mod = require('./index.cjs');
-export const { createRagPipeline, createPipeline, packContext, createError, wrapError, ERROR_CODES, retry, withRetry, ChunkingEngine, BM25Search, reciprocalRankFusion, HybridRetriever, ScoringReranker, EmbeddingReranker, CascadeReranker, MemoryCache, RedisCache, CostCalculator, PRICING_METADATA, CostTracker, TokenBudget, createModelRouter, classifyQuery, MemoryRetriever, BaseConnector } = mod;
+export const { createRagPipeline, createPipeline, evaluationScores, toLangfuseScores, packContext, createError, wrapError, ERROR_CODES, retry, withRetry, ChunkingEngine, BM25Search, reciprocalRankFusion, HybridRetriever, ScoringReranker, EmbeddingReranker, CascadeReranker, MemoryCache, RedisCache, CostCalculator, PRICING_METADATA, CostTracker, TokenBudget, createModelRouter, classifyQuery, MemoryRetriever, BaseConnector } = mod;
 export default mod;

package/dist/types/adapters/ai-sdk-middleware.d.ts

@@ -35,6 +35,10 @@ export type GroundingMiddlewareOptions = {
      * - Run checkAnswer on the answer
      */
     check?: boolean;
+    /**
+     * - An LLM with `generate()` (this library's LLM contract, e.g. `createAiSdkAdapter({ ai, languageModel }).llm`) that rules on the sentences the lexical check failed for lack of word overlap; see checkAnswer. Give it the base model, not the wrapped one, or each judge call is grounded again
+     */
+    judge?: any;
     /**
      * - Return the passages as source parts
      */
@@ -96,6 +100,10 @@ export type GroundingReport = {
      * - Per-sentence citations
      */
     citations?: Array<any>;
+    /**
+     * - With the `judge` option: the verdicts, the number of calls, the token usage when known, and `error` when the judge failed (its sentences then stay unsupported)
+     */
+    judge?: any;
     /**
      * - What each enabled guard found
      */
@@ -135,6 +143,7 @@ export function groundingMiddleware(options?: GroundingMiddlewareOptions): any;
  * @property {Function} [countTokens] - Token counter for maxContextTokens
  * @property {string} [systemPrompt] - Replaces the default RAG system prompt
  * @property {boolean} [check=true] - Run checkAnswer on the answer
+ * @property {Object} [judge] - An LLM with `generate()` (this library's LLM contract, e.g. `createAiSdkAdapter({ ai, languageModel }).llm`) that rules on the sentences the lexical check failed for lack of word overlap; see checkAnswer. Give it the base model, not the wrapped one, or each judge call is grounded again
  * @property {boolean} [sources=true] - Return the passages as source parts
  * @property {Object|boolean} [preRetrieval] - PreRetrievalGuard options (true for defaults): injection detection on the query
  * @property {Object|boolean} [retrieval] - RetrievalGuard options (true for defaults): ACL, minimum score, injection in documents
@@ -152,6 +161,7 @@ export function groundingMiddleware(options?: GroundingMiddlewareOptions): any;
  * @property {number} [groundedness] - Share of supported sentences, 0..1
  * @property {string[]} [unsupported] - Sentences no passage supports
  * @property {Array<Object>} [citations] - Per-sentence citations
+ * @property {Object} [judge] - With the `judge` option: the verdicts, the number of calls, the token usage when known, and `error` when the judge failed (its sentences then stay unsupported)
  * @property {Object} guardrails - What each enabled guard found
  */
 export class GroundingBlockedError extends Error {