stonks-oracle/docs/equations.md

# Stonks Oracle — Mathematical Reference

Every equation, formula, threshold, and constant used in the signal processing, aggregation, recommendation, and trading pipeline. Organized by pipeline stage.

Code references are provided so each formula can be traced to its implementation.

---

## 1. Signal Scoring

**Source:** `services/aggregation/scoring.py`

### 1.1 Combined Signal Weight

Each document signal receives a composite weight:

```
W_combined = G_conf × W_recency × W_credibility × (1 + B_novelty) × M_context
```

| Component | Symbol | Formula | Range |
|---|---|---|---|
| Confidence gate | G_conf | 1 if extraction_confidence ≥ 0.2, else 0 | {0, 1} |
| Recency decay | W_recency | 2^(−t_age / t_half) | [0.01, 1.0] |
| Credibility | W_credibility | clamp(credibility, 0.1, 1.0)^α | [0.1, 1.0] |
| Novelty bonus | B_novelty | novelty_score × 0.25 | [0, 0.25] |
| Market context | M_context | 1 + boost_vol + boost_vol_surge | [1.0, 1.45] |

### 1.2 Recency Decay

```
W_recency = max( 2^(−t_age / t_half), 0.01 )
```

where `t_age` is document age in hours and half-lives by window are:

| Window | t_half (hours) |
|---|---|
| intraday | 2 |
| 1d | 12 |
| 7d | 72 |
| 30d | 240 |
| 90d | 720 |

### 1.3 Credibility Weight

```
W_credibility = clamp(c_raw, 0.1, 1.0)^α       where α = 1.0 (default)
```

α > 1 penalizes low-credibility sources more aggressively; α < 1 flattens the curve.

### 1.4 Market Context Multiplier

```
boost_vol = min( ln(1 + max(σ − 1.0, 0)) × 0.15, 0.30 )

boost_surge = 0.15   if ΔV% > 50%,  else 0

M_context = 1.0 + boost_vol + boost_surge
```

where σ is price volatility and ΔV% is volume change percentage.

### 1.5 Weighted Sentiment Average

```
S_avg = Σ(W_combined_i × impact_i × sentiment_i) / Σ(W_combined_i × impact_i)
```

- sentiment_i ∈ {+1.0 (positive), −1.0 (negative), 0.0 (neutral/mixed)}
- impact_i ∈ [0, 1] from extraction
- Returns 0.0 when denominator = 0

---

## 2. Trend Summary Assembly

**Source:** `services/aggregation/worker.py`

### 2.1 Trend Direction

| Condition | Direction |
|---|---|
| S_avg ≥ 0.15 | Bullish |
| S_avg ≤ −0.15 | Bearish |
| contradiction > 0.10 AND |S_avg| < 0.30 | Mixed |
| otherwise | Neutral |

### 2.2 Trend Strength

```
strength = min(|S_avg|, 1.0)
```

### 2.3 Contradiction Score

**Source:** `services/aggregation/contradiction.py`

```
contradiction = W_minority / (W_positive + W_negative)
```

where:
```
W_positive = Σ(W_combined_i × impact_i)   for signals with sentiment > 0
W_negative = Σ(W_combined_i × impact_i)   for signals with sentiment < 0
W_minority = min(W_positive, W_negative)
```

Range: [0, 1]. 0 = full agreement, 0.5 = equal-weight disagreement.

### 2.4 Trend Confidence

```
confidence = clamp(0.3 × F_count + 0.3 × C_avg + 0.4 × A_agreement − P_contradiction, 0, 1)
```

| Component | Formula |
|---|---|
| F_count (source count) | min(N_unique / 15, 0.8) |
| C_avg (extraction confidence) | mean of extraction confidences |
| A_agreement (signal agreement) | fraction_same_direction × min(1, log₂(N_unique + 1) / log₂(8)) |
| P_contradiction | contradiction_score × 0.4 |

---

## 3. Macro Impact Scoring (Layer 2)

**Source:** `services/aggregation/interpolation.py`

### 3.1 Overlap Components

**Geographic overlap:**
```
O_geo = Σ revenue_pct_r   for each event region r in company's revenue mix
```
Range: [0, 1]

**Supply chain overlap:**
```
O_supply = |event_regions ∩ supply_regions| / |supply_regions|
```

**Commodity overlap:**
```
O_commodity = |event_commodities ∩ company_commodities| / |company_commodities|
```

**Sector overlap:**
```
O_sector = 1.0 if company_sector ∈ event_affected_sectors, else 0.0
```

### 3.2 Raw Macro Impact Score

```
S_raw = W_severity × (0.35 × O_geo + 0.25 × O_supply + 0.25 × O_commodity + 0.15 × O_sector)
```

Severity weights:

| Severity | W_severity |
|---|---|
| critical | 1.0 |
| high | 0.75 |
| moderate | 0.5 |
| low | 0.25 |

### 3.3 Resilience Modifier

For international events, the raw score is adjusted by market position:

```
S_final = clamp(S_raw × R_tier, 0, 1)
```

| Market Position Tier | R_tier |
|---|---|
| Global leader | 0.70 |
| Multinational | 0.85 |
| Regional | 1.00 |
| Domestic | 1.20 |

For domestic-only events, R_tier = 1.0 regardless of tier.

### 3.4 Macro Impact Confidence

```
confidence = min(event_confidence × min(O_total + 0.3, 1.0), 1.0)
```

where O_total = O_geo + O_supply + O_commodity + O_sector.

### 3.5 Accelerated Staleness Decay

For short-term events older than 48 hours:

```
decay_standard = e^(−0.693 × t_age_hours / t_half_hours)     (t_half default = 168h)
decay_accelerated = decay_standard × 0.5
```

### 3.6 Macro Signal as WeightedSignal

When merged into the aggregation engine:

```
impact_score_macro = macro_impact_score × W_macro       (W_macro = 0.3 default)
sentiment_value = +1 if positive, −1 if negative
```

Recency decay uses the global event's publication time.

---

## 4. Competitive Signals (Layer 3)

### 4.1 Pattern Confidence

**Source:** `services/aggregation/pattern_matcher.py`

```
confidence = F_sample × 0.4 + F_consistency × 0.4 + F_recency × 0.2
```

| Factor | Formula |
|---|---|
| F_sample | min(N_samples / 20, 1.0) |
| F_consistency | max(pct_bullish, pct_bearish) |
| F_recency | 1.0 if age ≤ 7d; 0.7 if age ≤ 90d; 0.4 otherwise |

**Modifiers:**
- Major corporate decision (m&a, earnings, legal): confidence × 1.3
- Insufficient data (N_samples < min_pattern_samples): cap at 0.25
- Stale data (age > staleness_window_days): confidence × staleness_decay_penalty

**Lookback windows:**
- Routine signals: 180 days
- Major corporate decisions: 365 days

### 4.2 Cross-Company Signal Strength

**Source:** `services/aggregation/signal_propagation.py`

```
S_competitive = clamp(S_pattern_avg × R_relationship × C_pattern × I_source, 0, 1)
```

| Component | Description |
|---|---|
| S_pattern_avg | Average historical outcome strength [0, 1] |
| R_relationship | Relationship strength from competitor_relationships [0, 1] |
| C_pattern | Pattern confidence from §4.1 |
| I_source | Source document's impact_score [0, 1] |

**Threshold gate:** Skipped if R_relationship < propagation_strength_threshold (default 0.2).

### 4.3 Competitive Signal as WeightedSignal

```
impact_score_competitive = S_competitive × W_competitive     (W_competitive = 0.2 default)
direction = majority historical outcome (bullish or bearish)
```

---

## 5. Trend Projection

**Source:** `services/aggregation/projection.py`

### 5.1 Trend Momentum

```
momentum = S_current_signed − S_previous_signed
```

where `S_signed = direction_sign × strength` (bullish = +1, bearish = −1, neutral = 0).

When no previous data exists:
```
momentum = direction_sign × strength × 0.5
```

Range: [−1, 1]

### 5.2 Macro Decay Projection

For each active macro event projected forward by `H` days:

```
F_future = 2^(−(t_current + H) / t_half)
I_projected = macro_impact_score × F_future × W_severity
```

Decay half-lives:

| Duration | t_half (days) |
|---|---|
| short_term | 1.0 |
| medium_term | 7.0 |
| long_term | 30.0 |

Aggregate direction: bullish if W_pos > 1.2 × W_neg; bearish if W_neg > 1.2 × W_pos; mixed if both > 0.

### 5.3 Projection Blending

```
W_macro_blend = min(S_macro_projected × 0.4, 0.4)
W_company = 1.0 − W_macro_blend

S_blended = W_company × S_momentum_projected + W_macro_blend × S_macro_signed
```

**Catalyst boost:** `min(N_catalysts × 0.02, 0.1)` added to projected strength.

**Projected confidence:**
```
C_projected = C_base × 0.8 + min(S_macro × 0.15, 0.1)
```

**Divergence detection:** Flagged when projected direction ≠ current trend direction.

---

## 6. Data Quality Suppression

**Source:** `services/recommendation/suppression.py`

### 6.1 Data Quality Score

```
Q = 0.4 × Q_confidence + 0.3 × Q_freshness + 0.3 × Q_coverage
```

| Component | Formula |
|---|---|
| Q_confidence | min(C_avg_extraction / 0.8, 1.0) |
| Q_freshness | max(0, 1 − t_newest_hours / 168) |
| Q_coverage | (N_valid / N_total) × min(N_valid / 10, 1.0) |

**Suppression triggers** (any one → informational only):

| Check | Threshold |
|---|---|
| Avg extraction confidence | < 0.40 |
| Evidence staleness | > 168 hours (7 days) |
| Source type diversity | < 1 distinct type |
| Extraction failure rate | > 50% |
| Valid document count | < 2 |
| Data quality score | < 0.30 |

### 6.2 Safety Suppression

- **Macro-only:** If trend driven solely by macro signals with zero company evidence → forced informational
- **Pattern-only:** If trend driven solely by pattern/competitive signals with no company or macro support → forced informational

---

## 7. Recommendation Eligibility

**Source:** `services/recommendation/eligibility.py`

### 7.1 Gate Checks (all must pass)

| Check | Threshold |
|---|---|
| Confidence | ≥ 0.35 |
| Trend strength | ≥ 0.10 |
| Contradiction score | ≤ 0.60 |
| Evidence count | ≥ 2 |
| Direction | ≠ neutral |

### 7.2 Action Mapping

| Condition | Action |
|---|---|
| Bullish AND strength ≥ 0.25 | BUY |
| Bearish AND strength ≥ 0.25 | SELL |
| Directional AND confidence ≥ 0.50 | HOLD |
| Mixed or weak | WATCH |

### 7.3 Mode Escalation

| Mode | Requirements |
|---|---|
| live_eligible | confidence ≥ 0.70, contradiction ≤ 0.25, evidence ≥ 5 |
| paper_eligible | confidence ≥ 0.50 |
| informational | everything else (WATCH/HOLD always informational) |

### 7.4 Position Sizing

```
portfolio_pct = base + C_factor × S_factor × range × P_contradiction × P_evidence
```

| Component | Formula | Default |
|---|---|---|
| base | base_portfolio_pct | 0.01 (1%) |
| range | max_portfolio_pct − base_portfolio_pct | 0.09 (9%) |
| C_factor | confidence_sizing_weight × confidence | 0.8 × confidence |
| S_factor | 0.5 + 0.5 × trend_strength | [0.5, 1.0] |
| P_contradiction | 1 − (contradiction_penalty × contradiction_score) | penalty = 0.5 |
| P_evidence | 0.50 if evidence < 3; 0.75 if evidence < 5; 1.0 otherwise | |

Clamped to [base × 0.5, max_portfolio_pct].

**Max loss percentage** uses the same structure with base = 0.003 (0.3%) and max = 0.02 (2%).

---

## 8. Trading Engine — Position Sizing

**Source:** `services/trading/position_sizer.py`

### 8.1 Base Allocation

```
raw_pct = (max_position_pct × 0.5) × (confidence / min_confidence) × multiplier
clamped_pct = min(raw_pct, max_position_pct)
dollar_amount = min(active_pool × clamped_pct, absolute_position_cap)
```

### 8.2 Correlation Reduction

```
ρ_avg = Σ(ρ_i × w_i) / Σ(w_i)     for existing positions
```

| ρ_avg | Action |
|---|---|
| > 0.8 | Reject order |
| 0.5 < ρ_avg ≤ 0.8 | Reduce: factor = 1 − (ρ_avg − 0.5) / 0.3 |
| ≤ 0.5 | No reduction |

### 8.3 Sector Exposure Reduction

```
available = max(max_sector_pct × active_pool − current_sector_exposure, 0)
dollar_amount = min(dollar_amount, available)
```

### 8.4 Diversification Bonus

If < 3 sectors held AND entering a new sector: dollar_amount × 1.2 (capped at max_position_pct).

### 8.5 Earnings Proximity

| Days to earnings | Action |
|---|---|
| ≤ 1 | Reject |
| 1–3 | 50% reduction |
| > 3 | No adjustment |

### 8.6 Portfolio Heat Check

```
heat_new = dollar_amount × atr_multiplier × 0.02
heat_max = max_portfolio_heat × active_pool

Reject if: heat_current + heat_new > heat_max
```

### 8.7 Share Rounding

```
shares = floor(dollar_amount / current_price)
final_dollar = shares × current_price
```

Reject if shares = 0.

---

## 9. Stop-Loss and Take-Profit

**Source:** `services/trading/stop_loss_manager.py`

### 9.1 Initial Levels

```
stop_distance = ATR × M_atr
stop_loss = entry_price − stop_distance
take_profit = entry_price + stop_distance × R_reward_risk
```

| Trade type | M_atr | R_reward_risk |
|---|---|---|
| Standard | risk_tier.stop_loss_atr_multiplier | risk_tier.reward_risk_ratio |
| Micro-trade | 1.0 | 1.5 |

### 9.2 Dynamic Tightening

| Condition | Effective multiplier |
|---|---|
| High-severity macro event | base × 0.5 |
| Earnings within 3 days | base × 0.7 |
| Portfolio heat > 80% of max | base × 0.7 |
| Normal | base |

### 9.3 Trailing Stop Activation

Activates when:
```
favorable_move = current_price − entry_price > 0.5 × (take_profit − entry_price)
```

Once active, stop-loss floor = entry_price (breakeven).

---

## 10. Risk Management

### 10.1 Position Limits

**Source:** `services/risk/engine.py`

| Limit | Default | Formula |
|---|---|---|
| Max position % | 5% | position_value / portfolio_value ≤ 0.05 |
| Max position value | $10,000 | existing + new ≤ $10,000 |
| Max shares/order | 1,000 | quantity ≤ 1,000 |
| Max sector % | 25% | sector_value / portfolio_value ≤ 0.25 |
| Max daily loss % | 2% | |daily_pnl| / portfolio_value ≤ 0.02 |
| Max daily loss $ | $1,000 | |daily_pnl| ≤ $1,000 |
| Max daily trades | 20 | trade_count < 20 |

### 10.2 Order Clamping

**Source:** `services/risk/engine.py` — `clamp_order_to_position_limits()`

When a buy order exceeds position limits, instead of rejecting:

```
max_allowed_value = min(
    max_position_value − existing_value,
    max_position_pct × portfolio_value − existing_value
)
clamped_shares = min( floor(max_allowed_value / price_per_share), max_shares_per_order )
```

### 10.3 News Shock Lockout

Trigger: impact_score ≥ 0.80 for catalyst ∈ {earnings, legal, m_and_a}
Duration: 60 minutes (configurable)

### 10.4 Symbol Cooldown

Duration: 15 minutes between trades on same symbol.
Max concurrent positions per symbol: 1.

---

## 11. Circuit Breaker

**Source:** `services/trading/circuit_breaker.py`

| Trigger | Condition | Cooldown |
|---|---|---|
| Daily loss | |daily_pnl| / portfolio_value > 0.05 | 2 hours |
| Single position | position_loss_pct > 0.15 | 48 hours |
| Volatility | ≥ 3 stop-losses within 30-minute window | 2 hours |

---

## 12. Risk Tier Auto-Adjustment

**Source:** `services/trading/risk_tier_controller.py`

Tiers: conservative → moderate → aggressive

**Downgrade** (any one triggers, drops one level):
- 30-day win rate < 40%
- Current drawdown > 15%

**Upgrade** (all must be true, raises one level):
- 30-day win rate > 55%
- Reserve pool > 20% of portfolio
- Current drawdown < 5%

---

## 13. Portfolio Rebalancing

**Source:** `services/trading/rebalancer.py`

### 13.1 Single-Stock Rebalancing

```
excess = market_value − max_position_pct × active_pool
sell_qty = min( floor(excess / current_price), position_quantity )
```

### 13.2 Sector Rebalancing

```
sector_excess = Σ(market_value_i) − max_sector_pct × active_pool
```

Sell from lowest-confidence positions first until excess is covered.

### 13.3 Max Positions Enforcement

```
excess_count = N_positions − max_positions
```

Sell entire lowest-confidence positions until count is within limit.

---

## Constants Summary

| Constant | Value | Location |
|---|---|---|
| Confidence gate floor | 0.20 | scoring.py |
| Min recency weight | 0.01 | scoring.py |
| Credibility floor/ceiling | 0.10 / 1.0 | scoring.py |
| Novelty bonus max | 0.25 (25%) | scoring.py |
| Volatility boost threshold | 1.0 price units | scoring.py |
| Volatility boost max | 0.30 (30%) | scoring.py |
| Volume surge threshold | 50% | scoring.py |
| Volume surge boost | 0.15 (15%) | scoring.py |
| Bullish/bearish threshold | ±0.15 | worker.py |
| Mixed threshold | contradiction > 0.10, |S| < 0.30 | worker.py |
| Macro signal weight | 0.30 | config.py |
| Competitive signal weight | 0.20 | config.py |
| Macro confidence threshold | 0.40 | interpolation.py |
| Staleness accelerated decay | 0.50× | interpolation.py |
| Short-term staleness hours | 48 | interpolation.py |
| Pattern min samples | configurable | pattern_matcher.py |
| Major decision weight multiplier | 1.3× | pattern_matcher.py |
| Routine lookback | 180 days | pattern_matcher.py |
| Major decision lookback | 365 days | pattern_matcher.py |
| Propagation strength threshold | 0.20 | signal_propagation.py |
| Data quality min score | 0.30 | suppression.py |
| Evidence staleness max | 168 hours (7 days) | suppression.py |
| Recommendation min confidence | 0.35 | eligibility.py |
| Recommendation min strength | 0.10 | eligibility.py |
| Action strength threshold | 0.25 | eligibility.py |
| Live confidence threshold | 0.70 | eligibility.py |
| Paper confidence threshold | 0.50 | eligibility.py |
| Base portfolio allocation | 1% | eligibility.py |
| Max portfolio allocation | 10% | eligibility.py |
| Circuit breaker daily loss | 5% | circuit_breaker.py |
| Circuit breaker single position | 15% | circuit_breaker.py |
| Stop-loss cluster threshold | 3 hits / 30 min | circuit_breaker.py |
| Tier downgrade win rate | < 40% | risk_tier_controller.py |
| Tier upgrade win rate | > 55% | risk_tier_controller.py |
| Tier upgrade max drawdown | < 5% | risk_tier_controller.py |
| Tier upgrade min reserve | > 20% | risk_tier_controller.py |