optiondesk-engine 0.3.0__py3-none-any.whl

optiondesk_engine/__init__.py

@@ -0,0 +1,57 @@
+"""The analytics engine.
+
+Copyright (C) 2026 Iman Samizadeh.
+
+Licensed under the PolyForm Noncommercial License 1.0.0. Any noncommercial
+purpose is permitted, including personal study, research, and use by
+charitable, educational, public research, health, environmental and
+government organisations. Commercial use, which includes any use for
+commercial advantage or private monetary compensation, requires a separate
+written agreement with the copyright holder.
+
+The full terms are in LICENSE at the root of this package and at
+https://polyformproject.org/licenses/noncommercial/1.0.0
+
+This is research software. It is not investment advice, not a
+recommendation and not a solicitation. See DISCLAIMER.md.
+"""
+
+__version__ = "0.3.0"
+LICENSE = "PolyForm-Noncommercial-1.0.0"
+
+from optiondesk_engine.pricing.black_scholes import (
+    bs_price,
+    implied_vol,
+)
+from optiondesk_engine.pricing.greeks_full import (
+    GREEK_KEYS,
+    all_greeks,
+)
+from optiondesk_engine.backtest import (
+    bootstrap_mean_interval,
+    performance_stats,
+    permutation_p_value,
+    run_backtest,
+)
+from optiondesk_engine.strategies import (
+    PLAYBOOK,
+    Leg,
+    Outlook,
+    analyze,
+    build,
+    describe,
+    payoff_curve,
+    plan_friction,
+    probability_of_profit,
+    recommend,
+    split_chain,
+    tail_metrics,
+)
+
+__all__ = ["bs_price", "implied_vol", "all_greeks", "GREEK_KEYS",
+           "PLAYBOOK", "Leg", "Outlook", "analyze", "build", "describe",
+           "payoff_curve", "plan_friction", "probability_of_profit",
+           "recommend", "split_chain", "tail_metrics",
+           "run_backtest", "performance_stats", "permutation_p_value",
+           "bootstrap_mean_interval",
+           "__version__", "LICENSE"]

optiondesk_engine/analytics/__init__.py

@@ -0,0 +1,31 @@
+"""Chain-level analytics: positioning, exposure and pain.
+
+Copyright (C) 2026 Iman Samizadeh. Licensed under the PolyForm Noncommercial License 1.0.0.
+Commercial use requires a separate written agreement.
+
+Where the pricing modules answer "what is this contract worth", these
+answer "where is the open interest, and what does hedging it imply".
+"""
+
+from optiondesk_engine.analytics.exposure import (
+    chain_exposure,
+    max_pain,
+)
+from optiondesk_engine.analytics.compare import rank_strategies, score_plan
+from optiondesk_engine.analytics.ranking import (
+    FORMULA,
+    MIN_ABS_PREMIUM,
+    RR_CAP,
+    SCORE_WEIGHTS,
+    THIN_MULTIPLIER,
+    VRP_TILT,
+    rank_rows,
+    row_from_comparison,
+    score_row,
+)
+from optiondesk_engine.analytics.smile import smile_metrics
+
+__all__ = ["chain_exposure", "max_pain", "smile_metrics", "rank_strategies",
+           "score_plan", "score_row", "rank_rows", "row_from_comparison",
+           "SCORE_WEIGHTS", "RR_CAP", "VRP_TILT", "THIN_MULTIPLIER",
+           "MIN_ABS_PREMIUM", "FORMULA"]

optiondesk_engine/analytics/compare.py

@@ -0,0 +1,176 @@
+"""Rank structures against each other under a stated, visible criterion.
+
+Copyright (C) 2026 Iman Samizadeh. Licensed under the PolyForm Noncommercial License 1.0.0.
+Commercial use requires a separate written agreement.
+
+WHAT THIS IS. Given several plans built from the same chain, it puts them in
+one table and orders them by expected profit per unit of capital at risk,
+under the same lognormal model that produced their probabilities. Every
+component of the score is returned, so the order can be argued with rather
+than merely accepted.
+
+WHAT THIS IS NOT, and the caveat matters more than the ranking. The expected
+values come from a model, and the model disagrees with the market in a
+specific way: it prices every strike from one at-the-money volatility, while
+the market prices each strike with its own. That disagreement is the smile.
+Any structure that looks profitable in expectation is, to a first
+approximation, one that sells strikes where the market's volatility exceeds
+the single number the model used. That is a measurement of the smile, not a
+discovered edge, and it disappears the moment the model prices each strike
+at the volatility the market actually quotes.
+
+Two more reasons the top row is not a recommendation: mid-quote premiums are
+not fills, and the friction estimate is the only part of this that touches
+the cost of trading. A structure is excluded from the ranking outright when
+friction says it is untradeable, because a positive expectation that cannot
+be entered is not an opportunity.
+"""
+
+import math
+
+CAVEAT = (
+    "Ranked by model expected profit per unit of capital at risk, under a "
+    "lognormal settlement model at a single at-the-money volatility. The "
+    "market prices each strike with its own volatility, so a positive "
+    "expectation here largely measures that disagreement rather than an "
+    "edge. Premiums are mid quotes, not fills. This is an ordering of "
+    "structures under stated assumptions, not a recommendation to trade "
+    "any of them."
+)
+
+UNBOUNDED = "unlimited"
+
+
+def _risk_capital(plan):
+    """Capital genuinely at risk, or None when the loss is unbounded.
+
+    A structure with unbounded loss has no denominator, so it cannot be
+    ranked on return per unit of risk and is reported separately rather
+    than being given a flattering finite number.
+    """
+    analysis = plan.get("analysis") or {}
+    max_loss = analysis.get("max_loss")
+    if max_loss is None or isinstance(max_loss, str):
+        return None
+    try:
+        loss = float(max_loss)
+    except (TypeError, ValueError):
+        return None
+    # The engine returns float("-inf") for an unbounded loss; the shell
+    # serialises that to the string "unlimited". Checking only the string
+    # let an infinity through as a capital-at-risk of inf, which produced a
+    # return on risk of exactly 0.0 and ranked a naked short call above a
+    # defined-risk structure.
+    if not math.isfinite(loss):
+        return None
+    # A worst case that is a profit is not capital at risk.
+    if loss >= 0:
+        return None
+    loss = abs(loss)
+    return loss if loss > 1e-9 else None
+
+
+def score_plan(plan):
+    """Score components for one plan. Every field can be None."""
+    analysis = plan.get("analysis") or {}
+    probability = plan.get("probability") or {}
+    friction = plan.get("friction") or {}
+    greeks = plan.get("net_greeks") or {}
+
+    risk = _risk_capital(plan)
+    expected = probability.get("expected_pnl")
+    expected_return = (expected / risk
+                       if expected is not None and risk else None)
+
+    reasons = []
+    tradeable = friction.get("verdict") not in ("untradeable",)
+    if not tradeable:
+        reasons.append("friction says untradeable: " +
+                       str(friction.get("reason", "")))
+    if risk is None:
+        max_loss = analysis.get("max_loss")
+        if isinstance(max_loss, str) or (
+                isinstance(max_loss, (int, float))
+                and not math.isfinite(float(max_loss))):
+            reasons.append("loss is unbounded, so return on risk is "
+                           "undefined")
+        elif isinstance(max_loss, (int, float)) and float(max_loss) >= 0:
+            reasons.append("the worst outcome is a profit, so there is no "
+                           "capital at risk to divide by")
+        else:
+            reasons.append("no capital at risk could be established")
+    if expected is None:
+        reasons.append("no model expectation available")
+    elif not math.isfinite(float(expected)):
+        reasons.append("the model expectation is not a finite number")
+    if (plan.get("meta") or {}).get("degraded"):
+        reasons.append("built from a degraded snapshot")
+
+    # Redundant today, kept on purpose. rankable below also demands a
+    # finite expected_return, and expected_return is this expectation over
+    # a finite risk, so a NaN here is caught there whatever this line says.
+    # Mutation testing confirms it: removing the isfinite call changes no
+    # observable behaviour. It stays because the second test depends on how
+    # expected_return happens to be derived, and this one does not.
+    finite_expectation = (expected is not None
+                          and math.isfinite(float(expected)))
+    return {
+        "strategy": plan.get("strategy"),
+        "trade_type": analysis.get("trade_type"),
+        "net_cash": analysis.get("net_cash"),
+        "max_gain": analysis.get("max_gain"),
+        "max_loss": analysis.get("max_loss"),
+        "capital_at_risk": risk,
+        "reward_risk": analysis.get("reward_risk"),
+        "breakevens": analysis.get("breakevens"),
+        "probability_of_profit": probability.get("profit"),
+        "probability_of_loss": probability.get("loss"),
+        "expected_pnl": expected,
+        "expected_loss": probability.get("expected_loss"),
+        "expected_return_on_risk": expected_return,
+        "net_delta": greeks.get("delta"),
+        "net_theta": greeks.get("theta"),
+        "net_vega": greeks.get("vega"),
+        "net_gamma": greeks.get("gamma"),
+        "friction_verdict": friction.get("verdict"),
+        "friction_cost": friction.get("round_trip"),
+        "rankable": bool(tradeable and risk and finite_expectation
+                         and expected_return is not None
+                         and math.isfinite(expected_return)),
+        "excluded_because": reasons,
+    }
+
+
+def rank_strategies(plans):
+    """Compare plans and order the rankable ones, best first.
+
+    Returns the full table, the ordered subset, the leader, and the caveat
+    that must travel with any of it. The leader is None when nothing is
+    rankable, which is a real outcome and not an error.
+    """
+    rows = [score_plan(plan) for plan in plans]
+    rankable = [row for row in rows if row["rankable"]]
+    rankable.sort(key=lambda r: (-(r["expected_return_on_risk"] or 0.0),
+                                 -(r["probability_of_profit"] or 0.0),
+                                 r["strategy"] or ""))
+    for position, row in enumerate(rankable, start=1):
+        row["rank"] = position
+
+    leader = rankable[0] if rankable else None
+    margin = None
+    if len(rankable) > 1:
+        first = rankable[0]["expected_return_on_risk"]
+        second = rankable[1]["expected_return_on_risk"]
+        margin = first - second
+
+    return {
+        "rows": rows,
+        "ranked": rankable,
+        "leader": leader,
+        "margin_over_runner_up": margin,
+        "rankable_count": len(rankable),
+        "excluded_count": len(rows) - len(rankable),
+        "criterion": ("model expected profit divided by capital at risk, "
+                      "ties broken by model probability of profit"),
+        "caveat": CAVEAT,
+    }

optiondesk_engine/analytics/exposure.py

@@ -0,0 +1,227 @@
+"""Dealer gamma exposure, walls, and max pain from an option chain.
+
+Copyright (C) 2026 Iman Samizadeh. Licensed under the PolyForm Noncommercial License 1.0.0.
+Commercial use requires a separate written agreement.
+The concepts follow the dealer gamma work in the author's 001-qaunt desk
+(smartsheep.witty.analytics.gex and gamma_regime), reimplemented here
+against this project's chain contract.
+
+WHAT THIS IS, AND THE ASSUMPTION IT RESTS ON. Gamma exposure asks what
+market makers would have to buy or sell to stay delta neutral as the
+underlying moves. The arithmetic is exact; the sign convention is not. It
+assumes dealers are long calls and short puts against the public, which is
+the conventional assumption and is regularly wrong for individual names,
+particularly around events and in heavily retail-traded tickers. Positive
+net exposure is read as hedging that dampens moves, negative as hedging
+that amplifies them.
+
+That assumption is stated in the output as well as here, because a number
+this easy to quote is a number that travels without its caveat.
+
+Units: exposure is expressed per one percent move in the underlying, in
+the underlying's quote currency, which is the convention that makes the
+numbers comparable across strikes and underlyings.
+"""
+
+CONTRACT_MULTIPLIER = 100.0
+
+
+def _usable(contract):
+    return (contract.get("gamma") is not None
+            and contract.get("open_interest") is not None
+            and contract.get("strike") is not None)
+
+
+def chain_exposure(contracts, spot, multiplier=CONTRACT_MULTIPLIER):
+    """Gamma exposure by strike, the walls, and the flip level.
+
+    contracts must carry gamma (from the Greek ladder) plus open interest
+    and strike. Contracts missing any of the three are counted as skipped
+    rather than treated as zero: an absent open interest is not the same
+    as no open interest, and treating it as zero quietly moves every wall.
+
+    Returns per-strike rows, the call and put walls, the estimated gamma
+    flip level, and the totals, with the sign convention stated inline.
+    """
+    if spot is None or spot <= 0:
+        raise ValueError("spot must be positive")
+
+    by_strike = {}
+    skipped = 0
+    # Counted apart because they are different facts and a note that gives
+    # one cause for the other is wrong. On a live SPY chain every contract
+    # carried open interest and the skips were all missing gamma, while the
+    # artifact said the opposite.
+    skipped_reasons = {"no_gamma": 0, "no_open_interest": 0,
+                       "no_strike": 0, "not_an_option": 0}
+    call_oi = put_oi = 0
+    call_volume = put_volume = 0
+
+    for contract in contracts:
+        kind = contract.get("type")
+        if kind not in ("call", "put"):
+            skipped += 1
+            skipped_reasons["not_an_option"] += 1
+            continue
+        volume = contract.get("volume") or 0
+        if kind == "call":
+            call_volume += int(volume)
+        else:
+            put_volume += int(volume)
+        if not _usable(contract):
+            skipped += 1
+            if contract.get("gamma") is None:
+                skipped_reasons["no_gamma"] += 1
+            elif contract.get("open_interest") is None:
+                skipped_reasons["no_open_interest"] += 1
+            else:
+                skipped_reasons["no_strike"] += 1
+            continue
+        strike = float(contract["strike"])
+        open_interest = int(contract["open_interest"])
+        gamma = float(contract["gamma"])
+        if kind == "call":
+            call_oi += open_interest
+        else:
+            put_oi += open_interest
+
+        # Exposure per one percent move, in the underlying's quote
+        # currency. gamma * S * 0.01 is the delta change over a one percent
+        # move in share terms; multiplying by S again converts that share
+        # delta into currency, and the multiplier and open interest scale
+        # it to the whole strike.
+        exposure = gamma * open_interest * multiplier * spot * spot * 0.01
+        signed = exposure if kind == "call" else -exposure
+
+        row = by_strike.setdefault(strike, {
+            "strike": strike, "call_gex": 0.0, "put_gex": 0.0,
+            "net_gex": 0.0, "call_oi": 0, "put_oi": 0,
+        })
+        row["call_gex" if kind == "call" else "put_gex"] += signed
+        row["net_gex"] += signed
+        row["call_oi" if kind == "call" else "put_oi"] += open_interest
+
+    rows = sorted(by_strike.values(), key=lambda r: r["strike"])
+    if not rows:
+        return {
+            "rows": [], "net_gex": 0.0, "call_wall": None, "put_wall": None,
+            "gamma_flip": None, "skipped": skipped,
+            "skipped_reasons": dict(skipped_reasons),
+            "put_call_oi_ratio": None, "put_call_volume_ratio": None,
+            "assumption": _ASSUMPTION,
+        }
+
+    running = 0.0
+    for row in rows:
+        running += row["net_gex"]
+        row["cumulative_gex"] = running
+
+    # A chain with no calls at all made max() return the first row with a
+    # gamma of exactly zero, which was then reported as the call wall.
+    call_candidates = [r for r in rows if r["call_gex"] > 0]
+    put_candidates = [r for r in rows if r["put_gex"] < 0]
+    call_wall = (max(call_candidates, key=lambda r: r["call_gex"])
+                 if call_candidates else None)
+    put_wall = (min(put_candidates, key=lambda r: r["put_gex"])
+                if put_candidates else None)
+
+    # Every level where cumulative exposure crosses zero, linearly
+    # interpolated between the straddling strikes. An earlier version
+    # returned the first crossing and stopped, so a profile crossing five
+    # times reported the lowest one: at spot 100 it read "flip 81.67" while
+    # the nearest crossings were at 96.79 and 102.50. The headline is now
+    # the crossing nearest spot, and the rest are returned with it.
+    crossings = []
+    for previous, current in zip(rows, rows[1:]):
+        y0, y1 = previous["cumulative_gex"], current["cumulative_gex"]
+        if (y0 < 0 <= y1) or (y0 > 0 >= y1):
+            span = y1 - y0
+            if span == 0:
+                crossings.append(current["strike"])
+            else:
+                crossings.append(previous["strike"] + (0 - y0) * (
+                    current["strike"] - previous["strike"]) / span)
+    flip = (min(crossings, key=lambda level: abs(level - spot))
+            if crossings else None)
+
+    return {
+        "rows": rows,
+        "net_gex": running,
+        "call_wall": ({"strike": call_wall["strike"],
+                       "gex": call_wall["call_gex"]} if call_wall else None),
+        "put_wall": ({"strike": put_wall["strike"],
+                      "gex": put_wall["put_gex"]} if put_wall else None),
+        "gamma_flip": flip,
+        "gamma_flip_all": crossings,
+        "gamma_flip_note": (
+            "The crossing nearest spot. There {} {} crossing(s) in total, "
+            "listed in gamma_flip_all. The cumulative profile starts at the "
+            "lowest LISTED strike rather than at zero, so extending the "
+            "strike ladder shifts the whole profile and can move every "
+            "level.".format("is" if len(crossings) == 1 else "are",
+                            len(crossings))),
+        "spot": spot,
+        "regime": ("dampening" if running > 0 else "amplifying"),
+        "skipped": skipped,
+        "skipped_reasons": dict(skipped_reasons),
+        "call_open_interest": call_oi,
+        "put_open_interest": put_oi,
+        "put_call_oi_ratio": (put_oi / call_oi) if call_oi else None,
+        "put_call_volume_ratio": ((put_volume / call_volume)
+                                  if call_volume else None),
+        "assumption": _ASSUMPTION,
+    }
+
+
+_ASSUMPTION = (
+    "Signs assume dealers are long calls and short puts against the "
+    "public. That convention is often wrong for a single name, especially "
+    "around events and in heavily retail-traded tickers, and the walls "
+    "move with it. Exposure is per one percent move in the underlying."
+)
+
+
+def max_pain(contracts, multiplier=CONTRACT_MULTIPLIER):
+    """The strike where option holders collect the least at expiry.
+
+    For every listed strike, sum what all open contracts would pay out if
+    the underlying settled there. The minimum is the conventional max pain
+    level. It is a description of where open interest sits, not a forecast
+    of where price goes, and the evidence that price gravitates to it is
+    thin. It is reported because traders ask for it, with that caveat
+    attached.
+    """
+    priced = [c for c in contracts
+              if c.get("open_interest") is not None
+              and c.get("strike") is not None
+              and c.get("type") in ("call", "put")]
+    if not priced:
+        return None
+    # Every strike pays out zero when nothing is open, and the minimum then
+    # falls on whichever strike happens to be lowest. That is a number
+    # derived from no information, so it is refused.
+    if sum(int(c["open_interest"]) for c in priced) <= 0:
+        return None
+
+    strikes = sorted({float(c["strike"]) for c in priced})
+    profile = []
+    for settle in strikes:
+        payout = 0.0
+        for contract in priced:
+            strike = float(contract["strike"])
+            open_interest = int(contract["open_interest"])
+            if contract["type"] == "call":
+                payout += max(settle - strike, 0.0) * open_interest
+            else:
+                payout += max(strike - settle, 0.0) * open_interest
+        profile.append({"strike": settle, "payout": payout * multiplier})
+
+    best = min(profile, key=lambda p: p["payout"])
+    return {
+        "strike": best["strike"],
+        "payout_at_strike": best["payout"],
+        "profile": profile,
+        "note": ("The strike at which open contracts pay out least. It "
+                 "describes where open interest sits, not where price is "
+                 "going."),
+    }