@memberjunction/db-auto-doc 2.117.0 → 2.119.0

package/dist/core/BackpropagationEngine.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * Handles backpropagation of insights from child tables to parent tables
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BackpropagationEngine = void 0;
+class BackpropagationEngine {
+    constructor(promptEngine, stateManager, iterationTracker, maxDepth) {
+        this.promptEngine = promptEngine;
+        this.stateManager = stateManager;
+        this.iterationTracker = iterationTracker;
+        this.maxDepth = maxDepth;
+    }
+    /**
+     * Execute backpropagation for a set of triggers
+     */
+    async execute(state, run, triggers) {
+        let tablesUpdated = 0;
+        let totalTokensUsed = 0;
+        // Group triggers by target table
+        const triggersByTable = this.groupTriggersByTable(triggers);
+        for (const [tableKey, tableTriggers] of triggersByTable) {
+            const [schemaName, tableName] = tableKey.split('.');
+            const table = this.stateManager.findTable(state, schemaName, tableName);
+            if (!table) {
+                this.iterationTracker.addWarning(run, `Backpropagation target table not found: ${tableKey}`);
+                continue;
+            }
+            // Skip if no current description
+            if (!table.description) {
+                continue;
+            }
+            // Get current description details
+            const latestIteration = table.descriptionIterations[table.descriptionIterations.length - 1];
+            // Combine insights from all triggers for this table
+            const insights = tableTriggers.map(t => t.insight).join('\n\n');
+            // Execute backpropagation prompt
+            const result = await this.promptEngine.executePrompt('backpropagation', {
+                schemaName,
+                tableName,
+                currentDescription: table.description,
+                currentReasoning: latestIteration?.reasoning || '',
+                currentConfidence: latestIteration?.confidence || 0,
+                insights
+            }, {
+                responseFormat: 'JSON'
+            });
+            if (!result.success || !result.result) {
+                this.iterationTracker.addError(run, `Backpropagation failed for ${tableKey}: ${result.errorMessage}`);
+                continue;
+            }
+            totalTokensUsed += result.tokensUsed;
+            this.iterationTracker.addTokenUsage(run, result.tokensUsed, result.cost);
+            // Check if revision is needed
+            if (result.result.needsRevision) {
+                // Update table description
+                this.stateManager.updateTableDescription(table, result.result.revisedDescription || result.result.reasoning, result.result.reasoning, result.result.confidence, run.modelUsed, 'backpropagation');
+                tablesUpdated++;
+                this.iterationTracker.addLogEntry(run, {
+                    level: table.dependencyLevel || 0,
+                    schema: schemaName,
+                    table: tableName,
+                    action: 'backpropagate',
+                    result: 'changed',
+                    message: 'Description revised based on child table insights',
+                    tokensUsed: result.tokensUsed
+                });
+            }
+            else {
+                this.iterationTracker.addLogEntry(run, {
+                    level: table.dependencyLevel || 0,
+                    schema: schemaName,
+                    table: tableName,
+                    action: 'backpropagate',
+                    result: 'unchanged',
+                    message: 'No revision needed',
+                    tokensUsed: result.tokensUsed
+                });
+            }
+        }
+        if (tablesUpdated > 0) {
+            this.iterationTracker.incrementBackpropagation(run);
+        }
+        return { tablesUpdated, tokensUsed: totalTokensUsed };
+    }
+    /**
+     * Detect insights about parent tables from analysis result
+     * Uses LLM-provided insights instead of NLP pattern matching
+     */
+    detectParentInsights(table, analysisResult, schema, tableName) {
+        const triggers = [];
+        // Current table full name for source
+        const sourceTable = schema && tableName ? `${schema}.${tableName}` : 'unknown';
+        // Use LLM-provided parent table insights (much more accurate than NLP)
+        const parentInsights = analysisResult.parentTableInsights || [];
+        for (const insight of parentInsights) {
+            triggers.push({
+                sourceTable,
+                targetTable: insight.parentTable,
+                insight: insight.insight,
+                confidence: insight.confidence
+            });
+        }
+        return triggers;
+    }
+    /**
+     * Group triggers by target table
+     */
+    groupTriggersByTable(triggers) {
+        const grouped = new Map();
+        for (const trigger of triggers) {
+            if (!grouped.has(trigger.targetTable)) {
+                grouped.set(trigger.targetTable, []);
+            }
+            grouped.get(trigger.targetTable).push(trigger);
+        }
+        return grouped;
+    }
+}
+exports.BackpropagationEngine = BackpropagationEngine;
+//# sourceMappingURL=BackpropagationEngine.js.map

package/dist/core/BackpropagationEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BackpropagationEngine.js","sourceRoot":"","sources":["../../src/core/BackpropagationEngine.ts"],"names":[],"mappings":"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"}

package/dist/core/ConvergenceDetector.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Determines when analysis has converged
+ */
+import { DatabaseDocumentation, AnalysisRun } from '../types/state.js';
+import { ConvergenceConfig } from '../types/config.js';
+import { ConvergenceResult } from '../types/analysis.js';
+import { IterationTracker } from '../state/IterationTracker.js';
+import { StateManager } from '../state/StateManager.js';
+export declare class ConvergenceDetector {
+    private config;
+    private stateManager;
+    private iterationTracker;
+    constructor(config: ConvergenceConfig, stateManager: StateManager, iterationTracker: IterationTracker);
+    /**
+     * Check if analysis has converged
+     */
+    hasConverged(state: DatabaseDocumentation, run: AnalysisRun): ConvergenceResult;
+    /**
+     * Check if there were changes in recent iterations
+     */
+    private hasRecentChanges;
+    /**
+     * Calculate average confidence across all tables
+     */
+    calculateAverageConfidence(state: DatabaseDocumentation): number;
+}
+//# sourceMappingURL=ConvergenceDetector.d.ts.map

package/dist/core/ConvergenceDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConvergenceDetector.d.ts","sourceRoot":"","sources":["../../src/core/ConvergenceDetector.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAExD,qBAAa,mBAAmB;IAE5B,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,gBAAgB;gBAFhB,MAAM,EAAE,iBAAiB,EACzB,YAAY,EAAE,YAAY,EAC1B,gBAAgB,EAAE,gBAAgB;IAG5C;;OAEG;IACI,YAAY,CACjB,KAAK,EAAE,qBAAqB,EAC5B,GAAG,EAAE,WAAW,GACf,iBAAiB;IAiEpB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAQxB;;OAEG;IACI,0BAA0B,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM;CAkBxE"}

package/dist/core/ConvergenceDetector.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * Determines when analysis has converged
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConvergenceDetector = void 0;
+class ConvergenceDetector {
+    constructor(config, stateManager, iterationTracker) {
+        this.config = config;
+        this.stateManager = stateManager;
+        this.iterationTracker = iterationTracker;
+    }
+    /**
+     * Check if analysis has converged
+     */
+    hasConverged(state, run) {
+        const reasons = [];
+        // 1. Check max iterations
+        if (run.iterationsPerformed >= this.config.maxIterations) {
+            return {
+                converged: true,
+                reason: `Reached maximum iteration limit (${this.config.maxIterations})`,
+                iterationsPerformed: run.iterationsPerformed,
+                suggestions: ['Consider increasing maxIterations if results are unsatisfactory']
+            };
+        }
+        // 2. Check stability window (no changes in last N iterations)
+        if (run.iterationsPerformed >= 2) {
+            const hasChanges = this.hasRecentChanges(run, this.config.stabilityWindow);
+            if (!hasChanges) {
+                reasons.push(`No changes in last ${this.config.stabilityWindow} iterations (stability achieved)`);
+            }
+        }
+        // 3. Check confidence threshold
+        const lowConfidenceTables = this.stateManager.getLowConfidenceTables(state, this.config.confidenceThreshold);
+        if (lowConfidenceTables.length === 0 && run.iterationsPerformed >= 1) {
+            reasons.push(`All tables meet confidence threshold (${this.config.confidenceThreshold})`);
+        }
+        // Converged if we have at least 2 reasons and minimum iterations
+        if (reasons.length >= 2 && run.iterationsPerformed >= 2) {
+            return {
+                converged: true,
+                reason: reasons.join('; '),
+                iterationsPerformed: run.iterationsPerformed
+            };
+        }
+        // Not yet converged
+        const suggestions = [];
+        if (lowConfidenceTables.length > 0) {
+            suggestions.push(`${lowConfidenceTables.length} tables below confidence threshold - needs more iteration`);
+        }
+        if (run.iterationsPerformed < 2) {
+            suggestions.push('Minimum 2 iterations required before convergence check');
+        }
+        return {
+            converged: false,
+            reason: 'Analysis still evolving',
+            iterationsPerformed: run.iterationsPerformed,
+            suggestions
+        };
+    }
+    /**
+     * Check if there were changes in recent iterations
+     */
+    hasRecentChanges(run, windowSize) {
+        // Get log entries from last window
+        const logsPerIteration = Math.ceil(run.processingLog.length / run.iterationsPerformed);
+        const windowLogs = run.processingLog.slice(-(windowSize * logsPerIteration));
+        return windowLogs.some(entry => entry.result === 'changed');
+    }
+    /**
+     * Calculate average confidence across all tables
+     */
+    calculateAverageConfidence(state) {
+        let totalConfidence = 0;
+        let count = 0;
+        for (const schema of state.schemas) {
+            for (const table of schema.tables) {
+                if (table.descriptionIterations.length > 0) {
+                    const latest = table.descriptionIterations[table.descriptionIterations.length - 1];
+                    if (latest.confidence !== undefined) {
+                        totalConfidence += latest.confidence;
+                        count++;
+                    }
+                }
+            }
+        }
+        return count > 0 ? totalConfidence / count : 0;
+    }
+}
+exports.ConvergenceDetector = ConvergenceDetector;
+//# sourceMappingURL=ConvergenceDetector.js.map

package/dist/core/ConvergenceDetector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConvergenceDetector.js","sourceRoot":"","sources":["../../src/core/ConvergenceDetector.ts"],"names":[],"mappings":"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"}

package/dist/core/GuardrailsManager.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Manages granular guardrails enforcement for DBAutoDoc analysis
+ *
+ * Supports:
+ * - Per-phase token limits (discovery, analysis, sanity checks)
+ * - Per-iteration token and duration limits
+ * - Cost-based limits with configurable thresholds
+ * - Configurable warning thresholds at percentages of limits
+ * - Detailed tracking of exceedances and warnings
+ */
+import { GuardrailsConfig } from '../types/config.js';
+import { AnalysisRun, GuardrailExceeded, GuardrailWarning } from '../types/state.js';
+export type PhaseType = 'discovery' | 'analysis' | 'sanityChecks';
+export interface GuardrailCheckResult {
+    canContinue: boolean;
+    warning?: string;
+    reason?: string;
+    warnings?: GuardrailWarning[];
+    exceedances?: GuardrailExceeded[];
+}
+export declare class GuardrailsManager {
+    private config;
+    private startTime;
+    private phaseStartTimes;
+    private currentPhase?;
+    private currentIteration;
+    private iterationStartTime?;
+    constructor(config?: GuardrailsConfig);
+    /**
+     * Begin tracking a new phase
+     */
+    startPhase(phase: PhaseType): void;
+    /**
+     * End tracking current phase and record metrics
+     */
+    endPhase(run: AnalysisRun, phase: PhaseType): void;
+    /**
+     * Start tracking a new iteration
+     */
+    startIteration(iteration: number): void;
+    /**
+     * End tracking current iteration and record metrics
+     */
+    endIteration(run: AnalysisRun, iteration: number): void;
+    /**
+     * Check all guardrails and return enforcement status
+     */
+    checkGuardrails(run: AnalysisRun): GuardrailCheckResult;
+    /**
+     * Record guardrail enforcement in the run
+     */
+    recordEnforcement(run: AnalysisRun, result: GuardrailCheckResult): void;
+    /**
+     * Get tokens used in a specific phase
+     */
+    private getPhaseTokens;
+    /**
+     * Get estimated cost for a specific phase
+     */
+    private getPhaseCost;
+    /**
+     * Get tokens used in current iteration
+     */
+    private getCurrentIterationTokens;
+    /**
+     * Create a stop result with warnings and exceedances
+     */
+    private createStopResult;
+    /**
+     * Get current elapsed time in seconds
+     */
+    getElapsedSeconds(): number;
+    /**
+     * Get current phase token budget (remaining tokens)
+     */
+    getPhaseTokenBudgetRemaining(phase: PhaseType): number | undefined;
+}
+//# sourceMappingURL=GuardrailsManager.d.ts.map

package/dist/core/GuardrailsManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuardrailsManager.d.ts","sourceRoot":"","sources":["../../src/core/GuardrailsManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAqE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAExJ,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,cAAc,CAAC;AAElE,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC9B,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACnC;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,eAAe,CAAqC;IAC5D,OAAO,CAAC,YAAY,CAAC,CAAY;IACjC,OAAO,CAAC,gBAAgB,CAAa;IACrC,OAAO,CAAC,kBAAkB,CAAC,CAAS;gBAExB,MAAM,CAAC,EAAE,gBAAgB;IAKrC;;OAEG;IACI,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAKzC;;OAEG;IACI,QAAQ,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI;IA0BzD;;OAEG;IACI,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAK9C;;OAEG;IACI,YAAY,CAAC,GAAG,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAqB9D;;OAEG;IACI,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG,oBAAoB;IA+N9D;;OAEG;IACI,iBAAiB,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,oBAAoB,GAAG,IAAI;IAuB9E;;OAEG;IACH,OAAO,CAAC,cAAc;IActB;;OAEG;IACH,OAAO,CAAC,YAAY;IAcpB;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAUjC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAaxB;;OAEG;IACI,iBAAiB,IAAI,MAAM;IAIlC;;OAEG;IACI,4BAA4B,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS;CAU1E"}