@absolutejs/absolute 0.19.0-beta.623 → 0.19.0-beta.625

package/dist/types/ai.d.ts

@@ -88,6 +88,10 @@ export type RAGSectionRetrievalDiagnostic = {
     siblingScoreGap?: number;
     topChunkId?: string;
     topSource?: string;
+    topContextLabel?: string;
+    topLocatorLabel?: string;
+    sourceAwareChunkReasonLabel?: string;
+    sourceAwareUnitScopeLabel?: string;
     vectorHits: number;
     lexicalHits: number;
     hybridHits: number;
@@ -289,7 +293,7 @@ export type RAGEmbeddingProvider = {
     defaultModel?: string;
 };
 export type RAGEmbeddingProviderLike = RAGEmbeddingFunction | RAGEmbeddingProvider;
-export type RAGContentFormat = 'text' | 'markdown' | 'html';
+export type RAGContentFormat = 'text' | 'markdown' | 'html' | 'jsonl' | 'tsv' | 'csv' | 'xml' | 'yaml';
 export type RAGFileExtractionInput = {
     data: Uint8Array;
     path?: string;
@@ -753,6 +757,15 @@ export type RAGSQLiteNativeDiagnostics = {
     lastLoadError?: string;
     lastQueryError?: string;
     lastUpsertError?: string;
+    lastQueryPlan?: {
+        pushdownApplied: boolean;
+        pushdownClauseCount: number;
+        filteredCandidateCount?: number;
+        initialSearchK?: number;
+        finalSearchK?: number;
+        backfillCount?: number;
+        queryMode: 'json_fallback' | 'native_vec0';
+    };
 };
 export type RAGPostgresNativeDiagnostics = {
     requested: boolean;
@@ -1062,6 +1075,53 @@ export type CreateRAGAccessControlOptions<TContext = unknown> = {
     resolveScope?: RAGAccessControlScopeResolver<TContext>;
 };
 export type RAGSyncSourceStatus = 'idle' | 'running' | 'completed' | 'failed' | 'disabled';
+export type RAGSyncSourceDiagnosticCode = 'sync_failed' | 'retry_scheduled' | 'storage_resume_pending' | 'email_resume_pending' | 'lineage_conflict_detected' | 'duplicate_sync_key_detected' | 'targeted_refresh_applied' | 'noop_sync' | 'extraction_failures_detected' | 'extractor_missing' | 'ocr_extractor_recommended' | 'canonical_dedupe_applied' | 'robots_blocked' | 'nofollow_skipped' | 'noindex_skipped';
+export type RAGSyncSourceDiagnosticEntry = {
+    code: RAGSyncSourceDiagnosticCode;
+    severity: 'info' | 'warning' | 'error';
+    summary: string;
+};
+export type RAGSyncRetryGuidance = {
+    action: 'wait_for_retry' | 'resume_sync' | 'resolve_conflicts' | 'rerun_sync' | 'inspect_source' | 'configure_extractor';
+    reason: string;
+    nextRetryAt?: number;
+    resumeCursor?: string;
+    syncKeys?: string[];
+};
+export type RAGSyncExtractionFailure = {
+    itemLabel: string;
+    itemKind: 'directory_file' | 'url' | 'storage_object' | 'email_attachment';
+    reason: string;
+    remediation: 'configure_extractor' | 'add_ocr_extractor' | 'inspect_file';
+};
+export type RAGSyncExtractionRecoveryAction = {
+    remediation: RAGSyncExtractionFailure['remediation'];
+    itemKinds: RAGSyncExtractionFailure['itemKind'][];
+    itemLabels: string[];
+    reasons: string[];
+    count: number;
+    summary: string;
+};
+export type RAGSyncExtractionRecoveryPreview = {
+    actions: RAGSyncExtractionRecoveryAction[];
+    recommendedAction?: RAGSyncExtractionRecoveryAction;
+    unresolvedFailures: RAGSyncExtractionFailure[];
+    summary?: string;
+};
+export type RAGSyncExtractionRecoveryHandler = (action: RAGSyncExtractionRecoveryAction) => Promise<boolean | void> | boolean | void;
+export type RAGSyncExtractionRecoveryHandlers = Partial<Record<RAGSyncExtractionFailure['remediation'], RAGSyncExtractionRecoveryHandler>>;
+export type RAGSyncExtractionRecoveryResult = RAGSyncExtractionRecoveryPreview & {
+    completedActions: RAGSyncExtractionRecoveryAction[];
+    failedActions: RAGSyncExtractionRecoveryAction[];
+    skippedActions: RAGSyncExtractionRecoveryAction[];
+    errorsByRemediation?: Partial<Record<RAGSyncExtractionFailure['remediation'], string>>;
+};
+export type RAGSyncSourceDiagnostics = {
+    summary: string;
+    entries: RAGSyncSourceDiagnosticEntry[];
+    extractionFailures?: RAGSyncExtractionFailure[];
+    retryGuidance?: RAGSyncRetryGuidance;
+};
 export type RAGSyncSourceRecord = {
     id: string;
     label: string;
@@ -1079,11 +1139,69 @@ export type RAGSyncSourceRecord = {
     nextRetryAt?: number;
     documentCount?: number;
     chunkCount?: number;
+    reconciliation?: RAGSyncSourceReconciliationSummary;
+    diagnostics?: RAGSyncSourceDiagnostics;
     metadata?: Record<string, unknown>;
 };
+export type RAGSyncSourceReconciliationSummary = {
+    refreshMode: 'noop' | 'targeted';
+    staleDocumentIds: string[];
+    staleSyncKeys: string[];
+    refreshedDocumentIds: string[];
+    refreshedSyncKeys: string[];
+    unchangedDocumentIds: string[];
+    unchangedSyncKeys: string[];
+    targetedRefreshSyncKeys: string[];
+    duplicateSyncKeyGroups: Array<{
+        syncKey: string;
+        count: number;
+        documentIds: string[];
+    }>;
+    lineageConflicts: Array<{
+        syncKey: string;
+        lineageIds: string[];
+        versionIds: string[];
+        latestDocumentIds: string[];
+        documentIds: string[];
+        documents: Array<{
+            documentId: string;
+            lineageId?: string;
+            versionId?: string;
+            versionNumber?: number;
+            isLatestVersion: boolean;
+        }>;
+        reasons: Array<'duplicate_sync_key' | 'multiple_lineages' | 'multiple_versions' | 'multiple_latest_versions'>;
+    }>;
+};
+export type RAGSyncConflictResolutionStrategy = 'keep_latest' | 'keep_highest_version';
+export type RAGSyncConflictResolutionAction = {
+    syncKey: string;
+    keepDocumentId: string;
+    deleteDocumentIds: string[];
+    reasons: RAGSyncSourceReconciliationSummary['lineageConflicts'][number]['reasons'];
+};
+export type RAGSyncConflictResolutionAmbiguity = {
+    syncKey: string;
+    reasons: RAGSyncSourceReconciliationSummary['lineageConflicts'][number]['reasons'];
+    candidateDocumentIds: string[];
+    recommendedStrategy?: RAGSyncConflictResolutionStrategy;
+};
+export type RAGSyncConflictResolutionPreview = {
+    strategy: RAGSyncConflictResolutionStrategy;
+    actions: RAGSyncConflictResolutionAction[];
+    unresolvedSyncKeys: string[];
+    unresolvedConflicts: RAGSyncConflictResolutionAmbiguity[];
+};
+export type RAGSyncConflictResolutionResult = RAGSyncConflictResolutionPreview & {
+    deletedDocumentIds: string[];
+    failedDocumentIds: string[];
+    errorsByDocumentId?: Record<string, string>;
+};
 export type RAGSyncSourceRunResult = {
     documentCount?: number;
     chunkCount?: number;
+    reconciliation?: RAGSyncSourceReconciliationSummary;
+    diagnostics?: RAGSyncSourceDiagnostics;
     metadata?: Record<string, unknown>;
 };
 export type RAGSyncSourceDefinition = {
@@ -1101,8 +1219,21 @@ export type RAGSyncSourceContext = {
     collection: RAGCollection;
     listDocuments?: () => Promise<RAGIndexedDocument[]> | RAGIndexedDocument[];
     deleteDocument?: (id: string) => Promise<boolean> | boolean;
+    sourceRecord?: RAGSyncSourceRecord;
     signal?: AbortSignal;
 };
+export type RAGSQLiteStoreMigrationIssue = {
+    tableName: string;
+    columnName: string;
+    definition: string;
+};
+export type RAGSQLiteStoreMigrationInspection = {
+    issues: RAGSQLiteStoreMigrationIssue[];
+    summary?: string;
+};
+export type RAGSQLiteStoreMigrationResult = RAGSQLiteStoreMigrationInspection & {
+    applied: RAGSQLiteStoreMigrationIssue[];
+};
 export type RAGStorageSyncObject = {
     key: string;
     size?: number;
@@ -1160,6 +1291,79 @@ export type RAGUrlSyncSourceOptions = {
     retryAttempts?: number;
     retryDelayMs?: number;
 };
+export type RAGFeedSyncInput = {
+    url: string;
+    title?: string;
+    metadata?: Record<string, unknown>;
+};
+export type RAGFeedSyncSourceOptions = {
+    id: string;
+    label: string;
+    feeds: RAGFeedSyncInput[];
+    description?: string;
+    autoDiscoverFromHTML?: boolean;
+    maxEntriesPerFeed?: number;
+    maxDiscoveredFeeds?: number;
+    baseMetadata?: Record<string, unknown>;
+    defaultChunking?: RAGChunkingOptions;
+    chunkingRegistry?: RAGChunkingRegistryLike;
+    extractors?: RAGFileExtractor[];
+    extractorRegistry?: RAGFileExtractorRegistryLike;
+    metadata?: Record<string, unknown>;
+    retryAttempts?: number;
+    retryDelayMs?: number;
+};
+export type RAGSitemapSyncInput = {
+    url: string;
+    title?: string;
+    metadata?: Record<string, unknown>;
+};
+export type RAGSitemapSyncSourceOptions = {
+    id: string;
+    label: string;
+    sitemaps: RAGSitemapSyncInput[];
+    description?: string;
+    maxUrlsPerSitemap?: number;
+    autoDiscoverFromRobots?: boolean;
+    maxNestedSitemaps?: number;
+    baseMetadata?: Record<string, unknown>;
+    defaultChunking?: RAGChunkingOptions;
+    chunkingRegistry?: RAGChunkingRegistryLike;
+    extractors?: RAGFileExtractor[];
+    extractorRegistry?: RAGFileExtractorRegistryLike;
+    metadata?: Record<string, unknown>;
+    retryAttempts?: number;
+    retryDelayMs?: number;
+};
+export type RAGSiteDiscoveryInput = {
+    url: string;
+    title?: string;
+    metadata?: Record<string, unknown>;
+};
+export type RAGSiteDiscoverySyncSourceOptions = {
+    id: string;
+    label: string;
+    sites: RAGSiteDiscoveryInput[];
+    description?: string;
+    autoDiscoverFeeds?: boolean;
+    autoDiscoverSitemaps?: boolean;
+    autoDiscoverLinkedPages?: boolean;
+    maxDiscoveredFeeds?: number;
+    maxEntriesPerFeed?: number;
+    maxUrlsPerSitemap?: number;
+    maxNestedSitemaps?: number;
+    maxLinkedPages?: number;
+    maxLinksPerPage?: number;
+    maxLinkDepth?: number;
+    baseMetadata?: Record<string, unknown>;
+    defaultChunking?: RAGChunkingOptions;
+    chunkingRegistry?: RAGChunkingRegistryLike;
+    extractors?: RAGFileExtractor[];
+    extractorRegistry?: RAGFileExtractorRegistryLike;
+    metadata?: Record<string, unknown>;
+    retryAttempts?: number;
+    retryDelayMs?: number;
+};
 export type RAGStorageSyncSourceOptions = {
     id: string;
     label: string;
@@ -1173,7 +1377,9 @@ export type RAGStorageSyncSourceOptions = {
     chunkingRegistry?: RAGChunkingRegistryLike;
     extractors?: RAGFileExtractor[];
     extractorRegistry?: RAGFileExtractorRegistryLike;
+    maxPagesPerRun?: number;
     metadata?: Record<string, unknown>;
+    resumeFromLastCursor?: boolean;
     retryAttempts?: number;
     retryDelayMs?: number;
 };
@@ -1225,7 +1431,9 @@ export type RAGEmailSyncSourceOptions = {
     chunkingRegistry?: RAGChunkingRegistryLike;
     extractors?: RAGFileExtractor[];
     extractorRegistry?: RAGFileExtractorRegistryLike;
+    maxPagesPerRun?: number;
     metadata?: Record<string, unknown>;
+    resumeFromLastCursor?: boolean;
     retryAttempts?: number;
     retryDelayMs?: number;
 };
@@ -1453,6 +1661,10 @@ export type RAGEvaluationCase = {
     expectedChunkIds?: string[];
     expectedSources?: string[];
     expectedDocumentIds?: string[];
+    goldenSet?: boolean;
+    hardNegativeChunkIds?: string[];
+    hardNegativeSources?: string[];
+    hardNegativeDocumentIds?: string[];
     label?: string;
     metadata?: Record<string, unknown>;
 };
@@ -1494,6 +1706,7 @@ export type RAGAnswerGroundingEvaluationCaseResult = {
     matchedIds: string[];
     missingIds: string[];
     extraIds: string[];
+    failureClasses?: Array<'no_expected_targets' | 'no_citations' | 'unresolved_citations' | 'missing_expected_sources' | 'extra_citations' | 'section_source_miss' | 'section_graph_source_miss' | 'section_hierarchy_source_miss' | 'spreadsheet_source_miss' | 'media_source_miss' | 'ocr_source_miss'>;
     groundedAnswer: RAGGroundedAnswer;
     metadata?: Record<string, unknown>;
 };
@@ -1533,6 +1746,7 @@ export type RAGAnswerGroundingEvaluationHistoryStore = {
         suiteId?: string;
         limit?: number;
     }) => Promise<RAGAnswerGroundingEvaluationRun[]> | RAGAnswerGroundingEvaluationRun[];
+    pruneRuns?: (input?: RAGEvaluationHistoryPruneInput) => Promise<RAGEvaluationHistoryPruneResult> | RAGEvaluationHistoryPruneResult;
 };
 export type RAGAnswerGroundingEvaluationLeaderboardEntry = {
     runId: string;
@@ -1631,6 +1845,8 @@ export type RAGAnswerGroundingEvaluationCaseDiff = {
     currentMissingIds: string[];
     previousExtraIds: string[];
     currentExtraIds: string[];
+    previousFailureClasses?: NonNullable<RAGAnswerGroundingEvaluationCaseResult['failureClasses']>;
+    currentFailureClasses?: NonNullable<RAGAnswerGroundingEvaluationCaseResult['failureClasses']>;
     previousReferenceCount?: number;
     currentReferenceCount: number;
     previousResolvedCitationCount?: number;
@@ -1659,6 +1875,7 @@ export type RAGAnswerGroundingEvaluationCaseSnapshot = {
     matchedIds: string[];
     missingIds: string[];
     extraIds: string[];
+    failureClasses?: NonNullable<RAGAnswerGroundingEvaluationCaseResult['failureClasses']>;
     ungroundedReferenceNumbers: number[];
     answer: string;
     previousAnswer?: string;
@@ -1725,6 +1942,7 @@ export type RAGEvaluationCaseResult = {
     matchedIds: string[];
     missingIds: string[];
     mode: 'chunkId' | 'source' | 'documentId';
+    failureClasses?: Array<'no_expected_targets' | 'no_results' | 'no_match' | 'partial_recall' | 'extra_noise' | 'section_evidence_miss' | 'section_graph_miss' | 'section_hierarchy_miss' | 'spreadsheet_evidence_miss' | 'media_evidence_miss' | 'ocr_evidence_miss' | 'routing_miss'>;
     metadata?: Record<string, unknown>;
 };
 export type RAGEvaluationSummary = {
@@ -1753,6 +1971,67 @@ export type RAGEvaluationSuite = {
     input: RAGEvaluationInput;
     metadata?: Record<string, unknown>;
 };
+export type RAGEvaluationSuiteDatasetSummary = {
+    suiteId: string;
+    caseCount: number;
+    goldenSetCount: number;
+    hardNegativeCaseCount: number;
+    hardNegativeChunkIdCount: number;
+    hardNegativeSourceCount: number;
+    hardNegativeDocumentIdCount: number;
+};
+export type RAGEvaluationSuiteGenerationOptions = {
+    suiteId: string;
+    documents: RAGIndexedDocument[];
+    label?: string;
+    description?: string;
+    maxCases?: number;
+    topK?: number;
+    scoreThreshold?: number;
+    filter?: Record<string, unknown>;
+    retrieval?: RAGCollectionSearchParams['retrieval'];
+    includeGoldenSet?: boolean;
+    hardNegativePerCase?: number;
+    metadata?: Record<string, unknown>;
+};
+export type RAGEvaluationSuiteSnapshot = {
+    id: string;
+    suiteId: string;
+    label?: string;
+    description?: string;
+    version: number;
+    createdAt: number;
+    caseCount: number;
+    suite: RAGEvaluationSuite;
+    metadata?: Record<string, unknown>;
+};
+export type RAGEvaluationSuiteSnapshotDiff = {
+    suiteId: string;
+    currentSnapshotId: string;
+    previousSnapshotId?: string;
+    addedCaseIds: string[];
+    removedCaseIds: string[];
+    changedCaseIds: string[];
+    unchangedCaseIds: string[];
+    orderChanged: boolean;
+    caseCountDelta: number;
+};
+export type RAGEvaluationSuiteSnapshotHistoryStore = {
+    saveSnapshot: (snapshot: RAGEvaluationSuiteSnapshot) => Promise<void> | void;
+    listSnapshots: (input?: {
+        suiteId?: string;
+        limit?: number;
+    }) => Promise<RAGEvaluationSuiteSnapshot[]> | RAGEvaluationSuiteSnapshot[];
+    pruneSnapshots?: (input?: RAGEvaluationHistoryPruneInput) => Promise<RAGEvaluationHistoryPruneResult> | RAGEvaluationHistoryPruneResult;
+};
+export type RAGEvaluationSuiteSnapshotHistory = {
+    suiteId: string;
+    suiteLabel?: string;
+    snapshots: RAGEvaluationSuiteSnapshot[];
+    latestSnapshot?: RAGEvaluationSuiteSnapshot;
+    previousSnapshot?: RAGEvaluationSuiteSnapshot;
+    diff?: RAGEvaluationSuiteSnapshotDiff;
+};
 export type RAGEvaluationSuiteRun = {
     id: string;
     suiteId: string;
@@ -1777,6 +2056,17 @@ export type RAGEvaluationHistoryStore = {
         suiteId?: string;
         limit?: number;
     }) => Promise<RAGEvaluationSuiteRun[]> | RAGEvaluationSuiteRun[];
+    pruneRuns?: (input?: RAGEvaluationHistoryPruneInput) => Promise<RAGEvaluationHistoryPruneResult> | RAGEvaluationHistoryPruneResult;
+};
+export type RAGEvaluationHistoryPruneInput = {
+    suiteId?: string;
+    maxAgeMs?: number;
+    maxRunsPerSuite?: number;
+    now?: number;
+};
+export type RAGEvaluationHistoryPruneResult = {
+    removedCount: number;
+    keptCount: number;
 };
 export type RAGEvaluationCaseDiff = {
     caseId: string;
@@ -1790,6 +2080,8 @@ export type RAGEvaluationCaseDiff = {
     currentMatchedIds: string[];
     previousMissingIds: string[];
     currentMissingIds: string[];
+    previousFailureClasses?: NonNullable<RAGEvaluationCaseResult['failureClasses']>;
+    currentFailureClasses?: NonNullable<RAGEvaluationCaseResult['failureClasses']>;
 };
 export type RAGEvaluationRunDiff = {
     suiteId: string;
@@ -1798,6 +2090,12 @@ export type RAGEvaluationRunDiff = {
     regressedCases: RAGEvaluationCaseDiff[];
     improvedCases: RAGEvaluationCaseDiff[];
     unchangedCases: RAGEvaluationCaseDiff[];
+    traceLeadChanges?: Array<{
+        caseId: string;
+        label?: string;
+        previousLead?: string;
+        currentLead: string;
+    }>;
     summaryDelta: {
         passingRate: number;
         averageF1: number;
@@ -1851,6 +2149,38 @@ export type RAGEvaluationCaseTraceSnapshot = {
     previousCandidateTopK?: number;
     lexicalTopK: number;
     previousLexicalTopK?: number;
+    topContextLabel?: string;
+    previousTopContextLabel?: string;
+    topLocatorLabel?: string;
+    previousTopLocatorLabel?: string;
+    leadSpeakerCue?: string;
+    previousLeadSpeakerCue?: string;
+    leadSpeakerAttributionCue?: string;
+    previousLeadSpeakerAttributionCue?: string;
+    leadChannelCue?: string;
+    previousLeadChannelCue?: string;
+    leadChannelAttributionCue?: string;
+    previousLeadChannelAttributionCue?: string;
+    leadContinuityCue?: string;
+    previousLeadContinuityCue?: string;
+    sqliteQueryMode?: 'json_fallback' | 'native_vec0';
+    previousSqliteQueryMode?: 'json_fallback' | 'native_vec0';
+    sqliteQueryPushdownApplied?: boolean;
+    previousSqliteQueryPushdownApplied?: boolean;
+    sqliteQueryPushdownClauseCount?: number;
+    previousSqliteQueryPushdownClauseCount?: number;
+    sqliteQueryFilteredCandidates?: number;
+    previousSqliteQueryFilteredCandidates?: number;
+    sqliteQueryInitialSearchK?: number;
+    previousSqliteQueryInitialSearchK?: number;
+    sqliteQueryFinalSearchK?: number;
+    previousSqliteQueryFinalSearchK?: number;
+    sqliteQueryBackfillCount?: number;
+    previousSqliteQueryBackfillCount?: number;
+    sourceAwareChunkReasonLabel?: string;
+    previousSourceAwareChunkReasonLabel?: string;
+    sourceAwareUnitScopeLabel?: string;
+    previousSourceAwareUnitScopeLabel?: string;
     stageCounts: Partial<Record<RAGRetrievalTraceStage, number>>;
     previousStageCounts: Partial<Record<RAGRetrievalTraceStage, number>>;
     traceChange: 'new' | 'changed' | 'unchanged';
@@ -1941,11 +2271,69 @@ export type RAGEvaluationHistoryPresentation = {
     rows: RAGLabelValueRow[];
     caseTraces: RAGEvaluationCaseTracePresentation[];
 };
+export type RAGEvaluationSuiteSnapshotPresentation = {
+    id: string;
+    label: string;
+    summary: string;
+    version: number;
+    rows: RAGLabelValueRow[];
+};
+export type RAGEvaluationSuiteSnapshotHistoryPresentation = {
+    summary: string;
+    rows: RAGLabelValueRow[];
+    snapshots: RAGEvaluationSuiteSnapshotPresentation[];
+};
 export type RAGAnswerGroundingHistoryPresentation = {
     summary: string;
     rows: RAGLabelValueRow[];
     caseSnapshots: RAGAnswerGroundingCaseSnapshotPresentation[];
 };
+export type RAGEvaluationEntityQualitySummary = {
+    key: string;
+    label: string;
+    entityType: 'source' | 'document';
+    totalCases: number;
+    passedCases: number;
+    partialCases: number;
+    failedCases: number;
+    passingRate: number;
+    averageF1: number;
+    failureCounts: Record<string, number>;
+    caseIds: string[];
+};
+export type RAGAnswerGroundingEntityQualitySummary = {
+    key: string;
+    label: string;
+    entityType: 'source' | 'document';
+    totalCases: number;
+    passedCases: number;
+    partialCases: number;
+    failedCases: number;
+    passingRate: number;
+    averageCitationF1: number;
+    averageResolvedCitationRate: number;
+    failureCounts: Record<string, number>;
+    caseIds: string[];
+};
+export type RAGEvaluationEntityQualityView = {
+    bySource: RAGEvaluationEntityQualitySummary[];
+    byDocument: RAGEvaluationEntityQualitySummary[];
+};
+export type RAGAnswerGroundingEntityQualityView = {
+    bySource: RAGAnswerGroundingEntityQualitySummary[];
+    byDocument: RAGAnswerGroundingEntityQualitySummary[];
+};
+export type RAGEntityQualityPresentation = {
+    key: string;
+    label: string;
+    summary: string;
+    rows: RAGLabelValueRow[];
+};
+export type RAGEntityQualityViewPresentation = {
+    summary: string;
+    rows: RAGLabelValueRow[];
+    entities: RAGEntityQualityPresentation[];
+};
 export type RAGComparisonPresentation = {
     id: string;
     label: string;