@fullstackcraftllc/floe 0.0.13 → 0.0.15

package/dist/hedgeflow/regime.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveRegimeParams = deriveRegimeParams;
+exports.interpolateIVAtStrike = interpolateIVAtStrike;
+/**
+ * Derive regime parameters from the IV surface
+ */
+function deriveRegimeParams(ivSurface, spot) {
+    const { strikes, smoothedIVs } = ivSurface;
+    const atmIV = interpolateIVAtStrike(strikes, smoothedIVs, spot) / 100;
+    const skew = calculateSkewAtSpot(strikes, smoothedIVs, spot);
+    const impliedSpotVolCorr = skewToCorrelation(skew);
+    const curvature = calculateCurvatureAtSpot(strikes, smoothedIVs, spot);
+    const impliedVolOfVol = curvatureToVolOfVol(curvature, atmIV);
+    const regime = ivToRegime(atmIV);
+    const expectedDailySpotMove = atmIV / Math.sqrt(252);
+    const expectedDailyVolMove = impliedVolOfVol / Math.sqrt(252);
+    return {
+        atmIV,
+        impliedSpotVolCorr,
+        impliedVolOfVol,
+        regime,
+        expectedDailySpotMove,
+        expectedDailyVolMove,
+    };
+}
+function skewToCorrelation(skew) {
+    const SKEW_TO_CORR_SCALE = 0.15;
+    return Math.max(-0.95, Math.min(0.5, skew * SKEW_TO_CORR_SCALE));
+}
+function curvatureToVolOfVol(curvature, atmIV) {
+    const VOL_OF_VOL_SCALE = 2.0;
+    return Math.sqrt(Math.abs(curvature)) * VOL_OF_VOL_SCALE * atmIV;
+}
+function ivToRegime(atmIV) {
+    if (atmIV < 0.15)
+        return 'calm';
+    if (atmIV < 0.20)
+        return 'normal';
+    if (atmIV < 0.35)
+        return 'stressed';
+    return 'crisis';
+}
+function interpolateIVAtStrike(strikes, ivs, targetStrike) {
+    if (strikes.length === 0 || ivs.length === 0)
+        return 20;
+    if (strikes.length === 1)
+        return ivs[0];
+    let lower = 0;
+    let upper = strikes.length - 1;
+    for (let i = 0; i < strikes.length - 1; i++) {
+        if (strikes[i] <= targetStrike && strikes[i + 1] >= targetStrike) {
+            lower = i;
+            upper = i + 1;
+            break;
+        }
+    }
+    if (targetStrike <= strikes[0])
+        return ivs[0];
+    if (targetStrike >= strikes[strikes.length - 1])
+        return ivs[ivs.length - 1];
+    const t = (targetStrike - strikes[lower]) / (strikes[upper] - strikes[lower]);
+    return ivs[lower] + t * (ivs[upper] - ivs[lower]);
+}
+function calculateSkewAtSpot(strikes, ivs, spot) {
+    if (strikes.length < 2)
+        return 0;
+    let lowerIdx = 0;
+    let upperIdx = strikes.length - 1;
+    for (let i = 0; i < strikes.length - 1; i++) {
+        if (strikes[i] <= spot && strikes[i + 1] >= spot) {
+            lowerIdx = i;
+            upperIdx = i + 1;
+            break;
+        }
+    }
+    const dIV = ivs[upperIdx] - ivs[lowerIdx];
+    const dK = strikes[upperIdx] - strikes[lowerIdx];
+    return dK > 0 ? (dIV / dK) * spot : 0;
+}
+function calculateCurvatureAtSpot(strikes, ivs, spot) {
+    if (strikes.length < 3)
+        return 0;
+    let centerIdx = 0;
+    for (let i = 0; i < strikes.length; i++) {
+        if (Math.abs(strikes[i] - spot) < Math.abs(strikes[centerIdx] - spot)) {
+            centerIdx = i;
+        }
+    }
+    if (centerIdx === 0 || centerIdx === strikes.length - 1)
+        return 0;
+    const h = (strikes[centerIdx + 1] - strikes[centerIdx - 1]) / 2;
+    if (h <= 0)
+        return 0;
+    const ivMinus = ivs[centerIdx - 1];
+    const iv = ivs[centerIdx];
+    const ivPlus = ivs[centerIdx + 1];
+    return ((ivPlus - 2 * iv + ivMinus) / (h * h)) * spot * spot;
+}

package/dist/hedgeflow/types.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Regime classification based on IV level and surface characteristics
+ */
+export type MarketRegime = 'calm' | 'normal' | 'stressed' | 'crisis';
+/**
+ * Parameters derived from the IV surface itself (no external data needed)
+ */
+export interface RegimeParams {
+    /** ATM implied volatility (as decimal, e.g., 0.18 for 18%) */
+    atmIV: number;
+    /** Implied spot-vol correlation derived from skew */
+    impliedSpotVolCorr: number;
+    /** Implied vol-of-vol derived from smile curvature */
+    impliedVolOfVol: number;
+    /** Regime classification */
+    regime: MarketRegime;
+    /** Expected daily spot move (as decimal) */
+    expectedDailySpotMove: number;
+    /** Expected daily vol move (as decimal) */
+    expectedDailyVolMove: number;
+}
+/**
+ * Configuration for the hedge impulse curve computation
+ */
+export interface HedgeImpulseConfig {
+    /** Price grid range as percentage of spot (e.g. 3 for ±3%). Default: 3 */
+    rangePercent?: number;
+    /** Price grid step as percentage of spot (e.g. 0.05 for 0.05%). Default: 0.05 */
+    stepPercent?: number;
+    /**
+     * Gaussian kernel width in number of strike spacings.
+     * Auto-detected from the option chain's strike spacing.
+     * Default: 2 (i.e. lambda = 2 * modal strike spacing)
+     */
+    kernelWidthStrikes?: number;
+}
+/**
+ * Hedge impulse value at a single price level
+ *
+ * The hedge impulse H(S) represents the net dealer delta hedge change
+ * per unit spot move if price were at S. It combines gamma and vanna
+ * via the empirical spot-vol coupling:
+ *
+ *   H(S) = Gamma(S) - (k / S) * Vanna(S)
+ *
+ * where k is derived from the IV surface skew slope.
+ */
+export interface HedgeImpulsePoint {
+    /** Price level */
+    price: number;
+    /** Smoothed gamma exposure at this price level (kernel-weighted from strikes) */
+    gamma: number;
+    /** Smoothed vanna exposure at this price level (kernel-weighted from strikes) */
+    vanna: number;
+    /** Combined hedge impulse: gamma - (k/S) * vanna */
+    impulse: number;
+}
+/**
+ * A zero crossing of the hedge impulse curve
+ */
+export interface ZeroCrossing {
+    /** Price at which the crossing occurs (interpolated) */
+    price: number;
+    /** Direction: 'rising' means impulse goes from negative to positive */
+    direction: 'rising' | 'falling';
+}
+/**
+ * A local extremum (basin or peak) of the hedge impulse curve
+ */
+export interface ImpulseExtremum {
+    /** Price at the extremum */
+    price: number;
+    /** Impulse value at the extremum */
+    impulse: number;
+    /** 'basin' = positive local max (attractor), 'peak' = negative local min (accelerator) */
+    type: 'basin' | 'peak';
+}
+/**
+ * Directional asymmetry analysis around current spot
+ */
+export interface DirectionalAsymmetry {
+    /** Integrated impulse from spot to spot + integrationRange */
+    upside: number;
+    /** Integrated impulse from spot to spot - integrationRange */
+    downside: number;
+    /** Integration range used (percentage of spot) */
+    integrationRangePercent: number;
+    /** Which side has more negative impulse (= path of least resistance) */
+    bias: 'up' | 'down' | 'neutral';
+    /** Ratio of |upside| to |downside| impulse. >1 means upside is larger magnitude */
+    asymmetryRatio: number;
+}
+/**
+ * Regime classification based on the impulse curve shape
+ */
+export type ImpulseRegime = 'pinned' | 'expansion' | 'squeeze-up' | 'squeeze-down' | 'neutral';
+/**
+ * Complete hedge impulse curve result
+ */
+export interface HedgeImpulseCurve {
+    /** Current spot price */
+    spot: number;
+    /** Expiration timestamp */
+    expiration: number;
+    /** Timestamp when this curve was computed */
+    computedAt: number;
+    /** Spot-vol coupling coefficient derived from IV surface */
+    spotVolCoupling: number;
+    /** Kernel width used (in price units) */
+    kernelWidth: number;
+    /** Strike spacing detected from the option chain */
+    strikeSpacing: number;
+    /** The full curve of impulse values across the price grid */
+    curve: HedgeImpulsePoint[];
+    /** Impulse value at current spot (interpolated) */
+    impulseAtSpot: number;
+    /** Slope of the impulse curve at current spot (dH/dS) */
+    slopeAtSpot: number;
+    /** Zero crossings of the impulse curve */
+    zeroCrossings: ZeroCrossing[];
+    /** Local extrema (basins = attractors, peaks = accelerators) */
+    extrema: ImpulseExtremum[];
+    /** Directional asymmetry analysis */
+    asymmetry: DirectionalAsymmetry;
+    /** Regime classification */
+    regime: ImpulseRegime;
+    /** Nearest attractor (positive impulse basin) above spot, if any */
+    nearestAttractorAbove: number | null;
+    /** Nearest attractor (positive impulse basin) below spot, if any */
+    nearestAttractorBelow: number | null;
+}
+/**
+ * Configuration for charm integral computation
+ */
+export interface CharmIntegralConfig {
+    /** Time step for the integral in minutes. Default: 15 */
+    timeStepMinutes?: number;
+}
+/**
+ * Charm integral at a single time bucket
+ */
+export interface CharmBucket {
+    /** Minutes remaining to expiry at start of this bucket */
+    minutesRemaining: number;
+    /** Instantaneous CEX at this time */
+    instantaneousCEX: number;
+    /** Cumulative CEX from now to this time */
+    cumulativeCEX: number;
+}
+/**
+ * Complete charm integral result
+ */
+export interface CharmIntegral {
+    /** Current spot price */
+    spot: number;
+    /** Expiration timestamp */
+    expiration: number;
+    /** Timestamp when this was computed */
+    computedAt: number;
+    /** Minutes remaining from computation time to expiry */
+    minutesRemaining: number;
+    /** Total charm integral from now to close (cumulative expected delta change) */
+    totalCharmToClose: number;
+    /** Direction: positive = net buying pressure from charm, negative = net selling */
+    direction: 'buying' | 'selling' | 'neutral';
+    /** Bucketed charm integral curve for visualization */
+    buckets: CharmBucket[];
+    /** Per-strike charm breakdown (for understanding what drives the integral) */
+    strikeContributions: Array<{
+        strike: number;
+        charmExposure: number;
+        fractionOfTotal: number;
+    }>;
+}
+/**
+ * Complete hedge flow analysis combining impulse curve and charm integral
+ */
+export interface HedgeFlowAnalysis {
+    /** The instantaneous hedge impulse curve (left panel) */
+    impulseCurve: HedgeImpulseCurve;
+    /** The charm integral to close (right panel) */
+    charmIntegral: CharmIntegral;
+    /** Regime params derived from IV surface */
+    regimeParams: RegimeParams;
+}

package/dist/hedgeflow/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/impliedpdf/adjusted.d.ts

@@ -0,0 +1,173 @@
+import { ImpliedProbabilityDistribution, getProbabilityInRange, getCumulativeProbability, getQuantile } from './index';
+import { ExposurePerExpiry, NormalizedOption } from '../types';
+/**
+ * Configuration for exposure-based PDF adjustments
+ */
+export interface ExposureAdjustmentConfig {
+    /** Gamma adjustment settings */
+    gamma: {
+        /** Enable gamma-based kurtosis adjustment */
+        enabled: boolean;
+        /** Strength of attractor effect at +GEX strikes (0-1) */
+        attractorStrength: number;
+        /** Strength of repellent effect at -GEX strikes (0-1) */
+        repellentStrength: number;
+        /** Minimum absolute GEX to consider significant (in dollars) */
+        threshold: number;
+        /** Decay rate for influence distance (higher = more localized) */
+        decayRate: number;
+    };
+    /** Vanna adjustment settings */
+    vanna: {
+        /** Enable vanna-based tail adjustment */
+        enabled: boolean;
+        /** Spot-vol beta: IV change per 1% spot move (typically -2 to -4 for indices) */
+        spotVolBeta: number;
+        /** Maximum tail fattening multiplier */
+        maxTailMultiplier: number;
+        /** Number of feedback iterations to simulate */
+        feedbackIterations: number;
+    };
+    /** Charm adjustment settings */
+    charm: {
+        /** Enable charm-based mean shift */
+        enabled: boolean;
+        /** Time horizon multiplier ('intraday' = 0.25, 'daily' = 1.0, 'weekly' = 5.0) */
+        timeHorizon: 'intraday' | 'daily' | 'weekly';
+        /** Scaling factor for mean shift */
+        shiftScale: number;
+    };
+}
+/**
+ * Result of exposure-adjusted PDF calculation
+ */
+export interface AdjustedPDFResult {
+    /** Original market-implied distribution */
+    baseline: ImpliedProbabilityDistribution;
+    /** Exposure-adjusted distribution */
+    adjusted: ImpliedProbabilityDistribution;
+    /** Gamma modifier applied at each strike (multiplicative) */
+    gammaModifiers: number[];
+    /** Vanna modifier applied at each strike (multiplicative) */
+    vannaModifiers: number[];
+    /** Charm-induced mean shift (in price units) */
+    charmShift: number;
+    /** Comparison metrics between baseline and adjusted */
+    comparison: PDFComparison;
+}
+/**
+ * Comparison metrics between baseline and adjusted PDFs
+ */
+export interface PDFComparison {
+    /** Shift in expected value */
+    meanShift: number;
+    /** Shift as percentage of spot */
+    meanShiftPercent: number;
+    /** Change in standard deviation */
+    stdDevChange: number;
+    /** Change in tail skew ratio */
+    tailSkewChange: number;
+    /** 5th percentile: baseline vs adjusted */
+    leftTail: {
+        baseline: number;
+        adjusted: number;
+        ratio: number;
+    };
+    /** 95th percentile: baseline vs adjusted */
+    rightTail: {
+        baseline: number;
+        adjusted: number;
+        ratio: number;
+    };
+    /** Dominant adjustment factor */
+    dominantFactor: 'gamma' | 'vanna' | 'charm' | 'none';
+}
+/**
+ * Default configuration tuned for SPX-like indices
+ */
+export declare const DEFAULT_ADJUSTMENT_CONFIG: ExposureAdjustmentConfig;
+/**
+ * Configuration for low volatility / grinding markets
+ */
+export declare const LOW_VOL_CONFIG: ExposureAdjustmentConfig;
+/**
+ * Configuration for high volatility / crisis markets
+ */
+export declare const CRISIS_CONFIG: ExposureAdjustmentConfig;
+/**
+ * Configuration for OPEX week
+ */
+export declare const OPEX_CONFIG: ExposureAdjustmentConfig;
+/**
+ * Estimate an exposure-adjusted implied probability distribution.
+ *
+ * This function takes the standard market-implied PDF (Breeden-Litzenberger)
+ * and adjusts it based on dealer Greek exposures to produce a "mechanically-informed"
+ * probability distribution that accounts for:
+ *
+ * - **Gamma**: Creates "sticky" zones (+GEX) where price pins, and "slippery" zones
+ *   (-GEX) where price accelerates through
+ * - **Vanna**: Fattens tails based on the IV-spot feedback loop (selloffs spike IV,
+ *   which forces more selling via negative vanna)
+ * - **Charm**: Shifts the mean based on predictable delta decay over time
+ *
+ * @param symbol - Underlying ticker symbol
+ * @param underlyingPrice - Current spot price
+ * @param callOptions - Call options for a single expiry
+ * @param exposures - Exposure metrics from calculateGammaVannaCharmExposures()
+ * @param config - Adjustment configuration (uses defaults if not provided)
+ * @returns Baseline and adjusted PDFs with comparison metrics
+ *
+ * @example
+ * ```typescript
+ * // Get exposures first
+ * const allExposures = calculateGammaVannaCharmExposures(chain, ivSurfaces);
+ * const expiryExposures = allExposures.find(e => e.expiration === targetExpiry);
+ *
+ * // Calculate adjusted PDF
+ * const result = estimateExposureAdjustedPDF(
+ *   'SPX',
+ *   4520,
+ *   callOptionsForExpiry,
+ *   expiryExposures
+ * );
+ *
+ * // Compare probabilities
+ * const target = 4400;
+ * const baselineProb = getCumulativeProbability(result.baseline, target);
+ * const adjustedProb = getCumulativeProbability(result.adjusted, target);
+ * console.log(`Market says ${baselineProb}% chance of ${target}`);
+ * console.log(`Flow-adjusted: ${adjustedProb}% chance`);
+ * ```
+ */
+export declare function estimateExposureAdjustedPDF(symbol: string, underlyingPrice: number, callOptions: NormalizedOption[], exposures: ExposurePerExpiry, config?: Partial<ExposureAdjustmentConfig>): AdjustedPDFResult | {
+    success: false;
+    error: string;
+};
+/**
+ * Get the "edge" - the difference between market-implied and flow-adjusted
+ * probability of reaching a price level.
+ *
+ * Positive edge means the market is underpricing the probability of reaching that level.
+ * Negative edge means the market is overpricing it.
+ *
+ * @example
+ * ```typescript
+ * const result = estimateExposureAdjustedPDF(...);
+ * const edge = getEdgeAtPrice(result, 4400);
+ * console.log(`Edge at 4400: ${(edge * 100).toFixed(2)}%`);
+ * // Output: "Edge at 4400: 2.35%"
+ * // Meaning: flow mechanics suggest 2.35% higher probability than market prices
+ * ```
+ */
+export declare function getEdgeAtPrice(result: AdjustedPDFResult, price: number): number;
+/**
+ * Get price levels where the adjustment is most significant
+ */
+export declare function getSignificantAdjustmentLevels(result: AdjustedPDFResult, threshold?: number): Array<{
+    strike: number;
+    baselineProb: number;
+    adjustedProb: number;
+    edge: number;
+}>;
+export { getProbabilityInRange, getCumulativeProbability, getQuantile };