@devilsdev/rag-core 3.4.0 → 3.6.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/retrieval/pinecone-retriever.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Retriever on a Pinecone serverless index over its REST API, with no
+ * client package. The index must exist, with a dense vector of your
+ * embedding model's dimension; use the cosine metric for the scores the
+ * other retrievers return.
+ */
+export class PineconeRetriever {
+    /**
+     * @param {Object} options
+     * @param {string} [options.apiKey] - Defaults to PINECONE_API_KEY
+     * @param {string} [options.index] - The index name, described on first use
+     * @param {string} [options.host] - The index host (from the console), instead of or with `index`
+     * @param {string} [options.namespace='rag_documents'] - A namespace this retriever owns
+     * @param {'auto'|'documents'|'vectors'} [options.api='auto'] - Document index (Documents API) or vector index; auto reads it from the index description
+     * @param {string} [options.vectorField] - The document index's dense_vector field (default: the schema's)
+     * @param {number} [options.freshnessTimeoutMs=30000] - How long a read waits for this retriever's writes to be indexed; 0 to not wait
+     * @param {string} [options.cacheKey] - Cache identity; change it when the index changes
+     * @param {Function} [options.fetch] - fetch implementation (defaults to the global)
+     */
+    constructor(options?: {
+        apiKey?: string;
+        index?: string;
+        host?: string;
+        namespace?: string;
+        api?: "auto" | "documents" | "vectors";
+        vectorField?: string;
+        freshnessTimeoutMs?: number;
+        cacheKey?: string;
+        fetch?: Function;
+    });
+    index: string;
+    namespace: string;
+    freshnessTimeoutMs: number;
+    cacheKey: string;
+    _apiKey: string;
+    _host: string;
+    _api: "auto" | "documents" | "vectors";
+    _vectorField: string;
+    _fetch: any;
+    _resolving: any;
+    _writeLsn: number;
+    _dimension: any;
+    /**
+     * Cache identity for createRagPipeline({ cache }): none unless you set
+     * `cacheKey`, since other clients can change the index.
+     * @param {'retriever'} role
+     * @returns {string|null}
+     */
+    getCacheKey(role: "retriever"): string | null;
+    /**
+     * One REST call; resolves the parsed body and the response headers.
+     * @private
+     */
+    private _call;
+    /**
+     * The index's host and kind, from its description (once): a document
+     * index's dense_vector field and dimension, or a vector index's.
+     * @private
+     */
+    private _resolve;
+    /** @private */
+    private _describe;
+    _indexDimension: any;
+    /** A data-plane call; records the log sequence number of writes. @private */
+    private _data;
+    /** The Documents API path for this namespace. @private */
+    private _docs;
+    /**
+     * A search, repeated until it reflects this retriever's writes (when the
+     * index reports log sequence numbers) or `freshnessTimeoutMs` passes.
+     * Resolves `[{ id, score, fields }]`.
+     * @private
+     */
+    private _search;
+    /** Waits until this retriever's writes are indexed (for list and size). @private */
+    private _waitForWrites;
+    /**
+     * Inserts or replaces documents.
+     * @param {Array<{ id: string, vector: number[], content?: string, metadata?: Object }>} docs
+     * @returns {Promise<void>}
+     */
+    store(docs: Array<{
+        id: string;
+        vector: number[];
+        content?: string;
+        metadata?: any;
+    }>): Promise<void>;
+    /**
+     * The documents most similar to a query vector.
+     * @param {number[]|{ queryVector?: number[], topK?: number, signal?: AbortSignal }} request
+     *   A vector, or an object with one (required; optional in the type to
+     *   match the retriever contract)
+     * @param {number} [k=10] - Results when `request` is a vector
+     * @returns {Promise<Array<{ id: string, score: number, content: string, metadata: Object }>>}
+     */
+    retrieve(request: number[] | {
+        queryVector?: number[];
+        topK?: number;
+        signal?: AbortSignal;
+    }, k?: number): Promise<Array<{
+        id: string;
+        score: number;
+        content: string;
+        metadata: any;
+    }>>;
+    /** @private */
+    private _delete;
+    /**
+     * Deletes the chunks of one source (`metadata.source`), for re-ingesting.
+     * @param {string} source
+     */
+    removeBySource(source: string): Promise<void>;
+    /**
+     * Deletes documents by id.
+     * @param {string[]} ids
+     */
+    delete(ids: string[]): Promise<void>;
+    /** Deletes every document this retriever stored in its namespace. */
+    clear(): Promise<void>;
+    /**
+     * Every document, without vectors.
+     * @param {{ limit?: number }} [options]
+     * @returns {Promise<Array<{ id: string, content: string, metadata: Object }>>}
+     */
+    list({ limit }?: {
+        limit?: number;
+    }): Promise<Array<{
+        id: string;
+        content: string;
+        metadata: any;
+    }>>;
+    /** @returns {Promise<number>} The documents this retriever stored */
+    size(): Promise<number>;
+    /** Documents API: fetch by filter, page by page. @private */
+    private _listDocuments;
+    /** Vectors API: list ids, then fetch them. @private */
+    private _listVectors;
+}
+/** The record id for a document id: itself when Pinecone accepts it. */
+export function recordId(id: any): string;
+export const API_VERSION: "2026-07";

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/dist/types/utils/optional-peer.d.ts

@@ -2,7 +2,10 @@
  * Load an optional peer dependency. `load` must be a literal
  * `() => require('name')`, so bundlers (esbuild, Wrangler, webpack) can see
  * and include the package; probing with require.resolve() instead fails in
- * bundles even when the package is there.
+ * bundles even when the package is there. A bundle of a project without the
+ * package fails to build, though, because the require isn't inside a
+ * `try`: loaders on the main entry's path use `missingPeer` with the
+ * require in their own `try` instead.
  *
  * Only the package itself being absent becomes a `MISSING_DEPENDENCY` error
  * carrying `hint`; any other failure, including a module missing inside the
@@ -14,3 +17,20 @@
  * @returns {any} The module
  */
 export function loadOptionalPeer(name: string, load: () => any, hint: string): any;
+/**
+ * For a loader that requires an optional peer inside its own `try`, which
+ * bundlers (esbuild, Wrangler) then include when the package is installed
+ * and leave out, without failing the build, when it isn't:
+ *
+ *   try {
+ *     return require('openai');
+ *   } catch (error) {
+ *     throw missingPeer(error, 'openai', hint);
+ *   }
+ *
+ * @param {Error} error - What require() threw
+ * @param {string} name - The package name
+ * @param {string} hint - The error message when the package is missing
+ * @returns {Error} A `MISSING_DEPENDENCY` error carrying `hint` when the package itself is absent; otherwise `error`
+ */
+export function missingPeer(error: Error, name: string, hint: string): Error;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devilsdev/rag-core",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "description": "createRagPipeline and its building blocks: retrieval, reranking, caching, cost tracking and model routing.",
   "keywords": [
     "rag",
@@ -26,6 +26,7 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "workerd": "./dist/index.cjs",
       "require": "./dist/index.cjs",
       "import": "./dist/index.mjs"
     },