@mnemopay/sdk 0.9.3 → 1.0.0

package/dist/behavioral.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Behavioral Finance Engine — Psychology-Backed Financial Intelligence
+ *
+ * Implements Nobel Prize-winning behavioral economics research to help
+ * AI agents (and their human principals) make better financial decisions.
+ *
+ * Core models implemented:
+ *   1. Prospect Theory value function (Kahneman & Tversky, 1979/1992)
+ *   2. Quasi-hyperbolic discounting (Laibson, 1997)
+ *   3. Dynamic cooling-off periods (MnemoPay original)
+ *   4. Loss-framed nudges (Tversky & Kahneman, 1981)
+ *   5. Commitment devices / Save More Tomorrow (Thaler & Benartzi, 2004)
+ *   6. Regret memory + prediction (Zeelenberg & Pieters, 2007)
+ *   7. Overconfidence brake (Barber & Odean, 2000)
+ *   8. Intelligent expense reframing (Thaler, 1985 mental accounting)
+ *   9. Endowed progress effect (Nunes & Dreze, 2006)
+ *   10. Anti-herd alerting (Shiller, 2000)
+ *
+ * All parameters sourced from peer-reviewed publications with exact citations.
+ * Zero external dependencies.
+ *
+ * References (selected):
+ *   - Tversky & Kahneman (1992). "Advances in Prospect Theory"
+ *   - Laibson (1997). "Golden Eggs and Hyperbolic Discounting"
+ *   - Thaler & Benartzi (2004). "Save More Tomorrow"
+ *   - Barber & Odean (2000). "Trading Is Hazardous to Your Wealth"
+ *   - Madrian & Shea (2001). "The Power of Suggestion"
+ */
+export interface ProspectValue {
+    /** The psychologically perceived value (positive = gain, negative = loss) */
+    value: number;
+    /** Original monetary amount */
+    amount: number;
+    /** Whether this is a gain or loss */
+    domain: "gain" | "loss";
+    /** Loss aversion multiplier applied (lambda) */
+    lossAversion: number;
+    /** Explanation for the agent/user */
+    explanation: string;
+}
+export interface CoolingOffResult {
+    /** Whether a cooling-off period is recommended */
+    recommended: boolean;
+    /** Hours to wait before executing */
+    hours: number;
+    /** Reason for the recommendation */
+    reason: string;
+    /** Risk level of the purchase */
+    riskLevel: "low" | "medium" | "high" | "extreme";
+    /** Estimated regret probability based on history */
+    regretProbability: number;
+}
+export interface CommitmentResult {
+    /** Projected savings rates over time */
+    projectedRates: number[];
+    /** Projected total savings at each cycle */
+    projectedSavings: number[];
+    /** Final rate after all cycles */
+    finalRate: number;
+    /** Explanation of the SMarT plan */
+    explanation: string;
+}
+export interface LossFrame {
+    /** The loss-framed message */
+    message: string;
+    /** Equivalent gain message for comparison */
+    gainMessage: string;
+    /** Expected effectiveness multiplier vs gain framing */
+    effectivenessMultiplier: number;
+    /** Days of goal delay this spending causes */
+    goalDelayDays: number;
+}
+export interface ReframedExpense {
+    /** Original amount and frequency */
+    original: {
+        amount: number;
+        frequency: string;
+    };
+    /** Reframed amounts at different timescales */
+    daily: number;
+    weekly: number;
+    monthly: number;
+    annual: number;
+    /** The most psychologically impactful frame */
+    impactFrame: string;
+    /** Opportunity cost: what else this money could do */
+    opportunityCost: string;
+}
+export interface RegretEntry {
+    /** Purchase amount */
+    amount: number;
+    /** Category of purchase */
+    category: string;
+    /** Self-rated regret 0-10 (10 = deeply regret) */
+    regretScore: number;
+    /** ISO timestamp */
+    timestamp: string;
+}
+export interface RegretPrediction {
+    /** Predicted regret probability 0-1 */
+    probability: number;
+    /** Confidence in the prediction 0-1 */
+    confidence: number;
+    /** Historical context */
+    historicalRegretRate: number;
+    /** Category-specific regret rate */
+    categoryRegretRate: number;
+    /** Recommendation */
+    recommendation: string;
+    /** Whether to invoke cooling-off */
+    triggerCoolingOff: boolean;
+}
+export interface TradeEntry {
+    /** Timestamp of trade */
+    timestamp: number;
+    /** Trade amount */
+    amount: number;
+    /** Direction */
+    direction: "buy" | "sell";
+    /** Asset or category */
+    asset: string;
+    /** Realized P/L if closed */
+    realizedPL?: number;
+}
+export interface OverconfidenceResult {
+    /** Whether overconfidence is detected */
+    detected: boolean;
+    /** Current trading frequency (trades per period) */
+    frequency: number;
+    /** Optimal frequency (derived from historical performance) */
+    optimalFrequency: number;
+    /** Estimated annual performance drag from overtrading (percentage points) */
+    performanceDrag: number;
+    /** Disposition effect detected (holding losers, selling winners) */
+    dispositionEffect: boolean;
+    /** Recommendation */
+    recommendation: string;
+}
+export interface AssetMetrics {
+    /** Current price-to-earnings ratio */
+    peRatio: number;
+    /** Historical mean P/E */
+    historicalMeanPE: number;
+    /** Historical standard deviation of P/E */
+    historicalStdPE: number;
+    /** Recent price change (percent, 30-day) */
+    recentReturn30d: number;
+    /** Volume spike (current vs average) */
+    volumeRatio: number;
+}
+export interface HerdAlert {
+    /** Whether herd behavior is detected */
+    detected: boolean;
+    /** Severity: low, medium, high */
+    severity: "low" | "medium" | "high";
+    /** CAPE-like ratio relative to mean */
+    valuationSigma: number;
+    /** Alert message */
+    message: string;
+    /** Contrarian recommendation */
+    recommendation: string;
+}
+export interface FinancialGoal {
+    /** Goal name */
+    name: string;
+    /** Target amount */
+    target: number;
+    /** Current progress toward goal */
+    current: number;
+    /** Monthly savings rate toward this goal */
+    monthlySavings: number;
+}
+export interface EndowedProgress {
+    /** Percentage complete toward goal */
+    percentComplete: number;
+    /** Framed message using endowed progress effect */
+    message: string;
+    /** Expected completion boost from endowed framing (Nunes & Dreze: 34% vs 19%) */
+    expectedCompletionRate: number;
+}
+export interface BehavioralConfig {
+    /** Prospect theory: loss aversion coefficient. Tversky & Kahneman 1992: 2.25 */
+    lambda: number;
+    /** Prospect theory: gain curvature. T&K 1992: 0.88 */
+    alpha: number;
+    /** Prospect theory: loss curvature. T&K 1992: 0.88 */
+    beta_pt: number;
+    /** Quasi-hyperbolic: present bias. Laibson 1997: 0.70 */
+    beta_discount: number;
+    /** Quasi-hyperbolic: exponential discount. Laibson 1997: 0.96 */
+    delta: number;
+    /** Base cooling-off hours for amount = income. Default 2 */
+    baseCoolingHours: number;
+    /** Minimum purchase amount to trigger cooling-off. Default 100 */
+    coolingThreshold: number;
+    /** Overconfidence: max trades per month before alert. Barber & Odean: monthly turnover > 8.8% */
+    maxTradesPerMonth: number;
+    /** Annual performance drag per excess trade (basis points). B&O 2000: ~6.5pp for highest quartile */
+    excessTradeCostBps: number;
+}
+export declare const DEFAULT_BEHAVIORAL_CONFIG: BehavioralConfig;
+export declare class BehavioralEngine {
+    readonly config: BehavioralConfig;
+    private regretHistory;
+    private static readonly MAX_REGRET_HISTORY;
+    constructor(config?: Partial<BehavioralConfig>);
+    prospectValue(amount: number): ProspectValue;
+    /**
+     * Compare gain vs loss framing of the same amount.
+     * Shows why loss framing is 2.25x more effective for behavior change.
+     */
+    compareFraming(amount: number): {
+        gainValue: number;
+        lossValue: number;
+        ratio: number;
+        insight: string;
+    };
+    discount(periods: number): number;
+    /**
+     * Calculate the present-biased value of a future amount.
+     * Shows how much a rational agent values $X received in T periods.
+     */
+    presentValue(futureAmount: number, periods: number): {
+        discountedValue: number;
+        discountFactor: number;
+        lostValue: number;
+        explanation: string;
+    };
+    coolingOff(amount: number, monthlyIncome: number, userBeta?: number): CoolingOffResult;
+    lossFrame(spendAmount: number, goal: FinancialGoal): LossFrame;
+    commitmentDevice(currentSavingsRate: number, raisePercent: number, cycles: number): CommitmentResult;
+    recordRegret(entry: RegretEntry): void;
+    predictRegret(amount: number, category: string): RegretPrediction;
+    overconfidenceBrake(trades: TradeEntry[], periodDays?: number): OverconfidenceResult;
+    reframeExpense(amount: number, frequency: "daily" | "weekly" | "monthly" | "annual"): ReframedExpense;
+    endowedProgress(goal: FinancialGoal): EndowedProgress;
+    antiHerdAlert(metrics: AssetMetrics): HerdAlert;
+    private _computeRegretRatio;
+    private _validateConfig;
+    /** Get regret history for analysis */
+    getRegretHistory(): RegretEntry[];
+    /** Serialize for persistence */
+    serialize(): {
+        config: BehavioralConfig;
+        regretHistory: RegretEntry[];
+    };
+    /** Deserialize with validation */
+    static deserialize(data: {
+        config?: Partial<BehavioralConfig>;
+        regretHistory?: RegretEntry[];
+    }): BehavioralEngine;
+}
+//# sourceMappingURL=behavioral.d.ts.map

package/dist/behavioral.d.ts.map

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