@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.
- package/FREE_TIER_ARCHITECTURE.md +232 -232
- package/README.md +206 -206
- package/dist/handlers/index.d.mts +2 -2
- package/dist/handlers/index.d.ts +2 -2
- package/dist/handlers/index.js +271 -202
- package/dist/handlers/index.mjs +271 -202
- package/dist/{BatchProcessor-B8OLSahY.d.ts → index--RhMcXrt.d.ts} +380 -379
- package/dist/{index-BC635WW-.d.ts → index-DE8qPWpI.d.mts} +3 -17
- package/dist/{BatchProcessor-OVOIlNfK.d.mts → index-Dex_gQ3P.d.mts} +380 -379
- package/dist/{index-D2mY1CrY.d.mts → index-DkOhRqEc.d.ts} +3 -17
- package/dist/index.css +869 -1302
- package/dist/index.d.mts +37 -18
- package/dist/index.d.ts +37 -18
- package/dist/index.js +421 -225
- package/dist/index.min.css +2 -2
- package/dist/index.mjs +445 -249
- package/dist/server.d.mts +36 -31
- package/dist/server.d.ts +36 -31
- package/dist/server.js +271 -202
- package/dist/server.mjs +271 -202
- package/package.json +156 -148
- package/dist/{ILLMProvider-BynaFBpy.d.mts → ILLMProvider-DO5gj-e5.d.mts} +83 -83
- package/dist/{ILLMProvider-BynaFBpy.d.ts → ILLMProvider-DO5gj-e5.d.ts} +83 -83
|
@@ -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,
|
|
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.mjs';
|
|
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
|
-
*
|
|
474
|
+
* Dynamically resolved SDK Version from package.json
|
|
580
475
|
*/
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
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
|
-
|
|
588
|
-
|
|
495
|
+
interface RemoteEmbeddingConfig {
|
|
496
|
+
provider: string;
|
|
497
|
+
model: string;
|
|
498
|
+
baseUrl: string;
|
|
499
|
+
apiKey: string;
|
|
500
|
+
profile?: string;
|
|
589
501
|
}
|
|
590
|
-
|
|
591
|
-
|
|
502
|
+
interface RemoteLLMConfig {
|
|
503
|
+
provider: string;
|
|
504
|
+
model: string;
|
|
505
|
+
baseUrl: string;
|
|
506
|
+
apiKey: string;
|
|
507
|
+
profile?: string;
|
|
592
508
|
}
|
|
593
|
-
|
|
594
|
-
|
|
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
|
-
|
|
597
|
-
|
|
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
|
-
|
|
600
|
-
|
|
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
|
-
|
|
603
|
-
|
|
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
|
-
|
|
606
|
-
|
|
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
|
-
|
|
609
|
-
|
|
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
|
-
*
|
|
606
|
+
* Interface implemented by pluggable Renderer Strategies in RendererRegistry.
|
|
613
607
|
*/
|
|
614
|
-
|
|
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
|
-
*
|
|
713
|
+
* LicenseConfigResolver — Resolves LLM and embedding configuration
|
|
714
|
+
* based on the user's license tier from Retrivora admin dashboard.
|
|
753
715
|
*
|
|
754
|
-
*
|
|
755
|
-
*
|
|
716
|
+
* The end-user SDK only needs:
|
|
717
|
+
* - licenseKey (JWT token from Retrivora)
|
|
718
|
+
* - projectId (workspace identifier)
|
|
756
719
|
*
|
|
757
|
-
*
|
|
758
|
-
*
|
|
759
|
-
*
|
|
760
|
-
*
|
|
761
|
-
*
|
|
762
|
-
*
|
|
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
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
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
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
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
|
-
*
|
|
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
|
|
802
|
-
|
|
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
|
-
*
|
|
805
|
-
*
|
|
806
|
-
*
|
|
807
|
-
*
|
|
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
|
-
|
|
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
|
-
*
|
|
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
|
|
785
|
+
private static fetchTierConfig;
|
|
830
786
|
/**
|
|
831
|
-
*
|
|
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
|
|
789
|
+
private static fetchProviderCredentials;
|
|
836
790
|
/**
|
|
837
|
-
*
|
|
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
|
|
793
|
+
private static buildConfigs;
|
|
841
794
|
/**
|
|
842
|
-
*
|
|
843
|
-
* Processes up to `concurrency` items at the same time.
|
|
795
|
+
* Get provider-specific vector DB options
|
|
844
796
|
*/
|
|
845
|
-
static
|
|
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 };
|