@retrivora-ai/rag-engine 2.5.2 → 2.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,5 @@
1
1
  import { CSSProperties, MouseEvent, ReactNode, ElementType } from 'react';
2
- import { W as WidgetPosition, P as Product, u as UIConfig, c as ProjectChatSettings, q as RagMessage, y as VectorMatch, L as LLMConfig, f as EmbeddingConfig, V as VectorDBConfig, U as UITransformationResponse, p as RagConfig, I as ILLMProvider, h as IngestDocument, C as ChatMessage, e as ChatResponse, _ as RetrievalResult, v as UniversalRagConfig } from './ILLMProvider-BynaFBpy.js';
2
+ import { W as WidgetPosition, P as Product, u as UIConfig, c as ProjectChatSettings, q as RagMessage, y as VectorMatch, p as RagConfig, I as ILLMProvider, h as IngestDocument, C as ChatMessage, e as ChatResponse, _ as RetrievalResult, v as UniversalRagConfig, U as UITransformationResponse, L as LLMConfig, f as EmbeddingConfig, V as VectorDBConfig } from './ILLMProvider-DO5gj-e5.js';
3
3
 
4
4
  interface ArchitectureCardProps {
5
5
  icon: ReactNode;
@@ -159,246 +159,6 @@ interface ConfigProviderProps {
159
159
  children: ReactNode;
160
160
  }
161
161
 
162
- /**
163
- * Dynamically resolved SDK Version from package.json
164
- */
165
- declare const SDK_VERSION: string;
166
-
167
- /**
168
- * ConfigFetcher.ts — Dynamically fetches project credentials from Retrivora Control Plane
169
- * without hardcoding plain-text master keys in NPM package binaries.
170
- *
171
- * SECURITY: The SDK must ONLY call the Retrivora Control Plane at https://www.retrivora.com.
172
- * It must never call the end user's own localhost or any other endpoint.
173
- * LLM and embedding calls are proxied through https://www.retrivora.com/api/v1 which
174
- * forwards to https://llm.retrivora.com with the server-side LITELLM_MASTER_KEY.
175
- */
176
-
177
- interface RemoteVectorConfig {
178
- apiKey: string;
179
- indexName: string;
180
- provider: string;
181
- projectId?: string;
182
- namespace?: string;
183
- }
184
- interface RemoteEmbeddingConfig {
185
- provider: string;
186
- model: string;
187
- baseUrl: string;
188
- apiKey: string;
189
- profile?: string;
190
- }
191
- interface RemoteLLMConfig {
192
- provider: string;
193
- model: string;
194
- baseUrl: string;
195
- apiKey: string;
196
- profile?: string;
197
- }
198
- interface RemoteConfig {
199
- projectId?: string;
200
- tier?: string;
201
- isActive?: boolean;
202
- expiresAt?: string;
203
- vectorDb: RemoteVectorConfig;
204
- embedding: RemoteEmbeddingConfig;
205
- llm: RemoteLLMConfig;
206
- workspace?: {
207
- namespace: string;
208
- indexName: string;
209
- };
210
- projectSettings?: ProjectChatSettings;
211
- }
212
-
213
- declare class ConfigFetcher {
214
- private static cache;
215
- private static readonly TTL_MS;
216
- /**
217
- * Fetch full project configuration (vectorDb + embedding + llm + workspace) from Retrivora Control Plane.
218
- *
219
- * The SDK calls https://www.retrivora.com/api/v1/config with the project ID and license key.
220
- * The server validates the license against the database and returns:
221
- * - validity (tier, isActive, expiresAt)
222
- * - LLM model info
223
- * - embedding model info
224
- * - Pinecone index name and workspace/namespace
225
- *
226
- * The Pinecone API key is NOT returned (server-only). The SDK uses local
227
- * PINECONE_API_KEY if available, or vector operations are handled server-side.
228
- */
229
- static fetchRemoteConfig(projectId: string, licenseKey?: string): Promise<RemoteConfig | null>;
230
- /** Convenience: fetch only vector DB config (backwards compat). */
231
- static fetchRemoteVectorConfig(projectId: string, licenseKey?: string): Promise<RemoteVectorConfig | null>;
232
- }
233
-
234
- /**
235
- * LicenseConfigResolver — Resolves LLM and embedding configuration
236
- * based on the user's license tier from Retrivora admin dashboard.
237
- *
238
- * The end-user SDK only needs:
239
- * - licenseKey (JWT token from Retrivora)
240
- * - projectId (workspace identifier)
241
- *
242
- * Configuration includes:
243
- * 1. Tier-based model selection (/api/v1/config)
244
- * 2. Provider API credentials (/api/v1/credentials)
245
- * 3. Vector DB and rate limit settings
246
- *
247
- * All provider API keys (Gemini, Groq, Pinecone) are stored on Retrivora backend
248
- * and never exposed to end-users directly.
249
- */
250
-
251
- interface LicenseTierConfig {
252
- tier: 'free_trial' | 'free' | 'hobby' | 'pro' | 'enterprise';
253
- llmModel: string;
254
- embeddingModel: string;
255
- embeddingDimensions: number;
256
- maxTokens: number;
257
- chunkSize: number;
258
- chunkOverlap: number;
259
- topK: number;
260
- vectorDb: {
261
- provider: string;
262
- indexName: string;
263
- };
264
- rateLimit?: {
265
- requestsPerMinute: number;
266
- tokensPerDay: number;
267
- };
268
- systemPrompt?: string;
269
- }
270
- interface ProviderCredentials {
271
- geminiApiKey?: string;
272
- groqApiKey?: string;
273
- pineconeApiKey?: string;
274
- textEmbeddingProvider?: string;
275
- }
276
- interface ProviderCredentials {
277
- geminiApiKey?: string;
278
- groqApiKey?: string;
279
- pineconeApiKey?: string;
280
- textEmbeddingProvider?: string;
281
- }
282
- /**
283
- * Resolver for license-based configuration.
284
- * This is called by the end-user SDK after they instantiate with licenseKey + projectId.
285
- */
286
- declare class LicenseConfigResolver {
287
- private static readonly RETRIVORA_CONFIG_URL;
288
- private static readonly RETRIVORA_CREDENTIALS_URL;
289
- private static readonly CACHE_TTL_MS;
290
- private static configCache;
291
- /**
292
- * Validate and resolve configuration from license key
293
- * @param licenseKey JWT token from Retrivora (format: rtv_eyJ...)
294
- * @param projectId Workspace identifier
295
- * @returns Resolved LLM and embedding configs with provider credentials
296
- */
297
- static resolveFromLicense(licenseKey: string, projectId: string): Promise<{
298
- llmConfig: LLMConfig;
299
- embeddingConfig: EmbeddingConfig;
300
- vectorDbConfig: VectorDBConfig;
301
- tierConfig: LicenseTierConfig;
302
- credentials: ProviderCredentials;
303
- }>;
304
- /**
305
- * Fetch tier configuration from Retrivora config API
306
- */
307
- private static fetchTierConfig;
308
- /**
309
- * Fetch provider credentials from Retrivora credentials API
310
- */
311
- private static fetchProviderCredentials;
312
- /**
313
- * Build LLM, embedding, and vector DB configs from tier and credentials
314
- */
315
- private static buildConfigs;
316
- /**
317
- * Get provider-specific vector DB options
318
- */
319
- private static getVectorDbOptions;
320
- /**
321
- * Clear configuration cache (useful for testing or manual refresh)
322
- */
323
- static clearCache(): void;
324
- /**
325
- * Get cache stats for debugging
326
- */
327
- static getCacheStats(): {
328
- size: number;
329
- entries: string[];
330
- };
331
- }
332
-
333
- /**
334
- * Primary rendering outcome types supported by the decision engine.
335
- */
336
- type RenderType = 'text' | 'table' | 'carousel' | 'chart' | 'mixed' | 'card' | 'none';
337
- /**
338
- * Chart sub-types available when renderType === 'chart'.
339
- */
340
- type ChartType = 'bar' | 'line' | 'pie' | 'scatter';
341
- /**
342
- * High-level intent classification categories.
343
- */
344
- type IntentCategory = 'information_lookup' | 'product_search' | 'recommendation' | 'comparison' | 'analytics' | 'trend_analysis' | 'ranking' | 'summarization';
345
- /**
346
- * Individual section specifier for multi-section (mixed) responses.
347
- */
348
- interface RenderSectionDecision {
349
- type: RenderType;
350
- chartType?: ChartType;
351
- title?: string;
352
- }
353
- /**
354
- * Final decision produced by the Visualization Decision Engine.
355
- */
356
- interface RenderDecision {
357
- /** Primary rendering format selected */
358
- renderType: RenderType;
359
- /** Specific chart sub-type if renderType === 'chart' */
360
- chartType?: ChartType;
361
- /** Confidence score between 0.0 and 1.0 */
362
- confidence: number;
363
- /** Human-readable explanation of why this decision was reached */
364
- reason: string;
365
- /** Sub-sections if renderType === 'mixed' */
366
- sections?: RenderSectionDecision[];
367
- }
368
- /**
369
- * Context provided to the intent classifier & decision engine rules.
370
- */
371
- interface DecisionContext {
372
- /** Original user prompt/query string */
373
- userQuery: string;
374
- /** Vector DB retrieved documents / context records */
375
- retrievedDocuments?: VectorMatch[];
376
- /** Optional LLM text response if already available */
377
- llmResponse?: string;
378
- /** Additional custom metadata or config settings */
379
- metadata?: Record<string, unknown>;
380
- }
381
- /**
382
- * Interface implemented by rule strategies in the Rule Engine.
383
- */
384
- interface IRenderRule {
385
- /** Unique name of the decision rule */
386
- name: string;
387
- /** Precedence score (higher priority rules run first) */
388
- priority: number;
389
- /** Evaluate the rule against current query context and classified intent */
390
- evaluate(context: DecisionContext, intent: IntentCategory): RenderDecision | null;
391
- }
392
- /**
393
- * Interface implemented by pluggable Renderer Strategies in RendererRegistry.
394
- */
395
- interface IRendererStrategy {
396
- /** Render type identifier handled by this strategy */
397
- type: RenderType | string;
398
- /** Transform input data into a standardized UITransformationResponse payload */
399
- render(data: unknown, options?: Record<string, unknown>): UITransformationResponse;
400
- }
401
-
402
162
  /**
403
163
  * DocumentChunker — splits long text into overlapping chunks
404
164
  * suitable for vector embedding and retrieval.
@@ -443,6 +203,141 @@ declare class DocumentChunker {
443
203
  }>): Chunk[];
444
204
  }
445
205
 
206
+ type CircuitState = 'closed' | 'open' | 'half-open';
207
+ interface CircuitBreakerOptions {
208
+ failureThreshold?: number;
209
+ resetTimeoutMs?: number;
210
+ halfOpenMaxCalls?: number;
211
+ }
212
+ declare class CircuitBreaker {
213
+ private state;
214
+ private failureCount;
215
+ private successCount;
216
+ private lastFailureAt;
217
+ private halfOpenCalls;
218
+ private readonly failureThreshold;
219
+ readonly resetTimeoutMs: number;
220
+ private readonly halfOpenMaxCalls;
221
+ constructor(options?: CircuitBreakerOptions);
222
+ record(success: boolean): void;
223
+ canExecute(): boolean;
224
+ /**
225
+ * Increments the half-open probe counter when a call is attempted in
226
+ * half-open state. Must be called after `canExecute()` returns true and
227
+ * the state is half-open. Safe to call in other states (no-op).
228
+ */
229
+ incrementHalfOpen(): void;
230
+ /**
231
+ * Returns the number of milliseconds the caller should wait before retrying.
232
+ * Returns 0 when the circuit is closed or half-open (i.e., calls are allowed).
233
+ *
234
+ * Fix TYPE-1: replaces direct access to private `lastFailureAt` field via
235
+ * `(cb as any).lastFailureAt` in BatchProcessor.
236
+ */
237
+ retryAfterMs(): number;
238
+ wrap<T>(fn: () => Promise<T>): Promise<T>;
239
+ getState(): CircuitState;
240
+ getFailureCount(): number;
241
+ reset(): void;
242
+ }
243
+
244
+ /**
245
+ * BatchProcessor.ts — Handles batch operations with retry logic.
246
+ *
247
+ * Provides exponential backoff, partial failure tracking, and
248
+ * configurable batch sizing for efficient bulk operations.
249
+ *
250
+ * Fix ARCH-3: BatchProcessor no longer holds a static module-level
251
+ * CircuitBreaker that was shared across all callers. Each call site
252
+ * that needs circuit-breaking should create its own CircuitBreaker
253
+ * and pass it via BatchOptions.circuitBreaker so failures in one
254
+ * upstream (e.g., Pinecone) do not trip the breaker for unrelated
255
+ * upstreams (e.g., PostgreSQL).
256
+ */
257
+
258
+ interface BatchOptions {
259
+ /** Maximum number of items per batch */
260
+ batchSize?: number;
261
+ /** Maximum number of retries for transient failures */
262
+ maxRetries?: number;
263
+ /** Initial delay before retry in milliseconds */
264
+ initialDelayMs?: number;
265
+ /** Maximum delay between retries in milliseconds */
266
+ maxDelayMs?: number;
267
+ /** Multiplier for exponential backoff */
268
+ backoffMultiplier?: number;
269
+ /** Whether to throw on any partial failure */
270
+ throwOnPartialFailure?: boolean;
271
+ /**
272
+ * Optional circuit breaker scoped to the upstream being called.
273
+ *
274
+ * Fix ARCH-3: provide your own CircuitBreaker instance per upstream so
275
+ * failures in one provider (e.g., Pinecone) do not trip the breaker for
276
+ * unrelated providers (e.g., PostgreSQL). When omitted, calls are made
277
+ * directly without circuit-breaking.
278
+ */
279
+ circuitBreaker?: CircuitBreaker;
280
+ }
281
+ interface BatchResult<T> {
282
+ results: T[];
283
+ errors: Array<{
284
+ index: number;
285
+ error: Error;
286
+ itemCount?: number;
287
+ }>;
288
+ totalProcessed: number;
289
+ totalFailed: number;
290
+ }
291
+ /**
292
+ * Determines if an error is transient (should retry)
293
+ */
294
+ declare function isTransientError(error: unknown): boolean;
295
+ declare class BatchProcessor {
296
+ /**
297
+ * Execute a processor call, optionally through a caller-provided circuit
298
+ * breaker. Only transient failures count toward opening the circuit.
299
+ *
300
+ * Fix ARCH-3: removed the static module-level `cb` field. Callers must
301
+ * supply their own CircuitBreaker via BatchOptions.circuitBreaker.
302
+ * Fix TYPE-1: uses the public retryAfterMs() and incrementHalfOpen()
303
+ * API instead of accessing private fields via `as any`.
304
+ */
305
+ private static executeWithCircuitBreaker;
306
+ /**
307
+ * Processes an array of items in configurable batches with retry logic.
308
+ *
309
+ * @param items - Items to process
310
+ * @param processor - Async function that processes a batch of items
311
+ * @param options - Configuration for batch size, retries, etc.
312
+ * @returns Object with results, errors, and statistics
313
+ *
314
+ * @example
315
+ * const docs = [...];
316
+ * const result = await BatchProcessor.processBatch(
317
+ * docs,
318
+ * (batch) => vectorDB.batchUpsert(batch),
319
+ * { batchSize: 100, maxRetries: 3 }
320
+ * );
321
+ */
322
+ static processBatch<T, R>(items: T[], processor: (batch: T[]) => Promise<R>, options?: BatchOptions): Promise<BatchResult<R>>;
323
+ /**
324
+ * Processes items sequentially (one at a time) with retry logic.
325
+ * Useful for operations that don't support batching or when granular
326
+ * error tracking is needed.
327
+ */
328
+ static processSequential<T, R>(items: T[], processor: (item: T) => Promise<R>, options?: BatchOptions): Promise<BatchResult<R>>;
329
+ /**
330
+ * Maps over items with retry logic, returning results in order.
331
+ * Like Array.map() but with async processing and automatic retries.
332
+ */
333
+ static mapWithRetry<T, R>(items: T[], mapper: (item: T) => Promise<R>, options?: BatchOptions): Promise<R[]>;
334
+ /**
335
+ * Parallel processor with concurrency limit.
336
+ * Processes up to `concurrency` items at the same time.
337
+ */
338
+ static processConcurrent<T, R>(items: T[], processor: (item: T) => Promise<R>, concurrency?: number, options?: BatchOptions): Promise<BatchResult<R>>;
339
+ }
340
+
446
341
  /**
447
342
  * Pipeline — orchestrates the RAG flow: Embed → Search → Augment → Generate.
448
343
  *
@@ -576,42 +471,146 @@ declare class Retrivora {
576
471
  }
577
472
 
578
473
  /**
579
- * Named SDK exceptions make failures machine-readable for host applications.
474
+ * Dynamically resolved SDK Version from package.json
580
475
  */
581
- type RetrivoraErrorCode = 'PROVIDER_NOT_FOUND' | 'EMBEDDING_FAILED' | 'RETRIEVAL_FAILED' | 'RATE_LIMITED' | 'CONFIGURATION_ERROR' | 'AUTHENTICATION_ERROR' | 'SDK_VERSION_UNSUPPORTED' | 'LICENSE_VALIDATION_ERROR';
582
- declare class RetrivoraError extends Error {
583
- readonly code: RetrivoraErrorCode;
584
- readonly details?: unknown;
585
- constructor(message: string, code: RetrivoraErrorCode, details?: unknown);
476
+ declare const SDK_VERSION: string;
477
+
478
+ /**
479
+ * ConfigFetcher.ts — Dynamically fetches project credentials from Retrivora Control Plane
480
+ * without hardcoding plain-text master keys in NPM package binaries.
481
+ *
482
+ * SECURITY: The SDK must ONLY call the Retrivora Control Plane at https://www.retrivora.com.
483
+ * It must never call the end user's own localhost or any other endpoint.
484
+ * LLM and embedding calls are proxied through https://www.retrivora.com/api/v1 which
485
+ * forwards to https://llm.retrivora.com with the server-side LITELLM_MASTER_KEY.
486
+ */
487
+
488
+ interface RemoteVectorConfig {
489
+ apiKey: string;
490
+ indexName: string;
491
+ provider: string;
492
+ projectId?: string;
493
+ namespace?: string;
586
494
  }
587
- declare class ProviderNotFoundException extends RetrivoraError {
588
- constructor(providerType: string, provider: string, details?: unknown);
495
+ interface RemoteEmbeddingConfig {
496
+ provider: string;
497
+ model: string;
498
+ baseUrl: string;
499
+ apiKey: string;
500
+ profile?: string;
589
501
  }
590
- declare class EmbeddingFailedException extends RetrivoraError {
591
- constructor(message?: string, details?: unknown);
502
+ interface RemoteLLMConfig {
503
+ provider: string;
504
+ model: string;
505
+ baseUrl: string;
506
+ apiKey: string;
507
+ profile?: string;
592
508
  }
593
- declare class RetrievalException extends RetrivoraError {
594
- constructor(message?: string, details?: unknown);
509
+ interface RemoteConfig {
510
+ projectId?: string;
511
+ tier?: string;
512
+ isActive?: boolean;
513
+ expiresAt?: string;
514
+ allowedModels?: string[];
515
+ vectorDb: RemoteVectorConfig;
516
+ embedding: RemoteEmbeddingConfig;
517
+ llm: RemoteLLMConfig;
518
+ workspace?: {
519
+ namespace: string;
520
+ indexName: string;
521
+ };
522
+ projectSettings?: ProjectChatSettings;
595
523
  }
596
- declare class RateLimitException extends RetrivoraError {
597
- constructor(message?: string, details?: unknown);
524
+
525
+ declare class ConfigFetcher {
526
+ private static cache;
527
+ private static readonly TTL_MS;
528
+ /**
529
+ * Fetch full project configuration (vectorDb + embedding + llm + workspace) from Retrivora Control Plane.
530
+ *
531
+ * The SDK calls https://www.retrivora.com/api/v1/config with the project ID and license key.
532
+ * The server validates the license against the database and returns:
533
+ * - validity (tier, isActive, expiresAt)
534
+ * - LLM model info
535
+ * - embedding model info
536
+ * - Pinecone index name and workspace/namespace
537
+ *
538
+ * The Pinecone API key is NOT returned (server-only). The SDK uses local
539
+ * PINECONE_API_KEY if available, or vector operations are handled server-side.
540
+ */
541
+ static fetchRemoteConfig(projectId: string, licenseKey?: string): Promise<RemoteConfig | null>;
542
+ /** Convenience: fetch only vector DB config (backwards compat). */
543
+ static fetchRemoteVectorConfig(projectId: string, licenseKey?: string): Promise<RemoteVectorConfig | null>;
598
544
  }
599
- declare class ConfigurationException extends RetrivoraError {
600
- constructor(message: string, details?: unknown);
545
+
546
+ /**
547
+ * Primary rendering outcome types supported by the decision engine.
548
+ */
549
+ type RenderType = 'text' | 'table' | 'carousel' | 'chart' | 'mixed' | 'card' | 'none';
550
+ /**
551
+ * Chart sub-types available when renderType === 'chart'.
552
+ */
553
+ type ChartType = 'bar' | 'line' | 'pie' | 'scatter';
554
+ /**
555
+ * High-level intent classification categories.
556
+ */
557
+ type IntentCategory = 'information_lookup' | 'product_search' | 'recommendation' | 'comparison' | 'analytics' | 'trend_analysis' | 'ranking' | 'summarization';
558
+ /**
559
+ * Individual section specifier for multi-section (mixed) responses.
560
+ */
561
+ interface RenderSectionDecision {
562
+ type: RenderType;
563
+ chartType?: ChartType;
564
+ title?: string;
601
565
  }
602
- declare class AuthenticationException extends RetrivoraError {
603
- constructor(message?: string, details?: unknown);
566
+ /**
567
+ * Final decision produced by the Visualization Decision Engine.
568
+ */
569
+ interface RenderDecision {
570
+ /** Primary rendering format selected */
571
+ renderType: RenderType;
572
+ /** Specific chart sub-type if renderType === 'chart' */
573
+ chartType?: ChartType;
574
+ /** Confidence score between 0.0 and 1.0 */
575
+ confidence: number;
576
+ /** Human-readable explanation of why this decision was reached */
577
+ reason: string;
578
+ /** Sub-sections if renderType === 'mixed' */
579
+ sections?: RenderSectionDecision[];
604
580
  }
605
- declare class SDKVersionUnsupportedError extends RetrivoraError {
606
- constructor(message?: string, details?: unknown);
581
+ /**
582
+ * Context provided to the intent classifier & decision engine rules.
583
+ */
584
+ interface DecisionContext {
585
+ /** Original user prompt/query string */
586
+ userQuery: string;
587
+ /** Vector DB retrieved documents / context records */
588
+ retrievedDocuments?: VectorMatch[];
589
+ /** Optional LLM text response if already available */
590
+ llmResponse?: string;
591
+ /** Additional custom metadata or config settings */
592
+ metadata?: Record<string, unknown>;
607
593
  }
608
- declare class LicenseValidationError extends RetrivoraError {
609
- constructor(message?: string, details?: unknown);
594
+ /**
595
+ * Interface implemented by rule strategies in the Rule Engine.
596
+ */
597
+ interface IRenderRule {
598
+ /** Unique name of the decision rule */
599
+ name: string;
600
+ /** Precedence score (higher priority rules run first) */
601
+ priority: number;
602
+ /** Evaluate the rule against current query context and classified intent */
603
+ evaluate(context: DecisionContext, intent: IntentCategory): RenderDecision | null;
610
604
  }
611
605
  /**
612
- * Wraps any unknown error into an appropriate RetrivoraError subclass.
606
+ * Interface implemented by pluggable Renderer Strategies in RendererRegistry.
613
607
  */
614
- declare function wrapError(err: unknown, defaultCode: RetrivoraErrorCode, defaultMessage?: string): RetrivoraError;
608
+ interface IRendererStrategy {
609
+ /** Render type identifier handled by this strategy */
610
+ type: RenderType | string;
611
+ /** Transform input data into a standardized UITransformationResponse payload */
612
+ render(data: unknown, options?: Record<string, unknown>): UITransformationResponse;
613
+ }
615
614
 
616
615
  /**
617
616
  * Input contract for `LicenseValidator.validate()`.
@@ -710,139 +709,141 @@ declare class LicenseValidator {
710
709
  validate(request: LicenseValidationRequest): Promise<LicenseValidationResponse>;
711
710
  }
712
711
 
713
- type CircuitState = 'closed' | 'open' | 'half-open';
714
- interface CircuitBreakerOptions {
715
- failureThreshold?: number;
716
- resetTimeoutMs?: number;
717
- halfOpenMaxCalls?: number;
718
- }
719
- declare class CircuitBreaker {
720
- private state;
721
- private failureCount;
722
- private successCount;
723
- private lastFailureAt;
724
- private halfOpenCalls;
725
- private readonly failureThreshold;
726
- readonly resetTimeoutMs: number;
727
- private readonly halfOpenMaxCalls;
728
- constructor(options?: CircuitBreakerOptions);
729
- record(success: boolean): void;
730
- canExecute(): boolean;
731
- /**
732
- * Increments the half-open probe counter when a call is attempted in
733
- * half-open state. Must be called after `canExecute()` returns true and
734
- * the state is half-open. Safe to call in other states (no-op).
735
- */
736
- incrementHalfOpen(): void;
737
- /**
738
- * Returns the number of milliseconds the caller should wait before retrying.
739
- * Returns 0 when the circuit is closed or half-open (i.e., calls are allowed).
740
- *
741
- * Fix TYPE-1: replaces direct access to private `lastFailureAt` field via
742
- * `(cb as any).lastFailureAt` in BatchProcessor.
743
- */
744
- retryAfterMs(): number;
745
- wrap<T>(fn: () => Promise<T>): Promise<T>;
746
- getState(): CircuitState;
747
- getFailureCount(): number;
748
- reset(): void;
749
- }
750
-
751
712
  /**
752
- * BatchProcessor.ts — Handles batch operations with retry logic.
713
+ * LicenseConfigResolver — Resolves LLM and embedding configuration
714
+ * based on the user's license tier from Retrivora admin dashboard.
753
715
  *
754
- * Provides exponential backoff, partial failure tracking, and
755
- * configurable batch sizing for efficient bulk operations.
716
+ * The end-user SDK only needs:
717
+ * - licenseKey (JWT token from Retrivora)
718
+ * - projectId (workspace identifier)
756
719
  *
757
- * Fix ARCH-3: BatchProcessor no longer holds a static module-level
758
- * CircuitBreaker that was shared across all callers. Each call site
759
- * that needs circuit-breaking should create its own CircuitBreaker
760
- * and pass it via BatchOptions.circuitBreaker so failures in one
761
- * upstream (e.g., Pinecone) do not trip the breaker for unrelated
762
- * upstreams (e.g., PostgreSQL).
720
+ * Configuration includes:
721
+ * 1. Tier-based model selection (/api/v1/config)
722
+ * 2. Provider API credentials (/api/v1/credentials)
723
+ * 3. Vector DB and rate limit settings
724
+ *
725
+ * All provider API keys (Gemini, Groq, Pinecone) are stored on Retrivora backend
726
+ * and never exposed to end-users directly.
763
727
  */
764
728
 
765
- interface BatchOptions {
766
- /** Maximum number of items per batch */
767
- batchSize?: number;
768
- /** Maximum number of retries for transient failures */
769
- maxRetries?: number;
770
- /** Initial delay before retry in milliseconds */
771
- initialDelayMs?: number;
772
- /** Maximum delay between retries in milliseconds */
773
- maxDelayMs?: number;
774
- /** Multiplier for exponential backoff */
775
- backoffMultiplier?: number;
776
- /** Whether to throw on any partial failure */
777
- throwOnPartialFailure?: boolean;
778
- /**
779
- * Optional circuit breaker scoped to the upstream being called.
780
- *
781
- * Fix ARCH-3: provide your own CircuitBreaker instance per upstream so
782
- * failures in one provider (e.g., Pinecone) do not trip the breaker for
783
- * unrelated providers (e.g., PostgreSQL). When omitted, calls are made
784
- * directly without circuit-breaking.
785
- */
786
- circuitBreaker?: CircuitBreaker;
729
+ interface LicenseTierConfig {
730
+ tier: 'free_trial' | 'free' | 'hobby' | 'pro' | 'enterprise';
731
+ llmModel: string;
732
+ embeddingModel: string;
733
+ embeddingDimensions: number;
734
+ maxTokens: number;
735
+ chunkSize: number;
736
+ chunkOverlap: number;
737
+ topK: number;
738
+ vectorDb: {
739
+ provider: string;
740
+ indexName: string;
741
+ };
742
+ rateLimit?: {
743
+ requestsPerMinute: number;
744
+ tokensPerDay: number;
745
+ };
746
+ systemPrompt?: string;
787
747
  }
788
- interface BatchResult<T> {
789
- results: T[];
790
- errors: Array<{
791
- index: number;
792
- error: Error;
793
- itemCount?: number;
794
- }>;
795
- totalProcessed: number;
796
- totalFailed: number;
748
+ interface ProviderCredentials {
749
+ geminiApiKey?: string;
750
+ groqApiKey?: string;
751
+ pineconeApiKey?: string;
752
+ textEmbeddingProvider?: string;
753
+ }
754
+ interface ProviderCredentials {
755
+ geminiApiKey?: string;
756
+ groqApiKey?: string;
757
+ pineconeApiKey?: string;
758
+ textEmbeddingProvider?: string;
797
759
  }
798
760
  /**
799
- * Determines if an error is transient (should retry)
761
+ * Resolver for license-based configuration.
762
+ * This is called by the end-user SDK after they instantiate with licenseKey + projectId.
800
763
  */
801
- declare function isTransientError(error: unknown): boolean;
802
- declare class BatchProcessor {
764
+ declare class LicenseConfigResolver {
765
+ private static readonly RETRIVORA_CONFIG_URL;
766
+ private static readonly RETRIVORA_CREDENTIALS_URL;
767
+ private static readonly CACHE_TTL_MS;
768
+ private static configCache;
803
769
  /**
804
- * Execute a processor call, optionally through a caller-provided circuit
805
- * breaker. Only transient failures count toward opening the circuit.
806
- *
807
- * Fix ARCH-3: removed the static module-level `cb` field. Callers must
808
- * supply their own CircuitBreaker via BatchOptions.circuitBreaker.
809
- * Fix TYPE-1: uses the public retryAfterMs() and incrementHalfOpen()
810
- * API instead of accessing private fields via `as any`.
770
+ * Validate and resolve configuration from license key
771
+ * @param licenseKey JWT token from Retrivora (format: rtv_eyJ...)
772
+ * @param projectId Workspace identifier
773
+ * @returns Resolved LLM and embedding configs with provider credentials
811
774
  */
812
- private static executeWithCircuitBreaker;
775
+ static resolveFromLicense(licenseKey: string, projectId: string): Promise<{
776
+ llmConfig: LLMConfig;
777
+ embeddingConfig: EmbeddingConfig;
778
+ vectorDbConfig: VectorDBConfig;
779
+ tierConfig: LicenseTierConfig;
780
+ credentials: ProviderCredentials;
781
+ }>;
813
782
  /**
814
- * Processes an array of items in configurable batches with retry logic.
815
- *
816
- * @param items - Items to process
817
- * @param processor - Async function that processes a batch of items
818
- * @param options - Configuration for batch size, retries, etc.
819
- * @returns Object with results, errors, and statistics
820
- *
821
- * @example
822
- * const docs = [...];
823
- * const result = await BatchProcessor.processBatch(
824
- * docs,
825
- * (batch) => vectorDB.batchUpsert(batch),
826
- * { batchSize: 100, maxRetries: 3 }
827
- * );
783
+ * Fetch tier configuration from Retrivora config API
828
784
  */
829
- static processBatch<T, R>(items: T[], processor: (batch: T[]) => Promise<R>, options?: BatchOptions): Promise<BatchResult<R>>;
785
+ private static fetchTierConfig;
830
786
  /**
831
- * Processes items sequentially (one at a time) with retry logic.
832
- * Useful for operations that don't support batching or when granular
833
- * error tracking is needed.
787
+ * Fetch provider credentials from Retrivora credentials API
834
788
  */
835
- static processSequential<T, R>(items: T[], processor: (item: T) => Promise<R>, options?: BatchOptions): Promise<BatchResult<R>>;
789
+ private static fetchProviderCredentials;
836
790
  /**
837
- * Maps over items with retry logic, returning results in order.
838
- * Like Array.map() but with async processing and automatic retries.
791
+ * Build LLM, embedding, and vector DB configs from tier and credentials
839
792
  */
840
- static mapWithRetry<T, R>(items: T[], mapper: (item: T) => Promise<R>, options?: BatchOptions): Promise<R[]>;
793
+ private static buildConfigs;
841
794
  /**
842
- * Parallel processor with concurrency limit.
843
- * Processes up to `concurrency` items at the same time.
795
+ * Get provider-specific vector DB options
844
796
  */
845
- static processConcurrent<T, R>(items: T[], processor: (item: T) => Promise<R>, concurrency?: number, options?: BatchOptions): Promise<BatchResult<R>>;
797
+ private static getVectorDbOptions;
798
+ /**
799
+ * Clear configuration cache (useful for testing or manual refresh)
800
+ */
801
+ static clearCache(): void;
802
+ /**
803
+ * Get cache stats for debugging
804
+ */
805
+ static getCacheStats(): {
806
+ size: number;
807
+ entries: string[];
808
+ };
809
+ }
810
+
811
+ /**
812
+ * Named SDK exceptions make failures machine-readable for host applications.
813
+ */
814
+ type RetrivoraErrorCode = 'PROVIDER_NOT_FOUND' | 'EMBEDDING_FAILED' | 'RETRIEVAL_FAILED' | 'RATE_LIMITED' | 'CONFIGURATION_ERROR' | 'AUTHENTICATION_ERROR' | 'SDK_VERSION_UNSUPPORTED' | 'LICENSE_VALIDATION_ERROR';
815
+ declare class RetrivoraError extends Error {
816
+ readonly code: RetrivoraErrorCode;
817
+ readonly details?: unknown;
818
+ constructor(message: string, code: RetrivoraErrorCode, details?: unknown);
819
+ }
820
+ declare class ProviderNotFoundException extends RetrivoraError {
821
+ constructor(providerType: string, provider: string, details?: unknown);
822
+ }
823
+ declare class EmbeddingFailedException extends RetrivoraError {
824
+ constructor(message?: string, details?: unknown);
825
+ }
826
+ declare class RetrievalException extends RetrivoraError {
827
+ constructor(message?: string, details?: unknown);
828
+ }
829
+ declare class RateLimitException extends RetrivoraError {
830
+ constructor(message?: string, details?: unknown);
846
831
  }
832
+ declare class ConfigurationException extends RetrivoraError {
833
+ constructor(message: string, details?: unknown);
834
+ }
835
+ declare class AuthenticationException extends RetrivoraError {
836
+ constructor(message?: string, details?: unknown);
837
+ }
838
+ declare class SDKVersionUnsupportedError extends RetrivoraError {
839
+ constructor(message?: string, details?: unknown);
840
+ }
841
+ declare class LicenseValidationError extends RetrivoraError {
842
+ constructor(message?: string, details?: unknown);
843
+ }
844
+ /**
845
+ * Wraps any unknown error into an appropriate RetrivoraError subclass.
846
+ */
847
+ declare function wrapError(err: unknown, defaultCode: RetrivoraErrorCode, defaultMessage?: string): RetrivoraError;
847
848
 
848
849
  export { type RenderSectionDecision as $, AuthenticationException as A, type BatchOptions as B, type ChatWidgetProps as C, type DocumentUploadProps as D, EmbeddingFailedException as E, type RemoteVectorConfig as F, type RenderDecision as G, type RenderType as H, type IRenderRule as I, RetrievalException as J, Retrivora as K, type LicenseTierConfig as L, type MessageBubbleProps as M, RetrivoraError as N, type RetrivoraErrorCode as O, type ProductCardProps as P, SDKVersionUnsupportedError as Q, type RemoteConfig as R, type SourceCardProps as S, SDK_VERSION as T, isTransientError as U, type ArchitectureCardProps as V, DocumentChunker as W, LicenseConfigResolver as X, Pipeline as Y, type PipelineStep as Z, type ProviderPill as _, type ChatWindowProps as a, type Snippet as a0, wrapError as a1, type ConfigProviderProps as b, type ClientConfig as c, type ProductCarouselProps as d, type ChatViewportSize as e, BatchProcessor as f, type BatchResult as g, type ChartType as h, type Chunk as i, type ChunkOptions as j, CircuitBreaker as k, type CircuitBreakerOptions as l, ConfigFetcher as m, ConfigurationException as n, type DecisionContext as o, type IRendererStrategy as p, type IntentCategory as q, LicenseValidationError as r, type LicenseValidationRequest as s, type LicenseValidationResponse as t, LicenseValidator as u, type ProviderCredentials as v, ProviderNotFoundException as w, RateLimitException as x, type RemoteEmbeddingConfig as y, type RemoteLLMConfig as z };