optiondesk-engine 0.3.0__tar.gz

optiondesk_engine-0.3.0/LICENSE

@@ -0,0 +1,76 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+Required Notice: Copyright 2026 Iman Samizadeh
+(https://github.com/Iman/agent-driven-options-desk-and-skills)
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

optiondesk_engine-0.3.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.5
+Name: optiondesk-engine
+Version: 0.3.0
+Summary: Option pricing and Greek analytics engine for the option desk
+Author: Iman Samizadeh
+License: PolyForm-Noncommercial-1.0.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'

optiondesk_engine-0.3.0/README.md

@@ -0,0 +1,34 @@
+# optiondesk-engine
+
+Pricing and analytics for the option desk. Licensed under the PolyForm
+Noncommercial License 1.0.0, the same terms as the rest of the project. See
+`LICENSE` for the full text and `../LICENSES.md` for what that permits.
+
+The engine is pure computation. It has no network access, no data providers,
+no file system layout opinions and no dependencies outside the standard
+library. It takes numbers and returns numbers, which is what makes it testable
+against closed-form and finite-difference benchmarks.
+
+The shell fetches data and writes artifacts. The engine turns the data
+into analytics. Neither imports the other's internals: the shell reaches the
+engine through one adapter module, and degrades with an explicit message when
+the engine is not installed.
+
+Current contents:
+
+- `pricing/`: European Black-Scholes-Merton with a continuous dividend
+  yield, a Newton-Raphson implied volatility solver with a bisection
+  fallback that refuses prices carrying no volatility information, and the
+  full analytic Greek ladder from first to third order in documented units.
+- `strategies/`: the expiry payoff engine, the five-direction outlook
+  framework, the structure playbook, and the friction and liquidity gate.
+- `analytics/`: dealer gamma exposure with walls and flip levels, max pain,
+  volatility smile geometry, and the structure ranking.
+- `simulation/`: GARCH(1,1) with Student-t innovations sampled by adaptive
+  random-walk Metropolis, posterior predictive paths, value at risk and
+  expected shortfall, and position profit distributions.
+- `backtest/`: the historical runner with modelled premiums, the
+  performance and significance statistics, and forward-test marking.
+
+Read DISCLAIMER.md at the repository root before using any of it. Modelled
+premiums are not achievable prices.

optiondesk_engine-0.3.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "optiondesk-engine"
+version = "0.3.0"
+description = "Option pricing and Greek analytics engine for the option desk"
+requires-python = ">=3.11"
+license = { text = "PolyForm-Noncommercial-1.0.0" }
+authors = [{ name = "Iman Samizadeh" }]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/optiondesk_engine"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

optiondesk_engine-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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."),
+    }