dexbot 1.4.16 → 1.4.17

package/analysis/ama_fitting/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "ama_fitting",
+  "version": "1.4.17",
+  "description": "Tools for fitting AMA parameters to market data",
+  "main": "../../dist/analysis/ama_fitting/optimizer_high_resolution.js",
+  "scripts": {
+    "optimize": "npm --prefix ../.. run build && node ../../dist/analysis/ama_fitting/optimizer_high_resolution.js",
+    "chart:lp-local": "npm --prefix ../.. run build && node ../../dist/analysis/ama_fitting/generate_unified_comparison_chart.js"
+  },
+  "dependencies": {},
+  "type": "module"
+}

package/analysis/analyze_derivatives.ts

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+
+/**
+ * DERIVATIVE TREND ANALYSIS
+ *
+ * Runs DerivativeAnalyzer over candle data and generates an interactive HTML chart.
+ * Trend is detected from SMA, MACD, and RSI only.
+ *
+ * Usage:
+ *   tsx analysis/analyze_derivatives.ts \\
+ *     --source json \
+ *     --file market_adapter/data/lp/<path>/<to>/<lp-candles>.json
+ *
+ *   tsx analysis/analyze_derivatives.ts \\
+ *     --source market_adapter \
+ *     --bot-key XRP-BTS
+ *
+ * Output:
+ *   analysis/charts/derivative_chart.html
+ */
+
+
+import { pathToFileURL } from 'node:url';
+import { DerivativeAnalyzer } from './trend_detection/derivative_analyzer.js';
+import { generateHTML } from './derivative_chart_generator.js';
+import { writeChartFile } from './chart_utils.js';
+import { resolveSource, listAvailableBots, type SourceConfig } from './resolve_source.js';
+'use strict';
+
+
+interface CliConfig {
+    source: { type: string; config: SourceConfig };
+    slowSmaPeriod: number;
+    fastSmaPeriod: number | undefined;
+    minBarsForConfirmation: number;
+    macdFastPeriod: number;
+    macdSlowPeriod: number;
+    macdSignalPeriod: number;
+    macdMinHist: number;
+    trendFilter: boolean;
+    trendFilterMinBars: number;
+    momentumGateEnabled: boolean;
+    momentumGateMinBars: number;
+    momentumGateRsiZone: number;
+    fastSmaCommitmentBars: number;
+    priceRegimeGate: boolean;
+    priceRegimeMinDistancePct: number;
+    rsiPeriod: number;
+    interpConfirmBars: number;
+    interpHoldBars: number;
+    rsiZone: number;
+    rsiExtreme: number;
+    chartFile: string;
+    quiet: boolean;
+    listBots: boolean;
+}
+
+interface PriceSource {
+    name: string;
+    fetchCandles(): Promise<any[]>;
+    extractMarketPrice(candle: any): { marketPrice: any; timestamp: any };
+}
+
+function parseArgs(): CliConfig {
+    const args = process.argv.slice(2);
+    const config: CliConfig = {
+        source: { type: 'market_adapter', config: { botKey: '' } },
+        slowSmaPeriod:        500,
+        fastSmaPeriod:        undefined,
+        minBarsForConfirmation: 3,
+        macdFastPeriod: 12,
+        macdSlowPeriod: 26,
+        macdSignalPeriod: 9,
+        macdMinHist: 0.02,
+        trendFilter: false,
+        trendFilterMinBars: 3,
+        momentumGateEnabled: false,
+        momentumGateMinBars: 3,
+        momentumGateRsiZone: 35,
+        fastSmaCommitmentBars: 2,
+        priceRegimeGate: true,
+        priceRegimeMinDistancePct: 0.35,
+        rsiPeriod: 14,
+        interpConfirmBars: 3,
+        interpHoldBars: 3,
+        rsiZone: 10,
+        rsiExtreme: 90,
+        chartFile: 'analysis/charts/derivative_chart.html',
+        quiet: false,
+        listBots: false,
+    };
+
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if      (arg === '--source')    config.source.type                  = args[++i];
+        else if (arg === '--bot-key')   config.source.config.botKey         = args[++i];
+        else if (arg === '--file')      { config.source.config.filePath = args[++i]; config.source.type = 'json'; }
+        else if (arg === '--sma')       config.slowSmaPeriod                = parseInt(args[++i]);
+        else if (arg === '--fast-sma')  config.fastSmaPeriod                = parseInt(args[++i]);
+        else if (arg === '--confirm')   config.minBarsForConfirmation       = parseInt(args[++i]);
+        else if (arg === '--macd-fast')  { config.macdFastPeriod            = parseInt(args[++i]); }
+        else if (arg === '--macd-slow')  { config.macdSlowPeriod            = parseInt(args[++i]); }
+        else if (arg === '--macd-signal'){ config.macdSignalPeriod          = parseInt(args[++i]); }
+        else if (arg === '--macd-min-hist') { config.macdMinHist            = parseFloat(args[++i]); }
+        else if (arg === '--rsi')          { const v = parseInt(args[i + 1]); if (!isNaN(v)) { config.rsiPeriod = v; i++; } }
+        else if (arg === '--interp-confirm') config.interpConfirmBars        = parseInt(args[++i]);
+        else if (arg === '--interp-hold')    config.interpHoldBars           = parseInt(args[++i]);
+        else if (arg === '--rsi-zone')       config.rsiZone                  = parseFloat(args[++i]);
+        else if (arg === '--rsi-extreme')    config.rsiExtreme               = parseFloat(args[++i]);
+        else if (arg === '--trend-filter')          config.trendFilter          = true;
+        else if (arg === '--trend-filter-min-bars') config.trendFilterMinBars  = parseInt(args[++i]);
+        else if (arg === '--momentum-gate')         config.momentumGateEnabled  = true;
+        else if (arg === '--momentum-gate-bars')    config.momentumGateMinBars  = parseInt(args[++i]);
+        else if (arg === '--momentum-gate-rsi-zone') config.momentumGateRsiZone = parseFloat(args[++i]);
+        else if (arg === '--fast-sma-commitment-bars') config.fastSmaCommitmentBars = parseInt(args[++i]);
+        else if (arg === '--no-price-regime-gate')  config.priceRegimeGate      = false;
+        else if (arg === '--price-regime-buffer-pct') config.priceRegimeMinDistancePct = parseFloat(args[++i]);
+        else if (arg === '--chart')       config.chartFile                  = args[++i];
+        else if (arg === '--list-bots')  config.listBots                   = true;
+        else if (arg === '--quiet')     config.quiet                        = true;
+        else if (arg === '--help' || arg === '-h') { showHelp(); process.exit(0); }
+    }
+
+    return config;
+}
+
+function showHelp() {
+    console.log(`
+Derivative Trend Analysis
+
+Analyzes candle data using SMA, MACD, and RSI as trend signals.
+Generates an interactive HTML chart.
+
+Usage:
+  tsx analysis/analyze_derivatives.ts \\
+    --source <type> \\
+    [--bot-key KEY] [--file PATH]
+
+Sources:
+  market_adapter   Use market_adapter state (default)   --bot-key KEY
+  json             JSON candles file                    --file path/to/file.json
+
+Analyzer options:
+  Core indicators:
+    --sma N        SMA period (default 500)
+    --fast-sma N   Fast SMA period (optional, enables trend filter source + fast-SMA commitment)
+    --macd-fast N  MACD fast period (default 12)
+    --macd-slow N  MACD slow period (default 26)
+    --macd-signal N  MACD signal period (default 9)
+    --macd-min-hist N  MACD histogram/line threshold (default 0.02)
+    --rsi [N]      RSI period (default 14)
+    --rsi-zone N   RSI bull/bear zone offset from 50 (default 10)
+    --rsi-extreme N  RSI extreme threshold (default 90)
+
+  Confirmation and hysteresis:
+    --confirm N    Bars required for confirmation (default 3)
+    --interp-confirm N  Bars required to confirm BULL/BEAR (default 3)
+    --interp-hold N  Bars to hold confirmed BULL/BEAR downgrades (default 3)
+
+  Trend filters and gates:
+    --trend-filter  Enable derivative trend filter
+    --trend-filter-min-bars N  Sustained bars for trend filter (default 3)
+    --momentum-gate  Enable MACD+RSI recovery gate
+    --momentum-gate-bars N  Momentum gate persistence (default 3)
+    --momentum-gate-rsi-zone N  RSI divergence threshold (default 35)
+    --fast-sma-commitment-bars N  Consecutive bars price must stay beyond fastSMA (default 2)
+    --no-price-regime-gate  Disable slow-SMA macro regime gate
+    --price-regime-buffer-pct N  Required slow-SMA clearance in % (default 0.35)
+
+  Source input:
+    --source <type>  Data source (default market_adapter)
+    --bot-key KEY    Market adapter bot key (required)
+    --file PATH      JSON candle input
+
+  Output:
+    --chart FILE   Chart output path (default: analysis/charts/derivative_chart.html)
+    --list-bots    List available bot keys from bots.json
+    --quiet        Suppress log output
+    `);
+}
+
+async function analyze(source: PriceSource, config: CliConfig): Promise<{
+    config: {
+        source: string;
+        slowSmaPeriod: number;
+        fastSmaPeriod: number | undefined;
+        macdFastPeriod: number;
+        macdSlowPeriod: number;
+        macdSignalPeriod: number;
+        macdMinHist: number;
+        trendFilter: boolean;
+        trendFilterMinBars: number;
+        momentumGateEnabled: boolean;
+        momentumGateMinBars: number;
+        momentumGateRsiZone: number;
+        fastSmaCommitmentBars: number;
+        priceRegimeGate: boolean;
+        priceRegimeMinDistancePct: number;
+        rsiPeriod: number;
+        interpConfirmBars: number;
+        interpHoldBars: number;
+        rsiZone: number;
+        rsiExtreme: number;
+        minBarsForConfirmation: number;
+    };
+    allResults: any[];
+    lastAnalysis: any;
+}> {
+    if (!config.quiet) console.log(`[Derivatives] Loading candles from ${source.name}...`);
+
+    const candles = await source.fetchCandles();
+    if (!Array.isArray(candles) || candles.length === 0) {
+        throw new Error('No candles returned from source');
+    }
+    if (!config.quiet) console.log(`[Derivatives] Loaded ${candles.length} candles`);
+
+    const analyzer = new DerivativeAnalyzer({
+        slowSmaPeriod:          config.slowSmaPeriod,
+        fastSmaPeriod:          config.fastSmaPeriod,
+        macdFastPeriod:         config.macdFastPeriod,
+        macdSlowPeriod:         config.macdSlowPeriod,
+        macdSignalPeriod:       config.macdSignalPeriod,
+        macdMinHist:            config.macdMinHist,
+        trendFilterEnabled:     config.trendFilter,
+        trendFilterMinBars:     config.trendFilterMinBars,
+        momentumGateEnabled:    config.momentumGateEnabled,
+        momentumGateMinBars:    config.momentumGateMinBars,
+        momentumGateRsiZone:    config.momentumGateRsiZone,
+        fastSmaCommitmentBars:  config.fastSmaCommitmentBars,
+        priceRegimeGateEnabled: config.priceRegimeGate,
+        priceRegimeMinDistancePct: config.priceRegimeMinDistancePct,
+        rsiPeriod:              config.rsiPeriod,
+        interpConfirmBars:      config.interpConfirmBars,
+        interpHoldBars:         config.interpHoldBars,
+        rsiBullThreshold:       50 + config.rsiZone,
+        rsiBearThreshold:       50 - config.rsiZone,
+        rsiOverboughtLevel:     config.rsiExtreme,
+        rsiOversoldLevel:       100 - config.rsiExtreme,
+        minBarsForConfirmation: config.minBarsForConfirmation,
+    });
+
+    const allResults: any[] = [];
+    for (let i = 0; i < candles.length; i++) {
+        const { marketPrice, timestamp } = source.extractMarketPrice(candles[i]);
+        try {
+            allResults.push(analyzer.update(marketPrice, timestamp));
+        } catch (err: unknown) {
+            throw new Error(`Failed at candle ${i}: ${(err as any)?.message ?? err}`);
+        }
+    }
+
+    const last = allResults[allResults.length - 1];
+    if (!config.quiet) {
+        const parts: string[] = [];
+        if (config.slowSmaPeriod)    parts.push(`SMA(${config.slowSmaPeriod}): ${last.smaRawTrend} (${last.smaBarsInTrend} bars)`);
+        if (config.fastSmaPeriod)    parts.push(`fastSMA(${config.fastSmaPeriod}): ${last.fastSmaRawTrend} (${last.fastSmaBarsInTrend} bars)`);
+        parts.push(`MACD: ${last.macdTrend} hist=${last.macdHistogram}`);
+        parts.push(`RSI(${config.rsiPeriod}): ${last.rsi !== null ? last.rsi.toFixed(1) : 'n/a'} [${last.rsiZone}]`);
+        console.log(`[Derivatives] Done — ${last.isReady ? '' : '(warming up) '}${parts.join('  ')}`);
+    }
+
+    return {
+        config: {
+            source:              source.name,
+            slowSmaPeriod:       config.slowSmaPeriod,
+            fastSmaPeriod:       config.fastSmaPeriod,
+            macdFastPeriod:      config.macdFastPeriod,
+            macdSlowPeriod:      config.macdSlowPeriod,
+            macdSignalPeriod:    config.macdSignalPeriod,
+            macdMinHist:         config.macdMinHist,
+            trendFilter:         config.trendFilter,
+            trendFilterMinBars:  config.trendFilterMinBars,
+            momentumGateEnabled: config.momentumGateEnabled,
+            momentumGateMinBars: config.momentumGateMinBars,
+            momentumGateRsiZone: config.momentumGateRsiZone,
+            fastSmaCommitmentBars: config.fastSmaCommitmentBars,
+            priceRegimeGate:     config.priceRegimeGate,
+            priceRegimeMinDistancePct: config.priceRegimeMinDistancePct,
+            rsiPeriod:           config.rsiPeriod,
+            interpConfirmBars:   config.interpConfirmBars,
+            interpHoldBars:      config.interpHoldBars,
+            rsiZone:             config.rsiZone,
+            rsiExtreme:          config.rsiExtreme,
+            minBarsForConfirmation: config.minBarsForConfirmation,
+        },
+        allResults,
+        lastAnalysis: last,
+    };
+}
+
+async function main(): Promise<void> {
+    const config = parseArgs();
+
+    try {
+        if (config.listBots) {
+            listAvailableBots();
+            return;
+        }
+
+        const { source } = resolveSource({ ...config.source.config, type: config.source.type }, { quiet: config.quiet });
+        const report = await analyze(source, config);
+
+        const html = generateHTML(report, 'Derivative Trend Analysis');
+        writeChartFile(config.chartFile, html);
+
+        if (!config.quiet) console.log(`[Derivatives] ✓ Chart saved to ${config.chartFile}`);
+    } catch (err: unknown) {
+        console.error(`[Derivatives] Error: ${(err as any)?.message ?? err}`);
+        process.exit(1);
+    }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    main().catch((err: unknown) => { console.error(err); process.exit(1); });
+}
+
+export { analyze }
+

package/analysis/analyze_dynamic_weight.ts

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+
+/**
+ * DYNAMIC WEIGHT RESEARCH TOOL
+ *
+ * Computes AMA slope + Kalman + Hurst + PE signals and generates an
+ * interactive HTML chart for researching dynamic weight parameters.
+ *
+ * Usage:
+ *   tsx analysis/analyze_dynamic_weight.ts \
+ *     --source json \
+ *     --file market_adapter/data/lp/<path>/<to>/<lp-candles>.json
+ */
+
+import { KalmanTrendAnalyzer } from './trend_detection/kalman_trend_analyzer.js';
+import { HurstAnalyzer } from './trend_detection/hurst_analyzer.js';
+import { PermutationEntropyAnalyzer } from './trend_detection/permutation_entropy_analyzer.js';
+import { generateHTML } from './trend_detection/dynamic_weight_chart_generator.js';
+import { calculateAMA } from '../market_adapter/core/strategies/ama.js';
+import { computeAmaSlopeWeights } from '../market_adapter/core/strategies/ama_slope_model.js';
+import { MARKET_ADAPTER } from '../modules/constants.js';
+import { writeChartFile } from './chart_utils.js';
+import { getCandleClose } from './math_utils.js';
+import { resolveSource, listAvailableBots, type SourceConfig } from './resolve_source.js';
+
+'use strict';
+
+// AMA Slope weight calculation config — use DEFAULTS from market adapter
+const AMA_WEIGHT_CONFIG = {
+    lookbackBars:           MARKET_ADAPTER.DYNAMIC_WEIGHT_AMA_LOOKBACK_BARS,
+    amaMaxSlopePct:         MARKET_ADAPTER.DYNAMIC_WEIGHT_AMA_MAX_SLOPE_PCT,
+    kalmanMaxSlopePct:      MARKET_ADAPTER.DYNAMIC_WEIGHT_KALMAN_MAX_SLOPE_PCT,
+    neutralZonePct:         MARKET_ADAPTER.DYNAMIC_WEIGHT_AMA_NEUTRAL_ZONE_PCT,
+    volatilityExponent:     MARKET_ADAPTER.DYNAMIC_WEIGHT_VOLATILITY_EXPONENT,
+    volatilityScaleX:       MARKET_ADAPTER.DYNAMIC_WEIGHT_VOLATILITY_SCALE_X_DEFAULT,
+    volatilityThreshold:    MARKET_ADAPTER.DYNAMIC_WEIGHT_SYMMETRIC_SHIFT_THRESHOLD,
+    maxSlopeOffset:         MARKET_ADAPTER.DYNAMIC_WEIGHT_ASYMMETRIC_OFFSET_CLAMP,
+    maxVolatilityOffset:    MARKET_ADAPTER.DYNAMIC_WEIGHT_SYMMETRIC_SHIFT_CLAMP,
+};
+
+// Kalman configuration
+const KALMAN_CONFIG = {
+    rNoise: MARKET_ADAPTER.DYNAMIC_WEIGHT_KALMAN_R_NOISE_DEFAULT,
+    qTactical: MARKET_ADAPTER.DYNAMIC_WEIGHT_KALMAN_Q_TACTICAL_DEFAULT,
+    qModal: MARKET_ADAPTER.DYNAMIC_WEIGHT_KALMAN_Q_MODAL_DEFAULT,
+};
+
+// Regime analyzers configuration (Hurst + Permutation Entropy)
+const { HURST_CONFIG, PE_CONFIG } = MARKET_ADAPTER;
+
+
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const config: {
+        source: { type: string; config: SourceConfig };
+        chartFile: string;
+        alpha: any;
+        gain: any;
+        dispWeight: any;
+        clipPct: any;
+        quiet: boolean;
+        listBots: boolean;
+        lookbackBars?: number;
+        dispScaleMinPct?: number;
+    } = {
+        source: { type: 'market_adapter', config: { botKey: '' } },
+        chartFile: 'analysis/charts/dynamic_weight_chart.html',
+        alpha: MARKET_ADAPTER.DYNAMIC_WEIGHT_ALPHA,
+        gain: MARKET_ADAPTER.DYNAMIC_WEIGHT_GAIN,
+        dispWeight: MARKET_ADAPTER.DYNAMIC_WEIGHT_DW,
+        clipPct: MARKET_ADAPTER.DYNAMIC_WEIGHT_CLIP_PERCENTILE,
+        quiet: false,
+        listBots: false,
+    };
+
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--source') config.source.type = args[++i];
+        else if (arg === '--bot-key') config.source.config.botKey = args[++i];
+        else if (arg === '--file') {
+            config.source.config.filePath = args[++i];
+            config.source.type = 'json';
+        }
+        else if (arg === '--chart') config.chartFile = args[++i];
+        else if (arg === '--alpha') config.alpha = parseFloat(args[++i]);
+        else if (arg === '--gain') config.gain = parseFloat(args[++i]);
+        else if (arg === '--dw') config.dispWeight = parseFloat(args[++i]);
+        else if (arg === '--lb') config.lookbackBars = parseInt(args[++i], 10);
+        else if (arg === '--clip') config.clipPct = parseFloat(args[++i]);
+        else if (arg === '--list-bots') config.listBots = true;
+        else if (arg === '--quiet') config.quiet = true;
+    }
+
+    return config;
+}
+
+async function main() {
+    try {
+        const config = parseArgs();
+
+        if (config.listBots) {
+            listAvailableBots();
+            return;
+        }
+
+        const { source, amaConfig, amaKey } = resolveSource({ ...config.source.config, type: config.source.type }, { quiet: config.quiet });
+
+        const AMA_CONFIG = amaConfig;
+        if (!config.quiet) console.log(`[DynamicWeight] Loading candles from ${source.name}...`);
+
+        const candles = await source.fetchCandles();
+        if (!Array.isArray(candles) || candles.length === 0) {
+            throw new Error('No candles returned from source');
+        }
+
+        // ── Kalman analysis ──────────────────────────────────────────────────
+        const analyzer = new KalmanTrendAnalyzer({
+            rNoise: KALMAN_CONFIG.rNoise,
+            qTactical: KALMAN_CONFIG.qTactical,
+            qModal: KALMAN_CONFIG.qModal,
+        });
+
+        // ── Hurst & PE analyzers ──────────────────────────────────────────────
+        const hurstAnalyzer = new HurstAnalyzer({
+            window: HURST_CONFIG.window,
+            scales: HURST_CONFIG.scales,
+        });
+        const peAnalyzer = new PermutationEntropyAnalyzer({
+            m:      PE_CONFIG.m,
+            delay:  PE_CONFIG.delay,
+            window: PE_CONFIG.window,
+        });
+
+        const allResults: any[] = [];
+        for (let i = 0; i < candles.length; i++) {
+            const { marketPrice, timestamp } = source.extractMarketPrice(candles[i]);
+            const result = analyzer.update(marketPrice);
+            const hurst = hurstAnalyzer.update(marketPrice);
+            const pe    = peAnalyzer.update(marketPrice);
+            result.timestamp = timestamp;
+            result.price = marketPrice;
+            (result as any).hurst = hurst.isReady ? (hurst as any).hurst : null;
+            (result as any).pe    = pe.isReady    ? (pe as any).normalizedEntropy : null;
+            allResults.push(result);
+        }
+
+        // ── AMA weight calculation ───────────────────────────────────────────
+        const closes = candles.map(c => getCandleClose(c) ?? 0);
+        const amaValues = calculateAMA(closes, AMA_CONFIG);
+        for (let i = 0; i < allResults.length; i++) {
+            // The research chart keeps ATR out of the Kalman branch on purpose.
+            // Production applies ATR later as a separate symmetric volatility penalty.
+            const atr = 0;
+            const weightVariance = 0;
+
+            const weights = computeAmaSlopeWeights(amaValues.slice(0, i + 1), weightVariance, {
+                erPeriod: AMA_CONFIG.erPeriod,
+                lookbackBars: config.lookbackBars ?? AMA_WEIGHT_CONFIG.lookbackBars,
+                maxSlopePct: AMA_WEIGHT_CONFIG.amaMaxSlopePct,
+                neutralZonePct: AMA_WEIGHT_CONFIG.neutralZonePct,
+                volatilityExponent: AMA_WEIGHT_CONFIG.volatilityExponent,
+                volatilityScaleX: AMA_WEIGHT_CONFIG.volatilityScaleX,
+                volatilityThreshold: AMA_WEIGHT_CONFIG.volatilityThreshold,
+                maxSlopeOffset: AMA_WEIGHT_CONFIG.maxSlopeOffset,
+                maxVolatilityOffset: AMA_WEIGHT_CONFIG.maxVolatilityOffset,
+            });
+
+            (allResults[i] as any).ama3Price = amaValues[i] ?? null;
+            (allResults[i] as any).atr = atr;
+            (allResults[i] as any).weightVariance = weightVariance;
+            (allResults[i] as any).amaSlopePct = weights.slopePct;
+            (allResults[i] as any).amaWeightReady = weights.isReady;
+            (allResults[i] as any).amaSlopeOffset = weights.slopeOffset;
+            (allResults[i] as any).amaSymmetricDelta = weights.symmetricDelta;
+        }
+
+        // ── Generate chart ───────────────────────────────────────────────────
+        const html = generateHTML({
+            allResults,
+            amaConfig: AMA_CONFIG,
+            amaKey,
+            amaWeightConfig: {
+                ...AMA_WEIGHT_CONFIG,
+                lookbackBars: config.lookbackBars ?? AMA_WEIGHT_CONFIG.lookbackBars,
+            },
+            alpha: config.alpha,
+            gain: config.gain,
+            dispWeight: config.dispWeight,
+            clipPct: config.clipPct,
+            regimeSensitivity: MARKET_ADAPTER.DYNAMIC_WEIGHT_REGIME_SENSITIVITY,
+            dispScaleMinPct:  config.dispScaleMinPct  ?? MARKET_ADAPTER.DYNAMIC_WEIGHT_DISP_SCALE_MIN_PCT,
+            minOutputThreshold: MARKET_ADAPTER.DYNAMIC_WEIGHT_ASYMMETRIC_TREND_THRESHOLD,
+            outputClamp: MARKET_ADAPTER.DYNAMIC_WEIGHT_ASYMMETRIC_OFFSET_CLAMP,
+            marketAdapter: {
+                alpha:                   MARKET_ADAPTER.DYNAMIC_WEIGHT_ALPHA,
+                gain:                    MARKET_ADAPTER.DYNAMIC_WEIGHT_GAIN,
+                dispWeight:              MARKET_ADAPTER.DYNAMIC_WEIGHT_DW,
+                clipPercentile:         MARKET_ADAPTER.DYNAMIC_WEIGHT_CLIP_PERCENTILE,
+                regimeSensitivity:       MARKET_ADAPTER.DYNAMIC_WEIGHT_REGIME_SENSITIVITY,
+                minOutputThreshold:      MARKET_ADAPTER.DYNAMIC_WEIGHT_ASYMMETRIC_TREND_THRESHOLD,
+                outputClamp:             MARKET_ADAPTER.DYNAMIC_WEIGHT_ASYMMETRIC_OFFSET_CLAMP,
+                amaLookbackBars:        MARKET_ADAPTER.DYNAMIC_WEIGHT_AMA_LOOKBACK_BARS,
+                amaMaxSlopePct:         MARKET_ADAPTER.DYNAMIC_WEIGHT_AMA_MAX_SLOPE_PCT,
+                kalmanMaxSlopePct:      MARKET_ADAPTER.DYNAMIC_WEIGHT_KALMAN_MAX_SLOPE_PCT,
+                amaNeutralZonePct:      MARKET_ADAPTER.DYNAMIC_WEIGHT_AMA_NEUTRAL_ZONE_PCT,
+                dispScaleMinPct:        MARKET_ADAPTER.DYNAMIC_WEIGHT_DISP_SCALE_MIN_PCT,
+            },
+        }, 'Dynamic Weight Research Tool');
+
+        writeChartFile(config.chartFile, html);
+
+        if (!config.quiet) console.log(`[DynamicWeight] ✓ Chart saved to ${config.chartFile}`);
+    } catch (err: unknown) {
+        console.error(`[DynamicWeight] Error: ${(err as any)?.message ?? err}`);
+        process.exit(1);
+    }
+}
+
+main().catch((err: unknown) => { console.error(err); process.exit(1); });

package/analysis/analyze_kalman.ts

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+
+/**
+ * KALMAN TREND ANALYSIS RUNNER
+ *
+ * Runs KalmanTrendAnalyzer over candle data and generates an interactive HTML chart.
+ *
+ * Usage:
+ *   tsx analysis/analyze_kalman.ts \
+ *     --source json \
+ *     --file market_adapter/data/lp/<path>/<to>/<lp-candles>.json
+ */
+
+import { KalmanTrendAnalyzer } from './trend_detection/kalman_trend_analyzer.js';
+import { generateHTML } from './trend_detection/kalman_chart_generator.js';
+import { calculateAMA } from '../market_adapter/core/strategies/ama.js';
+import { computeAverageAmaSlopePct } from '../market_adapter/core/strategies/dynamic_weight_series.js';
+import { getCandleClose } from './math_utils.js';
+import { writeChartFile } from './chart_utils.js';
+import { resolveSource, listAvailableBots, type SourceConfig } from './resolve_source.js';
+
+'use strict';
+
+const LOOKBACK_BARS   = 72;
+const NEUTRAL_ZONE    = 0.15;
+const MAX_SLOPE_PCT   = 3.0;
+const MAX_SLOPE_OFFSET = 0.5;
+
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const config: {
+        source: { type: string; config: SourceConfig };
+        rNoise: number;
+        qNoise: number;
+        chartFile: string;
+        quiet: boolean;
+        listBots: boolean;
+    } = {
+        source: { type: 'market_adapter', config: { botKey: '' } },
+        rNoise: 0.05,
+        qNoise: 0.005,
+        chartFile: 'analysis/charts/kalman_chart.html',
+        quiet: false,
+        listBots: false,
+    };
+
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--source') config.source.type = args[++i];
+        else if (arg === '--bot-key') config.source.config.botKey = args[++i];
+        else if (arg === '--file') {
+            config.source.config.filePath = args[++i];
+            config.source.type = 'json';
+        }
+        else if (arg === '--r') config.rNoise = parseFloat(args[++i]);
+        else if (arg === '--q') config.qNoise = parseFloat(args[++i]);
+        else if (arg === '--chart') config.chartFile = args[++i];
+        else if (arg === '--list-bots') config.listBots = true;
+        else if (arg === '--quiet') config.quiet = true;
+    }
+
+    return config;
+}
+
+async function main() {
+    const config = parseArgs();
+
+    try {
+        if (config.listBots) {
+            listAvailableBots();
+            return;
+        }
+
+        const { source, amaConfig } = resolveSource({ ...config.source.config, type: config.source.type }, { quiet: config.quiet });
+        if (!config.quiet) console.log(`[Kalman] Loading candles from ${source.name}...`);
+
+        const candles = await source.fetchCandles();
+        if (!Array.isArray(candles) || candles.length === 0) {
+            throw new Error('No candles returned from source');
+        }
+
+        // ── Kalman analysis ──────────────────────────────────────────────────
+        const analyzer = new KalmanTrendAnalyzer({
+            rNoise: config.rNoise,
+            qNoise: config.qNoise
+        });
+
+        const allResults: any[] = [];
+        for (let i = 0; i < candles.length; i++) {
+            const { marketPrice, timestamp } = source.extractMarketPrice(candles[i]);
+            const result = analyzer.update(marketPrice);
+            result.timestamp = timestamp;
+            allResults.push(result);
+        }
+
+        // ── AMA weight offset (for comparison panel) ─────────────────────────
+        const closes    = candles.map(c => getCandleClose(c) ?? 0);
+        const amaValues = calculateAMA(closes, amaConfig);
+        const warmup    = amaConfig.erPeriod + LOOKBACK_BARS + 1;
+
+        for (let i = 0; i < allResults.length; i++) {
+            if (i < warmup) { allResults[i].amaWeightOffset = null; continue; }
+            const last = amaValues[i];
+            const past = amaValues[i - LOOKBACK_BARS];
+            if (!last || !past || past === 0) { allResults[i].amaWeightOffset = null; continue; }
+            const slopePct = computeAverageAmaSlopePct(last, past, LOOKBACK_BARS)! * LOOKBACK_BARS;
+            if (Math.abs(slopePct) < NEUTRAL_ZONE) {
+                allResults[i].amaWeightOffset = 0;
+            } else {
+                allResults[i].amaWeightOffset = Math.max(-MAX_SLOPE_OFFSET,
+                    Math.min(MAX_SLOPE_OFFSET, (slopePct / MAX_SLOPE_PCT) * MAX_SLOPE_OFFSET));
+            }
+        }
+
+        // ── Generate chart ───────────────────────────────────────────────────
+        const html = generateHTML({ allResults }, 'Kalman Trend Analysis');
+        writeChartFile(config.chartFile, html);
+
+        if (!config.quiet) console.log(`[Kalman] ✓ Chart saved to ${config.chartFile}`);
+    } catch (err: unknown) {
+        console.error(`[Kalman] Error: ${(err as any)?.message ?? err}`);
+        process.exit(1);
+    }
+}
+
+main().catch((err: unknown) => { console.error(err); process.exit(1); });