@devilsdev/rag-core 3.4.0 → 3.6.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";
@@ -473,6 +531,7 @@ export { LocalEmbedder } from "./types/connectors/local-embedder";
 export { MemoryRetriever } from "./types/connectors/memory-retriever";
 export { PgVectorRetriever } from "./types/retrieval/pgvector-retriever";
 export { QdrantRetriever } from "./types/retrieval/qdrant-retriever";
+export { PineconeRetriever } from "./types/retrieval/pinecone-retriever";
 export { OpenAIConnector } from "./types/connectors/openai-connector";
 export { AnthropicConnector } from "./types/connectors/anthropic-connector";
 export { CohereConnector } from "./types/connectors/cohere-connector";