@juspay/neurolink 9.54.2 → 9.54.4

package/dist/types/{proxyTypes.d.ts → proxy.d.ts}

@@ -15,6 +15,8 @@
  */
 import type { Span } from "@opentelemetry/api";
 import type { ProxyTracer } from "../proxy/proxyTracer.js";
+import type { FallbackEntry, ProxyRoutingConfig, CloakingConfig } from "./subscription.js";
+import type { RouteDeprecation } from "./server.js";
 /**
  * Type describing the ModelRouter contract.
  * Defined here to avoid a circular dependency between types and implementation.
@@ -22,7 +24,7 @@ import type { ProxyTracer } from "../proxy/proxyTracer.js";
 export type ModelRouterInterface = {
     resolve(requestedModel: string): RouteResult;
     isClaudeTarget(requestedModel: string): boolean;
-    getFallbackChain(): import("./subscriptionTypes.js").FallbackEntry[];
+    getFallbackChain(): FallbackEntry[];
 };
 /** A single text block in a Claude content array. */
 export type ClaudeTextBlock = {
@@ -405,9 +407,9 @@ export type ProxyConfigFile = {
     /** Map of provider names to their account lists */
     accounts: Record<string, ProxyAccountConfig[]>;
     /** Routing configuration (strategy, model mappings, fallback chain) */
-    routing?: Partial<import("./subscriptionTypes.js").ProxyRoutingConfig>;
+    routing?: Partial<ProxyRoutingConfig>;
     /** Cloaking plugin configuration */
-    cloaking?: import("./subscriptionTypes.js").CloakingConfig;
+    cloaking?: CloakingConfig;
 };
 /** Options for loadProxyConfig. */
 export type LoadProxyConfigOptions = {
@@ -677,7 +679,7 @@ export type HonoRateLimitEntry = {
 export type DeprecatedRouteInfo = {
     method: string;
     path: string;
-    deprecation: import("../server/types.js").RouteDeprecation;
+    deprecation: RouteDeprecation;
 };
 /** Cache entry for response caching middleware. */
 export type ResponseCacheEntry<T = unknown> = {
@@ -735,3 +737,13 @@ export type ProxyHealthResponse = {
     healthPath: "/health";
     statusPath: "/status";
 };
+export type ProxyPaths = {
+    /** Base directory for proxy state files */
+    stateDir: string;
+    /** logs/ — request/response logs */
+    logsDir: string;
+    /** account-quotas.json — per-account rate limit state */
+    quotaFile: string;
+    /** Whether this is a dev-mode isolated instance */
+    isDev: boolean;
+};

package/dist/{rag/types.d.ts → types/rag.d.ts}

@@ -1,10 +1,610 @@
 /**
- * RAG Document Processing Types
+ * RAG Type Definitions
  *
- * Comprehensive type definitions for RAG (Retrieval-Augmented Generation)
- * document processing, including chunking strategies, metadata extraction,
- * vector queries, and Graph RAG support.
+ * Canonical type file for all RAG (Retrieval-Augmented Generation) interfaces.
+ * All exported interfaces from src/lib/rag/ are collected here as type aliases.
  */
+/**
+ * Citation format options
+ */
+export type CitationFormat = "inline" | "footnote" | "numbered" | "none";
+/**
+ * Chunker type - all chunking strategies implement this
+ */
+export type Chunker = {
+    /** Strategy name for identification */
+    readonly strategy: ChunkingStrategy;
+    /**
+     * Split text into chunks
+     * @param text - The text to chunk
+     * @param config - Strategy-specific configuration
+     * @returns Array of chunks
+     */
+    chunk(text: string, config?: BaseChunkerConfig): Promise<Chunk[]>;
+};
+/**
+ * Context assembly options
+ */
+export type ContextAssemblyOptions = {
+    /** Maximum characters in assembled context */
+    maxChars?: number;
+    /** Maximum tokens (approximate, 4 chars/token) */
+    maxTokens?: number;
+    /** Citation format to use */
+    citationFormat?: CitationFormat;
+    /** Separator between chunks */
+    separator?: string;
+    /** Include chunk metadata in context */
+    includeMetadata?: boolean;
+    /** Deduplicate overlapping content */
+    deduplicate?: boolean;
+    /** Similarity threshold for deduplication (0-1) */
+    dedupeThreshold?: number;
+    /** Order by relevance score */
+    orderByRelevance?: boolean;
+    /** Include section headers */
+    includeSectionHeaders?: boolean;
+    /** Header template (use {index}, {source}, {score} placeholders) */
+    headerTemplate?: string;
+};
+/**
+ * Context window representation
+ */
+export type ContextWindow = {
+    /** Assembled context text */
+    text: string;
+    /** Number of chunks included */
+    chunkCount: number;
+    /** Total character count */
+    charCount: number;
+    /** Estimated token count */
+    tokenCount: number;
+    /** Chunks that were truncated/excluded */
+    truncatedChunks: number;
+    /** Citation map (id -> citation text) */
+    citations: Map<string, string>;
+};
+/**
+ * Supported metadata extractor types
+ */
+export type MetadataExtractorType = "llm" | "title" | "summary" | "keywords" | "questions" | "custom" | "composite";
+/**
+ * Metadata Extractor type - all extractors implement this
+ */
+export type MetadataExtractor = {
+    /** Extractor type identifier */
+    readonly type: MetadataExtractorType;
+    /**
+     * Extract metadata from chunks
+     * @param chunks - Array of chunks to extract metadata from
+     * @param params - Extraction parameters
+     * @returns Array of extraction results
+     */
+    extract(chunks: Chunk[], params?: ExtractParams): Promise<ExtractionResult[]>;
+};
+/**
+ * Metadata extractor configuration
+ */
+export type MetadataExtractorConfig = {
+    /** Extractor type */
+    type: MetadataExtractorType;
+    /** Language model provider */
+    provider?: string;
+    /** Model name for LLM-based extraction */
+    modelName?: string;
+    /** Custom prompt template */
+    promptTemplate?: string;
+    /** Maximum tokens for LLM response */
+    maxTokens?: number;
+    /** Temperature for LLM generation */
+    temperature?: number;
+};
+/**
+ * Metadata extractor metadata for discovery and documentation
+ */
+export type MetadataExtractorMetadata = {
+    /** Human-readable description */
+    description: string;
+    /** Default configuration */
+    defaultConfig: Partial<MetadataExtractorConfig>;
+    /** Supported configuration options */
+    supportedOptions: string[];
+    /** Recommended use cases */
+    useCases: string[];
+    /** Alternative names for this extractor */
+    aliases: string[];
+    /** Whether this extractor requires an AI model */
+    requiresModel: boolean;
+    /** Extraction types this extractor can produce */
+    extractionTypes: string[];
+};
+/**
+ * RAG-specific retry configuration
+ */
+export type RAGRetryConfig = {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries: number;
+    /** Initial delay in ms (default: 1000) */
+    initialDelay: number;
+    /** Maximum delay in ms (default: 30000) */
+    maxDelay: number;
+    /** Backoff multiplier (default: 2) */
+    backoffMultiplier: number;
+    /** Whether to add jitter (default: true) */
+    jitter: boolean;
+    /**
+     * Custom function to determine if error is retryable.
+     *
+     * Note: In `isRetryable()`, this callback is invoked *before* the built-in
+     * abort-error check. If you provide a custom `shouldRetry`, it should
+     * explicitly handle abort errors (e.g. return `false` for them) when
+     * cancellation correctness is required. Otherwise an aborted operation
+     * could be retried instead of propagating immediately.
+     */
+    shouldRetry?: (error: Error) => boolean;
+    /** Retryable error codes */
+    retryableErrorCodes?: string[];
+    /** Retryable HTTP status codes */
+    retryableStatusCodes?: number[];
+};
+/**
+ * Circuit breaker configuration
+ */
+export type RAGCircuitBreakerConfig = {
+    /** Number of failures before opening circuit (default: 5) */
+    failureThreshold: number;
+    /** Time in ms before attempting reset (default: 60000) */
+    resetTimeout: number;
+    /** Max calls allowed in half-open state (default: 3) */
+    halfOpenMaxCalls: number;
+    /** Operation timeout in ms (default: 30000) */
+    operationTimeout: number;
+    /** Minimum calls before calculating failure rate (default: 10) */
+    minimumCallsBeforeCalculation: number;
+    /** Time window for statistics in ms (default: 300000 - 5 minutes) */
+    statisticsWindowSize: number;
+};
+/**
+ * Circuit breaker statistics
+ */
+export type RAGCircuitBreakerStats = {
+    state: CircuitState;
+    totalCalls: number;
+    successfulCalls: number;
+    failedCalls: number;
+    failureRate: number;
+    windowCalls: number;
+    lastStateChange: Date;
+    nextRetryTime?: Date;
+    halfOpenCalls: number;
+    averageLatency: number;
+    p95Latency: number;
+};
+/**
+ * Embedding model configuration
+ */
+export type EmbeddingModelConfig = {
+    provider: string;
+    modelName: string;
+};
+/**
+ * Generation model configuration
+ */
+export type GenerationModelConfig = {
+    provider: string;
+    modelName: string;
+    temperature?: number;
+    maxTokens?: number;
+};
+/**
+ * RAG pipeline configuration
+ */
+export type RAGPipelineConfig = {
+    /** Pipeline identifier */
+    id?: string;
+    /** Vector store instance (defaults to in-memory) */
+    vectorStore?: VectorStore;
+    /** BM25 index for hybrid search (defaults to in-memory) */
+    bm25Index?: BM25Index;
+    /** Index name for vector store */
+    indexName?: string;
+    /** Embedding model configuration */
+    embeddingModel: EmbeddingModelConfig;
+    /** Generation model configuration (for RAG responses) */
+    generationModel?: GenerationModelConfig;
+    /** Default chunking strategy */
+    defaultChunkingStrategy?: ChunkingStrategy;
+    /** Default chunk size */
+    defaultChunkSize?: number;
+    /** Default chunk overlap */
+    defaultChunkOverlap?: number;
+    /** Enable hybrid search (vector + BM25) */
+    enableHybridSearch?: boolean;
+    /** Enable Graph RAG */
+    enableGraphRAG?: boolean;
+    /** Graph RAG similarity threshold */
+    graphThreshold?: number;
+    /** Default number of results to retrieve */
+    defaultTopK?: number;
+    /** Enable reranking */
+    enableReranking?: boolean;
+    /** Reranking model configuration */
+    rerankingModel?: EmbeddingModelConfig;
+};
+/**
+ * Ingestion options
+ */
+export type IngestOptions = {
+    /** Chunking strategy override */
+    strategy?: ChunkingStrategy;
+    /** Chunk size override */
+    chunkSize?: number;
+    /** Chunk overlap override */
+    chunkOverlap?: number;
+    /** Custom metadata to add */
+    metadata?: Record<string, unknown>;
+    /** Extract metadata using LLM */
+    extractMetadata?: boolean;
+};
+/**
+ * Query options
+ */
+export type QueryOptions = {
+    /** Number of chunks to retrieve */
+    topK?: number;
+    /** Use hybrid search */
+    hybrid?: boolean;
+    /** Use Graph RAG */
+    graph?: boolean;
+    /** Enable reranking */
+    rerank?: boolean;
+    /** Metadata filter */
+    filter?: Record<string, unknown>;
+    /** Include sources in response */
+    includeSources?: boolean;
+    /** Generate response (vs just retrieve) */
+    generate?: boolean;
+    /** Custom system prompt for generation */
+    systemPrompt?: string;
+    /** Temperature for generation */
+    temperature?: number;
+};
+/**
+ * Query response
+ */
+export type RAGResponse = {
+    /** Generated answer (if generate=true) */
+    answer?: string;
+    /** Retrieved context chunks */
+    context: string;
+    /** Source documents/chunks */
+    sources: Array<{
+        id: string;
+        text: string;
+        score: number;
+        metadata?: Record<string, unknown>;
+    }>;
+    /** Query metadata */
+    metadata: {
+        queryTime: number;
+        retrievalMethod: string;
+        chunksRetrieved: number;
+        reranked: boolean;
+    };
+};
+/**
+ * Pipeline statistics
+ */
+export type PipelineStats = {
+    totalDocuments: number;
+    totalChunks: number;
+    indexName: string;
+    embeddingDimension?: number;
+    hybridSearchEnabled: boolean;
+    graphRAGEnabled: boolean;
+};
+/**
+ * Supported reranker types
+ */
+export type RerankerType = "llm" | "cross-encoder" | "cohere" | "simple" | "batch";
+/**
+ * Reranker type - all rerankers implement this
+ */
+export type Reranker = {
+    /** Reranker type identifier */
+    readonly type: RerankerType;
+    /**
+     * Rerank results based on query relevance
+     * @param results - Vector search results to rerank
+     * @param query - Original search query
+     * @param options - Reranking options
+     * @returns Reranked results with scores
+     */
+    rerank(results: VectorQueryResult[], query: string, options?: RerankerOptions): Promise<RerankResult[]>;
+};
+/**
+ * Reranker configuration
+ */
+export type RerankerConfig = {
+    /** Reranker type */
+    type: RerankerType;
+    /** Model name for LLM-based rerankers */
+    model?: string | {
+        provider: string;
+        modelName: string;
+    };
+    /** Provider for the model */
+    provider?: string;
+    /** Number of results to return after reranking */
+    topK?: number;
+    /** Scoring weights */
+    weights?: {
+        semantic?: number;
+        vector?: number;
+        position?: number;
+    };
+    /** API key for external services (e.g., Cohere) */
+    apiKey?: string;
+};
+/**
+ * Reranker metadata for discovery and documentation
+ */
+export type RerankerMetadata = {
+    /** Human-readable description */
+    description: string;
+    /** Default configuration */
+    defaultConfig: Partial<RerankerConfig>;
+    /** Supported configuration options */
+    supportedOptions: string[];
+    /** Recommended use cases */
+    useCases: string[];
+    /** Alternative names for this reranker */
+    aliases: string[];
+    /** Whether this reranker requires an AI model */
+    requiresModel: boolean;
+    /** Whether this reranker requires external API */
+    requiresExternalAPI: boolean;
+};
+/**
+ * BM25 Index type
+ * Implementations should provide sparse retrieval capabilities
+ */
+export type BM25Index = {
+    /**
+     * Search documents using BM25 algorithm
+     * @param query - Search query string
+     * @param topK - Number of results to return
+     * @returns Array of BM25 results
+     */
+    search(query: string, topK?: number): Promise<BM25Result[]>;
+    /**
+     * Add documents to the index
+     * @param documents - Documents to index
+     */
+    addDocuments(documents: Array<{
+        id: string;
+        text: string;
+        metadata?: Record<string, unknown>;
+    }>): Promise<void>;
+};
+/**
+ * Hybrid search configuration for creating a search function
+ */
+export type HybridSearchOptions = {
+    /** Vector store instance */
+    vectorStore: VectorStore;
+    /** BM25 index instance */
+    bm25Index: BM25Index;
+    /** Index name for vector store */
+    indexName: string;
+    /** Embedding model configuration (optional - uses defaults from ProviderFactory if not specified) */
+    embeddingModel?: {
+        provider?: string;
+        modelName?: string;
+    };
+    /** Default search configuration */
+    defaultConfig?: HybridSearchConfig;
+};
+/**
+ * Abstract vector store type
+ * Vector stores should implement this type to work with the query tool
+ */
+export type VectorStore = {
+    query(params: {
+        indexName: string;
+        queryVector: number[];
+        topK?: number;
+        filter?: MetadataFilter;
+        includeVectors?: boolean;
+    }): Promise<VectorQueryResult[]>;
+};
+/**
+ * Document loader options
+ */
+export type LoaderOptions = {
+    /** Custom metadata to add to document */
+    metadata?: Record<string, unknown>;
+    /** Encoding for text files */
+    encoding?: BufferEncoding;
+    /** Document type override */
+    type?: DocumentType;
+};
+/**
+ * Web loader options
+ */
+export type WebLoaderOptions = LoaderOptions & {
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Custom headers for request */
+    headers?: Record<string, string>;
+    /** Extract only main content (remove navigation, ads, etc.) */
+    extractMainContent?: boolean;
+    /** Selector for main content (CSS selector) */
+    contentSelector?: string;
+    /** User agent string */
+    userAgent?: string;
+};
+/**
+ * PDF loader options
+ */
+export type PDFLoaderOptions = LoaderOptions & {
+    /** Page range to extract (e.g., "1-5" or "1,3,5") */
+    pageRange?: string;
+    /** Extract images as base64 */
+    extractImages?: boolean;
+    /** OCR for scanned documents */
+    enableOCR?: boolean;
+    /** Preserve layout formatting */
+    preserveLayout?: boolean;
+};
+/**
+ * CSV loader options
+ */
+export type CSVLoaderOptions = LoaderOptions & {
+    /** Delimiter character */
+    delimiter?: string;
+    /** Whether first row is header */
+    hasHeader?: boolean;
+    /** Column names (if no header) */
+    columns?: string[];
+    /** Output format */
+    outputFormat?: "text" | "json" | "markdown";
+};
+/**
+ * Abstract document loader type
+ */
+export type DocumentLoader = {
+    /**
+     * Load document from source
+     * @param source - File path, URL, or content
+     * @param options - Loader options
+     * @returns Promise resolving to MDocument
+     */
+    load(source: string, options?: LoaderOptions): Promise<import("../rag/document/MDocument.js").MDocument>;
+    /**
+     * Check if loader can handle the source
+     * @param source - File path, URL, or content
+     * @returns True if loader can handle the source
+     */
+    canHandle(source: string): boolean;
+};
+/** Circuit breaker state. */
+export type CircuitState = "closed" | "open" | "half-open";
+/** Event map for RAG circuit breaker. */
+export type RAGCircuitBreakerEvents = {
+    stateChange: [
+        {
+            oldState: CircuitState;
+            newState: CircuitState;
+            reason: string;
+            timestamp: Date;
+        }
+    ];
+    callSuccess: [{
+        duration: number;
+        timestamp: Date;
+        operationType?: string;
+    }];
+    callFailure: [
+        {
+            error: string;
+            duration: number;
+            timestamp: Date;
+            operationType?: string;
+        }
+    ];
+    circuitOpen: [{
+        failureRate: number;
+        totalCalls: number;
+        timestamp: Date;
+    }];
+    circuitHalfOpen: [{
+        timestamp: Date;
+    }];
+    circuitClosed: [{
+        timestamp: Date;
+    }];
+};
+import type { Tool } from "ai";
+/** Prepared RAG tool ready for injection into generate/stream. */
+export type RAGPreparedTool = {
+    /** The tool to inject into the tools Record */
+    tool: Tool;
+    /** Tool name (key for the tools Record) */
+    toolName: string;
+    /** Number of chunks indexed */
+    chunksIndexed: number;
+    /** Number of files loaded */
+    filesLoaded: number;
+};
+/**
+ * RAG configuration for generate() and stream() APIs.
+ *
+ * When provided, NeuroLink automatically:
+ * 1. Loads the specified files
+ * 2. Chunks them using the selected strategy
+ * 3. Generates embeddings
+ * 4. Stores in an in-memory vector store
+ * 5. Creates a search tool the AI can invoke on demand
+ *
+ * @example
+ * ```typescript
+ * const result = await neurolink.generate({
+ *   input: { text: "What is RAG?" },
+ *   provider: "vertex",
+ *   rag: {
+ *     files: ["./docs/guide.md", "./docs/api.md"],
+ *     strategy: "markdown",
+ *     chunkSize: 512,
+ *     topK: 5,
+ *   }
+ * });
+ * ```
+ */
+export type RAGConfig = {
+    /** File paths to load and index for retrieval */
+    files: string[];
+    /**
+     * Chunking strategy to use. If not specified, auto-detected from file extension.
+     * @default "recursive"
+     */
+    strategy?: ChunkingStrategy;
+    /**
+     * Maximum chunk size in characters.
+     * @default 1000
+     */
+    chunkSize?: number;
+    /**
+     * Overlap between adjacent chunks in characters.
+     * @default 200
+     */
+    chunkOverlap?: number;
+    /**
+     * Number of top results to retrieve per query.
+     * @default 5
+     */
+    topK?: number;
+    /**
+     * Tool name visible to the AI model.
+     * @default "search_knowledge_base"
+     */
+    toolName?: string;
+    /**
+     * Tool description for the AI model explaining what the knowledge base contains.
+     * @default "Search the loaded documents for relevant information to answer the user's question"
+     */
+    toolDescription?: string;
+    /**
+     * Embedding model provider for generating embeddings.
+     * Defaults to the same provider used for generation.
+     */
+    embeddingProvider?: string;
+    /**
+     * Embedding model name.
+     * Defaults to the provider's default embedding model.
+     */
+    embeddingModel?: string;
+};
 /**
  * Supported document types for processing
  */
@@ -213,17 +813,6 @@ export type ChunkerConfig = CharacterChunkerConfig | RecursiveChunkerConfig | Se
 /**
  * Chunker type - all chunking strategies implement this
  */
-export type Chunker = {
-    /** Strategy name for identification */
-    readonly strategy: ChunkingStrategy;
-    /**
-     * Split text into chunks
-     * @param text - The text to chunk
-     * @param config - Strategy-specific configuration
-     * @returns Array of chunks
-     */
-    chunk(text: string, config?: BaseChunkerConfig): Promise<Chunk[]>;
-};
 /**
  * Chunker metadata for factory registration
  */
@@ -393,21 +982,6 @@ export type VectorQueryResult = {
 /**
  * Reranker configuration
  */
-export type RerankerConfig = {
-    /** Language model for reranking */
-    model: {
-        provider: string;
-        modelName: string;
-    };
-    /** Scoring weights */
-    weights?: {
-        semantic?: number;
-        vector?: number;
-        position?: number;
-    };
-    /** Number of results after reranking */
-    topK?: number;
-};
 /**
  * Provider-specific query options
  */
@@ -615,7 +1189,6 @@ export type GraphStats = {
 /**
  * Reranker type options
  */
-export type RerankerType = "cross-encoder" | "colbert" | "cohere" | "llm";
 /**
  * Reranker options
  */
@@ -698,4 +1271,3 @@ export type RAGCommandArgs = {
     /** Use Graph RAG */
     graph?: boolean;
 };
-export type { RAGConfig } from "../types/ragTypes.js";