@holoscript/framework 6.0.3 → 6.0.4

package/dist/training/index.d.ts

@@ -1,1734 +0,0 @@
-/**
- * Spatial Training Data Types
- *
- * Type definitions for the spatial reasoning training data pipeline.
- * Used to generate instruction-response pairs from HoloScript compositions
- * with spatial constraints (spatial_adjacent, spatial_contains, spatial_reachable)
- * for fine-tuning LLMs on spatial reasoning tasks.
- *
- * @module training/SpatialTrainingDataTypes
- */
-/**
- * Difficulty levels for generated spatial reasoning examples.
- *
- * - basic: 2 objects, single spatial relationship
- * - intermediate: 3-5 objects, multiple relationships, mixed constraint types
- * - advanced: 6+ objects, occlusion, nested containment, chained reachability
- */
-type SpatialDifficulty = 'basic' | 'intermediate' | 'advanced';
-/**
- * The three core spatial relationship types from HoloScript's constraint system.
- */
-type SpatialRelationshipType = 'spatial_adjacent' | 'spatial_contains' | 'spatial_reachable';
-/**
- * A scene object with spatial properties for training data generation.
- */
-interface SceneObject {
-    /** Unique identifier for the object */
-    id: string;
-    /** Object type (e.g., 'cube', 'sphere', 'zone', 'npc') */
-    type: string;
-    /** 3D position */
-    position: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    /** 3D scale */
-    scale: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    /** Bounding box (for containment checks) */
-    bounds?: {
-        min: {
-            x: number;
-            y: number;
-            z: number;
-        };
-        max: {
-            x: number;
-            y: number;
-            z: number;
-        };
-    };
-    /** Whether this object acts as an obstacle */
-    isObstacle?: boolean;
-    /** Optional color for visual description */
-    color?: string;
-    /** Optional geometry type */
-    geometry?: string;
-}
-/**
- * A spatial relationship between two scene objects.
- */
-interface SpatialRelationship {
-    /** The relationship type */
-    type: SpatialRelationshipType;
-    /** Source object ID */
-    sourceId: string;
-    /** Target object ID */
-    targetId: string;
-    /** Whether the relationship is satisfied (true=positive, false=negative) */
-    satisfied: boolean;
-    /** Constraint parameters */
-    params: SpatialRelationshipParams;
-}
-/**
- * Parameters for spatial relationship constraints.
- */
-interface SpatialRelationshipParams {
-    /** For adjacent: maximum distance */
-    maxDistance?: number;
-    /** For adjacent: minimum distance */
-    minDistance?: number;
-    /** For adjacent: axis restriction */
-    axis?: string;
-    /** For contains: margin */
-    margin?: number;
-    /** For contains: strict mode */
-    strict?: boolean;
-    /** For reachable: max path length */
-    maxPathLength?: number;
-    /** For reachable: obstacle types */
-    obstacleTypes?: string[];
-    /** For reachable: algorithm */
-    algorithm?: string;
-}
-/**
- * A complete scene with objects and spatial relationships.
- */
-interface SpatialScene {
-    /** Scene name/identifier */
-    name: string;
-    /** Objects in the scene */
-    objects: SceneObject[];
-    /** Spatial relationships between objects */
-    relationships: SpatialRelationship[];
-    /** Difficulty level */
-    difficulty: SpatialDifficulty;
-    /** The HoloScript composition source */
-    holoScriptSource: string;
-}
-/**
- * A single training example with instruction and response.
- * Suitable for fine-tuning LLMs on spatial reasoning tasks.
- */
-interface SpatialTrainingExample {
-    /** Unique example ID */
-    id: string;
-    /** The instruction/question for the LLM */
-    instruction: string;
-    /** The expected response/answer */
-    response: string;
-    /** The HoloScript source that defines the scene */
-    context: string;
-    /** Spatial relationship type being tested */
-    relationshipType: SpatialRelationshipType;
-    /** Whether this is a positive or negative example */
-    isPositive: boolean;
-    /** Difficulty level */
-    difficulty: SpatialDifficulty;
-    /** Tags for categorization */
-    tags: string[];
-}
-/**
- * Configuration options for the SpatialTrainingDataGenerator.
- */
-interface SpatialGeneratorConfig {
-    /** Number of examples to generate per relationship type per difficulty level */
-    examplesPerCategory?: number;
-    /** Which relationship types to include */
-    relationshipTypes?: SpatialRelationshipType[];
-    /** Which difficulty levels to include */
-    difficultyLevels?: SpatialDifficulty[];
-    /** Ratio of positive to negative examples (default 0.5 = equal) */
-    positiveRatio?: number;
-    /** Random seed for reproducibility (if provided) */
-    seed?: number;
-    /** Whether to include HoloScript context in output */
-    includeContext?: boolean;
-}
-/**
- * Statistics about generated training data.
- */
-interface SpatialGeneratorStats {
-    /** Total number of examples generated */
-    totalExamples: number;
-    /** Breakdown by relationship type */
-    byRelationship: Record<SpatialRelationshipType, number>;
-    /** Breakdown by difficulty */
-    byDifficulty: Record<SpatialDifficulty, number>;
-    /** Breakdown by positive/negative */
-    positiveCount: number;
-    negativeCount: number;
-    /** Number of unique templates used */
-    uniqueTemplatesUsed: number;
-}
-/**
- * JSONL line format for fine-tuning output.
- * Each line in the JSONL file is one of these objects.
- */
-interface SpatialTrainingJSONLEntry {
-    /** The instruction/question */
-    instruction: string;
-    /** The expected response */
-    response: string;
-    /** Metadata for filtering/analysis */
-    metadata: {
-        id: string;
-        relationship_type: SpatialRelationshipType;
-        is_positive: boolean;
-        difficulty: SpatialDifficulty;
-        tags: string[];
-    };
-}
-
-/**
- * Spatial Training Data Generator
- *
- * Generates labeled spatial reasoning examples from HoloScript compositions
- * with spatial constraints (spatial_adjacent, spatial_contains, spatial_reachable).
- *
- * Outputs instruction-response pairs in JSONL format suitable for fine-tuning
- * LLMs on spatial reasoning tasks.
- *
- * Features:
- * - 12+ instruction templates per spatial relationship type (per G.002 mandate)
- * - Randomized scene parameters (object counts, positions, scales, relationships)
- * - Both positive and negative examples for each spatial relationship type
- * - Configurable difficulty levels (basic, intermediate, advanced)
- *
- * @module training/SpatialTrainingDataGenerator
- */
-
-/**
- * Generates labeled spatial reasoning examples from HoloScript compositions.
- *
- * @example
- * ```typescript
- * const generator = new SpatialTrainingDataGenerator({ seed: 42 });
- * const examples = generator.generate();
- * const jsonl = generator.exportJSONL(examples);
- * ```
- */
-declare class SpatialTrainingDataGenerator {
-    private readonly config;
-    private rng;
-    private exampleCounter;
-    constructor(config?: SpatialGeneratorConfig);
-    /**
-     * Generate all spatial training examples based on configuration.
-     */
-    generate(): SpatialTrainingExample[];
-    /**
-     * Generate examples for a specific relationship type.
-     */
-    generateForRelationship(relType: SpatialRelationshipType): SpatialTrainingExample[];
-    /**
-     * Generate examples for a specific difficulty level.
-     */
-    generateForDifficulty(difficulty: SpatialDifficulty): SpatialTrainingExample[];
-    /**
-     * Export examples as JSONL string (one JSON object per line).
-     */
-    exportJSONL(examples: SpatialTrainingExample[]): string;
-    /**
-     * Export examples as JSON array string.
-     */
-    exportJSON(examples: SpatialTrainingExample[]): string;
-    /**
-     * Get statistics about generated examples.
-     */
-    getStats(examples: SpatialTrainingExample[]): SpatialGeneratorStats;
-    /**
-     * Reset the generator with a new seed.
-     */
-    reseed(seed: number): void;
-    /**
-     * Generate a spatial scene for the given relationship type and difficulty.
-     */
-    generateScene(relType: SpatialRelationshipType, difficulty: SpatialDifficulty, isPositive: boolean): SpatialScene;
-    private generateAdjacentScene;
-    private buildAdjacentHoloScript;
-    private generateContainsScene;
-    private buildContainsHoloScript;
-    private generateReachableScene;
-    private buildReachableHoloScript;
-    private generateExample;
-    private getObjectCount;
-    private randomPosition;
-    private randomScale;
-    private pickUniqueName;
-}
-/**
- * Create a new SpatialTrainingDataGenerator with the given configuration.
- */
-declare function createSpatialTrainingDataGenerator(config?: SpatialGeneratorConfig): SpatialTrainingDataGenerator;
-
-/**
- * SparsityMonitorTypes.ts
- *
- * Type definitions for SNN (Spiking Neural Network) sparsity monitoring
- * in the self-improvement pipeline. Tracks spike rates, activation sparsity,
- * energy efficiency metrics, and detects sparsity regime violations.
- *
- * Key threshold (W.041): SNN layers must maintain >= 93% activation sparsity
- * to preserve the energy efficiency advantages of spike-based computation.
- *
- * @module training/SparsityMonitorTypes
- */
-/**
- * Metrics for a single SNN layer during a simulation timestep or batch.
- */
-interface SNNLayerMetrics {
-    /** Unique layer identifier (e.g., "lif_hidden_1", "snn_output") */
-    layerId: string;
-    /** Total number of neurons in this layer */
-    neuronCount: number;
-    /** Number of neurons that spiked (fired) in this timestep/batch */
-    spikeCount: number;
-    /** Spike rate = spikeCount / neuronCount (0-1) */
-    spikeRate: number;
-    /** Activation sparsity = 1 - spikeRate (0-1); higher = sparser = better */
-    activationSparsity: number;
-    /** Average membrane potential across neurons (for LIF models) */
-    avgMembranePotential?: number;
-    /** Simulation timestep index */
-    timestep: number;
-}
-/**
- * A point-in-time snapshot of sparsity metrics across all SNN layers.
- */
-interface SparsitySnapshot {
-    /** ISO 8601 timestamp of measurement */
-    timestamp: string;
-    /** Per-layer metrics at this point in time */
-    layers: SNNLayerMetrics[];
-    /** Aggregate sparsity across all layers (weighted by neuron count) */
-    aggregateSparsity: number;
-    /** Aggregate spike rate across all layers */
-    aggregateSpikeRate: number;
-    /** Total neurons across all layers */
-    totalNeurons: number;
-    /** Total spikes across all layers */
-    totalSpikes: number;
-    /** Energy efficiency metrics at this snapshot */
-    energyEfficiency: EnergyEfficiencyMetrics;
-    /** Any violations detected at this snapshot */
-    violations: SparsityViolation[];
-}
-/**
- * Theoretical energy efficiency metrics comparing SNN spike-based
- * computation vs. equivalent dense (ANN) computation.
- *
- * The key insight: in an SNN, only spiking neurons perform multiply-accumulate
- * (MAC) operations on their synaptic connections. Silent neurons contribute
- * zero computation. This is the source of SNN energy efficiency.
- */
-interface EnergyEfficiencyMetrics {
-    /** Total theoretical operations if all neurons were active (dense ANN baseline) */
-    denseOps: number;
-    /** Actual operations performed (only spiking neurons contribute) */
-    sparseOps: number;
-    /** Operations saved = denseOps - sparseOps */
-    opsSaved: number;
-    /** Efficiency ratio = opsSaved / denseOps (0-1); higher = more efficient */
-    efficiencyRatio: number;
-    /** Estimated energy savings factor (relative to dense baseline = 1.0) */
-    energySavingsFactor: number;
-}
-/**
- * A detected violation of the sparsity threshold.
- *
- * Per W.041 from SNN research: SNN layers must maintain >= 93% activation
- * sparsity. Below this threshold, the energy efficiency advantage of
- * spike-based computation degrades significantly.
- */
-interface SparsityViolation {
-    /** The layer that violated the threshold */
-    layerId: string;
-    /** The measured activation sparsity (0-1) */
-    measuredSparsity: number;
-    /** The required minimum sparsity threshold (default: 0.93) */
-    requiredThreshold: number;
-    /** How far below the threshold: threshold - measured */
-    deficit: number;
-    /** Severity classification */
-    severity: 'warning' | 'critical';
-    /** ISO 8601 timestamp of violation detection */
-    detectedAt: string;
-    /** Timestep at which the violation was detected */
-    timestep: number;
-}
-/**
- * Configuration for the SparsityMonitor.
- */
-interface SparsityMonitorConfig {
-    /** Minimum activation sparsity threshold (default: 0.93 per W.041) */
-    sparsityThreshold: number;
-    /** Window size for rolling average calculations (default: 50 timesteps) */
-    windowSize: number;
-    /** Whether to track per-layer detailed metrics (default: true) */
-    perLayerTracking: boolean;
-    /** Whether energy efficiency calculation is enabled (default: true) */
-    energyMetricsEnabled: boolean;
-    /** Average synaptic connections per neuron (for ops calculation, default: 100) */
-    avgSynapsesPerNeuron: number;
-    /** MAC operations per synaptic event (default: 2 - multiply + accumulate) */
-    opsPerSynapse: number;
-    /** Critical severity threshold: sparsity below this is critical (default: 0.85) */
-    criticalThreshold: number;
-    /** Maximum violations to retain in history (default: 1000) */
-    maxViolationHistory: number;
-}
-/**
- * Aggregate statistics from the SparsityMonitor.
- */
-interface SparsityMonitorStats {
-    /** Total number of timesteps recorded */
-    totalTimesteps: number;
-    /** Total number of snapshots taken */
-    totalSnapshots: number;
-    /** Number of layers being tracked */
-    trackedLayers: number;
-    /** Overall mean sparsity across all timesteps and layers */
-    meanSparsity: number;
-    /** Minimum sparsity observed */
-    minSparsity: number;
-    /** Maximum sparsity observed */
-    maxSparsity: number;
-    /** Standard deviation of sparsity measurements */
-    stdDevSparsity: number;
-    /** Total violations detected */
-    totalViolations: number;
-    /** Violations by severity */
-    violationsBySeverity: {
-        warning: number;
-        critical: number;
-    };
-    /** Per-layer mean sparsity */
-    perLayerMeanSparsity: Record<string, number>;
-    /** Mean energy efficiency ratio */
-    meanEnergyEfficiency: number;
-    /** Whether the system is currently in compliance (no active violations) */
-    inCompliance: boolean;
-}
-/**
- * An entry compatible with the quality-history.json format used by the
- * self-improvement pipeline. Allows sparsity metrics to be tracked
- * alongside existing quality metrics.
- */
-interface SparsityQualityHistoryEntry {
-    /** ISO 8601 timestamp */
-    timestamp: string;
-    /** Monitoring cycle number */
-    cycle: number;
-    /** Aggregate sparsity as composite score (0-1) */
-    composite: number;
-    /** Grade based on sparsity compliance */
-    grade: 'A' | 'B' | 'C' | 'D' | 'F';
-    /** Focus area identifier */
-    focus: 'snn-sparsity';
-    /** Human-readable summary */
-    summary: string;
-    /** Detailed sparsity metrics */
-    sparsityMetrics: {
-        aggregateSparsity: number;
-        aggregateSpikeRate: number;
-        energyEfficiencyRatio: number;
-        violationCount: number;
-        layerCount: number;
-        totalNeurons: number;
-        inCompliance: boolean;
-    };
-}
-
-/**
- * SparsityMonitor.ts
- *
- * Monitors SNN (Spiking Neural Network) sparsity during simulation,
- * tracking spike rates and activation sparsity across layers, calculating
- * energy efficiency metrics, and detecting sparsity regime violations.
- *
- * Integrates with the self-improvement pipeline via:
- * - SelfImproveHarvester: provides metrics for continuous quality monitoring
- * - quality-history.json: outputs compatible entries for historical tracking
- *
- * Key threshold (W.041): SNN layers must maintain >= 93% activation sparsity.
- *
- * Usage:
- * ```ts
- * const monitor = new SparsityMonitor({ sparsityThreshold: 0.93 });
- *
- * // Record layer activity during simulation
- * monitor.recordLayerActivity('lif_hidden_1', {
- *   neuronCount: 1000,
- *   spikeCount: 50,
- *   timestep: 0,
- * });
- *
- * // Take a snapshot
- * const snapshot = monitor.takeSnapshot();
- *
- * // Check for violations
- * const violations = monitor.getActiveViolations();
- *
- * // Get quality-history.json compatible entry
- * const entry = monitor.toQualityHistoryEntry(1);
- * ```
- *
- * @module training/SparsityMonitor
- */
-
-/**
- * Input data for recording layer activity. The monitor computes
- * derived fields (spikeRate, activationSparsity) from these inputs.
- */
-interface LayerActivityInput {
-    /** Total number of neurons in the layer */
-    neuronCount: number;
-    /** Number of neurons that spiked */
-    spikeCount: number;
-    /** Simulation timestep index */
-    timestep: number;
-    /** Optional: average membrane potential */
-    avgMembranePotential?: number;
-}
-/**
- * Monitors SNN activation sparsity across layers during simulation.
- *
- * Provides:
- * 1. Per-layer spike rate and activation sparsity tracking
- * 2. Energy efficiency calculation (theoretical ops saved via sparsity)
- * 3. Sparsity regime violation detection (W.041: >= 93% threshold)
- * 4. Integration with SelfImproveHarvester for continuous quality monitoring
- * 5. Output compatible with quality-history.json format
- */
-declare class SparsityMonitor {
-    private config;
-    /** Current layer metrics indexed by layerId, latest values per layer */
-    private currentLayerMetrics;
-    /** Historical layer metrics: layerId -> array of metrics over time */
-    private layerHistory;
-    /** Snapshots taken over time */
-    private snapshots;
-    /** Detected violations */
-    private violations;
-    /** Rolling window of aggregate sparsity values for stats */
-    private sparsityWindow;
-    /** Total timesteps recorded across all layers */
-    private totalTimestepsRecorded;
-    constructor(config?: Partial<SparsityMonitorConfig>);
-    /**
-     * Record activity for a single SNN layer at a given timestep.
-     *
-     * Computes spike rate and activation sparsity from the raw input,
-     * checks for threshold violations, and stores the metrics.
-     *
-     * @param layerId - Unique identifier for the layer
-     * @param input - Raw activity data (neuronCount, spikeCount, timestep)
-     * @returns The computed SNNLayerMetrics for this recording
-     */
-    recordLayerActivity(layerId: string, input: LayerActivityInput): SNNLayerMetrics;
-    /**
-     * Record activity for multiple layers at the same timestep (batch recording).
-     *
-     * @param layerInputs - Map of layerId -> activity input
-     * @returns Array of computed metrics for each layer
-     */
-    recordBatchActivity(layerInputs: Map<string, LayerActivityInput> | Record<string, LayerActivityInput>): SNNLayerMetrics[];
-    /**
-     * Take a point-in-time snapshot of all current layer metrics.
-     *
-     * The snapshot captures aggregate statistics across all tracked layers,
-     * computes energy efficiency, and checks for violations.
-     *
-     * @returns The snapshot, or null if no layer metrics have been recorded
-     */
-    takeSnapshot(): SparsitySnapshot | null;
-    /**
-     * Calculate theoretical energy efficiency metrics for the given layers.
-     *
-     * Dense ops = sum of (neuronCount * avgSynapsesPerNeuron * opsPerSynapse) per layer
-     * Sparse ops = sum of (spikeCount * avgSynapsesPerNeuron * opsPerSynapse) per layer
-     *
-     * The ratio of ops saved reflects the theoretical computational advantage
-     * of SNN sparsity over equivalent dense ANN computation.
-     */
-    calculateEnergyEfficiency(layers: SNNLayerMetrics[]): EnergyEfficiencyMetrics;
-    /**
-     * Check a single layer's metrics against the sparsity threshold.
-     * If a violation is detected, it is recorded in the violations history.
-     */
-    private checkViolation;
-    /**
-     * Detect violations for an array of layer metrics (used in snapshots).
-     */
-    private detectViolationsForLayers;
-    /**
-     * Get all violations currently affecting active layers
-     * (the most recent metric per layer that is below threshold).
-     */
-    getActiveViolations(): SparsityViolation[];
-    /**
-     * Get all historical violations.
-     */
-    getViolationHistory(): SparsityViolation[];
-    /**
-     * Compute aggregate statistics across all recorded data.
-     */
-    getStats(): SparsityMonitorStats;
-    /**
-     * Generate an entry compatible with the quality-history.json format.
-     *
-     * The composite score is based on the aggregate sparsity relative to
-     * the threshold: score = min(1, aggregateSparsity / threshold).
-     *
-     * @param cycle - The monitoring cycle number
-     * @returns A quality history entry with sparsity-specific metrics
-     */
-    toQualityHistoryEntry(cycle: number): SparsityQualityHistoryEntry;
-    /**
-     * Generate a human-readable summary string for the quality history entry.
-     */
-    private generateSummary;
-    /**
-     * Get metrics formatted for integration with SelfImproveHarvester.
-     *
-     * Returns a record of key metrics that can be attached to harvest records
-     * as additional metadata for training data quality assessment.
-     */
-    getHarvesterMetrics(): Record<string, number | boolean>;
-    /**
-     * Get all recorded snapshots.
-     */
-    getSnapshots(): SparsitySnapshot[];
-    /**
-     * Get the most recent snapshot, or null if none have been taken.
-     */
-    getLatestSnapshot(): SparsitySnapshot | null;
-    /**
-     * Get current layer metrics.
-     */
-    getCurrentLayerMetrics(): Map<string, SNNLayerMetrics>;
-    /**
-     * Get history for a specific layer.
-     */
-    getLayerHistory(layerId: string): SNNLayerMetrics[];
-    /**
-     * Get the current configuration.
-     */
-    getConfig(): SparsityMonitorConfig;
-    /**
-     * Reset all recorded data and start fresh.
-     */
-    reset(): void;
-}
-/**
- * Create a new SparsityMonitor with optional configuration overrides.
- */
-declare function createSparsityMonitor(config?: Partial<SparsityMonitorConfig>): SparsityMonitor;
-
-/**
- * SoftDedup - Soft Deduplication via N-gram Commonness Scoring
- *
- * Instead of hard-deleting duplicate training examples, SoftDedup computes
- * n-gram commonness scores and assigns sampling weights. Examples with
- * high-frequency n-grams (template-generated / near-duplicate content)
- * receive lower sampling weights, reducing their influence during training
- * without discarding them entirely.
- *
- * Based on training rule W.008:
- *   "Reweight duplicates instead of deleting them. SoftDedup uses n-gram
- *    commonness scores to reduce sampling weight of high-frequency data.
- *    26% faster training, +1.77% accuracy vs hard dedup alone."
- *
- * Pipeline position: Quality Filter -> Hard Dedup (W.004) -> SoftDedup (W.008)
- *
- * @module training/SoftDedup
- */
-/**
- * Configuration for the SoftDedup algorithm.
- */
-interface SoftDedupConfig {
-    /**
-     * N-gram sizes to compute commonness scores for.
-     * Using multiple sizes captures both local (small n) and structural (large n)
-     * patterns. Default: [3, 5, 7] (character-level trigrams, 5-grams, 7-grams).
-     */
-    ngramSizes: number[];
-    /**
-     * Whether to use word-level n-grams instead of character-level.
-     * Word-level captures semantic similarity; character-level captures
-     * template-level patterns. Default: false (character-level).
-     */
-    wordLevel: boolean;
-    /**
-     * Minimum sampling weight. Even the most common examples keep at least
-     * this weight to prevent complete exclusion. Default: 0.1 (10% weight).
-     * Must be in range (0, 1].
-     */
-    minWeight: number;
-    /**
-     * Maximum sampling weight. Rare/unique examples get at most this weight.
-     * Default: 1.0 (100% weight). Must be in range [minWeight, 1].
-     */
-    maxWeight: number;
-    /**
-     * Temperature parameter controlling how aggressively to downweight
-     * common examples. Higher temperature = more uniform weights.
-     * Lower temperature = more aggressive downweighting.
-     * Default: 1.0.
-     */
-    temperature: number;
-    /**
-     * Percentile threshold for "common" n-grams.
-     * N-grams appearing more frequently than this percentile of all n-gram
-     * frequencies are considered "common". Default: 0.7 (top 30% are common).
-     * Must be in range [0, 1].
-     */
-    commonThresholdPercentile: number;
-}
-/**
- * Result for a single training example after SoftDedup scoring.
- */
-interface SoftDedupResult {
-    /** Index of the example in the input array */
-    index: number;
-    /** Computed commonness score (0 = unique, 1 = fully common) */
-    commonnessScore: number;
-    /** Assigned sampling weight (minWeight to maxWeight) */
-    samplingWeight: number;
-    /** N-gram statistics for this example */
-    ngramStats: NgramStats;
-}
-/**
- * N-gram statistics for a single example.
- */
-interface NgramStats {
-    /** Total number of n-grams extracted */
-    totalNgrams: number;
-    /** Number of n-grams classified as "common" */
-    commonNgrams: number;
-    /** Ratio of common n-grams to total (0 to 1) */
-    commonRatio: number;
-}
-/**
- * Aggregate statistics for the entire SoftDedup run.
- */
-interface SoftDedupStats {
-    /** Total examples processed */
-    totalExamples: number;
-    /** Mean sampling weight across all examples */
-    meanWeight: number;
-    /** Median sampling weight */
-    medianWeight: number;
-    /** Standard deviation of sampling weights */
-    stdWeight: number;
-    /** Number of examples at minimum weight (heavily downweighted) */
-    atMinWeight: number;
-    /** Number of examples at maximum weight (unique/rare) */
-    atMaxWeight: number;
-    /** Effective dataset size (sum of all weights) */
-    effectiveDatasetSize: number;
-    /** Reduction ratio: 1 - (effectiveSize / totalExamples) */
-    reductionRatio: number;
-    /** Number of unique n-grams in the corpus */
-    uniqueNgramsInCorpus: number;
-    /** Commonness threshold frequency (absolute count) */
-    commonThresholdFrequency: number;
-}
-/**
- * Default SoftDedup configuration.
- * Tuned for HoloScript/Brittney training datasets (920K-1.5M examples).
- */
-declare const DEFAULT_SOFTDEDUP_CONFIG: SoftDedupConfig;
-/**
- * SoftDedup processor for training data.
- *
- * Computes n-gram commonness scores and assigns sampling weights
- * to training examples. Works AFTER hard dedup (W.004).
- *
- * @example
- * ```ts
- * const dedup = new SoftDedup();
- * const results = dedup.process([
- *   'composition MyScene { orb Player { Grabbable {} } }',
- *   'composition MyScene { orb Player { Grabbable {} } }',  // near-duplicate
- *   'world Arena { orb Enemy { Physics { mass: 10 } } }',   // unique
- * ]);
- *
- * // results[0].samplingWeight ~= 0.3 (common template)
- * // results[1].samplingWeight ~= 0.3 (common template)
- * // results[2].samplingWeight ~= 1.0 (unique content)
- * ```
- */
-declare class SoftDedup {
-    private config;
-    constructor(config?: Partial<SoftDedupConfig>);
-    /**
-     * Process a dataset of text examples and compute sampling weights.
-     *
-     * @param examples - Array of text strings (training examples)
-     * @returns Array of SoftDedupResult with sampling weights
-     */
-    process(examples: string[]): SoftDedupResult[];
-    /**
-     * Compute aggregate statistics for a set of SoftDedup results.
-     */
-    computeStats(results: SoftDedupResult[]): SoftDedupStats;
-    /**
-     * Get the current configuration.
-     */
-    getConfig(): Readonly<SoftDedupConfig>;
-    /**
-     * Extract n-grams from a text string.
-     * Supports both character-level and word-level n-grams.
-     */
-    private extractNgrams;
-    /**
-     * Build a frequency map of all n-grams across the entire corpus.
-     */
-    private buildCorpusFrequencies;
-    /**
-     * Compute the frequency threshold above which an n-gram is considered "common".
-     * Uses the configured percentile of the frequency distribution.
-     */
-    private computeThreshold;
-    /**
-     * Convert a commonness score (0-1) to a sampling weight.
-     *
-     * Uses exponential decay with temperature scaling:
-     *   weight = maxWeight * exp(-commonnessScore / temperature)
-     *
-     * Then clamps to [minWeight, maxWeight].
-     */
-    private commonnessToWeight;
-    /**
-     * Validate configuration parameters.
-     * @throws Error if configuration is invalid
-     */
-    private validateConfig;
-}
-/**
- * Create a SoftDedup processor with optional configuration overrides.
- *
- * @example
- * ```ts
- * const dedup = createSoftDedup({ wordLevel: true, temperature: 0.5 });
- * const results = dedup.process(myDataset);
- * const stats = dedup.computeStats(results);
- * console.log(`Effective dataset size: ${stats.effectiveDatasetSize}`);
- * ```
- */
-declare function createSoftDedup(config?: Partial<SoftDedupConfig>): SoftDedup;
-
-/**
- * LRScheduler - Learning Rate Scheduler with Warmup + Cosine Decay
- *
- * Implements the learning rate schedule described in training rule W.009:
- *   "Always use warmup (10% steps) + cosine decay."
- *
- * The schedule has two phases:
- * 1. **Linear Warmup**: LR ramps linearly from 0 to baseLR over the
- *    first warmupSteps (typically 10% of total steps).
- * 2. **Cosine Decay**: LR decays from baseLR to minLR following a
- *    cosine curve over the remaining steps.
- *
- * This prevents early divergence in deep networks and enables smooth
- * convergence. Pairs with W.006 base LR (2e-4 for SFT, 1e-6 for GRPO).
- *
- * @module training/LRScheduler
- */
-/**
- * Configuration for the LR scheduler.
- */
-interface LRSchedulerConfig {
-    /**
-     * Base (peak) learning rate.
-     * Per W.006: 2e-4 for SFT, 1e-6 for GRPO.
-     */
-    baseLR: number;
-    /**
-     * Total number of training steps.
-     * Computed as: (dataset_size / effective_batch_size) * num_epochs.
-     */
-    totalSteps: number;
-    /**
-     * Warmup ratio: fraction of totalSteps used for linear warmup.
-     * Per W.009: 10% warmup steps (warmupRatio = 0.1).
-     * Must be in range [0, 1).
-     */
-    warmupRatio: number;
-    /**
-     * Minimum learning rate at the end of cosine decay.
-     * Typically 0 or a very small value (e.g., 1e-7).
-     * Must be in range [0, baseLR).
-     */
-    minLR: number;
-    /**
-     * Number of cosine annealing cycles.
-     * Default: 1 (single cosine decay from peak to min).
-     * Values > 1 create "cosine annealing with warm restarts" (SGDR).
-     */
-    numCycles: number;
-}
-/**
- * Snapshot of the LR scheduler state at a given step.
- */
-interface LRSchedulerSnapshot {
-    /** Current training step */
-    step: number;
-    /** Current learning rate */
-    learningRate: number;
-    /** Current phase: 'warmup' or 'decay' */
-    phase: 'warmup' | 'decay';
-    /** Progress through current phase (0 to 1) */
-    phaseProgress: number;
-    /** Overall training progress (0 to 1) */
-    overallProgress: number;
-}
-/**
- * Summary statistics for the full LR schedule.
- */
-interface LRScheduleStats {
-    /** Peak learning rate (baseLR) */
-    peakLR: number;
-    /** Minimum learning rate (minLR or end-of-decay value) */
-    minLR: number;
-    /** Number of warmup steps */
-    warmupSteps: number;
-    /** Number of decay steps */
-    decaySteps: number;
-    /** Total training steps */
-    totalSteps: number;
-    /** Average learning rate across all steps */
-    avgLR: number;
-}
-/**
- * Default LR scheduler configuration for HoloScript/Brittney SFT training.
- * Based on W.006 (baseLR=2e-4) and W.009 (warmupRatio=0.1, cosine decay).
- */
-declare const DEFAULT_LR_SCHEDULER_CONFIG: LRSchedulerConfig;
-/**
- * LR scheduler configuration for GRPO training.
- * Uses lower baseLR (1e-6) per GRPOConfig.ts.
- */
-declare const GRPO_LR_SCHEDULER_CONFIG: LRSchedulerConfig;
-/**
- * Learning Rate Scheduler with warmup + cosine decay.
- *
- * Computes the learning rate at any given training step.
- * Stateless: does not track the current step internally. This makes it
- * safe to use in distributed training where multiple workers may query
- * different steps simultaneously.
- *
- * @example
- * ```ts
- * const scheduler = new LRScheduler({
- *   baseLR: 2e-4,
- *   totalSteps: 10000,
- *   warmupRatio: 0.1,
- *   minLR: 1e-7,
- *   numCycles: 1,
- * });
- *
- * // Step 0: LR = 0 (start of warmup)
- * scheduler.getLR(0);     // 0
- *
- * // Step 500: LR = 1e-4 (midway through warmup)
- * scheduler.getLR(500);   // ~0.0001
- *
- * // Step 1000: LR = 2e-4 (end of warmup, peak LR)
- * scheduler.getLR(1000);  // 0.0002
- *
- * // Step 5500: LR ~= 1e-4 (midway through cosine decay)
- * scheduler.getLR(5500);
- *
- * // Step 10000: LR ~= 1e-7 (end of training)
- * scheduler.getLR(10000); // ~0.0000001
- * ```
- */
-declare class LRScheduler {
-    private config;
-    private warmupSteps;
-    constructor(config?: Partial<LRSchedulerConfig>);
-    /**
-     * Get the learning rate at a given training step.
-     *
-     * @param step - Current training step (0-indexed)
-     * @returns The learning rate at this step
-     */
-    getLR(step: number): number;
-    /**
-     * Get a detailed snapshot of the scheduler state at a given step.
-     *
-     * @param step - Current training step (0-indexed)
-     * @returns LRSchedulerSnapshot with full state information
-     */
-    getSnapshot(step: number): LRSchedulerSnapshot;
-    /**
-     * Compute summary statistics for the full LR schedule.
-     * Samples every step to compute the average LR.
-     *
-     * For large totalSteps, this samples at most 10000 evenly-spaced points
-     * for efficiency.
-     */
-    getStats(): LRScheduleStats;
-    /**
-     * Generate the full LR schedule as an array of [step, lr] pairs.
-     * Useful for plotting or debugging.
-     *
-     * @param numPoints - Number of points to sample (default: 100)
-     * @returns Array of [step, learningRate] tuples
-     */
-    getSchedule(numPoints?: number): Array<[number, number]>;
-    /**
-     * Get the number of warmup steps.
-     */
-    getWarmupSteps(): number;
-    /**
-     * Get the current configuration.
-     */
-    getConfig(): Readonly<LRSchedulerConfig>;
-    /**
-     * Validate configuration parameters.
-     * @throws Error if configuration is invalid
-     */
-    private validateConfig;
-}
-/**
- * Create an LR scheduler for SFT training with optional overrides.
- *
- * @example
- * ```ts
- * const scheduler = createSFTScheduler({ totalSteps: 5000 });
- * const lr = scheduler.getLR(100);
- * ```
- */
-declare function createSFTScheduler(config?: Partial<LRSchedulerConfig>): LRScheduler;
-/**
- * Create an LR scheduler for GRPO training with optional overrides.
- *
- * @example
- * ```ts
- * const scheduler = createGRPOScheduler({ totalSteps: 2000 });
- * const lr = scheduler.getLR(100);
- * ```
- */
-declare function createGRPOScheduler(config?: Partial<LRSchedulerConfig>): LRScheduler;
-
-/**
- * Compiler-Based Quality Scoring Pipeline for Training Data
- * Metrics: syntax_validity, schema_compliance, semantic_correctness
- * @version 1.0.0
- */
-interface QualityScore {
-    syntaxValidity: number;
-    schemaCompliance: number;
-    semanticCorrectness: number;
-    compositeScore: number;
-    details: QualityDetail[];
-}
-interface QualityDetail {
-    metric: string;
-    score: number;
-    message: string;
-}
-interface QualityScoringConfig {
-    syntaxWeight: number;
-    schemaWeight: number;
-    semanticWeight: number;
-    minPassScore: number;
-    knownTraits: Set<string>;
-    knownTypes: Set<string>;
-}
-declare const DEFAULT_SCORING_CONFIG: QualityScoringConfig;
-declare class QualityScoringPipeline {
-    private config;
-    constructor(config?: Partial<QualityScoringConfig>);
-    score(source: string): QualityScore;
-    passes(score: QualityScore): boolean;
-    private scoreSyntax;
-    private scoreSchema;
-    private scoreSemantic;
-}
-
-/**
- * TrainingPipelineConfig - Unified Training Pipeline Configuration
- *
- * Integrates all training pipeline components:
- * - Quality Scoring (W.010): Multi-dimensional quality filtering
- * - Hard Dedup (W.004): Exact/near-duplicate removal (external)
- * - SoftDedup (W.008): N-gram commonness-based reweighting
- * - LR Schedule (W.009): Warmup + cosine decay
- * - Hyperparameters (W.006, W.007): Learning rate, batch size, epochs
- *
- * Pipeline order: Quality Filter -> Hard Dedup -> SoftDedup -> Training
- *
- * @module training/TrainingPipelineConfig
- */
-
-/**
- * Complete training pipeline configuration.
- *
- * Encompasses all stages from data preparation through training execution.
- */
-interface TrainingPipelineConfig {
-    /** Data quality filtering configuration (W.010) */
-    qualityScoring: QualityScoringConfig;
-    /** Soft deduplication configuration (W.008) */
-    softDedup: SoftDedupConfig;
-    /** Learning rate schedule configuration (W.009) */
-    lrSchedule: LRSchedulerConfig;
-    /** Core training hyperparameters (W.006, W.007) */
-    hyperparameters: TrainingHyperparameters;
-    /** Pipeline-level settings */
-    pipeline: PipelineSettings;
-}
-/**
- * Core training hyperparameters per W.006 and W.007.
- */
-interface TrainingHyperparameters {
-    /**
-     * Base learning rate.
-     * Per W.006: 2e-4 for SFT (NOT 2e-5).
-     */
-    learningRate: number;
-    /**
-     * Number of training epochs.
-     * Per W.006: 2 epochs (NOT 3). "Loss converges in 1-2 epochs."
-     */
-    epochs: number;
-    /**
-     * Optimizer.
-     * Per W.006: paged_adamw_8bit (NOT adamw_torch).
-     */
-    optimizer: 'paged_adamw_8bit' | 'adamw_torch' | 'adafactor';
-    /**
-     * Micro-batch size per device.
-     * Per W.007: 8-16 for 7B models.
-     */
-    microBatchSize: number;
-    /**
-     * Gradient accumulation steps.
-     * Per W.007: 2-4 steps for effective batch 32-512.
-     */
-    gradientAccumulationSteps: number;
-    /**
-     * Maximum gradient norm for clipping.
-     */
-    maxGradNorm: number;
-    /**
-     * Weight decay coefficient.
-     */
-    weightDecay: number;
-}
-/**
- * Pipeline-level settings controlling the data preparation flow.
- */
-interface PipelineSettings {
-    /**
-     * Whether to apply quality scoring filter before training.
-     * Per W.010: Apply BEFORE deduplication to avoid wasting compute on junk.
-     */
-    enableQualityFilter: boolean;
-    /**
-     * Whether to apply SoftDedup after hard dedup.
-     * Per W.008: Apply AFTER hard dedup (W.004), not instead of it.
-     */
-    enableSoftDedup: boolean;
-    /**
-     * Whether to use the LR scheduler (warmup + cosine decay).
-     * Per W.009: Always use.
-     */
-    enableLRSchedule: boolean;
-    /**
-     * Seed for reproducibility.
-     */
-    seed?: number;
-}
-/**
- * Default training pipeline configuration.
- *
- * Implements the full optimization pipeline:
- * - Quality Filter (W.010) -> Hard Dedup (W.004) -> SoftDedup (W.008)
- * - LR Schedule: warmup 10% + cosine decay (W.009)
- * - Hyperparameters: LR=2e-4, epochs=2, paged_adamw_8bit (W.006)
- * - Batch: micro=8, accumulation=4, effective=32 (W.007)
- */
-declare const DEFAULT_TRAINING_PIPELINE_CONFIG: TrainingPipelineConfig;
-/** Deep partial utility type */
-type DeepPartial<T> = {
-    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
-};
-/**
- * Build a TrainingPipelineConfig with custom overrides.
- *
- * @example
- * ```ts
- * const config = buildTrainingPipelineConfig({
- *   hyperparameters: { learningRate: 1e-4, epochs: 3 },
- *   softDedup: { temperature: 0.5 },
- *   lrSchedule: { totalSteps: 5000 },
- * });
- * ```
- */
-declare function buildTrainingPipelineConfig(overrides?: DeepPartial<TrainingPipelineConfig>): TrainingPipelineConfig;
-/**
- * Compute the total training steps from dataset size and hyperparameters.
- *
- * @param datasetSize - Number of training examples (after dedup)
- * @param config - Training pipeline configuration
- * @returns Total number of training steps
- */
-declare function computeTotalSteps(datasetSize: number, config: TrainingPipelineConfig): number;
-
-/**
- * TrainingMonkey Integration Types
- *
- * Type definitions for integrating HoloScript spatial reasoning training data
- * with the TrainingMonkey fine-tuning pipeline. Converts from the internal
- * SpatialTrainingJSONLEntry format to TrainingMonkey's Alpaca-style format
- * with SoftDedup (W.008) n-gram reweighting and train/validation splits.
- *
- * @module training/trainingmonkey/TrainingMonkeyTypes
- */
-/**
- * Alpaca instruction-following format used by TrainingMonkey.
- *
- * TrainingMonkey's train_v43.py reads:
- *   - example.get("instruction", "")
- *   - example.get("output", "")
- *
- * The optional `input` field provides additional context (e.g., HoloScript scene).
- */
-interface AlpacaEntry {
-    /** The instruction/question for the model */
-    instruction: string;
-    /** Optional additional input context (HoloScript scene source) */
-    input: string;
-    /** The expected output/response from the model */
-    output: string;
-}
-/**
- * Extended Alpaca entry with SoftDedup sampling weight and metadata.
- * Used for weighted sampling during training.
- */
-interface WeightedAlpacaEntry extends AlpacaEntry {
-    /** SoftDedup sampling weight (0.1 to 1.0). Higher = more likely to be sampled */
-    sampling_weight: number;
-    /** Original metadata preserved from the spatial reasoning dataset */
-    metadata?: {
-        id: string;
-        relationship_type: string;
-        is_positive: boolean;
-        difficulty: string;
-        tags: string[];
-    };
-}
-/**
- * Result of splitting a dataset into train/validation sets.
- */
-interface DatasetSplit {
-    /** Training set entries */
-    train: WeightedAlpacaEntry[];
-    /** Validation set entries */
-    validation: WeightedAlpacaEntry[];
-    /** Split statistics */
-    stats: SplitStats;
-}
-/**
- * Statistics about a train/validation split.
- */
-interface SplitStats {
-    /** Total examples before split */
-    totalExamples: number;
-    /** Number of training examples */
-    trainCount: number;
-    /** Number of validation examples */
-    validationCount: number;
-    /** Actual train ratio (trainCount / totalExamples) */
-    trainRatio: number;
-    /** Actual validation ratio (validationCount / totalExamples) */
-    validationRatio: number;
-    /** Whether the split is stratified by difficulty/relationship type */
-    stratified: boolean;
-}
-/**
- * TrainingMonkey-compatible training configuration.
- * Generated alongside the dataset for direct use with train_v43.py.
- */
-interface TrainingMonkeyConfig {
-    /** Model configuration */
-    model: {
-        /** Model identifier (e.g., "qwen7b", "phi35") */
-        name: string;
-        /** Maximum sequence length */
-        maxSeqLength: number;
-    };
-    /** Training hyperparameters (per W.006) */
-    hyperparameters: {
-        /** Learning rate. Per W.006: 2e-4 */
-        learningRate: number;
-        /** Number of epochs. Per W.006: 2 */
-        epochs: number;
-        /** Optimizer. Per W.006: paged_adamw_8bit */
-        optimizer: string;
-        /** Micro-batch size per device. Per W.007: 8-16 */
-        microBatchSize: number;
-        /** Gradient accumulation steps. Per W.007: 2-4 */
-        gradientAccumulationSteps: number;
-        /** Maximum gradient norm for clipping */
-        maxGradNorm: number;
-        /** Weight decay coefficient */
-        weightDecay: number;
-    };
-    /** LR schedule (per W.009) */
-    lrSchedule: {
-        /** Warmup ratio (10% of total steps) */
-        warmupRatio: number;
-        /** Schedule type */
-        type: 'cosine';
-    };
-    /** Dataset paths */
-    dataset: {
-        /** Path to training JSONL */
-        trainPath: string;
-        /** Path to validation JSONL */
-        validationPath: string;
-        /** Number of training examples */
-        trainCount: number;
-        /** Number of validation examples */
-        validationCount: number;
-        /** Total computed training steps */
-        totalSteps: number;
-    };
-    /** SoftDedup statistics */
-    softDedup: {
-        /** Whether SoftDedup was applied */
-        applied: boolean;
-        /** Mean sampling weight */
-        meanWeight: number;
-        /** Effective dataset size after reweighting */
-        effectiveSize: number;
-        /** Reduction ratio */
-        reductionRatio: number;
-    };
-}
-/**
- * Configuration for the TrainingMonkey integration pipeline.
- */
-interface TrainingMonkeyIntegrationConfig {
-    /** Path to the input JSONL file */
-    inputPath: string;
-    /** Directory for output files */
-    outputDir: string;
-    /** Train/validation split ratio (default: 0.9 = 90% train) */
-    trainRatio: number;
-    /** Random seed for reproducible splits */
-    seed: number;
-    /** Whether to apply SoftDedup reweighting (default: true) */
-    enableSoftDedup: boolean;
-    /** Target model name for config generation (default: "qwen7b") */
-    modelName: string;
-    /** Whether to stratify the split by metadata fields (default: true) */
-    stratify: boolean;
-}
-/**
- * Default configuration for TrainingMonkey integration.
- */
-declare const DEFAULT_INTEGRATION_CONFIG: TrainingMonkeyIntegrationConfig;
-/**
- * Complete result of running the TrainingMonkey integration pipeline.
- */
-interface IntegrationResult {
-    /** The dataset split (train/validation) */
-    split: DatasetSplit;
-    /** Generated training configuration */
-    config: TrainingMonkeyConfig;
-    /** Serialized train JSONL content */
-    trainJsonl: string;
-    /** Serialized validation JSONL content */
-    validationJsonl: string;
-    /** Serialized config JSON content */
-    configJson: string;
-}
-
-/**
- * TrainingMonkey Integration Module
- *
- * Converts HoloScript spatial reasoning JSONL training data into
- * TrainingMonkey's Alpaca format with:
- *   1. JSONL reading and parsing
- *   2. Alpaca format conversion (instruction/input/output)
- *   3. SoftDedup (W.008) n-gram reweighting for sampling
- *   4. Stratified train/validation splits (90/10)
- *   5. TrainingMonkey-compatible training config (W.006 hyperparameters)
- *   6. Ready-to-upload output file generation
- *
- * @module training/trainingmonkey/TrainingMonkeyIntegration
- */
-
-/**
- * Integrates HoloScript spatial reasoning data with TrainingMonkey.
- *
- * Full pipeline:
- *   readJsonl() -> convertToAlpaca() -> applySoftDedup() -> splitDataset() -> generateConfig()
- *
- * @example
- * ```ts
- * const integration = new TrainingMonkeyIntegration({
- *   inputPath: 'spatial-reasoning-10k.jsonl',
- *   outputDir: './output',
- * });
- *
- * const jsonlContent = fs.readFileSync('spatial-reasoning-10k.jsonl', 'utf-8');
- * const result = integration.process(jsonlContent);
- *
- * fs.writeFileSync('alpaca-train.jsonl', result.trainJsonl);
- * fs.writeFileSync('alpaca-val.jsonl', result.validationJsonl);
- * fs.writeFileSync('training-config.json', result.configJson);
- * ```
- */
-declare class TrainingMonkeyIntegration {
-    private config;
-    private softDedup;
-    constructor(config?: Partial<TrainingMonkeyIntegrationConfig>);
-    /**
-     * Run the full integration pipeline on raw JSONL content.
-     *
-     * @param jsonlContent - Raw JSONL string content from the dataset file
-     * @returns Complete IntegrationResult with split data, config, and serialized output
-     */
-    process(jsonlContent: string): IntegrationResult;
-    /**
-     * Parse raw JSONL content into SpatialTrainingJSONLEntry objects.
-     *
-     * @param jsonlContent - Raw JSONL string (one JSON object per line)
-     * @returns Array of parsed entries
-     * @throws Error if a line contains invalid JSON
-     */
-    readJsonl(jsonlContent: string): SpatialTrainingJSONLEntry[];
-    /**
-     * Convert spatial training entries to Alpaca format.
-     *
-     * Mapping:
-     *   instruction -> instruction (question/prompt)
-     *   input -> extracted HoloScript scene from instruction (if present)
-     *   output -> response (answer)
-     *
-     * @param entries - Parsed spatial training entries
-     * @returns Alpaca-formatted entries
-     */
-    convertToAlpaca(entries: SpatialTrainingJSONLEntry[]): AlpacaEntry[];
-    /**
-     * Apply SoftDedup (W.008) n-gram reweighting to Alpaca entries.
-     *
-     * Uses the instruction + output text to compute n-gram commonness scores
-     * and assigns sampling weights. Template-generated near-duplicates receive
-     * lower weights (min 0.1), while unique examples keep weight 1.0.
-     *
-     * @param alpacaEntries - Converted Alpaca entries
-     * @param originalEntries - Original JSONL entries (for metadata preservation)
-     * @returns Weighted Alpaca entries with sampling_weight and metadata
-     */
-    applySoftDedup(alpacaEntries: AlpacaEntry[], originalEntries: SpatialTrainingJSONLEntry[]): WeightedAlpacaEntry[];
-    /**
-     * Split weighted entries into train/validation sets.
-     *
-     * When stratified=true, the split preserves the distribution of
-     * relationship_type and difficulty across both sets.
-     *
-     * @param entries - Weighted Alpaca entries
-     * @returns DatasetSplit with train, validation, and stats
-     */
-    splitDataset(entries: WeightedAlpacaEntry[]): DatasetSplit;
-    /**
-     * Generate a TrainingMonkey-compatible training configuration.
-     *
-     * Uses W.006 hyperparameters:
-     *   - Learning rate: 2e-4
-     *   - Epochs: 2
-     *   - Optimizer: paged_adamw_8bit
-     *
-     * Uses W.007 batch sizing:
-     *   - Micro-batch: 8
-     *   - Gradient accumulation: 4
-     *   - Effective batch: 32
-     *
-     * Uses W.009 LR schedule:
-     *   - Warmup: 10% of total steps
-     *   - Schedule: cosine decay
-     *
-     * @param split - The dataset split result
-     * @returns TrainingMonkey-compatible config
-     */
-    generateConfig(split: DatasetSplit): TrainingMonkeyConfig;
-    /**
-     * Serialize weighted Alpaca entries to JSONL string.
-     *
-     * @param entries - Entries to serialize
-     * @returns JSONL string (one JSON object per line)
-     */
-    serializeJsonl(entries: WeightedAlpacaEntry[]): string;
-    /**
-     * Get the current integration configuration.
-     */
-    getConfig(): Readonly<TrainingMonkeyIntegrationConfig>;
-    /**
-     * Extract the question part and HoloScript scene from an instruction string.
-     *
-     * The spatial reasoning dataset embeds HoloScript scenes in instructions:
-     * ```
-     * Does the spatial_adjacent constraint pass?
-     *
-     * HoloScript Scene:
-     * ```holoscript
-     * composition "SpatialScene" { ... }
-     * ```
-     * ```
-     *
-     * This method splits the instruction into the question (instruction field)
-     * and the scene source (input field) for the Alpaca format.
-     */
-    private extractSceneFromInstruction;
-    /**
-     * Perform a stratified split preserving distribution of metadata fields.
-     * Groups by relationship_type + difficulty and splits each group proportionally.
-     */
-    private stratifiedSplit;
-    /**
-     * Perform a simple random split.
-     */
-    private randomSplit;
-    /**
-     * Fisher-Yates shuffle with seeded PRNG for deterministic ordering.
-     */
-    private fisherYatesShuffle;
-}
-/**
- * Create a TrainingMonkeyIntegration instance with optional config overrides.
- *
- * @example
- * ```ts
- * const integration = createTrainingMonkeyIntegration({
- *   inputPath: 'spatial-reasoning-10k.jsonl',
- *   outputDir: './output',
- *   trainRatio: 0.9,
- * });
- *
- * const result = integration.process(jsonlContent);
- * ```
- */
-declare function createTrainingMonkeyIntegration(config?: Partial<TrainingMonkeyIntegrationConfig>): TrainingMonkeyIntegration;
-
-/**
- * Training Constants
- *
- * Canonical constants shared between @holoscript/core and TrainingMonkey.
- * This module has ZERO imports from other workspace packages (G.GAP.01 prevention).
- *
- * @version 1.0.0
- */
-/**
- * 9 training categories covering all HoloScript domains
- */
-declare const TRAINING_CATEGORIES: readonly ["vr-interaction", "multiplayer", "physics", "ui-spatial", "ai-agents", "procedural", "audio-spatial", "visual-effects", "game-mechanics"];
-type TrainingCategory = (typeof TRAINING_CATEGORIES)[number];
-/**
- * 4 difficulty levels for training data
- */
-declare const DIFFICULTY_LEVELS: readonly ["beginner", "intermediate", "advanced", "production"];
-type DifficultyLevel = (typeof DIFFICULTY_LEVELS)[number];
-/**
- * Quality score thresholds for training data evaluation
- */
-declare const QUALITY_THRESHOLDS: {
-    readonly Excellent: {
-        readonly min: 90;
-        readonly max: 100;
-    };
-    readonly VeryGood: {
-        readonly min: 80;
-        readonly max: 89;
-    };
-    readonly Acceptable: {
-        readonly min: 70;
-        readonly max: 79;
-    };
-};
-type QualityTier = keyof typeof QUALITY_THRESHOLDS;
-/**
- * Default quality constraints for training data generators
- */
-declare const DEFAULT_GENERATOR_THRESHOLDS: {
-    readonly min_compression_ratio: 5;
-    readonly max_compression_ratio: 15;
-    readonly max_duplication_rate: 0.05;
-    readonly min_templates_per_difficulty: 10;
-    readonly min_quality_score: 0.7;
-};
-/**
- * RuleForge domain categories used by the rule generator
- */
-declare const RULEFORGE_DOMAINS: readonly ["ai_agents", "physics", "robotics", "audio", "rendering", "interaction", "multiplayer", "vr_ar"];
-type RuleForgeDomain = (typeof RULEFORGE_DOMAINS)[number];
-/**
- * Get quality tier for a given score
- */
-declare function getQualityTier(score: number): QualityTier | 'BelowAcceptable';
-/**
- * Validate that a category string is a valid TrainingCategory
- */
-declare function isValidCategory(category: string): category is TrainingCategory;
-/**
- * Validate that a difficulty string is a valid DifficultyLevel
- */
-declare function isValidDifficulty(difficulty: string): difficulty is DifficultyLevel;
-
-/**
- * Training Data Schema
- *
- * Canonical schema for training examples used across TM and HS.
- * Imports only from local constants.ts (G.GAP.01 prevention).
- *
- * @version 1.0.0
- */
-
-/**
- * A single training example in instruction/input/output format (JSONL-compatible)
- */
-interface TrainingExample {
-    instruction: string;
-    input: string;
-    output: string;
-    metadata: TrainingExampleMetadata;
-}
-/**
- * Metadata for a training example
- */
-interface TrainingExampleMetadata {
-    category: TrainingCategory;
-    difficulty: DifficultyLevel;
-    traits: string[];
-    keywords: string[];
-    version: string;
-    behavior_template?: string;
-    quality_score?: number;
-}
-/**
- * Quality scoring rubric for training examples (TM-compatible format)
- */
-interface TrainingQualityScore {
-    helpfulness: number;
-    correctness: number;
-    coherence: number;
-    complexity: number;
-    verbosity: number;
-    overall: number;
-}
-/**
- * Validation result for a training example
- */
-interface TrainingValidationResult {
-    valid: boolean;
-    errors: TrainingValidationError[];
-    warnings: string[];
-}
-interface TrainingValidationError {
-    field: string;
-    message: string;
-    severity: 'error' | 'warning' | 'info';
-}
-/**
- * Compression metrics for a training dataset
- */
-interface CompressionResult {
-    passed: boolean;
-    ratio: number;
-    total_examples: number;
-    unique_patterns: number;
-    quality_score?: number;
-    issue?: string;
-    recommendation?: string;
-}
-/**
- * Generator metrics for auditing training data quality
- */
-interface GeneratorMetrics {
-    file_size_bytes: number;
-    total_examples: number;
-    unique_patterns: number;
-    compression_ratio: number;
-    duplication_rate: number;
-    avg_quality_score: number;
-    generation_time_ms: number;
-}
-/**
- * Validate a training example against the schema
- */
-declare function validateTrainingExample(example: unknown): TrainingValidationResult;
-
-/**
- * Trait Mappings
- *
- * Maps TrainingMonkey trait names to canonical @holoscript/core trait IDs.
- * Provides validation utilities to check trait coverage.
- *
- * @version 1.0.0
- */
-
-/**
- * Training metadata that extends a trait definition
- */
-interface TrainingMetadata {
-    difficulty: 'beginner' | 'intermediate' | 'advanced' | 'production';
-    categories: TrainingCategory[];
-    exampleCount: number;
-    qualityScore: number;
-}
-/**
- * Mapping entry from TM trait to HS canonical trait
- */
-interface TraitMapping {
-    /** TrainingMonkey trait name */
-    tmName: string;
-    /** Canonical HoloScript trait name (null if unmapped) */
-    hsName: string | null;
-    /** Status of the mapping */
-    status: 'matched' | 'unmatched' | 'deprecated' | 'promoted';
-    /** Training metadata (populated from TM datasets) */
-    training?: TrainingMetadata;
-}
-/**
- * Result of a trait validation run
- */
-interface TraitValidationReport {
-    matched: number;
-    unmatched: number;
-    deprecated: number;
-    total: number;
-    details: TraitMapping[];
-}
-/**
- * Known TM traits from holoscript-trait-registry.ts (46 = 41 traits + 5 physics patterns)
- * These are the traits explicitly registered in TrainingMonkey.
- */
-declare const TM_REGISTERED_TRAITS: readonly ["llm_agent", "behavior_tree", "goal_oriented", "neural_link", "neural_forge", "spatial_awareness", "shared_world", "eye_tracked", "hand_tracking", "vision", "spatial_persona", "shareplay", "object_tracking", "scene_reconstruction", "realitykit_mesh", "room_mesh", "volumetric_window", "spatial_navigation", "stable_diffusion", "controlnet", "ai_texture_gen", "diffusion_realtime", "ai_inpainting", "ai_upscaling", "networked", "render_network", "openxr_hal", "hitl", "zora_coins", "neural_upscaling", "grabbable", "throwable", "pointable", "drawable", "attachable", "socket", "billboard", "ui_panel", "hud", "glowing", "physics", "persistent", "tool", "conversion_tracking", "impact_physics", "fragment_conversion", "damage_falloff", "cross_system_integration"];
-/**
- * Validate a trait name against a set of valid traits.
- * Returns the canonical name if found, null otherwise.
- */
-declare function validateTraitName(traitName: string, validTraits: ReadonlySet<string> | readonly string[]): string | null;
-/**
- * Generate a validation report comparing TM traits against HS registry.
- * @param tmTraits - Trait names from TrainingMonkey
- * @param hsTraits - Valid trait names from HoloScript core
- * @param deprecatedTraits - Set of deprecated trait names
- */
-declare function generateValidationReport(tmTraits: readonly string[], hsTraits: ReadonlySet<string> | readonly string[], deprecatedTraits?: ReadonlySet<string>): TraitValidationReport;
-
-export { type AlpacaEntry, DEFAULT_GENERATOR_THRESHOLDS, DEFAULT_INTEGRATION_CONFIG, DEFAULT_LR_SCHEDULER_CONFIG, DEFAULT_SCORING_CONFIG, DEFAULT_SOFTDEDUP_CONFIG, DEFAULT_TRAINING_PIPELINE_CONFIG, DIFFICULTY_LEVELS, type DatasetSplit, type DifficultyLevel, type EnergyEfficiencyMetrics, GRPO_LR_SCHEDULER_CONFIG, type GeneratorMetrics, type IntegrationResult, type LRScheduleStats, LRScheduler, type LRSchedulerConfig, type LRSchedulerSnapshot, type LayerActivityInput, type NgramStats, type PipelineSettings, QUALITY_THRESHOLDS, type QualityDetail, type QualityScore, type QualityScoringConfig, QualityScoringPipeline, type QualityTier, RULEFORGE_DOMAINS, type RuleForgeDomain, type SNNLayerMetrics, type SceneObject, SoftDedup, type SoftDedupConfig, type SoftDedupResult, type SoftDedupStats, SparsityMonitor, type SparsityMonitorConfig, type SparsityMonitorStats, type SparsityQualityHistoryEntry, type SparsitySnapshot, type SparsityViolation, type SpatialDifficulty, type SpatialGeneratorConfig, type SpatialGeneratorStats, type SpatialRelationship, type SpatialRelationshipParams, type SpatialRelationshipType, type SpatialScene, SpatialTrainingDataGenerator, type SpatialTrainingExample, type SpatialTrainingJSONLEntry, type SplitStats, TM_REGISTERED_TRAITS, TRAINING_CATEGORIES, type TrainingCategory, type CompressionResult as TrainingCompressionResult, type TrainingExample, type TrainingExampleMetadata, type TrainingHyperparameters, type TrainingMetadata, type TrainingMonkeyConfig, TrainingMonkeyIntegration, type TrainingMonkeyIntegrationConfig, type TrainingPipelineConfig, type TrainingQualityScore, type TrainingValidationError, type TrainingValidationResult, type TraitMapping, type TraitValidationReport, type WeightedAlpacaEntry, buildTrainingPipelineConfig, computeTotalSteps, createGRPOScheduler, createSFTScheduler, createSoftDedup, createSparsityMonitor, createSpatialTrainingDataGenerator, createTrainingMonkeyIntegration, generateValidationReport, getQualityTier, isValidCategory, isValidDifficulty, validateTrainingExample, validateTraitName };