optiondesk-agent 0.3.0__py3-none-any.whl

optiondesk_agent/__init__.py

@@ -0,0 +1,36 @@
+"""LangChain bindings for the option desk.
+
+Licensed under the PolyForm Noncommercial License 1.0.0; see LICENSE.
+This package is a language layer over the shell: it turns
+commands into tools, artifacts into documents, and questions into prompts
+that can only be answered from what is on disk.
+
+It never computes a number. Everything quantitative comes from the engine,
+which does not depend on this package.
+"""
+
+from optiondesk_agent.artifacts import ArtifactStore
+from optiondesk_agent.prompts import (
+    REPORTING_RULES,
+    build_answer_prompt,
+    build_router_prompt,
+)
+from optiondesk_agent.tools import desk_tools, tool_specs
+
+# Imported lazily by name: the graph needs langgraph, which is an optional
+# extra, and importing it here would make the whole package require it.
+__lazy__ = ("build_desk_graph", "open_desk")
+
+
+def __getattr__(name):
+    if name in __lazy__:
+        from optiondesk_agent import graph
+
+        return getattr(graph, name)
+    raise AttributeError(name)
+
+__version__ = "0.3.0"
+
+__all__ = ["ArtifactStore", "desk_tools", "tool_specs",
+           "build_answer_prompt", "build_router_prompt", "REPORTING_RULES",
+           "build_desk_graph", "open_desk", "__version__"]

optiondesk_agent/artifacts.py

@@ -0,0 +1,263 @@
+"""The artifact directory as retrievable documents.
+
+Artifacts are JSON, often large, and a language model reading one whole is
+mostly reading strike ladders. This turns each into a short document that
+carries what a question is usually about: what it is, when it was made,
+whether it is degraded, and the handful of numbers a person would quote.
+
+The full artifact is always one path away, and the path is in the document,
+so nothing here prevents a caller from reading the detail when the detail
+is the point.
+"""
+
+import json
+from pathlib import Path
+
+KINDS = ("chain", "greeks", "exposure", "strategy", "comparison",
+         "simulation", "backtest")
+
+
+def _load(path):
+    try:
+        with open(path, encoding="utf-8") as handle:
+            payload = json.load(handle)
+    except (ValueError, OSError):
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def _percent(value, digits=2):
+    return "n/a" if value is None else "{:.{d}f}%".format(value * 100,
+                                                          d=digits)
+
+
+def _meta(payload):
+    """The artifact's envelope, or an empty one.
+
+    The envelope carries the degraded flag, so it is read on every path
+    that describes an artifact and is the one part that cannot be allowed
+    to fail. `payload.get("meta", {})` is not enough: it returns the value
+    when the key is present and null, so the default never fires, and a
+    meta that is present but is not an object fails the same way.
+    """
+    meta = payload.get("meta")
+    return meta if isinstance(meta, dict) else {}
+
+
+def _summarise(kind, payload, path):
+    """One short paragraph per artifact, in the terms a person would use.
+
+    Never raises for any JSON object, which is all _load lets through. What
+    it cannot read it says it cannot read, because this runs over every
+    file in the directory in one pass and an exception here costs the
+    caller every other artifact as well.
+    """
+    meta = _meta(payload)
+    header = "{} for {}{}, generated {}".format(
+        kind, payload.get("underlying", "unknown"),
+        " expiry {}".format(payload["expiry"]) if payload.get("expiry")
+        else "", meta.get("generated_utc", "unknown"))
+    lines = [header]
+
+    if meta.get("degraded"):
+        lines.append("DEGRADED: {}".format(meta.get("degraded_reason")))
+    for note in (meta.get("notes") or [])[:3]:
+        lines.append("note: {}".format(note))
+
+    # The lines above are the ones the reporting rules turn on: what this
+    # is, when it was made, and whether it is degraded. They are built
+    # before this point and kept whatever happens next.
+    #
+    # Nothing validates an artifact on the way in. records() accepts any
+    # JSON object whose filename prefix is a known kind, so a file written
+    # by an older schema, or by something that is not the desk at all,
+    # reaches here intact. Reading a field it does not have used to raise
+    # through context_for, which summarises the whole directory in one
+    # pass: one bad file and the model was told nothing about any
+    # underlying. Losing this artifact's numbers is the smaller failure,
+    # and saying so is what keeps it from reading as a clean artifact.
+    try:
+        if kind == "chain":
+            counts = payload.get("counts", {})
+            lines.append(
+                "spot {} as of {}. {} contracts, {} with a usable implied "
+                "volatility, {} without.".format(
+                    payload.get("spot"), payload.get("spot_asof"),
+                    len(payload.get("contracts", [])), counts.get("with_iv"),
+                    counts.get("without_iv")))
+        elif kind == "greeks":
+            rows = payload.get("rows", [])
+            skipped = payload.get("skipped") or {}
+            lines.append(
+                "{} contracts graded, {} skipped for having no implied "
+                "volatility.".format(len(rows), skipped.get("no_iv")))
+            if rows:
+                spot = payload.get("spot")
+                atm = min(rows, key=lambda r: abs(r["strike"] - spot))
+                lines.append(
+                    "at the money {} strike {}: iv {}, delta {:.4f}, gamma "
+                    "{:.5f}, vega {:.2f}, theta {:.3f} per day.".format(
+                        atm["type"], atm["strike"], _percent(atm.get("iv")),
+                        atm.get("delta", 0), atm.get("gamma", 0),
+                        atm.get("vega", 0), atm.get("theta", 0)))
+        elif kind == "exposure":
+            exposure = payload.get("exposure", {})
+            smile = payload.get("smile") or {}
+            pain = payload.get("max_pain") or {}
+            lines.append(
+                "net gamma exposure {:.0f} per one percent move, regime {}. "
+                "call wall {}, put wall {}, flip {}. max pain {}. put to call "
+                "open interest {}.".format(
+                    exposure.get("net_gex", 0), exposure.get("regime"),
+                    (exposure.get("call_wall") or {}).get("strike"),
+                    (exposure.get("put_wall") or {}).get("strike"),
+                    exposure.get("gamma_flip"), pain.get("strike"),
+                    exposure.get("put_call_oi_ratio")))
+            lines.append(
+                "at the money volatility {}, 25 delta risk reversal {}, "
+                "expected move {}.".format(
+                    _percent(smile.get("atm_iv")),
+                    _percent(smile.get("risk_reversal")),
+                    smile.get("expected_move")))
+            lines.append("assumption: {}".format(exposure.get("assumption")))
+        elif kind == "strategy":
+            analysis = payload.get("analysis", {})
+            lines.append(
+                "{} {}: net {}, breakevens {}, max gain {}, max "
+                "loss {}.".format(
+                    payload.get("strategy"), analysis.get("trade_type"),
+                    analysis.get("net_cash"), analysis.get("breakevens"),
+                    analysis.get("max_gain"), analysis.get("max_loss")))
+            probability = payload.get("probability") or {}
+            if probability.get("profit") is not None:
+                lines.append("model probability of profit {}.".format(
+                    _percent(probability["profit"], 1)))
+            friction = payload.get("friction") or {}
+            if friction.get("verdict"):
+                lines.append("friction {}: {}".format(friction["verdict"],
+                                                      friction.get("reason")))
+        elif kind == "comparison":
+            leader = payload.get("leader") or {}
+            lines.append("{} structures ranked, {} excluded. Leader {} at {} "
+                         "expected return on capital at risk.".format(
+                             payload.get("rankable_count"),
+                             payload.get("excluded_count"),
+                             leader.get("strategy"),
+                             _percent(
+                                 leader.get("expected_return_on_risk"), 1)))
+            lines.append("criterion: {}".format(payload.get("criterion")))
+            lines.append("caveat: {}".format(payload.get("caveat")))
+        elif kind == "simulation":
+            posterior = payload.get("posterior", {})
+            risk = payload.get("risk") or {}
+            simulation = payload.get("simulation", {})
+            lines.append(
+                "horizon {} days, {} paths, converged {}. value at risk "
+                "95 {}, expected shortfall 95 {}.".format(
+                    simulation.get("horizon_days"), simulation.get("paths"),
+                    posterior.get("converged"), _percent(risk.get("var_95")),
+                    _percent(risk.get("es_95"))))
+            for structure in (payload.get("structures") or [])[:5]:
+                lines.append(
+                    "{}: probability of profit {} under realised volatility "
+                    "against {} under implied.".format(
+                        structure.get("strategy"),
+                        _percent(structure.get(
+                            "realised_vol_probability_of_profit"), 1),
+                        _percent(structure.get(
+                            "implied_vol_probability_of_profit"), 1)))
+        elif kind == "backtest":
+            statistics = payload.get("statistics") or {}
+            significance = payload.get("significance") or {}
+            lines.append(
+                "{} over {} trades: win rate {}, mean return on risk {}, "
+                "p value {}.".format(
+                    payload.get("strategy"), statistics.get("trades"),
+                    _percent(statistics.get("win_rate"), 1),
+                    _percent(statistics.get("mean_return")),
+                    significance.get("p_value")))
+            lines.append("honesty: {}".format(payload.get("honesty")))
+    except Exception as exc:
+        lines.append(
+            "detail unavailable: this {} artifact does not match the "
+            "current schema, so no number is quoted from it ({}: {}). "
+            "Re-run the command that writes it."
+            .format(kind, type(exc).__name__, exc))
+
+    lines.append("full artifact: {}".format(path))
+    return "\n".join(str(line) for line in lines)
+
+
+class ArtifactStore:
+    """Read only view of the artifact directory, as documents."""
+
+    def __init__(self, directory=None):
+        if directory is None:
+            from optiondesk.artifacts import artifact_dir
+
+            directory = artifact_dir()
+        self.directory = Path(directory)
+
+    def records(self, underlying=None, kinds=None):
+        """Every artifact as (kind, payload, path), newest first.
+
+        The sort key stats each file, and the directory is written to by
+        the commands while this reads it, so a file can vanish between the
+        glob and the stat. That raised FileNotFoundError out of here,
+        which is a failure of the whole read rather than of one artifact,
+        and it would land on whoever happened to be summarising while a
+        refresh ran. A file that is gone sorts last and is then dropped by
+        _load, which is what should happen to it.
+        """
+        if not self.directory.exists():
+            return []
+
+        def _age(path):
+            try:
+                return path.stat().st_mtime
+            except OSError:
+                return float("-inf")
+
+        out = []
+        for path in sorted(self.directory.glob("*.json"), key=_age,
+                           reverse=True):
+            kind = path.name.split("_")[0]
+            if kind not in KINDS or (kinds and kind not in kinds):
+                continue
+            payload = _load(path)
+            if payload is None:
+                continue
+            if underlying and str(payload.get("underlying", "")).upper() \
+                    != underlying.upper():
+                continue
+            out.append((kind, payload, str(path)))
+        return out
+
+    def documents(self, underlying=None, kinds=None):
+        """LangChain documents, one per artifact."""
+        from langchain_core.documents import Document
+
+        documents = []
+        for kind, payload, path in self.records(underlying, kinds):
+            documents.append(Document(
+                page_content=_summarise(kind, payload, path),
+                metadata={
+                    "kind": kind,
+                    "underlying": payload.get("underlying"),
+                    "expiry": payload.get("expiry"),
+                    "generated_utc": _meta(payload).get("generated_utc"),
+                    "degraded": bool(_meta(payload).get("degraded")),
+                    "path": path,
+                },
+            ))
+        return documents
+
+    def context_for(self, underlying=None, kinds=None, limit=12):
+        """A single context string, newest first, ready for a prompt."""
+        blocks = []
+        for kind, payload, path in self.records(underlying, kinds)[:limit]:
+            blocks.append(_summarise(kind, payload, path))
+        if not blocks:
+            return ("No artifacts are on disk for this request. Nothing can "
+                    "be answered from data that has not been pulled.")
+        return "\n\n".join(blocks)

optiondesk_agent/graph.py

@@ -0,0 +1,341 @@
+"""A desk routine as a state graph, with a bounded loop.
+
+Copyright (C) 2026 Iman Samizadeh. PolyForm Noncommercial 1.0.0, like the rest of this project.
+
+WHAT THIS IS FOR. Opening a desk on an underlying is not one call, it is a
+short dependency chain: a chain snapshot, then a Greek ladder from it, then
+positioning, then structures, then a comparison. Each step needs the
+previous one's artifact. Written as a script that is a sequence; written as
+a graph it becomes something you can inspect, resume, and stop early when
+the data says stop.
+
+THE LOOP, AND WHY IT IS BOUNDED. The gather node runs one missing step per
+visit and comes back. It loops until the artifact set is complete, the
+budget is spent, or a step fails in a way repeating cannot fix. Three
+distinct exits, because "it finished", "it ran out of turns" and "it broke"
+are three different outcomes and collapsing them is how an agent ends up
+reporting success on an empty directory.
+
+There is no model in this graph. Every node calls a deterministic command
+and reads an artifact, so the same inputs give the same outputs and a
+failure is reproducible. A language model belongs at the edges, deciding
+what to ask for and how to say what came back, and there is a node for that
+which stays inert unless you pass one in.
+
+WHAT COMPLETE DOES NOT MEAN. This graph reports that every stage produced
+an artifact. It does not report that the artifacts are right, and those are
+different claims. Three independent verifications in September 2026 found
+eleven defects in numbers that every stage of this graph would have called
+complete: a solver refusing contracts it could identify, significance tests
+assuming an independence that overlapping windows do not have, a maximum
+that was a property of its own scan window. The gather node checks that a
+file appeared. Nothing here checks what is in it.
+
+The report node carries degradation through for that reason. When a stage
+writes an artifact marked degraded, the summary says so rather than
+presenting a complete run, because "every stage finished" and "the figures
+can be relied on" are the two claims most easily confused by anything
+reading this output, human or otherwise.
+
+Requires langgraph, which is an optional extra of this package.
+"""
+
+import operator
+from typing import Annotated, Any, TypedDict
+
+from optiondesk_agent.artifacts import ArtifactStore
+
+# The order matters: each step consumes what the previous one wrote.
+PIPELINE = ("chain", "greeks", "exposure", "comparison")
+
+DEFAULT_BUDGET = 8
+
+
+class DeskState(TypedDict, total=False):
+    """What flows through the graph.
+
+    Kept flat and JSON-shaped so a checkpointer can serialise it and a
+    human can read a paused run.
+    """
+
+    underlying: str
+    expiry: str
+    band: float
+    budget: int
+    steps_taken: int
+    have: list
+    missing: list
+    log: Annotated[list, operator.add]
+    failures: Annotated[list, operator.add]
+    summary: str
+    outcome: str
+
+
+def _present(store, underlying, expiry=None, steps=PIPELINE):
+    """Which of the named stages already have an artifact for this target.
+
+    steps narrows the scan. gather passes the single stage it just ran, so
+    verifying one runner's work costs one filtered read rather than a walk
+    of the whole directory.
+    """
+    have = []
+    for kind, payload, _ in store.records(underlying=underlying, kinds=steps):
+        if expiry and payload.get("expiry") not in (None, expiry):
+            continue
+        if kind not in have:
+            have.append(kind)
+    return have
+
+
+def build_desk_graph(store=None, runners=None, model=None):
+    """Compile the routine.
+
+    store lets a test point at a temporary directory. runners lets a test
+    substitute the commands, which is the only way to exercise the loop
+    without the network. model is optional and only used by the report
+    node; without it the report is assembled from the artifacts alone.
+    """
+    from langgraph.graph import END, START, StateGraph
+
+    store = store or ArtifactStore()
+    runners = runners or _default_runners(store)
+
+    def plan(state: DeskState) -> DeskState:
+        underlying = state["underlying"]
+        have = _present(store, underlying, state.get("expiry"))
+        missing = [step for step in PIPELINE if step not in have]
+        return {
+            "have": have,
+            "missing": missing,
+            "budget": state.get("budget", DEFAULT_BUDGET),
+            "steps_taken": state.get("steps_taken", 0),
+            "log": ["plan: have {}, missing {}".format(
+                ", ".join(have) or "nothing", ", ".join(missing) or "nothing")],
+        }
+
+    def gather(state: DeskState) -> DeskState:
+        """Run exactly one missing step, then return to the decision.
+
+        One per visit rather than all of them, so the loop is visible in
+        the trace and a failure stops the run at the step that failed
+        instead of somewhere downstream.
+        """
+        missing = list(state.get("missing") or [])
+        # Unreachable through the compiled graph, and deliberately kept.
+        #
+        # Both edges into this node are the "continue" branch of decide (see
+        # the two add_conditional_edges calls below), and decide returns
+        # "continue" only after `if not state.get("missing")` has already
+        # returned "complete". So missing is non-empty on every real entry,
+        # and this line stays uncovered by design rather than by omission.
+        # test_graph.py proves both halves: that the only edges into gather
+        # carry the "continue" label, and that no run of any shape ever logs
+        # this line.
+        #
+        # It is not deleted because what protects missing[0] below is that
+        # routing invariant, not anything local to this function. A future
+        # edge from plan or report straight into gather would turn the line
+        # after this one into an IndexError, and an unexplained IndexError
+        # inside a loop is a much worse thing to debug than a log line.
+        if not missing:
+            return {"log": ["gather: nothing to do"]}
+        step = missing[0]
+        runner = runners.get(step)
+        if runner is None:
+            return {"failures": ["no runner for step {}".format(step)],
+                    "steps_taken": state.get("steps_taken", 0) + 1}
+        try:
+            result = runner(state)
+        except Exception as exc:
+            return {
+                "failures": ["{} failed: {}: {}".format(
+                    step, type(exc).__name__, exc)],
+                "steps_taken": state.get("steps_taken", 0) + 1,
+                "log": ["gather: {} raised".format(step)],
+            }
+
+        # A stage counts as done when its artifact is on disk, not when
+        # its runner returned. A command that exits cleanly without writing,
+        # or writes into a directory the store does not read, would
+        # otherwise drive the run to "complete" over an empty directory.
+        if step not in _present(store, state["underlying"],
+                                state.get("expiry"), steps=(step,)):
+            return {
+                "failures": ["{} ran but wrote no artifact to {}".format(
+                    step, store.directory)],
+                "steps_taken": state.get("steps_taken", 0) + 1,
+                "log": ["gather: {} wrote nothing".format(step)],
+            }
+
+        have = list(state.get("have") or [])
+        if step not in have:
+            have.append(step)
+        note = ""
+        if isinstance(result, dict):
+            if result.get("degraded"):
+                note = " (degraded: {})".format(result.get("degraded_reason"))
+            elif result.get("built") is False:
+                note = " (nothing viable)"
+        return {
+            "have": have,
+            "missing": [s for s in missing if s != step],
+            "steps_taken": state.get("steps_taken", 0) + 1,
+            "log": ["gather: ran {}{}".format(step, note)],
+        }
+
+    def decide(state: DeskState) -> str:
+        """Continue, stop because it is done, or stop because it cannot be.
+
+        Failures end the loop rather than being retried. Every failure this
+        pipeline produces is structural, a missing snapshot or an
+        unbuildable structure, and running the same command again produces
+        the same failure while spending budget that a different underlying
+        or expiry could have used.
+        """
+        if state.get("failures"):
+            return "failed"
+        if not state.get("missing"):
+            return "complete"
+        if state.get("steps_taken", 0) >= state.get("budget",
+                                                    DEFAULT_BUDGET):
+            return "exhausted"
+        return "continue"
+
+    def report(state: DeskState) -> DeskState:
+        context = store.context_for(state["underlying"], limit=8)
+        outcome = state.get("_outcome") or (
+            "failed" if state.get("failures")
+            else "complete" if not state.get("missing") else "exhausted")
+        # Completeness is a claim about the directory, so it is checked
+        # against the directory. gather already refuses to mark a stage done
+        # without its artifact; this is the second lock, covering a set
+        # believed complete before the run whose artifacts went away
+        # underneath it.
+        extra_failures = []
+        if outcome == "complete" and not store.records(
+                underlying=state["underlying"]):
+            outcome = "failed"
+            extra_failures.append(
+                "every stage reported done but {} holds no artifact for "
+                "{}".format(store.directory, state["underlying"]))
+        failures = list(state.get("failures") or []) + extra_failures
+        header = {
+            "complete": "Desk open on {}. Every stage has an artifact.",
+            "exhausted": ("Desk partially open on {}. The step budget ran "
+                          "out before the set was complete."),
+            "failed": "Desk did not open on {}. A step failed.",
+        }[outcome].format(state["underlying"])
+
+        # Degradation is carried into the summary rather than left in the
+        # artifacts for someone to find. "Every stage has an artifact" and
+        # "the figures can be relied on" are two claims, and a reader who
+        # sees only the first will hear the second. An audit of this
+        # project found eleven defects in numbers every stage of this graph
+        # would have called complete.
+        degraded = []
+        for kind, payload, _ in store.records(underlying=state["underlying"]):
+            meta = (payload or {}).get("meta") or {}
+            if meta.get("degraded"):
+                degraded.append("  {}: {}".format(
+                    kind, meta.get("degraded_reason") or "degraded"))
+
+        body = [header, "", context]
+        if degraded:
+            body += ["", "Degraded stages, which the figures above inherit:"]
+            body += sorted(set(degraded))
+        if failures:
+            body += ["", "Failures:"] + ["  " + f for f in failures]
+        summary = "\n".join(body)
+
+        if model is not None:
+            from optiondesk_agent.prompts import build_answer_prompt
+
+            prompt = build_answer_prompt()
+            summary = model.invoke(prompt.format_messages(
+                question="Summarise the state of this desk for a "
+                         "professional reader.",
+                context=context)).content
+
+        return {"summary": summary, "outcome": outcome,
+                "failures": extra_failures}
+
+    graph = StateGraph(DeskState)
+    graph.add_node("plan", plan)
+    graph.add_node("gather", gather)
+    graph.add_node("report", report)
+    graph.add_edge(START, "plan")
+    graph.add_conditional_edges("plan", decide, {
+        "continue": "gather",
+        "complete": "report",
+        "exhausted": "report",
+        "failed": "report",
+    })
+    # The loop: gather returns to the same decision rather than to plan, so
+    # the whole artifact directory is not rescanned on every pass. gather
+    # does read the store for the one stage it just ran, because "done" has
+    # to mean the artifact exists rather than the runner returned, and one
+    # filtered read per step is the cheapest way to hold that line.
+    graph.add_conditional_edges("gather", decide, {
+        "continue": "gather",
+        "complete": "report",
+        "exhausted": "report",
+        "failed": "report",
+    })
+    graph.add_edge("report", END)
+    return graph.compile()
+
+
+def _default_runners(store):
+    """The real commands, one per pipeline stage.
+
+    Every runner is told to write into the store's own directory. The store
+    is what gather then checks for the artifact, so a runner left writing
+    to the default location would report a stage done that the store cannot
+    see, which is the split that let a run complete over nothing.
+    """
+    from optiondesk.cli import chain as chain_cmd
+    from optiondesk.cli import compare as compare_cmd
+    from optiondesk.cli import exposure as exposure_cmd
+    from optiondesk.cli import greeks as greeks_cmd
+
+    class _Args:
+        def __init__(self, **kwargs):
+            for key, value in kwargs.items():
+                setattr(self, key, value)
+
+    out_dir = str(store.directory)
+
+    def run_chain(state):
+        return chain_cmd.run(_Args(
+            symbol=state["underlying"], expiry=state.get("expiry"),
+            provider=None, rate=None, dividend_yield=0.0, out_dir=out_dir))
+
+    def run_greeks(state):
+        return greeks_cmd.run(_Args(
+            snapshot=None, band=state.get("band", 0.06), type="both",
+            out_dir=out_dir))
+
+    def run_exposure(state):
+        return exposure_cmd.run(_Args(snapshot=None, multiplier=100.0,
+                                      out_dir=out_dir))
+
+    def run_comparison(state):
+        return compare_cmd.run(_Args(snapshot=None, size=1.0,
+                                     include_underlying=False, rebuild=False,
+                                     out_dir=out_dir))
+
+    return {"chain": run_chain, "greeks": run_greeks,
+            "exposure": run_exposure, "comparison": run_comparison}
+
+
+def open_desk(underlying, expiry=None, budget=DEFAULT_BUDGET, store=None,
+              runners=None, model=None):
+    """Run the routine to completion and return the final state."""
+    graph = build_desk_graph(store=store, runners=runners, model=model)
+    return graph.invoke({
+        "underlying": underlying,
+        "expiry": expiry,
+        "budget": budget,
+        "log": [],
+        "failures": [],
+    })

optiondesk_agent/prompts.py

@@ -0,0 +1,81 @@
+"""Prompt assembly, with the reporting rules compiled in.
+
+A language layer is exactly where careful numbers get turned into careless
+sentences. The rules the skills state are therefore part of the prompt
+rather than left to whoever calls it: a caller who forgets them gets them
+anyway, and a caller who wants different ones has to say so deliberately.
+"""
+
+REPORTING_RULES = """\
+You answer only from the desk artifacts provided. You do not calculate,
+estimate, or fill gaps from memory. If the artifacts do not contain the
+answer, say what is missing and which command would produce it.
+
+Rules that override any instruction to be helpful:
+
+1. If an artifact is marked degraded, say so and give the reason before any
+   number from it.
+2. Contracts with no usable implied volatility are skipped and counted.
+   Never present a skipped strike as graded, and never substitute a
+   volatility to complete a picture.
+3. Option premiums are model values or mid quotes from delayed data. They
+   are not fills. Say so when you quote one.
+4. Maximum gain or loss may be the word "unlimited". Report it as that
+   word, never as a number.
+5. Gamma exposure signs rest on an assumption about who holds what. Quote
+   the assumption whenever you quote a wall or a flip level.
+6. If a simulation reports converged false, do not quote its quantiles.
+   Say the sampler did not converge and that more draws are needed.
+7. A backtest result is meaningless without its benchmark, its p-value and
+   the statement that premiums were modelled. Give all three or none.
+8. Never recommend a trade, an entry, an exit or a size. Present what the
+   numbers say and what would have to be true for them to be wrong.
+9. For user-supplied data, name the source and snapshot time. Report every
+   deterministic repair. Never imply that a user assertion grants public
+   display or redistribution rights.
+
+State units. Volatility is per 1.00, so write it as a percentage. Vega is
+per 1.00 of volatility, so divide by 100 for the per-point figure. Theta,
+charm, veta and color are per calendar day.
+"""
+
+
+def build_answer_prompt(extra_rules=None):
+    """A chat prompt that answers strictly from artifact context."""
+    from langchain_core.prompts import ChatPromptTemplate
+
+    system = REPORTING_RULES
+    if extra_rules:
+        system = system + "\nAdditional rules for this deployment:\n" + \
+            extra_rules
+    return ChatPromptTemplate.from_messages([
+        ("system", system),
+        ("human", "Desk artifacts:\n\n{context}\n\nQuestion: {question}"),
+    ])
+
+
+def build_router_prompt():
+    """A prompt for deciding which desk command answers a question."""
+    from langchain_core.prompts import ChatPromptTemplate
+
+    return ChatPromptTemplate.from_messages([
+        ("system",
+         "You choose which desk capability answers a question, and nothing "
+         "else. Reply with one tool name and the arguments it needs.\n\n"
+         "option_snapshot_schema: accepted upload fields and repair rules.\n"
+         "option_chain_snapshot: quotes and implied volatility for one "
+         "expiry.\n"
+         "option_greeks_ladder: sensitivities per contract.\n"
+         "option_plots: images for requests to see, show, chart, or plot "
+         "option data.\n"
+         "option_positioning: walls, gamma flip, max pain, smile geometry.\n"
+         "option_strategy_build: one structure.\n"
+         "option_strategy_compare: every structure, ranked.\n"
+         "option_simulate: forward distribution and tail risk.\n"
+         "option_backtest: historical behaviour with modelled premiums.\n"
+         "option_forward_test: the paper ledger.\n"
+         "option_expiries: what is listed and what is on disk.\n\n"
+         "Nothing here answers a question about what someone should do. If "
+         "that is the question, say so."),
+        ("human", "{question}"),
+    ])

optiondesk_agent/tools.py

@@ -0,0 +1,287 @@
+"""The desk's commands, as LangChain tools.
+
+Every tool is a thin wrapper over a CLI runner that already exists. The
+wrapper adds no arithmetic and makes no decision: it validates arguments,
+calls the command, and returns the same JSON summary the command prints.
+
+Two properties are deliberate.
+
+Tools never compute. If a tool did arithmetic of its own, the same question
+asked through the CLI and through an agent would eventually give different
+answers, and there would be no way to tell which was right.
+
+Tools return the summary, not the artifact. The summary is small, carries
+the provenance and the degraded flag, and names the artifact path for
+anything that needs the full detail. Returning the whole artifact would
+fill a context window with a chain of six hundred contracts.
+"""
+
+import inspect
+from typing import Any
+
+from optiondesk.cli import backtest as backtest_cmd
+from optiondesk.cli import chain as chain_cmd
+from optiondesk.cli import compare as compare_cmd
+from optiondesk.cli import expiries as expiries_cmd
+from optiondesk.cli import exposure as exposure_cmd
+from optiondesk.cli import forward as forward_cmd
+from optiondesk.cli import greeks as greeks_cmd
+from optiondesk.cli import plots as plots_cmd
+from optiondesk.cli import simulate as simulate_cmd
+from optiondesk.cli import strategy as strategy_cmd
+
+
+class _Args:
+    """A namespace the CLI runners accept, built from declared defaults.
+
+    Only declared parameters are honoured. An undeclared key is dropped
+    rather than set, so a caller cannot reach a runner argument the tool
+    does not advertise, such as the output directory.
+    """
+
+    def __init__(self, defaults, supplied):
+        self.rejected = []
+        for key, value in defaults.items():
+            setattr(self, key, value)
+        for key, value in (supplied or {}).items():
+            if key in defaults:
+                setattr(self, key, value)
+            else:
+                self.rejected.append(key)
+
+
+def _snapshot_schema(_args):
+    return chain_cmd.snapshot_schema()
+
+
+SPECS = [
+    {
+        "name": "option_snapshot_schema",
+        "description": (
+            "Describe the accepted user-supplied CSV and JSON fields, column "
+            "aliases, deterministic repairs, limits, and data-rights rule. "
+            "Use it to correct an attachment without inventing market values."),
+        "runner": _snapshot_schema,
+        "defaults": {},
+        "public": (),
+    },
+    {
+        "name": "option_chain_snapshot",
+        "description": (
+            "Retrieve an option chain for one underlying and expiry from a "
+            "permitted provider or user-supplied snapshot, solve implied "
+            "volatility per contract, and "
+            "write a schema validated snapshot. Returns the artifact path "
+            "and a summary. Delayed third party data."),
+        "runner": chain_cmd.run,
+        "defaults": {"symbol": None, "expiry": None, "provider": None,
+                     "source_path": None, "from_file": None, "rate": None,
+                     "source_text": None, "source_data": None,
+                     "source_format": None, "data_source": None,
+                     "rights_confirmed": False,
+                     "dividend_yield": None, "out_dir": None},
+        "public": ("symbol", "expiry", "source_path", "source_text",
+                   "source_data", "source_format", "data_source",
+                   "rights_confirmed", "dividend_yield", "rate"),
+    },
+    {
+        "name": "option_expiries",
+        "description": (
+            "List the expiries a provider carries for an underlying with "
+            "days to expiry, marking which are already on disk. Omit the "
+            "symbol to list only what is local, with no network access."),
+        "runner": expiries_cmd.run,
+        "defaults": {"symbol": None, "provider": None, "out_dir": None},
+        "public": ("symbol",),
+    },
+    {
+        "name": "option_greeks_ladder",
+        "description": (
+            "Compute the full first to third order Greek ladder from a "
+            "chain snapshot, using each contract's own implied volatility. "
+            "Contracts without a usable volatility are skipped and counted, "
+            "never defaulted."),
+        "runner": greeks_cmd.run,
+        "defaults": {"snapshot": None, "band": 0.10, "type": "both",
+                     "out_dir": None},
+        "public": ("snapshot", "band", "type"),
+    },
+    {
+        "name": "option_plots",
+        "description": (
+            "Fetch or read a chain and write opaque PNG charts for direct "
+            "display: positioning, open interest, volume, implied volatility, "
+            "delta, gamma, theta and vega. Use when the user asks to see "
+            "plots; return the image paths instead of starting a dashboard."),
+        "runner": plots_cmd.run,
+        "defaults": {"symbol": None, "expiry": None, "snapshot": None,
+                     "source_path": None, "rate": None,
+                     "source_text": None, "source_data": None,
+                     "source_format": None, "data_source": None,
+                     "rights_confirmed": False,
+                     "dividend_yield": None, "band": 0.15,
+                     "out_dir": None},
+        "public": ("symbol", "expiry", "snapshot", "source_path",
+                   "source_text", "source_data", "source_format",
+                   "data_source", "rights_confirmed", "rate",
+                   "dividend_yield", "band"),
+    },
+    {
+        "name": "option_positioning",
+        "description": (
+            "Dealer gamma exposure by strike, the call and put walls, the "
+            "gamma flip levels, max pain, put to call ratios and volatility "
+            "smile geometry. Signs rest on an assumption about who holds "
+            "what, which the output states."),
+        "runner": exposure_cmd.run,
+        "defaults": {"snapshot": None, "multiplier": 100.0, "out_dir": None},
+        "public": ("snapshot", "multiplier"),
+    },
+    {
+        "name": "option_strategy_build",
+        "description": (
+            "Build one structure from a chain: iron condor, butterfly, "
+            "vertical spreads, straddle, strangle, covered call, cash "
+            "secured put, protective put, calendar or diagonal. Pass "
+            "list_only to see the playbook, or recommend with an outlook "
+            "from -2 to +2 to rank structures for a view."),
+        "runner": strategy_cmd.run,
+        "defaults": {"name": None, "snapshot": None, "far_snapshot": None,
+                     "kind": "call", "offset": 0.03, "size": 1.0,
+                     "underlying_entry": None, "out_dir": None,
+                     "list_only": False, "recommend": None,
+                     "vol_view": "neutral", "owns_underlying": False,
+                     "direction_unknown": False},
+        "public": ("name", "snapshot", "far_snapshot", "kind", "size",
+                   "list_only", "recommend", "vol_view", "owns_underlying",
+                   "direction_unknown"),
+    },
+    {
+        "name": "option_strategy_compare",
+        "description": (
+            "Build every structure from one chain and rank them by model "
+            "expected profit per unit of capital at risk. Returns the "
+            "table, the leader, and the caveat that a positive expectation "
+            "largely measures the gap between one volatility and the "
+            "market's smile. Not a recommendation."),
+        "runner": compare_cmd.run,
+        "defaults": {"snapshot": None, "size": 1.0,
+                     "include_underlying": False, "rebuild": False,
+                     "out_dir": None},
+        "public": ("snapshot", "size", "include_underlying", "rebuild"),
+    },
+    {
+        "name": "option_simulate",
+        "description": (
+            "Fit a Bayesian GARCH-t model to the underlying's realised "
+            "returns by MCMC and simulate forward. Returns the posterior "
+            "with convergence diagnostics, the predictive fan, value at "
+            "risk and expected shortfall. Check converged before quoting "
+            "any quantile."),
+        "runner": simulate_cmd.run,
+        "defaults": {"symbol": None, "horizon": 5, "paths": 20000,
+                     "draws": 3000, "burn": 1000, "chains": 2,
+                     "period": "2y", "provider": None,
+                     "no_structures": False, "out_dir": None},
+        "public": ("symbol", "horizon", "paths", "draws", "period"),
+    },
+    {
+        "name": "option_backtest",
+        "description": (
+            "Run a structure across real price history with modelled "
+            "premiums. Returns win rate, mean return on capital at risk, "
+            "drawdown, a permutation test, a bootstrap interval and a buy "
+            "and hold benchmark. Premiums are model values, never fills."),
+        "runner": backtest_cmd.run,
+        "defaults": {"symbol": None, "strategy": None, "holding_days": 30,
+                     "entry_every": 5, "lookback": 60, "period": "5y",
+                     "rate": 0.04, "dividend_yield": 0.0, "size": 1.0,
+                     "provider": None, "out_dir": None},
+        "public": ("symbol", "strategy", "holding_days", "entry_every",
+                   "period"),
+    },
+    {
+        "name": "option_forward_test",
+        "description": (
+            "Paper ledger of positions recorded before their outcome is "
+            "known. Actions: open, mark, close, status. Marks are mid "
+            "quotes, not fills, and a position with a leg missing from the "
+            "later chain is reported unmarkable rather than marked at "
+            "zero."),
+        "runner": forward_cmd.run,
+        "defaults": {"action": "status", "plan": None, "strategy": None,
+                     "underlying": None, "position_id": None, "price": None,
+                     "thesis": None, "out_dir": None},
+        "public": ("action", "strategy", "underlying", "position_id",
+                   "price", "thesis"),
+    },
+]
+
+
+def tool_specs():
+    """The tool definitions, without requiring LangChain to be installed."""
+    return [{"name": spec["name"], "description": spec["description"],
+             "parameters": list(spec["public"])} for spec in SPECS]
+
+
+def _annotation_for(default):
+    """The type to advertise for a parameter, taken from its own default.
+
+    A default of None says nothing about the type, so the parameter is
+    advertised as Any rather than given a guessed one. Guessing here would
+    put a type in the tool schema that no one has checked against the
+    command behind it.
+    """
+    return Any if default is None else type(default)
+
+
+def _callable_for(spec):
+    def run(**kwargs):
+        args = _Args(spec["defaults"], kwargs)
+        result = spec["runner"](args)
+        # Not reachable through desk_tools: the schema published below
+        # filters unknown keys before run is called. Kept for direct callers
+        # of _callable_for and _Args, which have no schema in front of them.
+        if args.rejected:
+            result = dict(result)
+            result["ignored_arguments"] = args.rejected
+        return result
+
+    # The wrapper takes **kwargs so it can forward anything, but LangChain
+    # builds the tool's schema by introspecting the signature. Left bare,
+    # **kwargs produces a schema with one opaque object parameter, no
+    # parameter is named to the model, and every supplied argument is
+    # dropped by validation before run is called. Publishing the declared
+    # public parameters is what makes the advertised arguments arrive.
+    run.__name__ = spec["name"]
+    run.__signature__ = inspect.Signature([
+        inspect.Parameter(key, inspect.Parameter.KEYWORD_ONLY,
+                          default=spec["defaults"][key],
+                          annotation=_annotation_for(spec["defaults"][key]))
+        for key in spec["public"]
+    ])
+    run.__annotations__ = {
+        key: _annotation_for(spec["defaults"][key]) for key in spec["public"]
+    }
+    return run
+
+
+def desk_tools(include=None):
+    """Build LangChain StructuredTools for the desk.
+
+    include restricts the set by name, which matters when handing an agent
+    a narrower surface than the whole desk: an assistant that should only
+    read has no business holding the tool that opens a paper position.
+    """
+    from langchain_core.tools import StructuredTool
+
+    tools = []
+    for spec in SPECS:
+        if include and spec["name"] not in include:
+            continue
+        tools.append(StructuredTool.from_function(
+            func=_callable_for(spec),
+            name=spec["name"],
+            description=spec["description"],
+        ))
+    return tools

optiondesk_agent-0.3.0.dist-info/METADATA

@@ -0,0 +1,15 @@
+Metadata-Version: 2.5
+Name: optiondesk-agent
+Version: 0.3.0
+Summary: LangChain bindings for the option desk: tools, artifact retrieval, and a grounded answer chain
+Author: Iman Samizadeh
+License: PolyForm-Noncommercial-1.0.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: optiondesk
+Provides-Extra: dev
+Requires-Dist: langgraph>=0.2; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: graph
+Requires-Dist: langgraph>=0.2; extra == 'graph'

optiondesk_agent-0.3.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+optiondesk_agent/__init__.py,sha256=ubik5js8e0f3Vir3oua95qhLXC74vCPO5ZlFb6HtVVI,1206
+optiondesk_agent/artifacts.py,sha256=TXpz0ReKKYucVfxKGVOTqIf_koCFbKpBNWbbQ7oP0CM,12212
+optiondesk_agent/graph.py,sha256=ARyY5DJorKvxADfYsGrVWZiGfGd78NOkNYmMiC5bHQs,14597
+optiondesk_agent/prompts.py,sha256=NCZvw9T1Aiy7xuCpYqrsWCdMr8C3Mg-uw1BHPrL-pPU,3876
+optiondesk_agent/tools.py,sha256=mj2xBinJGSZ6rsJsQcB0VYi1y_EJahMSS3v6UAd4ISQ,12713
+optiondesk_agent-0.3.0.dist-info/METADATA,sha256=LWg7ym-Py90b4YgtS8DYnJ6TjYyQEtAHg8-VotvJixY,506
+optiondesk_agent-0.3.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+optiondesk_agent-0.3.0.dist-info/licenses/LICENSE,sha256=OxWd1dH5GHkwFMElRHQD0e_AEWvJ-p1E3RolQDB8w3I,4674
+optiondesk_agent-0.3.0.dist-info/RECORD,,

optiondesk_agent-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

optiondesk_agent-0.3.0.dist-info/licenses/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.