optiondesk-agent 0.3.0__tar.gz

optiondesk_agent-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_agent-0.3.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,99 @@
+# optiondesk-agent
+
+LangChain bindings for the desk. PolyForm Noncommercial 1.0.0, like the
+rest of the project.
+
+## What this is, and what it deliberately is not
+
+It exposes the desk's capabilities as LangChain tools, turns the artifacts
+on disk into retrievable documents, and assembles a prompt that answers a
+question strictly from those artifacts.
+
+It is not in the compute path and must never be. Pricing, Greeks,
+positioning, simulation and backtests all happen in the engine, which has
+no dependency on this package and no knowledge that it exists. If LangChain
+were in the compute path, a dependency bump could change a Greek, and the
+numbers would stop being reproducible from the engine alone.
+
+The separation is the point:
+
+    engine    numbers, no dependencies, no network
+    shell     data, contracts, artifacts, MCP, dashboard
+    agent     language: tools, retrieval, and prompt assembly
+
+## Why it exists next to MCP
+
+MCP serves an agent runtime that already exists, such as Claude Code,
+Codex or Gemini CLI. This serves an application someone builds themselves,
+where the desk is one capability among several and the orchestration is
+theirs. Both call the same commands and read the same artifacts.
+
+## Use
+
+```python
+from optiondesk_agent import desk_tools, ArtifactStore, build_answer_prompt
+
+tools = desk_tools()                      # LangChain StructuredTools
+store = ArtifactStore()                   # documents from the artifact dir
+context = store.context_for("SPY")
+prompt = build_answer_prompt()            # carries the reporting rules
+```
+
+Bring your own model. This package deliberately declares no provider
+dependency, so it adds no key requirement and no vendor to the tree.
+
+## The graph
+
+A desk routine as a bounded state machine, in `graph.py`. It needs the
+optional extra:
+
+```
+pip install -e "agent[graph]"
+```
+
+```python
+from optiondesk_agent import open_desk
+
+state = open_desk("SPY", budget=8)
+state["outcome"]    # complete, exhausted, or failed
+state["summary"]
+state["log"]        # every step it took, in order
+```
+
+Opening a desk is a dependency chain rather than one call: a chain
+snapshot, then a Greek ladder from it, then positioning, then structures,
+then a comparison. Three nodes handle it. `plan` reads which stages already
+have an artifact. `gather` runs exactly one missing stage per visit and
+returns to the decision, which keeps the loop visible in the trace and
+stops a failure at the stage that failed rather than somewhere downstream.
+`report` assembles the summary.
+
+The three exits are kept distinct on purpose. `complete` means every stage
+has an artifact, `exhausted` means the step budget ran out, `failed` means
+a stage raised. Collapsing them into a boolean is how an agent ends up
+reporting success on an empty directory.
+
+There is no model in the graph. Every node runs a deterministic command, so
+the same inputs give the same outputs and a failure reproduces. Pass
+`model=` only if you want the closing summary written rather than
+assembled, and the reporting rules below still apply to it.
+
+Failures end the loop rather than being retried, because every failure this
+pipeline produces is structural: a missing snapshot, an unbuildable
+structure, a provider that is not answering. Running the same command again
+produces the same failure while spending budget a different underlying
+could have used.
+
+`langgraph` stays optional at import time. `import optiondesk_agent` works
+without it, and only touching `open_desk` or `build_desk_graph` pulls it in.
+
+For loops outside an application, in Claude Code itself, see `LOOPS.md` at
+the repository root.
+
+## The reporting rules travel with the prompt
+
+The prompt template carries the same rules the skills state: report the
+degraded flag before any number, never substitute a default volatility,
+never present modelled premiums as tradable, and never turn an analysis
+into a recommendation. A language layer is exactly where those rules get
+lost, so they are compiled into it rather than left to the caller.

optiondesk_agent-0.3.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "optiondesk-agent"
+version = "0.3.0"
+description = "LangChain bindings for the option desk: tools, artifact retrieval, and a grounded answer chain"
+requires-python = ">=3.11"
+license = { text = "PolyForm-Noncommercial-1.0.0" }
+authors = [{ name = "Iman Samizadeh" }]
+dependencies = ["langchain-core>=0.3", "optiondesk"]
+
+[project.optional-dependencies]
+graph = ["langgraph>=0.2"]
+dev = ["pytest", "langgraph>=0.2"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/optiondesk_agent"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

optiondesk_agent-0.3.0/src/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-0.3.0/src/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)