@wundam/orchex 1.0.0-rc.2 → 1.0.0-rc.21

package/dist/intelligence/learning-engine.js

@@ -1,433 +0,0 @@
-/**
- * Learning engine for adaptive threshold adjustment in Orchex Learn.
- * Correlates context characteristics with execution success and adapts thresholds.
- */
-import * as fs from 'fs/promises';
-import * as path from 'path';
-import { createLogger } from '../logging.js';
-const log = createLogger('learning-engine');
-/** Default thresholds before learning */
-export const DEFAULT_THRESHOLDS = {
-    maxOwnsCount: {
-        code: 4,
-        docs: 6,
-        tutorial: 3,
-        'integration-guide': 3,
-        test: 4,
-        migration: 3,
-        'api-reference': 4,
-        other: 4,
-    },
-    maxReadsCount: {
-        code: 4,
-        docs: 3,
-        tutorial: 4,
-        'integration-guide': 4,
-        test: 5,
-        migration: 4,
-        'api-reference': 3,
-        other: 4,
-    },
-    maxContextTokens: {
-        code: 140000,
-        docs: 80000,
-        tutorial: 100000,
-        'integration-guide': 100000,
-        test: 140000,
-        migration: 160000,
-        'api-reference': 80000,
-        other: 100000,
-    },
-    globalSoftLimit: 140000,
-    globalHardLimit: 180000,
-    sampleCount: 0,
-    confidence: 'low',
-    lastUpdated: new Date().toISOString(),
-    version: 1,
-};
-/** Minimum samples required for learning */
-export const MIN_SAMPLES_FOR_LEARNING = 20;
-/** Minimum samples for high confidence */
-export const HIGH_CONFIDENCE_THRESHOLD = 100;
-/** Minimum samples for medium confidence */
-export const MEDIUM_CONFIDENCE_THRESHOLD = 50;
-/**
- * Determine confidence level from sample count.
- */
-export function getConfidenceLevel(sampleCount) {
-    if (sampleCount >= HIGH_CONFIDENCE_THRESHOLD)
-        return 'high';
-    if (sampleCount >= MEDIUM_CONFIDENCE_THRESHOLD)
-        return 'medium';
-    return 'low';
-}
-/**
- * Categorize a stream based on its name and plan.
- * Order matters: more specific patterns before general ones.
- * Returns 'code' as default since most uncategorized streams are implementation work.
- */
-export function categorizeStream(name, plan) {
-    const text = `${name} ${plan ?? ''}`.toLowerCase();
-    // Test streams (most specific)
-    if (text.includes('test') || text.includes('spec'))
-        return 'test';
-    // Migration streams (includes refactor/restructure patterns)
-    if (text.includes('migration') ||
-        text.includes('migrate') ||
-        text.includes('refactor') ||
-        text.includes('restructure')) {
-        return 'migration';
-    }
-    // Integration guides (check before generic 'guide' match)
-    if (text.includes('integration') && (text.includes('guide') || text.includes('doc')))
-        return 'integration-guide';
-    // Tutorials (explicit 'tutorial' keyword or 'getting-started')
-    if (text.includes('tutorial') || text.includes('getting-started') || text.includes('getting started'))
-        return 'tutorial';
-    // API reference
-    if (text.includes('api') && (text.includes('ref') || text.includes('doc')))
-        return 'api-reference';
-    // Documentation (includes user-guide, generic guide, doc, readme, md)
-    if (text.includes('doc') || text.includes('readme') || text.includes('md') || text.includes('guide'))
-        return 'docs';
-    // Default to code - most streams without specific keywords are implementation work
-    return 'code';
-}
-/**
- * Correlate context characteristics with success from telemetry events.
- */
-export function correlateContextWithSuccess(events, minSamples = MIN_SAMPLES_FOR_LEARNING) {
-    const correlations = [];
-    const insights = [];
-    // Filter to stream events with context data
-    const streamEvents = events.filter(e => (e.eventType === 'stream_complete' || e.eventType === 'stream_failed') &&
-        e.contextTokensEstimated !== undefined);
-    if (streamEvents.length < minSamples) {
-        return {
-            correlations: [],
-            suggestedThresholds: {},
-            insights: [`Not enough data for learning. Have ${streamEvents.length}, need ${minSamples} samples.`],
-            hasEnoughData: false,
-        };
-    }
-    // Calculate overall success rate
-    const successCount = streamEvents.filter(e => e.eventType === 'stream_complete').length;
-    const overallSuccessRate = successCount / streamEvents.length;
-    insights.push(`Overall success rate: ${(overallSuccessRate * 100).toFixed(1)}% (${successCount}/${streamEvents.length})`);
-    // Analyze context size buckets
-    const contextBuckets = analyzeContextSizeBuckets(streamEvents);
-    if (contextBuckets.optimalRange) {
-        correlations.push({
-            factor: 'contextTokens',
-            successRate: contextBuckets.optimalSuccessRate,
-            sampleSize: contextBuckets.optimalSampleSize,
-            threshold: contextBuckets.optimalRange.max,
-            recommendation: `Optimal context size: ${contextBuckets.optimalRange.min.toLocaleString()}-${contextBuckets.optimalRange.max.toLocaleString()} tokens (${(contextBuckets.optimalSuccessRate * 100).toFixed(1)}% success)`,
-        });
-        insights.push(correlations[correlations.length - 1].recommendation);
-    }
-    // Analyze budget violations
-    const violationAnalysis = analyzeViolations(streamEvents);
-    if (violationAnalysis.softViolationSuccessRate !== undefined) {
-        correlations.push({
-            factor: 'softViolation',
-            successRate: violationAnalysis.softViolationSuccessRate,
-            sampleSize: violationAnalysis.softViolationCount,
-            threshold: 0,
-            recommendation: violationAnalysis.softViolationSuccessRate < 0.7
-                ? 'Soft limit violations have low success rate - consider lowering soft limit'
-                : 'Soft limit violations acceptable - current threshold is appropriate',
-        });
-    }
-    // Generate suggested thresholds
-    const suggestedThresholds = generateSuggestedThresholds(correlations, contextBuckets, streamEvents.length);
-    return {
-        correlations,
-        suggestedThresholds,
-        insights,
-        hasEnoughData: true,
-    };
-}
-function analyzeContextSizeBuckets(events) {
-    // Define buckets by token count
-    const buckets = [
-        { min: 0, max: 50000 },
-        { min: 50000, max: 100000 },
-        { min: 100000, max: 150000 },
-        { min: 150000, max: 200000 },
-    ];
-    let bestBucket = buckets[0];
-    let bestSuccessRate = 0;
-    let bestSampleSize = 0;
-    for (const bucket of buckets) {
-        const bucketEvents = events.filter(e => e.contextTokensEstimated !== undefined &&
-            e.contextTokensEstimated >= bucket.min &&
-            e.contextTokensEstimated < bucket.max);
-        if (bucketEvents.length >= 5) { // Minimum 5 samples per bucket
-            const successCount = bucketEvents.filter(e => e.eventType === 'stream_complete').length;
-            const successRate = successCount / bucketEvents.length;
-            if (successRate > bestSuccessRate) {
-                bestSuccessRate = successRate;
-                bestBucket = bucket;
-                bestSampleSize = bucketEvents.length;
-            }
-        }
-    }
-    return {
-        optimalRange: bestSampleSize >= 5 ? bestBucket : undefined,
-        optimalSuccessRate: bestSuccessRate,
-        optimalSampleSize: bestSampleSize,
-    };
-}
-function analyzeViolations(events) {
-    const softViolations = events.filter(e => e.budgetViolationType === 'soft');
-    const hardViolations = events.filter(e => e.budgetViolationType === 'hard');
-    return {
-        softViolationCount: softViolations.length,
-        softViolationSuccessRate: softViolations.length >= 5
-            ? softViolations.filter(e => e.eventType === 'stream_complete').length / softViolations.length
-            : undefined,
-        hardViolationCount: hardViolations.length,
-        hardViolationSuccessRate: hardViolations.length >= 5
-            ? hardViolations.filter(e => e.eventType === 'stream_complete').length / hardViolations.length
-            : undefined,
-    };
-}
-function generateSuggestedThresholds(correlations, bucketAnalysis, sampleCount) {
-    const suggestions = {
-        sampleCount,
-        confidence: getConfidenceLevel(sampleCount),
-        lastUpdated: new Date().toISOString(),
-        version: 1,
-    };
-    // Suggest global limits based on optimal bucket
-    if (bucketAnalysis.optimalRange) {
-        suggestions.globalSoftLimit = bucketAnalysis.optimalRange.max;
-        suggestions.globalHardLimit = Math.round(bucketAnalysis.optimalRange.max * 1.3);
-    }
-    return suggestions;
-}
-/**
- * Update thresholds based on learning results.
- */
-export function updateThresholds(current, learningResult, learningRate = 0.3) {
-    if (!learningResult.hasEnoughData) {
-        return current;
-    }
-    const updated = { ...current };
-    const suggestions = learningResult.suggestedThresholds;
-    // Apply learning with rate control
-    if (suggestions.globalSoftLimit !== undefined) {
-        updated.globalSoftLimit = Math.round(current.globalSoftLimit * (1 - learningRate) +
-            suggestions.globalSoftLimit * learningRate);
-    }
-    if (suggestions.globalHardLimit !== undefined) {
-        updated.globalHardLimit = Math.round(current.globalHardLimit * (1 - learningRate) +
-            suggestions.globalHardLimit * learningRate);
-    }
-    if (suggestions.sampleCount !== undefined) {
-        updated.sampleCount = suggestions.sampleCount;
-    }
-    if (suggestions.confidence !== undefined) {
-        updated.confidence = suggestions.confidence;
-    }
-    updated.lastUpdated = new Date().toISOString();
-    return updated;
-}
-/**
- * Get the path for learned thresholds storage.
- */
-function getThresholdsPath(projectDir) {
-    return path.join(projectDir, '.orchex', 'learn', 'thresholds.json');
-}
-/**
- * Save learned thresholds to project directory.
- */
-export async function saveLearnedThresholds(projectDir, thresholds) {
-    const filePath = getThresholdsPath(projectDir);
-    const dir = path.dirname(filePath);
-    await fs.mkdir(dir, { recursive: true });
-    await fs.writeFile(filePath, JSON.stringify(thresholds, null, 2), 'utf-8');
-}
-/**
- * Load learned thresholds from project directory.
- */
-export async function loadLearnedThresholds(projectDir) {
-    const filePath = getThresholdsPath(projectDir);
-    try {
-        const content = await fs.readFile(filePath, 'utf-8');
-        const parsed = JSON.parse(content);
-        // Validate version and structure
-        if (parsed.version !== 1) {
-            log.warn({ version: parsed.version }, 'unknown_thresholds_version');
-            return null;
-        }
-        return parsed;
-    }
-    catch {
-        // File doesn't exist or is invalid
-        return null;
-    }
-}
-/**
- * Get thresholds for a project, falling back to defaults.
- */
-export async function getThresholds(projectDir) {
-    const loaded = await loadLearnedThresholds(projectDir);
-    return loaded ?? { ...DEFAULT_THRESHOLDS };
-}
-/**
- * Get recommended limit for a stream category.
- */
-export function getRecommendedLimit(thresholds, category, limitType) {
-    switch (limitType) {
-        case 'owns':
-            return thresholds.maxOwnsCount[category] ?? DEFAULT_THRESHOLDS.maxOwnsCount.other;
-        case 'reads':
-            return thresholds.maxReadsCount[category] ?? DEFAULT_THRESHOLDS.maxReadsCount.other;
-        case 'tokens':
-            return thresholds.maxContextTokens[category] ?? thresholds.globalSoftLimit;
-    }
-}
-function getEventsPath(projectDir) {
-    return path.join(projectDir, '.orchex', 'learn', 'events.jsonl');
-}
-/**
- * Convert a stream result to a TelemetryEvent for learning.
- */
-export function streamResultToTelemetryEvent(result, provider, model) {
-    return {
-        id: `learn-${Date.now()}-${result.id}`,
-        sessionHash: 'local',
-        eventType: result.status === 'complete' ? 'stream_complete' : 'stream_failed',
-        timestamp: new Date().toISOString(),
-        durationMs: result.executionTimeMs,
-        success: result.status === 'complete',
-        tokensInput: result.tokensUsed?.input,
-        tokensOutput: result.tokensUsed?.output,
-        provider,
-        model,
-        contextTokensEstimated: result.contextMetrics?.estimatedTokens,
-        contextBudgetUtilization: result.contextMetrics?.budgetUtilization,
-        budgetViolationType: result.contextMetrics?.violationType,
-    };
-}
-/**
- * Append telemetry events to the local events file (.orchex/learn/events.jsonl).
- * Uses JSONL (one JSON object per line) for append-friendly storage.
- */
-export async function appendLocalEvents(projectDir, events) {
-    if (events.length === 0)
-        return;
-    const filePath = getEventsPath(projectDir);
-    const dir = path.dirname(filePath);
-    await fs.mkdir(dir, { recursive: true });
-    const lines = events.map(e => JSON.stringify(e)).join('\n') + '\n';
-    await fs.appendFile(filePath, lines, 'utf-8');
-}
-/**
- * Load all local telemetry events from the JSONL file.
- * Skips malformed lines silently.
- */
-export async function loadLocalEvents(projectDir) {
-    const filePath = getEventsPath(projectDir);
-    try {
-        const content = await fs.readFile(filePath, 'utf-8');
-        const events = [];
-        for (const line of content.split('\n')) {
-            if (!line.trim())
-                continue;
-            try {
-                events.push(JSON.parse(line));
-            }
-            catch {
-                // Skip malformed lines
-            }
-        }
-        return events;
-    }
-    catch {
-        // File doesn't exist
-        return [];
-    }
-}
-// ============================================================================
-// LE.2: Learning cycle — correlate, update, persist
-// ============================================================================
-/**
- * Run a complete learning cycle: load events → correlate → update → save.
- * Returns the learning result (or null if not enough data).
- * This is the main entry point called after an orchestration completes.
- */
-export async function runLearningCycle(projectDir) {
-    const events = await loadLocalEvents(projectDir);
-    if (events.length < MIN_SAMPLES_FOR_LEARNING) {
-        log.debug({ eventCount: events.length, minRequired: MIN_SAMPLES_FOR_LEARNING }, 'learning_skipped_insufficient_data');
-        return null;
-    }
-    const learningResult = correlateContextWithSuccess(events);
-    if (!learningResult.hasEnoughData) {
-        log.debug({ insights: learningResult.insights }, 'learning_insufficient_context_data');
-        return learningResult;
-    }
-    // Load current thresholds and apply learning
-    const current = await getThresholds(projectDir);
-    const updated = updateThresholds(current, learningResult);
-    // Persist updated thresholds
-    await saveLearnedThresholds(projectDir, updated);
-    log.info({
-        sampleCount: updated.sampleCount,
-        confidence: updated.confidence,
-        globalSoftLimit: updated.globalSoftLimit,
-        globalHardLimit: updated.globalHardLimit,
-    }, 'learning_cycle_completed');
-    return learningResult;
-}
-// ============================================================================
-// LE.4: Cloud aggregation — run learning on telemetry store events
-// ============================================================================
-/**
- * Run learning cycle from telemetry store events (cloud mode).
- * Aggregates across all users for global threshold learning.
- */
-export async function runCloudLearningCycle(events, projectDir) {
-    if (events.length < MIN_SAMPLES_FOR_LEARNING) {
-        return null;
-    }
-    const learningResult = correlateContextWithSuccess(events);
-    if (!learningResult.hasEnoughData) {
-        return learningResult;
-    }
-    const current = await getThresholds(projectDir);
-    const updated = updateThresholds(current, learningResult);
-    await saveLearnedThresholds(projectDir, updated);
-    log.info({
-        sampleCount: updated.sampleCount,
-        confidence: updated.confidence,
-        source: 'cloud_aggregation',
-    }, 'cloud_learning_cycle_completed');
-    return learningResult;
-}
-/**
- * Format a learning report for display.
- */
-export function formatLearningReport(result) {
-    const lines = ['=== Learning Report ===', ''];
-    if (!result.hasEnoughData) {
-        lines.push('Insufficient data for learning.');
-        lines.push(...result.insights);
-        return lines.join('\n');
-    }
-    lines.push('Insights:');
-    for (const insight of result.insights) {
-        lines.push(`  • ${insight}`);
-    }
-    if (result.correlations.length > 0) {
-        lines.push('', 'Correlations:');
-        for (const corr of result.correlations) {
-            lines.push(`  • ${corr.factor}: ${(corr.successRate * 100).toFixed(1)}% success (n=${corr.sampleSize})`);
-            lines.push(`    → ${corr.recommendation}`);
-        }
-    }
-    return lines.join('\n');
-}

package/dist/intelligence/learning-feedback.d.ts

@@ -1,96 +0,0 @@
-/**
- * Learning feedback module for adaptive heuristic adjustment.
- * Analyzes execution history to improve slicing thresholds.
- */
-import type { StreamCategory } from './learning-engine.js';
-/**
- * Heuristic thresholds for stream validation.
- */
-export interface HeuristicThresholds {
-    /** Maximum recommended owns count */
-    maxOwnsCount: number;
-    /** Maximum recommended reads count */
-    maxReadsCount: number;
-    /** Maximum "and" conjunctions in plan */
-    maxPlanAndCount: number;
-    /** Maximum expected output tokens */
-    maxOutputTokens: number;
-    /** Minimum acceptable success rate */
-    minSuccessRate: number;
-}
-/**
- * A suggested threshold adjustment based on learning.
- */
-export interface ThresholdAdjustment {
-    /** Field being adjusted */
-    field: keyof HeuristicThresholds;
-    /** Previous value */
-    oldValue: number;
-    /** Suggested new value */
-    newValue: number;
-    /** Reason for adjustment */
-    reason: string;
-    /** Confidence in the adjustment */
-    confidence: 'high' | 'medium' | 'low';
-}
-/**
- * Metrics for a stream category (from execution history).
- */
-export interface CategoryMetrics {
-    /** Category name */
-    category: StreamCategory;
-    /** Total executions */
-    totalExecutions: number;
-    /** Successful completions */
-    successCount: number;
-    /** Failures */
-    failureCount: number;
-    /** Timeout failures specifically */
-    timeoutCount: number;
-    /** Average owns count for this category */
-    avgOwnsCount: number;
-    /** Average reads count for this category */
-    avgReadsCount: number;
-    /** Average output tokens */
-    avgOutputTokens: number;
-    /** Success rate (0-1) */
-    successRate: number;
-}
-/**
- * Default heuristic thresholds (conservative starting point).
- */
-export declare const DEFAULT_THRESHOLDS: HeuristicThresholds;
-/**
- * Minimum samples required before learning from a category.
- */
-export declare const MIN_CATEGORY_SAMPLES = 5;
-/**
- * Minimum total samples before suggesting adjustments.
- */
-export declare const MIN_TOTAL_SAMPLES = 20;
-/**
- * Learn from execution metrics and suggest threshold adjustments.
- *
- * @param metrics - Map of category to execution metrics
- * @param currentThresholds - Current threshold values
- * @param minSamples - Minimum samples required for learning
- * @returns Array of suggested threshold adjustments
- */
-export declare function learnFromMetrics(metrics: Map<string, CategoryMetrics>, currentThresholds?: HeuristicThresholds, minSamples?: number): ThresholdAdjustment[];
-/**
- * Apply adjustments to thresholds with learning rate control.
- *
- * @param currentThresholds - Current threshold values
- * @param adjustments - Suggested adjustments
- * @param learningRate - How much to move toward suggested values (0-1)
- * @returns Updated thresholds
- */
-export declare function applyAdjustments(currentThresholds: HeuristicThresholds, adjustments: ThresholdAdjustment[], learningRate?: number): HeuristicThresholds;
-/**
- * Format adjustments as a human-readable report.
- */
-export declare function formatAdjustmentsReport(adjustments: ThresholdAdjustment[]): string;
-/**
- * Generate insights from category metrics.
- */
-export declare function generateCategoryInsights(metrics: Map<string, CategoryMetrics>): string[];