stratify-mcp 0.1.1__tar.gz

stratify_mcp-0.1.1/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: stratify-mcp
+Version: 0.1.1
+Summary: Python client for the Stratify MCP options-backtesting API
+Author: Stratify
+License: MIT
+Project-URL: Homepage, https://stratify.aeon-labs.site
+Project-URL: Documentation, https://stratify.aeon-labs.site/docs
+Project-URL: Source, https://github.com/Srinath-exe/stratify-mcp
+Project-URL: Issues, https://github.com/Srinath-exe/stratify-mcp/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=1.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# stratify-mcp
+
+Python client for [Stratify](https://stratify.aeon-labs.site) — real 1-minute NIFTY options data,
+honest backtests (out-of-sample, walk-forward, deflated Sharpe, all reported alongside the
+number, not instead of it).
+
+```bash
+pip install stratify-mcp
+```
+
+## Quickstart
+
+```python
+from stratify_mcp import StratifyClient
+
+# One-time: create an account and get a key. The key is shown once -- save it.
+signup = StratifyClient.signup("you@example.com")
+client = StratifyClient(api_key=signup["api_key"])
+
+result = client.run_backtest({
+    "legs": [
+        {"side": "sell", "type": "CE", "strike": {"delta_near": 0.2}},
+        {"side": "sell", "type": "PE", "strike": {"delta_near": 0.2}},
+    ],
+    # The reason for the trade, not just the trade.
+    "entry": {"cadence": "weekly", "dte": 3, "time": "09:30",
+              "when": {"vix": {"gte": 15}}},
+    # Managed while it is open: take profit, and roll the tested side if it doubles.
+    "rules": [
+        {"when": {"pnl_pct_of_credit": {"gte": 0.6}}, "then": "close"},
+        {"when": {"leg_mark_mult": {"gte": 2.0, "leg": 0}},
+         "then": {"roll": {"legs": [0], "to": {"delta_near": 0.2}}}, "max_times": 2},
+    ],
+    "portfolio": {"stop_after_losses": 3, "resume_after_days": 30},
+})
+
+print(result.summary["total_pnl_rupees"], result.summary["max_drawdown_rupees"])
+print(result.summary["ratios"])       # sharpe, profit_factor, calmar (only above 30 trades)
+print(result.honesty)          # out-of-sample split, walk-forward folds, deflated Sharpe
+result.trades                  # pandas.DataFrame, one row per trade
+result.equity_curve            # pandas.DataFrame
+print(result.report_url)       # shareable page with the full chart and every trade
+```
+
+Already have a key? Skip `signup()`:
+
+```python
+client = StratifyClient(api_key="sk_live_...")
+```
+
+## Why a Python client at all, when it's just JSON-RPC
+
+There's no separate REST endpoint for `run_backtest` — every tool is reached through one
+`POST /mcp` speaking MCP JSON-RPC 2.0. This package exists so you don't hand-roll that
+envelope: `client.run_backtest(...)` is a real function call, errors come back as Python
+exceptions you can `except`, and results come back as `pandas.DataFrame`s instead of raw
+JSON, because that's what you're actually going to do with a table of trades.
+
+## Errors
+
+```python
+from stratify_mcp import AuthenticationError, QuotaExceededError, ToolRefusalError
+
+try:
+    result = client.run_backtest(spec)
+except AuthenticationError:
+    ...  # bad or revoked key
+except QuotaExceededError as e:
+    ...  # e.limit, e.retry_after_seconds
+except ToolRefusalError as e:
+    ...  # the server read your spec and refused it -- str(e) says why
+```
+
+## Methods
+
+| Method | Returns |
+|---|---|
+| `run_backtest(spec, lots=1, detail="standard")` | `BacktestResult` |
+| `get_backtest(backtest_id, detail=None)` | `BacktestResult` |
+| `describe_coverage()` | `dict` — symbols, date range, structures, gates, biases, cost model |
+| `explain_methodology(topic=None)` | `dict` |
+| `list_strategies(order="consistency", limit=None)` | `dict` — `{"strategies": [...], "bar": {...}, ...}`, this account's strategies that held up out-of-sample |
+| `search(query)` / `fetch(id)` | `dict` |
+| `StratifyClient.signup(email)` (staticmethod) | `dict` — includes `api_key`, shown once |
+
+`detail` on `run_backtest`/`get_backtest`: `"summary"` (aggregates only, cheapest),
+`"standard"` (default — equity curve, breakdowns, first 25 trades), `"full"` (every
+stored trade).
+
+## `BacktestResult`
+
+| Property | Type |
+|---|---|
+| `.summary` | `dict` |
+| `.honesty` | `dict` |
+| `.interpretation` | `str` |
+| `.trades` | `pandas.DataFrame` |
+| `.equity_curve` | `pandas.DataFrame` |
+| `.qualified` / `.why_not_qualified` | `bool` / `str \| None` |
+| `.backtest_id` / `.report_url` | `str` |
+| `.warnings` | `list[str]` |
+| `.to_dict()` | the complete raw payload |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Tests run against a mocked transport and need no live server or API key.
+
+## License
+
+MIT.

stratify_mcp-0.1.1/README.md

@@ -0,0 +1,115 @@
+# stratify-mcp
+
+Python client for [Stratify](https://stratify.aeon-labs.site) — real 1-minute NIFTY options data,
+honest backtests (out-of-sample, walk-forward, deflated Sharpe, all reported alongside the
+number, not instead of it).
+
+```bash
+pip install stratify-mcp
+```
+
+## Quickstart
+
+```python
+from stratify_mcp import StratifyClient
+
+# One-time: create an account and get a key. The key is shown once -- save it.
+signup = StratifyClient.signup("you@example.com")
+client = StratifyClient(api_key=signup["api_key"])
+
+result = client.run_backtest({
+    "legs": [
+        {"side": "sell", "type": "CE", "strike": {"delta_near": 0.2}},
+        {"side": "sell", "type": "PE", "strike": {"delta_near": 0.2}},
+    ],
+    # The reason for the trade, not just the trade.
+    "entry": {"cadence": "weekly", "dte": 3, "time": "09:30",
+              "when": {"vix": {"gte": 15}}},
+    # Managed while it is open: take profit, and roll the tested side if it doubles.
+    "rules": [
+        {"when": {"pnl_pct_of_credit": {"gte": 0.6}}, "then": "close"},
+        {"when": {"leg_mark_mult": {"gte": 2.0, "leg": 0}},
+         "then": {"roll": {"legs": [0], "to": {"delta_near": 0.2}}}, "max_times": 2},
+    ],
+    "portfolio": {"stop_after_losses": 3, "resume_after_days": 30},
+})
+
+print(result.summary["total_pnl_rupees"], result.summary["max_drawdown_rupees"])
+print(result.summary["ratios"])       # sharpe, profit_factor, calmar (only above 30 trades)
+print(result.honesty)          # out-of-sample split, walk-forward folds, deflated Sharpe
+result.trades                  # pandas.DataFrame, one row per trade
+result.equity_curve            # pandas.DataFrame
+print(result.report_url)       # shareable page with the full chart and every trade
+```
+
+Already have a key? Skip `signup()`:
+
+```python
+client = StratifyClient(api_key="sk_live_...")
+```
+
+## Why a Python client at all, when it's just JSON-RPC
+
+There's no separate REST endpoint for `run_backtest` — every tool is reached through one
+`POST /mcp` speaking MCP JSON-RPC 2.0. This package exists so you don't hand-roll that
+envelope: `client.run_backtest(...)` is a real function call, errors come back as Python
+exceptions you can `except`, and results come back as `pandas.DataFrame`s instead of raw
+JSON, because that's what you're actually going to do with a table of trades.
+
+## Errors
+
+```python
+from stratify_mcp import AuthenticationError, QuotaExceededError, ToolRefusalError
+
+try:
+    result = client.run_backtest(spec)
+except AuthenticationError:
+    ...  # bad or revoked key
+except QuotaExceededError as e:
+    ...  # e.limit, e.retry_after_seconds
+except ToolRefusalError as e:
+    ...  # the server read your spec and refused it -- str(e) says why
+```
+
+## Methods
+
+| Method | Returns |
+|---|---|
+| `run_backtest(spec, lots=1, detail="standard")` | `BacktestResult` |
+| `get_backtest(backtest_id, detail=None)` | `BacktestResult` |
+| `describe_coverage()` | `dict` — symbols, date range, structures, gates, biases, cost model |
+| `explain_methodology(topic=None)` | `dict` |
+| `list_strategies(order="consistency", limit=None)` | `dict` — `{"strategies": [...], "bar": {...}, ...}`, this account's strategies that held up out-of-sample |
+| `search(query)` / `fetch(id)` | `dict` |
+| `StratifyClient.signup(email)` (staticmethod) | `dict` — includes `api_key`, shown once |
+
+`detail` on `run_backtest`/`get_backtest`: `"summary"` (aggregates only, cheapest),
+`"standard"` (default — equity curve, breakdowns, first 25 trades), `"full"` (every
+stored trade).
+
+## `BacktestResult`
+
+| Property | Type |
+|---|---|
+| `.summary` | `dict` |
+| `.honesty` | `dict` |
+| `.interpretation` | `str` |
+| `.trades` | `pandas.DataFrame` |
+| `.equity_curve` | `pandas.DataFrame` |
+| `.qualified` / `.why_not_qualified` | `bool` / `str \| None` |
+| `.backtest_id` / `.report_url` | `str` |
+| `.warnings` | `list[str]` |
+| `.to_dict()` | the complete raw payload |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Tests run against a mocked transport and need no live server or API key.
+
+## License
+
+MIT.

stratify_mcp-0.1.1/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stratify-mcp"
+version = "0.1.1"
+description = "Python client for the Stratify MCP options-backtesting API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Stratify" }]
+# pandas is a hard dependency, not optional: DataFrames are the whole point of this
+# package existing alongside the MCP server itself (PRODUCT_REQUIREMENTS.md distribution
+# surfaces table -- "Quants live here; returns pandas DataFrames"). Everything else is the
+# standard library on purpose, so installing this pulls in exactly one real dependency.
+dependencies = ["pandas>=1.5"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://stratify.aeon-labs.site"
+Documentation = "https://stratify.aeon-labs.site/docs"
+Source = "https://github.com/Srinath-exe/stratify-mcp"
+Issues = "https://github.com/Srinath-exe/stratify-mcp/issues"
+
+[tool.setuptools.packages.find]
+include = ["stratify_mcp*"]

stratify_mcp-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stratify_mcp-0.1.1/stratify_mcp/__init__.py

@@ -0,0 +1,12 @@
+from .client import StratifyClient
+from .exceptions import (AuthenticationError, ProtocolError, QuotaExceededError,
+                         StratifyError, ToolRefusalError, TransportError)
+from .models import BacktestResult
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "StratifyClient", "BacktestResult",
+    "StratifyError", "AuthenticationError", "QuotaExceededError",
+    "ToolRefusalError", "ProtocolError", "TransportError",
+]

stratify_mcp-0.1.1/stratify_mcp/client.py

@@ -0,0 +1,182 @@
+"""JSON-RPC client for the Stratify MCP server.
+
+There is no separate REST endpoint for running a backtest (server/app.py:9-16) -- every
+tool, including run_backtest, is only reachable through POST /mcp as MCP JSON-RPC 2.0
+tools/call. This client speaks that protocol directly rather than waiting on a future
+OpenAPI layer, using nothing beyond the standard library for the HTTP leg so installing
+this package pulls in exactly one real dependency: pandas, for the DataFrames quants
+actually asked for (PRODUCT_REQUIREMENTS.md, distribution surfaces table).
+"""
+import json
+import urllib.error
+import urllib.request
+from urllib.parse import urljoin
+
+from .exceptions import (AuthenticationError, ProtocolError, QuotaExceededError,
+                         ToolRefusalError, TransportError)
+from .models import BacktestResult
+
+DEFAULT_BASE_URL = "https://stratify-mcp.aeon-labs.site"
+DEFAULT_TIMEOUT = 120  # seconds -- server/app.py's own MCP endpoint allows a 7-year
+                       # backtest up to 120s at p95 under load (sites-available/stratify-mcp)
+
+_UNAUTHENTICATED = -32001
+_QUOTA_EXCEEDED = -32002
+
+
+class StratifyClient:
+    """One client per API key. Not thread-safe across concurrent calls sharing an
+    account's quota is fine (the server enforces that), but this object holds no
+    connection state, so making one per thread if you fan out is cheap and correct.
+
+        client = StratifyClient(api_key="sk_live_...")
+        result = client.run_backtest({
+            "structure": "short_strangle", "symbol": "NIFTY",
+            "params": {"pct_offset": 1.5, "sl_mult": 2.0},
+            "entry_time": "09:30",
+        })
+        result.trades          # pandas.DataFrame
+        result.equity_curve    # pandas.DataFrame
+        result.summary["cagr"]
+    """
+
+    def __init__(self, api_key, base_url=DEFAULT_BASE_URL, timeout=DEFAULT_TIMEOUT):
+        if not api_key:
+            raise ValueError("api_key is required -- get one from StratifyClient.signup()")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._request_id = 0
+
+    # ---------------------------------------------------------------- public API
+
+    def run_backtest(self, spec, lots=1, detail="standard"):
+        """spec: a dict matching the public StrategySpec shape (see describe_coverage() or
+        the server's knowledge base for the exact fields -- structure, params, entry_time,
+        etc.). detail: 'summary' (aggregates only), 'standard' (default -- equity curve,
+        breakdowns, first 25 trades), or 'full' (every trade up to the stored cap).
+        Returns a BacktestResult."""
+        payload = self._call("run_backtest",
+                             {"spec": spec, "lots": lots, "detail": detail})
+        return BacktestResult(payload)
+
+    def get_backtest(self, backtest_id, detail=None):
+        """Retrieve a previously run backtest by id, exactly as first computed."""
+        args = {"backtest_id": backtest_id}
+        if detail is not None:
+            args["detail"] = detail
+        return BacktestResult(self._call("get_backtest", args))
+
+    def describe_coverage(self):
+        """Symbols, date range, resolution, structures, gates, biases, cost model, known
+        gaps. Call this before building a spec -- it is unauthenticated on the server side
+        but routed the same way here for one consistent client surface."""
+        return self._call("describe_coverage", {})
+
+    def explain_methodology(self, topic=None):
+        """How a result is produced and how to judge it. `topic` narrows to one section;
+        omit it for the full document."""
+        args = {"topic": topic} if topic else {}
+        return self._call("explain_methodology", args)
+
+    def list_strategies(self, order="consistency", limit=None):
+        """This account's strategies that held up out-of-sample, ranked by worst
+        walk-forward fold by default -- not by P&L. Returns the full response dict, not a
+        bare list: {'strategies': [...], 'bar': {what qualifies, why not just P&L, ...},
+        'n_entries': int, ...} -- the qualification bar travels with the list because a
+        caller reading the empty-list case needs to know what it would take, not just that
+        nothing qualified yet. Verified against a real (empty) account rather than
+        assumed. Use client.list_strategies()['strategies'] for just the entries, or
+        pandas.DataFrame(client.list_strategies()['strategies']) for a table."""
+        args = {"order": order}
+        if limit is not None:
+            args["limit"] = limit
+        return self._call("list_strategies", args)
+
+    def search(self, query):
+        """Search what this service covers. Returns ids usable with fetch()."""
+        return self._call("search", {"query": query})
+
+    def fetch(self, id):  # noqa: A002 -- matches the tool's own parameter name
+        """Fetch a document or backtest result by id, as returned by search()."""
+        return self._call("fetch", {"id": id})
+
+    @staticmethod
+    def signup(email, base_url=DEFAULT_BASE_URL, timeout=DEFAULT_TIMEOUT):
+        """Create an account and issue the first API key. No approval step (decision §0)
+        -- returns immediately with a usable key. THE KEY IS SHOWN ONCE: store
+        response['api_key'] yourself, the server does not let you recover it later.
+        Returns the raw signup response dict (account_id, key_id, api_key, tier, limits,
+        mcp_endpoint, ...) rather than a StratifyClient, since the two most common next
+        steps -- print the key for a human, or hand it straight to StratifyClient(api_key=)
+        -- both want the plain dict."""
+        url = urljoin(base_url.rstrip("/") + "/", "v1/signup")
+        body = json.dumps({"email": email}).encode()
+        req = urllib.request.Request(
+            url, data=body, method="POST",
+            headers={"Content-Type": "application/json"})
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                return json.loads(resp.read())
+        except urllib.error.HTTPError as exc:
+            detail_body = exc.read()
+            try:
+                detail = json.loads(detail_body).get("error", detail_body.decode(errors="replace"))
+            except Exception:
+                detail = detail_body.decode(errors="replace")
+            raise TransportError(f"signup failed ({exc.code}): {detail}") from exc
+        except urllib.error.URLError as exc:
+            raise TransportError(f"could not reach {url}: {exc.reason}") from exc
+
+    # ---------------------------------------------------------------- transport
+
+    def _call(self, tool_name, arguments):
+        self._request_id += 1
+        body = json.dumps({
+            "jsonrpc": "2.0", "id": self._request_id, "method": "tools/call",
+            "params": {"name": tool_name, "arguments": arguments},
+        }).encode()
+        url = urljoin(self.base_url + "/", "mcp")
+        req = urllib.request.Request(
+            url, data=body, method="POST",
+            headers={"Content-Type": "application/json",
+                    "Authorization": f"Bearer {self.api_key}",
+                    "User-Agent": "stratify-py/1.0"})
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                message = json.loads(resp.read())
+        except urllib.error.HTTPError as exc:
+            # The server returns non-2xx only for origin/size checks ahead of JSON-RPC
+            # (app.py:_serve_mcp) -- a real tool refusal or quota hit still comes back 200
+            # with a JSON-RPC body, handled below.
+            raise TransportError(f"HTTP {exc.code} from {url}") from exc
+        except urllib.error.URLError as exc:
+            raise TransportError(f"could not reach {url}: {exc.reason}") from exc
+        except json.JSONDecodeError as exc:
+            raise TransportError("server response was not valid JSON") from exc
+
+        if "error" in message:
+            err = message["error"]
+            code, msg, data = err.get("code"), err.get("message", ""), err.get("data") or {}
+            if code == _UNAUTHENTICATED:
+                raise AuthenticationError(msg, data)
+            if code == _QUOTA_EXCEEDED:
+                raise QuotaExceededError(msg, limit=data.get("limit"),
+                                         retry_after_seconds=data.get("retry_after_seconds"))
+            raise ProtocolError(msg, code=code)
+
+        result = message.get("result") or {}
+        if result.get("isError"):
+            text = "; ".join(b.get("text", "") for b in result.get("content", []))
+            raise ToolRefusalError(text or "the server refused this call")
+
+        structured = result.get("structuredContent")
+        if structured is not None:
+            return structured
+        # Fallback for a client/server pairing that only carries the text block -- parse
+        # the same JSON the structuredContent would have held (server/app.py:_tool_text
+        # always sends both today, but this keeps the client correct if that ever changes).
+        for block in result.get("content", []):
+            if block.get("type") == "text":
+                return json.loads(block["text"])
+        return {}

stratify_mcp-0.1.1/stratify_mcp/exceptions.py

@@ -0,0 +1,52 @@
+"""Exceptions the client raises.
+
+Mirrors the three distinct failure shapes server/app.py actually produces (see its
+_handle() dispatcher) rather than collapsing them into one generic error -- a caller needs
+to tell "your key is wrong" from "you're over quota, retry in N seconds" from "the server
+looked at your spec and said no" apart, and each needs different handling code.
+"""
+
+
+class StratifyError(Exception):
+    """Base class for every error this client raises."""
+
+
+class TransportError(StratifyError):
+    """The request never got a JSON-RPC response at all -- a network failure, a timeout,
+    or a non-2xx HTTP status from something other than this API (a proxy, a CDN page)."""
+
+
+class AuthenticationError(StratifyError):
+    """JSON-RPC error -32001. The key is missing, malformed, or revoked. `how_to_fix` and
+    `alternative_headers`, when the server sent them, are on `.data`."""
+
+    def __init__(self, message, data=None):
+        super().__init__(message)
+        self.data = data or {}
+
+
+class QuotaExceededError(StratifyError):
+    """JSON-RPC error -32002. `limit` names which of the three dimensions (requests, CPU
+    seconds, price points) was hit; `retry_after_seconds` is how long to back off."""
+
+    def __init__(self, message, limit=None, retry_after_seconds=None):
+        super().__init__(message)
+        self.limit = limit
+        self.retry_after_seconds = retry_after_seconds
+
+
+class ToolRefusalError(StratifyError):
+    """Not a protocol error -- a successful JSON-RPC response with isError=true. This is
+    the server having read the spec and refused it on its own terms: too narrow a window,
+    an anti-oracle floor, a malformed structure parameter. The message is written for a
+    human (or a model) to read and correct, so it is passed through unmodified."""
+
+
+class ProtocolError(StratifyError):
+    """A JSON-RPC error this client did not anticipate (unknown method, malformed request,
+    internal server error). Carries the raw code and message rather than pretending to a
+    category the server didn't declare."""
+
+    def __init__(self, message, code=None):
+        super().__init__(message)
+        self.code = code

stratify_mcp-0.1.1/stratify_mcp/models.py

@@ -0,0 +1,110 @@
+"""Result wrapper. run_backtest and get_backtest return the same payload shape
+(server/tools.py's get_backtest builds it by re-loading exactly what run_backtest stored),
+so one class serves both.
+"""
+
+
+class BacktestResult:
+    """Wraps a run_backtest/get_backtest response. Every field the server sent is on
+    `.raw`; the properties below are conveniences over the common ones, built lazily so a
+    caller who only wants `.summary` never pays for a DataFrame construction they didn't
+    ask for.
+
+    `detail="summary"` responses have no `trades`/`equity_curve` at all (server/tools.py's
+    _trim() drops them to keep that request cheap and non-exposing) -- .trades and
+    .equity_curve return an empty DataFrame in that case rather than raising, since "there
+    is no per-trade data in a summary response" is an expected, not exceptional, state.
+    """
+
+    def __init__(self, payload):
+        self.raw = payload
+        self._trades_df = None
+        self._equity_df = None
+
+    @property
+    def summary(self):
+        """Aggregate metrics: total_pnl_rupees, mean_return_on_margin, win_rate,
+        max_drawdown_rupees, avg_margin_points, charges_share_of_gross, and
+        ratios.{sharpe,profit_factor,calmar} -- see explain_methodology('honesty') for
+        what each does and does not prove. No ratios at all below 30 trades (the sample
+        floor); check .honesty for why a number is or isn't here."""
+        return self.raw.get("summary", {})
+
+    @property
+    def honesty(self):
+        """The out-of-sample split, walk-forward folds, bootstrap interval and deflated
+        Sharpe -- read this before trusting `.summary` at all."""
+        return self.raw.get("honesty", {})
+
+    @property
+    def interpretation(self):
+        """Plain-language reading of this specific result, and what it does not support."""
+        return self.raw.get("interpretation")
+
+    @property
+    def trades(self):
+        """pandas.DataFrame, one row per trade. Requires pandas (a hard dependency of this
+        package, not optional -- see pyproject.toml)."""
+        if self._trades_df is None:
+            import pandas as pd
+            self._trades_df = pd.DataFrame(self.raw.get("trades") or [])
+        return self._trades_df
+
+    @property
+    def equity_curve(self):
+        """pandas.DataFrame, one row per trade in exit order -- cumulative net P&L and the
+        gap to the running peak. See .raw['equity_curve']['note'] for the exact column
+        semantics the server documents."""
+        if self._equity_df is None:
+            import pandas as pd
+            curve = self.raw.get("equity_curve") or {}
+            rows = curve.get("rows") or []
+            columns = curve.get("columns")
+            self._equity_df = pd.DataFrame(rows, columns=columns) if columns else pd.DataFrame(rows)
+        return self._equity_df
+
+    @property
+    def qualified(self):
+        """True if this result was strong enough (out-of-sample and walk-forward, not
+        just P&L) to be saved into this account's strategy book. See .why_not_qualified
+        when False."""
+        return (self.raw.get("strategy_book") or {}).get("qualified", False)
+
+    @property
+    def why_not_qualified(self):
+        """None when .qualified is True; otherwise the server's explanation of which
+        check(s) failed."""
+        book = self.raw.get("strategy_book") or {}
+        return None if book.get("qualified") else book.get("note")
+
+    @property
+    def backtest_id(self):
+        return self.raw.get("backtest_id")
+
+    @property
+    def report_url(self):
+        """A shareable, human-readable report page -- the full equity curve as a chart,
+        monthly bars, and every trade regardless of what `detail` was requested here."""
+        return self.raw.get("report_url")
+
+    @property
+    def warnings(self):
+        """Disclosed modeling gaps and approximations -- e.g. a naked-margin ratio
+        calibrated today and applied to the past. Always worth reading, never worth
+        hiding behind a flag."""
+        return self.raw.get("warnings", [])
+
+    def to_dict(self):
+        """The complete, unwrapped server payload."""
+        return self.raw
+
+    def __repr__(self):
+        # Field names verified against a real run_backtest response, not assumed: there is
+        # no "cagr" -- the summary's actual return metrics are total_pnl_rupees,
+        # mean_return_on_margin, and ratios.sharpe/profit_factor/calmar.
+        s = self.summary
+        n = s.get("n_trades")
+        pnl = s.get("total_pnl_rupees")
+        pnl_txt = f"pnl={pnl:+,.0f}Rs" if isinstance(pnl, (int, float)) else "pnl=n/a"
+        n_txt = f"n_trades={n}" if n is not None else "insufficient_sample"
+        return f"<BacktestResult {self.backtest_id or '(unsaved)'} {pnl_txt} {n_txt}>"

stratify_mcp-0.1.1/stratify_mcp.egg-info/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: stratify-mcp
+Version: 0.1.1
+Summary: Python client for the Stratify MCP options-backtesting API
+Author: Stratify
+License: MIT
+Project-URL: Homepage, https://stratify.aeon-labs.site
+Project-URL: Documentation, https://stratify.aeon-labs.site/docs
+Project-URL: Source, https://github.com/Srinath-exe/stratify-mcp
+Project-URL: Issues, https://github.com/Srinath-exe/stratify-mcp/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=1.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# stratify-mcp
+
+Python client for [Stratify](https://stratify.aeon-labs.site) — real 1-minute NIFTY options data,
+honest backtests (out-of-sample, walk-forward, deflated Sharpe, all reported alongside the
+number, not instead of it).
+
+```bash
+pip install stratify-mcp
+```
+
+## Quickstart
+
+```python
+from stratify_mcp import StratifyClient
+
+# One-time: create an account and get a key. The key is shown once -- save it.
+signup = StratifyClient.signup("you@example.com")
+client = StratifyClient(api_key=signup["api_key"])
+
+result = client.run_backtest({
+    "legs": [
+        {"side": "sell", "type": "CE", "strike": {"delta_near": 0.2}},
+        {"side": "sell", "type": "PE", "strike": {"delta_near": 0.2}},
+    ],
+    # The reason for the trade, not just the trade.
+    "entry": {"cadence": "weekly", "dte": 3, "time": "09:30",
+              "when": {"vix": {"gte": 15}}},
+    # Managed while it is open: take profit, and roll the tested side if it doubles.
+    "rules": [
+        {"when": {"pnl_pct_of_credit": {"gte": 0.6}}, "then": "close"},
+        {"when": {"leg_mark_mult": {"gte": 2.0, "leg": 0}},
+         "then": {"roll": {"legs": [0], "to": {"delta_near": 0.2}}}, "max_times": 2},
+    ],
+    "portfolio": {"stop_after_losses": 3, "resume_after_days": 30},
+})
+
+print(result.summary["total_pnl_rupees"], result.summary["max_drawdown_rupees"])
+print(result.summary["ratios"])       # sharpe, profit_factor, calmar (only above 30 trades)
+print(result.honesty)          # out-of-sample split, walk-forward folds, deflated Sharpe
+result.trades                  # pandas.DataFrame, one row per trade
+result.equity_curve            # pandas.DataFrame
+print(result.report_url)       # shareable page with the full chart and every trade
+```
+
+Already have a key? Skip `signup()`:
+
+```python
+client = StratifyClient(api_key="sk_live_...")
+```
+
+## Why a Python client at all, when it's just JSON-RPC
+
+There's no separate REST endpoint for `run_backtest` — every tool is reached through one
+`POST /mcp` speaking MCP JSON-RPC 2.0. This package exists so you don't hand-roll that
+envelope: `client.run_backtest(...)` is a real function call, errors come back as Python
+exceptions you can `except`, and results come back as `pandas.DataFrame`s instead of raw
+JSON, because that's what you're actually going to do with a table of trades.
+
+## Errors
+
+```python
+from stratify_mcp import AuthenticationError, QuotaExceededError, ToolRefusalError
+
+try:
+    result = client.run_backtest(spec)
+except AuthenticationError:
+    ...  # bad or revoked key
+except QuotaExceededError as e:
+    ...  # e.limit, e.retry_after_seconds
+except ToolRefusalError as e:
+    ...  # the server read your spec and refused it -- str(e) says why
+```
+
+## Methods
+
+| Method | Returns |
+|---|---|
+| `run_backtest(spec, lots=1, detail="standard")` | `BacktestResult` |
+| `get_backtest(backtest_id, detail=None)` | `BacktestResult` |
+| `describe_coverage()` | `dict` — symbols, date range, structures, gates, biases, cost model |
+| `explain_methodology(topic=None)` | `dict` |
+| `list_strategies(order="consistency", limit=None)` | `dict` — `{"strategies": [...], "bar": {...}, ...}`, this account's strategies that held up out-of-sample |
+| `search(query)` / `fetch(id)` | `dict` |
+| `StratifyClient.signup(email)` (staticmethod) | `dict` — includes `api_key`, shown once |
+
+`detail` on `run_backtest`/`get_backtest`: `"summary"` (aggregates only, cheapest),
+`"standard"` (default — equity curve, breakdowns, first 25 trades), `"full"` (every
+stored trade).
+
+## `BacktestResult`
+
+| Property | Type |
+|---|---|
+| `.summary` | `dict` |
+| `.honesty` | `dict` |
+| `.interpretation` | `str` |
+| `.trades` | `pandas.DataFrame` |
+| `.equity_curve` | `pandas.DataFrame` |
+| `.qualified` / `.why_not_qualified` | `bool` / `str \| None` |
+| `.backtest_id` / `.report_url` | `str` |
+| `.warnings` | `list[str]` |
+| `.to_dict()` | the complete raw payload |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Tests run against a mocked transport and need no live server or API key.
+
+## License
+
+MIT.

stratify_mcp-0.1.1/stratify_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+stratify_mcp/__init__.py
+stratify_mcp/client.py
+stratify_mcp/exceptions.py
+stratify_mcp/models.py
+stratify_mcp.egg-info/PKG-INFO
+stratify_mcp.egg-info/SOURCES.txt
+stratify_mcp.egg-info/dependency_links.txt
+stratify_mcp.egg-info/requires.txt
+stratify_mcp.egg-info/top_level.txt
+tests/test_client.py

stratify_mcp-0.1.1/stratify_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

stratify_mcp-0.1.1/stratify_mcp.egg-info/requires.txt

@@ -0,0 +1,4 @@
+pandas>=1.5
+
+[dev]
+pytest>=7

stratify_mcp-0.1.1/stratify_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+stratify_mcp

stratify_mcp-0.1.1/tests/test_client.py

@@ -0,0 +1,201 @@
+"""Unit tests against a mocked transport -- no live server required. Each test patches
+urllib.request.urlopen to hand back exactly the JSON-RPC envelope server/app.py would
+produce for that scenario (copied from reading app.py's _handle()/tools.py directly, not
+guessed), so these pin the wire contract this client actually depends on.
+"""
+import json
+import urllib.error
+from unittest.mock import patch
+
+import pytest
+
+from stratify_mcp import (AuthenticationError, BacktestResult, ProtocolError,
+                      QuotaExceededError, StratifyClient, ToolRefusalError)
+
+
+class _FakeResponse:
+    def __init__(self, body):
+        self._body = json.dumps(body).encode()
+
+    def read(self):
+        return self._body
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+
+def _rpc_result(structured):
+    return {"jsonrpc": "2.0", "id": 1,
+            "result": {"content": [{"type": "text", "text": json.dumps(structured)}],
+                      "structuredContent": structured, "isError": False}}
+
+
+def _rpc_error(code, message, data=None):
+    err = {"code": code, "message": message}
+    if data:
+        err["data"] = data
+    return {"jsonrpc": "2.0", "id": 1, "error": err}
+
+
+def _rpc_refusal(message):
+    return {"jsonrpc": "2.0", "id": 1,
+            "result": {"content": [{"type": "text", "text": message}], "isError": True}}
+
+
+def _client():
+    return StratifyClient(api_key="sk_live_test", base_url="https://example.invalid")
+
+
+def test_run_backtest_returns_backtest_result_with_dataframes():
+    payload = {
+        "backtest_id": "bt_123", "report_url": "https://example.invalid/r/tok",
+        "summary": {"cagr": 0.42, "n_trades": 40},
+        "honesty": {"oos_split": "70/30"},
+        "trades": [{"n": 1, "entry": "2025-07-01 09:30", "pnl_pts": 12.5},
+                   {"n": 2, "entry": "2025-07-08 09:30", "pnl_pts": -4.0}],
+        "equity_curve": {"columns": ["date", "equity_rupees"],
+                         "rows": [["2025-07-01", 100000], ["2025-07-08", 101250]]},
+        "strategy_book": {"qualified": True},
+    }
+    with patch("urllib.request.urlopen", return_value=_FakeResponse(_rpc_result(payload))) as m:
+        result = _client().run_backtest(
+            {"structure": "short_strangle", "params": {"pct_offset": 1.5}})
+
+    assert isinstance(result, BacktestResult)
+    assert result.backtest_id == "bt_123"
+    assert result.qualified is True
+    assert result.summary["cagr"] == 0.42
+    assert len(result.trades) == 2
+    assert list(result.trades["pnl_pts"]) == [12.5, -4.0]
+    assert list(result.equity_curve.columns) == ["date", "equity_rupees"]
+    assert len(result.equity_curve) == 2
+
+    # Confirms the actual wire request shape, not just the response handling.
+    sent_body = json.loads(m.call_args[0][0].data)
+    assert sent_body["method"] == "tools/call"
+    assert sent_body["params"]["name"] == "run_backtest"
+    assert sent_body["params"]["arguments"]["spec"]["structure"] == "short_strangle"
+    assert sent_body["params"]["arguments"]["detail"] == "standard"
+    assert m.call_args[0][0].get_header("Authorization") == "Bearer sk_live_test"
+
+
+def test_summary_detail_has_no_trades_but_does_not_raise():
+    payload = {"backtest_id": "bt_999", "summary": {"cagr": 0.1},
+              "strategy_book": {"qualified": False, "note": "n_trades below 30"}}
+    with patch("urllib.request.urlopen", return_value=_FakeResponse(_rpc_result(payload))):
+        result = _client().run_backtest({"structure": "long_option", "params": {}},
+                                        detail="summary")
+    assert result.qualified is False
+    assert result.why_not_qualified == "n_trades below 30"
+    assert result.trades.empty
+    assert result.equity_curve.empty
+
+
+def test_authentication_error():
+    body = _rpc_error(-32001, "missing or invalid API key",
+                      {"how_to_fix": "POST /v1/signup ..."})
+    with patch("urllib.request.urlopen", return_value=_FakeResponse(body)):
+        with pytest.raises(AuthenticationError) as exc_info:
+            _client().describe_coverage()
+    assert "how_to_fix" in exc_info.value.data
+
+
+def test_quota_exceeded_error_carries_limit_and_retry_after():
+    body = _rpc_error(-32002, "cpu_seconds_per_hour exceeded",
+                      {"limit": "cpu_seconds_per_hour", "retry_after_seconds": 120})
+    with patch("urllib.request.urlopen", return_value=_FakeResponse(body)):
+        with pytest.raises(QuotaExceededError) as exc_info:
+            _client().run_backtest({"structure": "credit_spread", "params": {}})
+    assert exc_info.value.limit == "cpu_seconds_per_hour"
+    assert exc_info.value.retry_after_seconds == 120
+
+
+def test_tool_refusal_is_not_a_protocol_error():
+    body = _rpc_refusal("this strategy's queries touched only 4 distinct contracts; at "
+                        "least 20 are required. Widen the period or the strike range")
+    with patch("urllib.request.urlopen", return_value=_FakeResponse(body)):
+        with pytest.raises(ToolRefusalError, match="distinct contracts"):
+            _client().run_backtest({"structure": "iron_condor", "params": {}})
+
+
+def test_unrecognised_error_code_becomes_protocol_error():
+    body = _rpc_error(-32603, "internal error")
+    with patch("urllib.request.urlopen", return_value=_FakeResponse(body)):
+        with pytest.raises(ProtocolError) as exc_info:
+            _client().describe_coverage()
+    assert exc_info.value.code == -32603
+
+
+def test_describe_coverage_search_fetch_list_strategies_send_correct_tool_names():
+    for method_call, tool_name, expected_args in [
+        (lambda c: c.describe_coverage(), "describe_coverage", {}),
+        (lambda c: c.explain_methodology("margin"), "explain_methodology", {"topic": "margin"}),
+        (lambda c: c.search("SENSEX weekly"), "search", {"query": "SENSEX weekly"}),
+        (lambda c: c.fetch("bt_1"), "fetch", {"id": "bt_1"}),
+        (lambda c: c.list_strategies(order="pnl", limit=5), "list_strategies",
+         {"order": "pnl", "limit": 5}),
+    ]:
+        with patch("urllib.request.urlopen", return_value=_FakeResponse(_rpc_result({"ok": True}))) as m:
+            method_call(_client())
+        sent = json.loads(m.call_args[0][0].data)
+        assert sent["params"]["name"] == tool_name
+        assert sent["params"]["arguments"] == expected_args
+
+
+def test_get_backtest_returns_backtest_result():
+    payload = {"backtest_id": "bt_777", "summary": {"cagr": 0.2},
+              "trades": [], "equity_curve": {"columns": [], "rows": []},
+              "strategy_book": {"qualified": False, "note": "x"}}
+    with patch("urllib.request.urlopen", return_value=_FakeResponse(_rpc_result(payload))) as m:
+        result = _client().get_backtest("bt_777", detail="full")
+    assert isinstance(result, BacktestResult)
+    assert result.backtest_id == "bt_777"
+    sent = json.loads(m.call_args[0][0].data)
+    assert sent["params"]["arguments"] == {"backtest_id": "bt_777", "detail": "full"}
+
+
+def test_signup_returns_raw_dict():
+    body = {"account_id": "acc_1", "key_id": "key_1", "api_key": "sk_live_new",
+           "tier": "free", "mcp_endpoint": "https://example.invalid/mcp"}
+    with patch("urllib.request.urlopen", return_value=_FakeResponse(body)) as m:
+        result = StratifyClient.signup("me@example.com", base_url="https://example.invalid")
+    assert result["api_key"] == "sk_live_new"
+    sent = json.loads(m.call_args[0][0].data)
+    assert sent == {"email": "me@example.com"}
+
+
+def test_signup_failure_raises_transport_error():
+    from stratify_mcp import TransportError
+
+    def raise_http_error(*a, **kw):
+        raise urllib.error.HTTPError(
+            "https://example.invalid/v1/signup", 400, "bad request", {},
+            fp=__import__("io").BytesIO(json.dumps({"error": "a valid email is required"}).encode()))
+
+    with patch("urllib.request.urlopen", side_effect=raise_http_error):
+        with pytest.raises(TransportError, match="a valid email is required"):
+            StratifyClient.signup("not-an-email", base_url="https://example.invalid")
+
+
+def test_missing_api_key_raises_immediately():
+    with pytest.raises(ValueError):
+        StratifyClient(api_key="")
+
+
+def test_repr_uses_real_field_names_not_a_nonexistent_cagr():
+    """Field names verified against a real local server run, not assumed: there is no
+    'cagr' in the actual summary payload -- the real return metric is total_pnl_rupees."""
+    result = BacktestResult({"backtest_id": "bt_1",
+                             "summary": {"total_pnl_rupees": 6584.19, "n_trades": 50}})
+    text = repr(result)
+    assert "bt_1" in text
+    assert "6,584" in text or "6584" in text
+    assert "n_trades=50" in text
+
+
+def test_repr_handles_insufficient_sample_without_crashing():
+    result = BacktestResult({"backtest_id": "bt_2", "summary": {}})
+    assert "insufficient_sample" in repr(result)