optiondesk 0.3.0__py3-none-any.whl

optiondesk/__init__.py

@@ -0,0 +1,12 @@
+"""Option desk shell.
+
+Licensed under the PolyForm Noncommercial License 1.0.0; see LICENSE.
+Data retrieval, schema-validated artifacts, agent runtime
+adapters and a local dashboard. The analytics live in the engine
+component, under the same licence; see LICENSES.md at the repository root.
+
+Nothing in this package is investment advice. See DISCLAIMER.md.
+"""
+
+__version__ = "0.3.0"
+LICENSE = "PolyForm-Noncommercial-1.0.0"

optiondesk/artifacts.py

@@ -0,0 +1,197 @@
+"""Artifact envelope and atomic writing.
+
+Every artifact this project writes carries the same meta block, because a
+number without provenance cannot be audited later. The block records what
+produced it, when, from which provider, and whether the result was degraded.
+
+Atomic write: serialise to a temporary file in the destination directory,
+then os.replace. A reader can then never catch a half-written file, and a
+failed run cannot leave a truncated artifact that looks complete.
+"""
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from optiondesk import __version__
+from optiondesk.config import artifact_dir
+
+# Carried inside every artifact. Short by necessity, and it points at the
+# full terms rather than trying to restate them.
+DISCLAIMER = (
+    "Research output, not investment advice, and not a recommendation or "
+    "solicitation. Option premiums here are theoretical model values, not "
+    "quotes and not achievable fills. Market data is third-party, may be "
+    "delayed or wrong, and its redistribution is governed by the provider's "
+    "terms. No warranty. See DISCLAIMER.md."
+)
+
+LICENSE_NOTE = (
+    "Produced by optiondesk under the PolyForm Noncommercial License 1.0.0. "
+    "Noncommercial use is permitted; commercial use requires a separate "
+    "written agreement with the copyright holder. See LICENSE and "
+    "LICENSES.md."
+)
+
+
+def utc_now():
+    """Current UTC time as an ISO-8601 string ending in Z.
+
+    Every artifact carries one, so timestamps written on different machines
+    still order correctly.
+    """
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def envelope(schema, tool, provider_used, degraded=False,
+             degraded_reason=None, inputs=None, engine_version=None,
+             notes=None):
+    """Build the meta block shared by every artifact.
+
+    Two distinct fields, because collapsing them destroys the signal.
+
+    degraded means the run produced lower quality output than this pipeline
+    normally can: a provider fell back, a rate could not be fetched, the
+    analytics engine was absent. A consumer should hesitate before quoting
+    the numbers, and degraded_reason says why.
+
+    notes records ordinary observations that are not defects. A chain where
+    some far wing contracts carry no quotes and therefore no implied
+    volatility is a normal chain, not a broken run. Marking that degraded
+    would make almost every artifact degraded and the flag would stop
+    meaning anything.
+    """
+    return {
+        "schema": schema,
+        "generated_utc": utc_now(),
+        "tool": tool,
+        "shell_version": __version__,
+        "engine_version": engine_version,
+        "provider_used": provider_used,
+        "degraded": bool(degraded),
+        "degraded_reason": degraded_reason,
+        "notes": list(notes or []),
+        "inputs": inputs or {},
+        "disclaimer": DISCLAIMER,
+        "license": LICENSE_NOTE,
+    }
+
+
+ARCHIVE_DIRNAME = "archive"
+
+
+def _archive_stamp(path):
+    """The time the outgoing artifact was generated, for its archived name.
+
+    Its own `meta.generated_utc` is preferred over the file's mtime,
+    because the mtime is when the bytes landed and the envelope is when the
+    measurement was taken. They differ whenever a file is copied.
+    """
+    try:
+        with open(path, encoding="utf-8") as handle:
+            stamp = json.load(handle).get("meta", {}).get("generated_utc")
+    except (ValueError, OSError, AttributeError):
+        stamp = None
+    if not isinstance(stamp, str) or not stamp:
+        try:
+            stamp = datetime.fromtimestamp(
+                path.stat().st_mtime, timezone.utc).isoformat()
+        except OSError:
+            stamp = utc_now()
+    # Colons are legal on this filesystem and a nuisance on others.
+    return stamp.replace(":", "").replace("-", "").replace("+0000", "Z")
+
+
+def archive_existing(path):
+    """Move an artifact about to be replaced into the archive.
+
+    WHY THE LIVE NAME DOES NOT CHANGE. Filenames are keyed by underlying
+    and expiry, so re-pulling the same chain replaced the previous one
+    outright and no measurement quoted from it could be produced again.
+    Timestamping the live file would fix that and break every consumer
+    that resolves the newest artifact by name: the dashboard, `expiries`,
+    the plan reuse in `compare`, and the graph's stage check. So the
+    timestamp goes on the outgoing copy instead, and the live name is
+    exactly what it was.
+
+    Identical content is not archived. Re-running a command that produces
+    the same bytes is not a new measurement, and archiving it would fill
+    the directory with copies of one answer.
+
+    Returns the archived path, or None if there was nothing to archive.
+    Never raises: losing the archive is worse than nothing, but losing the
+    write because the archive failed would be worse still.
+    """
+    if os.environ.get("OPTIONDESK_ARCHIVE", "1") == "0":
+        return None
+    try:
+        if not path.exists():
+            return None
+        archive_dir = path.parent / ARCHIVE_DIRNAME / utc_now()[:10]
+        archive_dir.mkdir(parents=True, exist_ok=True)
+        target = archive_dir / "{}_{}{}".format(
+            path.stem, _archive_stamp(path), path.suffix)
+        if target.exists():
+            return None
+        os.replace(path, target)
+        return target
+    except OSError:
+        return None
+
+
+def write_json(payload, filename, directory=None):
+    """Write one artifact atomically. Returns the path written.
+
+    Raises ValueError if the payload contains a NaN or an infinity, which
+    is deliberate: those are not representable in strict JSON, and an
+    artifact that only Python can read is not an interchange format.
+
+    An artifact this replaces is moved into `archive/<date>/` first, under
+    a name carrying the time it was generated. Set OPTIONDESK_ARCHIVE=0 to
+    turn that off.
+    """
+    target_dir = Path(directory) if directory else artifact_dir()
+    target_dir.mkdir(parents=True, exist_ok=True)
+    path = target_dir / filename
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    with open(tmp, "w", encoding="utf-8") as handle:
+        # allow_nan is off deliberately. The default writes NaN and
+        # Infinity as bare tokens, which Python reads back and a strict
+        # RFC 8259 parser rejects, so a non-finite number would leave this
+        # process looking healthy and break somewhere else. Failing here
+        # names the field instead.
+        json.dump(payload, handle, indent=1, sort_keys=False,
+                  allow_nan=False)
+        handle.write("\n")
+    # After the temporary file is written, so a serialisation failure
+    # cannot archive the old artifact and then leave nothing in its place.
+    if path.exists() and path.read_bytes() != tmp.read_bytes():
+        archive_existing(path)
+    os.replace(tmp, path)
+    return path
+
+
+def read_json(path):
+    """Read one artifact from disk.
+
+    Raises rather than returning an empty default, because a caller that
+    silently reads nothing goes on to report on an empty desk as though it were
+    a quiet one.
+    """
+    with open(path, "r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def latest(pattern, directory=None):
+    """Most recently modified artifact matching a glob, or None.
+
+    Used by the dashboard and by tools that chain off the previous step
+    without being told the exact filename.
+    """
+    target_dir = Path(directory) if directory else artifact_dir()
+    if not target_dir.exists():
+        return None
+    matches = sorted(target_dir.glob(pattern),
+                     key=lambda p: p.stat().st_mtime, reverse=True)
+    return matches[0] if matches else None

optiondesk/cli/__init__.py

@@ -0,0 +1,7 @@
+"""Command line entry points.
+
+Each command does one thing, writes one schema-validated artifact, and
+prints a short JSON summary to stdout. The summary is what an agent reads;
+the artifact is what the dashboard and later steps read. Both carry the same
+provenance and the same disclaimer.
+"""

optiondesk/cli/__main__.py

@@ -0,0 +1,122 @@
+"""optiondesk command dispatcher."""
+
+import argparse
+import json
+import sys
+
+from optiondesk import __version__, engine_bridge
+from optiondesk.artifacts import DISCLAIMER, artifact_dir
+from optiondesk.cli import backtest as backtest_cmd
+from optiondesk.cli import chain as chain_cmd
+from optiondesk.cli import forward as forward_cmd
+from optiondesk.cli import greeks as greeks_cmd
+from optiondesk.cli import keys as keys_cmd
+from optiondesk.cli import plots as plots_cmd
+from optiondesk.cli import compare as compare_cmd
+from optiondesk.cli import exposure as exposure_cmd
+from optiondesk.cli import expiries as expiries_cmd
+from optiondesk.cli import simulate as simulate_cmd
+from optiondesk.cli import strategy as strategy_cmd
+from optiondesk.config import configured_providers
+from optiondesk.providers import describe_all
+
+
+def _doctor(_args):
+    """Report what is installed, what is reachable, and what is missing."""
+    return {
+        "shell_version": __version__,
+        "artifact_dir": str(artifact_dir()),
+        "engine": engine_bridge.status(),
+        "providers": describe_all(),
+        "credentials": configured_providers(),
+        "disclaimer": DISCLAIMER,
+    }
+
+
+def build_parser():
+    """Assemble the top level parser by asking each command module to register
+    its own arguments.
+    """
+    parser = argparse.ArgumentParser(
+        prog="optiondesk",
+        description="Option desk: chain retrieval, analytics, artifacts. "
+                    "Research software, not investment advice. See "
+                    "DISCLAIMER.md.")
+    parser.add_argument("--version", action="version",
+                        version="optiondesk {}".format(__version__))
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    chain_cmd.add_arguments(sub.add_parser(
+        "chain", help="retrieve an option chain snapshot"))
+    greeks_cmd.add_arguments(sub.add_parser(
+        "greeks", help="full Greek ladder from a snapshot"))
+    strategy_cmd.add_arguments(sub.add_parser(
+        "strategy", help="build a multi-leg strategy from a snapshot"))
+    exposure_cmd.add_arguments(sub.add_parser(
+        "exposure", help="dealer gamma, walls, max pain and smile geometry"))
+    plots_cmd.add_arguments(sub.add_parser(
+        "plots", help="write chat-ready market and Greek PNG plots"))
+    expiries_cmd.add_arguments(sub.add_parser(
+        "expiries", help="list available expiries and what is on disk"))
+    compare_cmd.add_arguments(sub.add_parser(
+        "compare", help="every structure side by side, ranked"))
+    simulate_cmd.add_arguments(sub.add_parser(
+        "simulate", help="GARCH-t posterior, forward paths and tail risk"))
+    backtest_cmd.add_arguments(sub.add_parser(
+        "backtest", help="run a structure across real history, modelled "
+                         "premiums"))
+    forward_cmd.add_arguments(sub.add_parser(
+        "forward", help="paper ledger: open, mark, close, status"))
+    keys_cmd.add_arguments(sub.add_parser(
+        "keys", help="see, set or locate provider credentials"))
+    sub.add_parser("doctor",
+                   help="report engine, provider and credential status")
+
+    dash = sub.add_parser("dashboard", help="serve the local dashboard")
+    dash.add_argument("--host", default="127.0.0.1")
+    dash.add_argument("--port", type=int, default=8787)
+    dash.add_argument("--out-dir", default=None,
+                      help="artifact directory to read")
+    return parser
+
+
+def _dashboard(args):
+    from optiondesk.dashboard.app import serve
+    serve(args.host, args.port, args.out_dir)
+    return {"served": "http://{}:{}".format(args.host, args.port)}
+
+
+HANDLERS = {
+    "chain": chain_cmd.run,
+    "greeks": greeks_cmd.run,
+    "strategy": strategy_cmd.run,
+    "exposure": exposure_cmd.run,
+    "plots": plots_cmd.run,
+    "expiries": expiries_cmd.run,
+    "compare": compare_cmd.run,
+    "simulate": simulate_cmd.run,
+    "backtest": backtest_cmd.run,
+    "forward": forward_cmd.run,
+    "keys": keys_cmd.run,
+    "doctor": _doctor,
+    "dashboard": _dashboard,
+}
+
+
+def main(argv=None):
+    """Dispatch argv to the named subcommand and return its exit code."""
+    args = build_parser().parse_args(argv)
+    try:
+        result = HANDLERS[args.command](args)
+    except Exception as exc:
+        # One error shape for every failure, so an agent parsing stdout does
+        # not have to distinguish a traceback from a result.
+        print(json.dumps({"error": type(exc).__name__, "message": str(exc)},
+                         indent=1))
+        return 1
+    print(json.dumps(result, indent=1, default=str))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

optiondesk/cli/backtest.py

@@ -0,0 +1,223 @@
+"""optiondesk backtest: a structure entered repeatedly across real history.
+
+Real underlying closes, modelled premiums. Read the honesty field in the
+output before quoting any number from it, and read it again before showing
+anyone else.
+
+Alongside the performance statistics, this reports a permutation test and a
+bootstrap interval, because a mean return without a statement of how easily
+it could have arisen by chance is not a result. It also runs the same rule
+against the underlying itself, so a structure that merely tracks the market
+is visible as such rather than being credited with the market's move.
+"""
+
+import argparse
+import json
+
+from optiondesk import engine_bridge
+from optiondesk.artifacts import envelope, write_json
+from optiondesk.contracts import BACKTEST, SCHEMA_FILES, validate
+from optiondesk.providers import CAP_UNDERLYING_HISTORY, resolve
+
+
+def add_arguments(parser):
+    """Register the window and cadence: holding days, entry interval, lookback,
+    history period, rate, dividend yield, size, provider and output directory.
+    """
+    parser.add_argument("symbol", help="underlying ticker")
+    parser.add_argument("strategy", help="structure to test, for example "
+                                         "iron_condor")
+    parser.add_argument("--holding-days", type=int, default=30,
+                        dest="holding_days",
+                        help="trading days from entry to expiry; the model "
+                             "chain is priced over the same span")
+    parser.add_argument("--entry-every", type=int, default=5,
+                        dest="entry_every",
+                        help="trading days between entries")
+    parser.add_argument("--lookback", type=int, default=60,
+                        help="window for the trailing volatility estimate")
+    parser.add_argument("--period", default="5y",
+                        help="how much history to test, for example 5y")
+    parser.add_argument("--rate", type=float, default=0.04,
+                        help="risk-free rate per 1.00 used for pricing")
+    parser.add_argument("--dividend-yield", type=float, default=0.0,
+                        dest="dividend_yield")
+    parser.add_argument("--size", type=float, default=1.0,
+                        help="contracts per leg")
+    parser.add_argument("--provider", default=None)
+    parser.add_argument("--out-dir", default=None)
+    return parser
+
+
+def _benchmark(prices, dates, holding_days, entry_every, lookback,
+               engine_backtest):
+    """The same schedule, holding the underlying instead of the structure.
+
+    Without this, a structure that is simply long the market gets credit
+    for the market's drift and looks like a strategy.
+    """
+    returns = []
+    index = lookback
+    while index + holding_days < len(prices):
+        entry, exit_price = prices[index], prices[index + holding_days]
+        if entry > 0:
+            returns.append(exit_price / entry - 1.0)
+        index += entry_every
+    stats = engine_backtest.performance_stats(returns, holding_days)
+    if stats:
+        stats.pop("equity_curve", None)
+    return {"description": ("buy and hold the underlying over the same "
+                            "windows, for comparison"),
+            "statistics": stats}
+
+
+def run(args):
+    """Enter one structure repeatedly across real history and write a backtest
+    artifact with its honesty statement attached.
+    """
+    engine = engine_bridge.require()
+    strategies = engine_bridge.strategies()
+    engine_backtest = engine_bridge.backtest()
+
+    provider, choice = resolve(CAP_UNDERLYING_HISTORY, args.provider)
+    history = provider.underlying_history(args.symbol, period=args.period)
+
+    result = engine_backtest.run_backtest(
+        strategies, engine["bs_price"], history["closes"], history["dates"],
+        args.strategy, holding_days=args.holding_days,
+        entry_every=args.entry_every, lookback=args.lookback,
+        rate=args.rate, dividend_yield=args.dividend_yield, size=args.size)
+
+    returns = result["returns"]
+    statistics = engine_backtest.performance_stats(returns,
+                                                   args.holding_days)
+    # Consecutive entries share days whenever the hold is longer than the
+    # spacing between entries, and every statistic below is computed on
+    # returns that therefore are not independent. The block is how many
+    # consecutive trades overlap: thirty day holds entered every five
+    # trading days give six, which is exactly where the measured
+    # autocorrelation collapses.
+    overlap_block = max(1, -(-int(args.holding_days) // max(1, int(
+        args.entry_every))))
+    significance = engine_backtest.permutation_p_value(
+        returns, block=overlap_block)
+    interval = engine_backtest.bootstrap_mean_interval(
+        returns, block=overlap_block)
+    benchmark = _benchmark(history["closes"], history["dates"],
+                           args.holding_days, args.entry_every,
+                           args.lookback, engine_backtest)
+
+    notes = []
+    # `returns` holds return on capital at risk, and a trade only appears in
+    # it when that capital is definable. A structure with an unbounded loss,
+    # such as a ratio spread, produces trades with no denominator, so the
+    # two counts diverge. Reporting the shorter one as the trade count said
+    # "only 0 trades" about a run that entered 52, which names the wrong
+    # problem and sends the reader looking for missing data.
+    entered = len(result["trades"])
+    measurable = len(returns)
+    if entered and not measurable:
+        notes.append(
+            "{} trades were entered and none has a definable capital at "
+            "risk, because this structure's maximum loss is unbounded. "
+            "Return on risk has no denominator, so no statistic here can be "
+            "computed. Every entry and exit is still in the trade list, and "
+            "profit in cash terms is still there to read.".format(entered))
+    elif measurable < entered:
+        notes.append(
+            "{} of {} trades have no definable capital at risk and are "
+            "excluded from every statistic below".format(
+                entered - measurable, entered))
+    if measurable and measurable < 30:
+        notes.append("only {} trades: too few for any statistic here to "
+                     "carry weight".format(measurable))
+    if result["skipped"]:
+        notes.append("{} entries skipped, mostly where no viable structure "
+                     "existed at that volatility".format(
+                         len(result["skipped"])))
+    if significance and significance.get("block", 1) > 1:
+        notes.append(
+            "Entries overlap: each trade shares days with {} of its "
+            "neighbours, so the significance test flips signs a block at a "
+            "time and the interval resamples blocks. Treating these as {} "
+            "independent trades would understate the standard error by "
+            "roughly a factor of two.".format(
+                significance["block"] - 1, len(returns)))
+    if significance and significance["p_value"] > 0.05:
+        notes.append("the permutation test cannot distinguish this result "
+                     "from a rule with no edge")
+
+    equity_curve = (statistics or {}).pop("equity_curve", None)
+
+    payload = {
+        "meta": envelope(
+            schema=BACKTEST,
+            tool="optiondesk backtest",
+            provider_used=provider.name,
+            degraded=bool(choice["degraded"]),
+            degraded_reason="; ".join(choice["skipped"]) or None,
+            inputs={"symbol": args.symbol, "strategy": args.strategy,
+                    "holding_days": args.holding_days,
+                    "entry_every": args.entry_every,
+                    "period": args.period},
+            engine_version=engine["version"],
+            notes=notes,
+        ),
+        "underlying": args.symbol.upper(),
+        "strategy": args.strategy,
+        "premium_source": result["premium_source"],
+        "honesty": result["honesty"],
+        "settings": dict(result["settings"], equity_curve=equity_curve),
+        "statistics": statistics,
+        "significance": significance,
+        "interval": interval,
+        "benchmark": benchmark,
+        "trades": result["trades"],
+        "skipped": result["skipped"],
+    }
+    validate(payload, SCHEMA_FILES[BACKTEST])
+    filename = "backtest_{}_{}_{}d.json".format(
+        args.symbol.upper(), args.strategy, args.holding_days)
+    out = write_json(payload, filename, args.out_dir)
+
+    return {
+        "artifact": str(out),
+        "underlying": args.symbol.upper(),
+        "strategy": args.strategy,
+        "degraded": bool(choice["degraded"]),
+        "degraded_reason": "; ".join(choice["skipped"]) or None,
+        "trades": (statistics or {}).get("trades", 0),
+        "trades_entered": len(result["trades"]),
+        "win_rate": (statistics or {}).get("win_rate"),
+        "mean_return_on_risk": (statistics or {}).get("mean_return"),
+        "total_return_on_risk": (statistics or {}).get(
+            "total_return_on_risk"),
+        "max_drawdown_in_risk_units": (statistics or {}).get(
+            "max_drawdown_in_risk_units"),
+        "sharpe_per_trade": (statistics or {}).get("sharpe_per_trade"),
+        "p_value": (significance or {}).get("p_value"),
+        # How many consecutive trades share days. Published because a
+        # p-value computed at block 1 on overlapping windows is a different
+        # and more flattering number than one computed at the real block,
+        # and a reader comparing two runs has to be able to see which.
+        "overlap_block": (significance or {}).get("block"),
+        "mean_interval": ([interval["lower"], interval["upper"]]
+                          if interval else None),
+        "interval_excludes_zero": (interval or {}).get("excludes_zero"),
+        "benchmark_mean": ((benchmark["statistics"] or {}).get("mean_return")
+                           if benchmark["statistics"] else None),
+        "skipped_entries": len(result["skipped"]),
+        "notes": notes,
+        "honesty": result["honesty"],
+    }
+
+
+def main(argv=None):
+    """Parse argv for this command alone and run it, so the command works when
+    invoked directly as well as through the dispatcher.
+    """
+    parser = add_arguments(argparse.ArgumentParser(
+        prog="optiondesk backtest", description=__doc__.splitlines()[0]))
+    args = parser.parse_args(argv)
+    print(json.dumps(run(args), indent=1, default=str))
+    return 0