@devilsdev/rag-core 3.3.0 → 3.5.0

package/dist/types/observability/scores.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @param {object} result - A pipeline run result (or a stream's done
+ *   chunk) with `evaluation` and/or `citations`, or a checkAnswer() result
+ * @param {object} [options]
+ * @param {boolean} [options.explanations=false] - Include explanations,
+ *   which quote the answer
+ * @returns {Array<{name: string, value: number, target: 'retrieval'|'generation', label?: string, explanation?: string}>}
+ */
+export function evaluationScores(result: object, { explanations }?: {
+    explanations?: boolean;
+}): Array<{
+    name: string;
+    value: number;
+    target: "retrieval" | "generation";
+    label?: string;
+    explanation?: string;
+}>;
+/**
+ * The scores of a run result or answer check as Langfuse scores: the
+ * objects `langfuse.score.create()` takes (from `@langfuse/client`), and,
+ * without a trace id, the evaluations a Langfuse experiment evaluator
+ * returns. Langfuse is not a dependency.
+ *
+ * With `telemetry` on, a run result carries its OpenTelemetry trace and span
+ * ids in `result.telemetry`; Langfuse uses the same ids when it receives the
+ * spans (LangfuseSpanProcessor), so each score is attached to the trace and
+ * to the span it judges: the retrieval for contextPrecision and
+ * contextRecall, the generation for the rest. A score whose stage had no
+ * span (a cache hit) gets the trace only: Langfuse's default span filter
+ * keeps the stage spans (they have gen_ai.* attributes) but not the run
+ * span, so an observation id for it could point at nothing.
+ *
+ * @param {object} result - A pipeline run result, a stream's done chunk, or a checkAnswer() result
+ * @param {object} [options]
+ * @param {string} [options.traceId] - Overrides `result.telemetry.traceId`
+ * @param {string} [options.observationId] - Attach every score to this observation
+ * @param {string} [options.sessionId]
+ * @param {boolean} [options.comments=false] - Add explanations as comments; they quote the answer
+ * @returns {Array<{name: string, value: number, dataType: 'NUMERIC', traceId?: string, observationId?: string, sessionId?: string, comment?: string, metadata?: {label: string}}>}
+ */
+export function toLangfuseScores(result: object, options?: {
+    traceId?: string;
+    observationId?: string;
+    sessionId?: string;
+    comments?: boolean;
+}): Array<{
+    name: string;
+    value: number;
+    dataType: "NUMERIC";
+    traceId?: string;
+    observationId?: string;
+    sessionId?: string;
+    comment?: string;
+    metadata?: {
+        label: string;
+    };
+}>;

package/dist/types/reranker/cascade-reranker.d.ts

@@ -5,7 +5,7 @@
  *
  * @extends EventEmitter
  */
-export class CascadeReranker extends EventEmitter<[never]> {
+export class CascadeReranker extends EventEmitter {
     /**
      * @param {object[]} [rerankers=[]] - Array of objects with .rerank() method
      * @param {object} [options]

package/dist/types/reranker/embedding-reranker.d.ts

@@ -8,7 +8,7 @@
  *
  * @extends EventEmitter
  */
-export class EmbeddingReranker extends EventEmitter<[never]> {
+export class EmbeddingReranker extends EventEmitter {
     /**
      * @param {object} embedder - Must expose .embedQuery(text) or .embed(text)
      * @param {object} [options]

package/dist/types/reranker/scoring-reranker.d.ts

@@ -4,7 +4,7 @@
  *
  * @extends EventEmitter
  */
-export class ScoringReranker extends EventEmitter<[never]> {
+export class ScoringReranker extends EventEmitter {
     /**
      * @param {object} [options]
      * @param {number} [options.k1=1.2] - Term frequency saturation parameter

package/dist/types/retrieval/bm25-search.d.ts

@@ -2,7 +2,7 @@
  * Keyword search with BM25 ranking. Index documents with index(), then
  * search(query) returns them scored by term frequency and rarity.
  */
-export class BM25Search extends EventEmitter<[never]> {
+export class BM25Search extends EventEmitter {
     constructor(options?: {});
     config: {
         k1: number;

package/dist/types/retrieval/hybrid-retriever.d.ts

@@ -2,7 +2,7 @@
  * Runs several retrievers in parallel (for example vector and BM25) and
  * fuses their results with weighted reciprocal rank fusion.
  */
-export class HybridRetriever extends EventEmitter<[never]> {
+export class HybridRetriever extends EventEmitter {
     /**
      * @param {Array<{retriever: object, weight: number, name: string}>} retrievers
      * @param {object} options

package/dist/types/security/jwt-validator.d.ts

@@ -1,7 +1,7 @@
 /**
  * JWT Validator with hardened security
  */
-export class JWTValidator extends EventEmitter<[never]> {
+export class JWTValidator extends EventEmitter {
     constructor(options?: {});
     config: {
         algorithm: any;

package/dist/types/security/plugin-sandbox.d.ts

@@ -12,7 +12,7 @@
  * @class PluginSandbox
  * @extends EventEmitter
  */
-export class PluginSandbox extends EventEmitter<[never]> {
+export class PluginSandbox extends EventEmitter {
     constructor(options?: {});
     config: {
         timeout: any;

package/dist/types/streaming/sse-adapter.d.ts

@@ -11,7 +11,7 @@
  *   adapter.on('token', (t) => console.log('sent', t));
  *   await adapter.stream(asyncTokenGenerator, res);
  */
-export class SSEAdapter extends EventEmitter<[never]> {
+export class SSEAdapter extends EventEmitter {
     /**
      * @param {Object} [options] - Configuration overrides
      * @param {string} [options.eventName='token'] - SSE event name for token frames

package/dist/types/streaming/stream-router.d.ts

@@ -13,7 +13,7 @@
  *   const handler = router.createHandler(pipeline);
  *   app.post('/api/query', handler);
  */
-export class StreamRouter extends EventEmitter<[never]> {
+export class StreamRouter extends EventEmitter {
     /**
      * @param {Object} [options] - Configuration overrides
      * @param {string} [options.defaultTransport='sse'] - Fallback transport type

package/dist/types/streaming/streaming-embedder.d.ts

@@ -16,7 +16,7 @@
  *   se.on('done', (stats) => console.log('finished', stats));
  *   const all = await se.embedAll(documents);
  */
-export class StreamingEmbedder extends EventEmitter<[never]> {
+export class StreamingEmbedder extends EventEmitter {
     /**
      * @param {Object} embedder - Embedder instance with `.embed()` or `.embedQuery()`
      * @param {Object} [options] - Override any key from {@link DEFAULT_CONFIG}

package/dist/types/streaming/websocket-adapter.d.ts

@@ -12,7 +12,7 @@
  *   adapter.on('done', () => console.log('stream complete'));
  *   await adapter.stream(asyncTokenGenerator, ws);
  */
-export class WebSocketAdapter extends EventEmitter<[never]> {
+export class WebSocketAdapter extends EventEmitter {
     /**
      * @param {Object} [options] - Configuration overrides
      * @param {string} [options.messageType='token'] - Type field for token messages

package/dist/types/templates/scaffold.d.ts

@@ -9,7 +9,7 @@
  * const result = scaffolder.create('document-qa', '/path/to/my-project');
  * console.log(result.files); // list of created files
  */
-export class ProjectScaffolder extends EventEmitter<[never]> {
+export class ProjectScaffolder extends EventEmitter {
     /**
      * @param {Object} [options={}] - Scaffolder configuration
      * @param {boolean} [options.installDependencies=false] - Whether to auto-run npm install

package/dist/types/testing/contract-tests.d.ts

@@ -11,20 +11,22 @@
  * import { describe, it } from "vitest"; // or "node:test"
  * runContractTests("llm", () => new MyLLM(), { describe, it });
  *
- * @param {'loader'|'embedder'|'retriever'|'reranker'|'llm'} type - Plugin type
+ * @param {'loader'|'embedder'|'retriever'|'reranker'|'llm'|'detector'} type - Plugin type
  * @param {() => (object|Promise<object>)} factory - Returns a new, empty plugin for each check
  * @param {object} [options]
  * @param {string} [options.name] - Name of the test group (default: "<type> contract")
  * @param {boolean} [options.registry=false] - Also require the `metadata` pluginRegistry.register() needs
  * @param {(retriever: object, documents: object[]) => (void|Promise<void>)} [options.setup] - Retrievers: loads the test documents (default: `retriever.store(documents)`), for retrievers without store()
+ * @param {string} [options.positive] - Detectors: text the detector must flag, instead of the default sample for its kind
  * @param {Function} [options.describe] - Your framework's describe (default: the global one)
  * @param {Function} [options.it] - Your framework's it/test (default: the global it or test)
  * @returns {void}
  */
-export function runContractTests(type: "loader" | "embedder" | "retriever" | "reranker" | "llm", factory: () => (object | Promise<object>), options?: {
+export function runContractTests(type: "loader" | "embedder" | "retriever" | "reranker" | "llm" | "detector", factory: () => (object | Promise<object>), options?: {
     name?: string;
     registry?: boolean;
     setup?: (retriever: object, documents: object[]) => (void | Promise<void>);
+    positive?: string;
     describe?: Function;
     it?: Function;
 }): void;
@@ -35,16 +37,18 @@ export function runContractTests(type: "loader" | "embedder" | "retriever" | "re
  * const report = await checkContract("embedder", () => new MyEmbedder());
  * if (!report.passed) console.log(report.results.filter((r) => !r.passed));
  *
- * @param {'loader'|'embedder'|'retriever'|'reranker'|'llm'} type - Plugin type
+ * @param {'loader'|'embedder'|'retriever'|'reranker'|'llm'|'detector'} type - Plugin type
  * @param {() => (object|Promise<object>)} factory - Returns a new, empty plugin for each check
  * @param {object} [options]
  * @param {boolean} [options.registry=false] - Also require the `metadata` pluginRegistry.register() needs
  * @param {(retriever: object, documents: object[]) => (void|Promise<void>)} [options.setup] - Retrievers: loads the test documents (default: `retriever.store(documents)`), for retrievers without store()
+ * @param {string} [options.positive] - Detectors: text the detector must flag, instead of the default sample for its kind
  * @returns {Promise<{ type: string, passed: boolean, results: Array<{ name: string, passed: boolean, skipped: boolean, error?: string }> }>}
  */
-export function checkContract(type: "loader" | "embedder" | "retriever" | "reranker" | "llm", factory: () => (object | Promise<object>), options?: {
+export function checkContract(type: "loader" | "embedder" | "retriever" | "reranker" | "llm" | "detector", factory: () => (object | Promise<object>), options?: {
     registry?: boolean;
     setup?: (retriever: object, documents: object[]) => (void | Promise<void>);
+    positive?: string;
 }): Promise<{
     type: string;
     passed: boolean;

package/dist/types/utils/batch-processor.d.ts

@@ -1,7 +1,7 @@
 /**
  * Batch Processor Class
  */
-export class BatchProcessor extends EventEmitter<[never]> {
+export class BatchProcessor extends EventEmitter {
     constructor(options?: {});
     config: {
         maxTokensPerBatch: number;

package/dist/types/utils/connection-pool.d.ts

@@ -1,7 +1,7 @@
 /**
  * Connection Pool Manager Class
  */
-export class ConnectionPoolManager extends EventEmitter<[never]> {
+export class ConnectionPoolManager extends EventEmitter {
     constructor(options?: {});
     config: {
         maxSockets: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devilsdev/rag-core",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "createRagPipeline and its building blocks: retrieval, reranking, caching, cost tracking and model routing.",
   "keywords": [
     "rag",