talis-cli 0.2.1__tar.gz → 0.3.0__tar.gz

{talis_cli-0.2.1 → talis_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: talis-cli
-Version: 0.2.1
+Version: 0.3.0
 Summary: Command-line client for the Talis trading platform. Sign in via device flow, manage sessions, view portfolio, place orders.
 Author: Talis
 License-Expression: Apache-2.0
@@ -187,14 +187,21 @@ shape) — `claude_desktop_config.json`:
 }
 ```
 
-Tools (25):
+Tools (26):
 
-`amend_strategy`, `balance`, `brief_latest`, `buy`, `cancel_all_orders`,
+`amend_strategy`, `backtest`, `balance`, `brief_latest`, `buy`, `cancel_all_orders`,
 `cancel_order`, `chat`, `close`, `create_strategy`, `history`,
 `notifications_create`, `open_orders`, `outcomes`, `packets`, `place_order`,
 `portfolio`, `research`, `sell`, `start_strategy`, `stop_strategy`,
 `strategies`, `strategy`, `strategy_activity`, `validate_strategy`, `whoami`.
 
+**Strategy workflow.** `validate_strategy(dsl)` checks a DSL without side
+effects; `backtest(pair, dsl, days=30, interval="1h")` runs it through the live
+engine on real historical candles (read-only) and returns return, Sharpe,
+drawdown, trade count; `create_strategy(pair, dsl, paper=True)` runs it on the
+simulated book; the same call with `paper=False, confirm_real_money=True`
+deploys it live.
+
 **Safety — read this before pointing an agent at it.** The trading tools
 (`buy` / `sell` / `close` / `create_strategy`) execute with **REAL MONEY by
 default** (`paper=False`). Pass `paper=True` to simulate instead.

{talis_cli-0.2.1 → talis_cli-0.3.0}/README.md

@@ -159,14 +159,21 @@ shape) — `claude_desktop_config.json`:
 }
 ```
 
-Tools (25):
+Tools (26):
 
-`amend_strategy`, `balance`, `brief_latest`, `buy`, `cancel_all_orders`,
+`amend_strategy`, `backtest`, `balance`, `brief_latest`, `buy`, `cancel_all_orders`,
 `cancel_order`, `chat`, `close`, `create_strategy`, `history`,
 `notifications_create`, `open_orders`, `outcomes`, `packets`, `place_order`,
 `portfolio`, `research`, `sell`, `start_strategy`, `stop_strategy`,
 `strategies`, `strategy`, `strategy_activity`, `validate_strategy`, `whoami`.
 
+**Strategy workflow.** `validate_strategy(dsl)` checks a DSL without side
+effects; `backtest(pair, dsl, days=30, interval="1h")` runs it through the live
+engine on real historical candles (read-only) and returns return, Sharpe,
+drawdown, trade count; `create_strategy(pair, dsl, paper=True)` runs it on the
+simulated book; the same call with `paper=False, confirm_real_money=True`
+deploys it live.
+
 **Safety — read this before pointing an agent at it.** The trading tools
 (`buy` / `sell` / `close` / `create_strategy`) execute with **REAL MONEY by
 default** (`paper=False`). Pass `paper=True` to simulate instead.

{talis_cli-0.2.1 → talis_cli-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "talis-cli"
-version = "0.2.1"
+version = "0.3.0"
 description = "Command-line client for the Talis trading platform. Sign in via device flow, manage sessions, view portfolio, place orders."
 readme = "README.md"
 license = "Apache-2.0"

{talis_cli-0.2.1 → talis_cli-0.3.0}/talis/api.py

@@ -491,6 +491,27 @@ class Client:
             params={"tenant_id": tenant_id},
         )
 
+    def get_candles(self, *, symbol: str, interval: str = "1h", limit: int = 500,
+                    exchange: str | None = None) -> dict:
+        """Historical candles from the control plane (``GET /candles``).
+
+        Returns ``{"candles": [{t,o,h,l,c,v}, ...], "symbol", "interval"}`` —
+        abbreviated OHLCV keys, newest last. The backtester wants the full
+        names; ``backtest_candles`` in the MCP layer does that mapping.
+        """
+        params: dict[str, Any] = {"symbol": symbol, "interval": interval, "limit": limit}
+        if exchange:
+            params["exchange"] = exchange
+        return self._request("GET", "/candles", params=params)
+
+    def create_backtest(self, *, body: dict) -> dict:
+        """Submit a backtest (``POST /backtests``). Returns ``{backtest_id, status}``."""
+        return self._request("POST", "/backtests", json=body)
+
+    def get_backtest(self, *, backtest_id: str) -> dict:
+        """Backtest status + results (``GET /backtests/{id}``)."""
+        return self._request("GET", f"/backtests/{backtest_id}")
+
     def validate_strategy(self, *, dsl: dict) -> dict:
         """Validate a DSL WITHOUT creating anything. No side effects.
 

{talis_cli-0.2.1 → talis_cli-0.3.0}/talis/commands/mcp_server.py

@@ -35,8 +35,11 @@ Design notes
 from __future__ import annotations
 
 import contextlib
+import json
 import os
+import re
 import sys
+import time
 from typing import Any
 
 import typer
@@ -756,6 +759,116 @@ def close(symbol: str, paper: bool = False) -> dict:
     return resp
 
 
+_CANDLE_KEYS = {"t": "timestamp", "o": "open", "h": "high", "l": "low", "c": "close", "v": "volume"}
+_INTERVAL_MINUTES = {"1m": 1, "5m": 5, "15m": 15, "30m": 30, "1h": 60, "4h": 240, "1d": 1440}
+_BACKTEST_MAX_CANDLES = 5000      # the venue's candleSnapshot ceiling per request
+_PAIR_RE = re.compile(r"\b([A-Z0-9]{2,12}-USD)\b")
+
+
+def backtest_candles(raw: list[dict]) -> list[dict]:
+    """Map the control plane's abbreviated candle keys onto the backtester's."""
+    return [{_CANDLE_KEYS.get(k, k): v for k, v in c.items()} for c in raw]
+
+
+def backtest(pair: str, dsl: dict, days: int = 30, interval: str = "1h",
+             timeout_seconds: int = 180) -> dict:
+    """Backtest a Talis DSL strategy on `pair` over the last `days` of `interval` candles. Read-only — never places an order.
+
+    Runs the SAME engine that executes live strategies (fast mode) against
+    real historical candles fetched for you, so the result is what this exact
+    DSL would have done. Validates the DSL first; an invalid DSL returns the
+    validator's errors and runs nothing.
+
+    Returns the backtest id, the window actually covered, and `results` with
+    `total_return_pct`, `sharpe_ratio`, `max_drawdown_pct`, `total_trades`,
+    `profit_factor` (plus whatever else the engine reports). Cross-asset
+    triggers (e.g. "ETH-USD.rsi_14") get their candles fetched automatically.
+
+    Workflow: validate_strategy → backtest → create_strategy(paper=True) →
+    create_strategy(paper=False, confirm_real_money=True). `days` × `interval`
+    is capped at the venue's 5000-candle window; the response says if it was.
+    """
+    if interval not in _INTERVAL_MINUTES:
+        raise ValueError(f"interval must be one of {sorted(_INTERVAL_MINUTES)}")
+    if days <= 0:
+        raise ValueError("days must be positive")
+    creds = _require_creds()
+    trading_pair = to_trading_pair(pair)
+    dsl_config = dict(dsl)
+    cfg = dict(dsl_config.get("config") or {})
+    cfg.setdefault("exchange", _EXCHANGE)
+    cfg.setdefault("trading_pair", trading_pair)
+    dsl_config["config"] = cfg
+
+    wanted = days * 1440 // _INTERVAL_MINUTES[interval]
+    limit = min(wanted, _BACKTEST_MAX_CANDLES)
+    capped = wanted > _BACKTEST_MAX_CANDLES
+
+    with api.client_from_credentials(creds) as c:
+        check = c.validate_strategy(dsl=dsl_config)
+        if isinstance(check, dict) and check.get("valid") is False:
+            return {"valid": False, "errors": check.get("errors"),
+                    "summary": check.get("human_readable_summary"),
+                    "note": "DSL rejected by the engine validator; nothing was run."}
+        primary = c.get_candles(symbol=base_coin(trading_pair), interval=interval,
+                                limit=limit, exchange=cfg["exchange"])
+        raw = list(primary.get("candles") or [])
+        if not raw:
+            return {"error": f"no candles returned for {trading_pair} at {interval}"}
+        candles = backtest_candles(raw)
+        cross: dict[str, list[dict]] = {}
+        for other in sorted(set(_PAIR_RE.findall(json.dumps(dsl_config))) - {trading_pair}):
+            resp = c.get_candles(symbol=base_coin(other), interval=interval,
+                                 limit=limit, exchange=cfg["exchange"])
+            if resp.get("candles"):
+                cross[other] = backtest_candles(resp["candles"])
+        start_ts = int(candles[0]["timestamp"])
+        end_ts = int(candles[-1]["timestamp"])
+        body: dict[str, Any] = {
+            "tenant_id": creds.tenant_id,
+            "mode": "fast",
+            "exchange": cfg["exchange"],
+            "trading_pair": trading_pair,
+            "start_ts": start_ts,
+            "end_ts": end_ts,
+            "interval": interval,
+            "candles": candles,
+            "dsl": dsl_config,
+        }
+        if cross:
+            body["cross_asset_candles"] = cross
+        submitted = c.create_backtest(body=body)
+        backtest_id = submitted.get("backtest_id")
+        if not backtest_id:
+            return {"error": "backtest was not accepted", "response": submitted}
+        deadline = time.monotonic() + timeout_seconds
+        status = submitted
+        while time.monotonic() < deadline:
+            status = c.get_backtest(backtest_id=backtest_id)
+            if str(status.get("status", "")).upper() not in ("RUNNING", "PENDING", "QUEUED", ""):
+                break
+            time.sleep(2)
+
+    results = status.get("results") if isinstance(status, dict) else None
+    out: dict[str, Any] = {
+        "backtest_id": backtest_id,
+        "status": status.get("status"),
+        "pair": trading_pair,
+        "window": {"interval": interval, "candles": len(candles), "start_ts": start_ts,
+                   "end_ts": end_ts, "requested_days": days, "capped_to_venue_window": capped},
+        "cross_assets": sorted(cross),
+        "results": results,
+    }
+    if isinstance(results, dict):
+        out["summary"] = {k: results.get(k) for k in (
+            "total_return_pct", "sharpe_ratio", "max_drawdown_pct", "total_trades", "profit_factor")}
+    if str(out["status"] or "").upper() in ("RUNNING", "PENDING", "QUEUED"):
+        out["note"] = f"still running after {timeout_seconds}s; call again later via the API: GET /backtests/{backtest_id}"
+    out["next"] = ("create_strategy(pair, dsl, paper=True) runs it on the simulated book; "
+                   "create_strategy(pair, dsl, paper=False, confirm_real_money=True) goes live.")
+    return out
+
+
 def create_strategy(pair: str, dsl: dict, paper: bool = False,
                     confirm_real_money: bool = False) -> dict:
     """Create and auto-start a trading strategy on `pair` from a Talis DSL dict. Trades REAL money by default — a real strategy requires confirm_real_money=True; pass paper=True to simulate.
@@ -1259,6 +1372,7 @@ TOOL_FUNCTIONS = (
     strategy,
     strategy_activity,
     validate_strategy,
+    backtest,
     outcomes,
     buy,
     sell,
@@ -1293,7 +1407,9 @@ _SERVER_INSTRUCTIONS = (
     "never left unprotected. `stop_strategy` does NOT close the position; it "
     "only ends the automation and leaves any position unmanaged, so use `close` "
     "to actually exit, and `cancel_order` to kill an unfilled limit order. "
-    "Check `validate_strategy` before creating anything with paper=False. "
+    "Check `validate_strategy` before creating anything with paper=False, and "
+    "`backtest` (read-only, real historical candles, the live engine) to see what "
+    "a DSL would have done before deploying it. "
     "Withdrawals are not available through this server."
 )
 

{talis_cli-0.2.1 → talis_cli-0.3.0}/talis_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: talis-cli
-Version: 0.2.1
+Version: 0.3.0
 Summary: Command-line client for the Talis trading platform. Sign in via device flow, manage sessions, view portfolio, place orders.
 Author: Talis
 License-Expression: Apache-2.0
@@ -187,14 +187,21 @@ shape) — `claude_desktop_config.json`:
 }
 ```
 
-Tools (25):
+Tools (26):
 
-`amend_strategy`, `balance`, `brief_latest`, `buy`, `cancel_all_orders`,
+`amend_strategy`, `backtest`, `balance`, `brief_latest`, `buy`, `cancel_all_orders`,
 `cancel_order`, `chat`, `close`, `create_strategy`, `history`,
 `notifications_create`, `open_orders`, `outcomes`, `packets`, `place_order`,
 `portfolio`, `research`, `sell`, `start_strategy`, `stop_strategy`,
 `strategies`, `strategy`, `strategy_activity`, `validate_strategy`, `whoami`.
 
+**Strategy workflow.** `validate_strategy(dsl)` checks a DSL without side
+effects; `backtest(pair, dsl, days=30, interval="1h")` runs it through the live
+engine on real historical candles (read-only) and returns return, Sharpe,
+drawdown, trade count; `create_strategy(pair, dsl, paper=True)` runs it on the
+simulated book; the same call with `paper=False, confirm_real_money=True`
+deploys it live.
+
 **Safety — read this before pointing an agent at it.** The trading tools
 (`buy` / `sell` / `close` / `create_strategy`) execute with **REAL MONEY by
 default** (`paper=False`). Pass `paper=True` to simulate instead.

{talis_cli-0.2.1 → talis_cli-0.3.0}/talis_cli.egg-info/SOURCES.txt

@@ -47,6 +47,7 @@ tests/test_history.py
 tests/test_login_flow.py
 tests/test_loopback_login.py
 tests/test_mcp.py
+tests/test_mcp_backtest.py
 tests/test_mcp_balance_contract.py
 tests/test_mcp_docstring_contract.py
 tests/test_mcp_mode_contract.py

{talis_cli-0.2.1 → talis_cli-0.3.0}/tests/test_mcp.py

@@ -439,7 +439,8 @@ class TestNotifications:
 EXPECTED_TOOLS = [
     "whoami", "portfolio", "balance", "research", "packets", "brief_latest",
     "history", "open_orders", "strategies", "strategy", "strategy_activity",
-    "validate_strategy", "outcomes",
+    "validate_strategy",
+    "backtest", "outcomes",
     "buy", "sell", "close", "place_order", "cancel_order", "cancel_all_orders",
     "create_strategy", "amend_strategy", "start_strategy", "stop_strategy",
     "chat", "notifications_create",

talis_cli-0.3.0/tests/test_mcp_backtest.py

@@ -0,0 +1,109 @@
+"""`backtest` over MCP: validate → fetch candles → POST /backtests (fast) → poll.
+
+Pinned facts (verified against engine/api/routes/backtests.py + market.py):
+* /candles answers abbreviated keys {t,o,h,l,c,v}; the backtester wants the
+  full names — the tool must map them or the run silently sees no data.
+* fast mode requires `dsl`; the tool sends the DSL with its config block
+  completed (exchange + trading_pair), exactly what create_strategy sends.
+* an INVALID DSL must never reach /backtests.
+* cross-asset references ("ETH-USD.rsi_14") need their own candles.
+* the tool is read-only: no order route is ever touched.
+"""
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+import respx
+
+from talis.commands import mcp_server
+
+BASE = "http://api.test"
+DSL = {
+    "type": "position",
+    "config": {"leverage": 3},
+    "entry": {"trigger": {"indicator": {"indicator": "ETH-USD.rsi_14", "op": "<", "value": 30}},
+              "side": "buy", "amount": {"value": 100, "mode": "usd"}},
+    "exits": [{"name": "tp", "trigger": {"price_percent_from_entry": {"op": ">=", "value": 5}}}],
+}
+CANDLES = [{"t": 1_700_000_000_000 + i * 3_600_000, "o": 1, "h": 2, "l": 0.5, "c": 1.5, "v": 10}
+           for i in range(3)]
+
+
+@pytest.fixture(autouse=True)
+def _no_sleep(monkeypatch):
+    monkeypatch.setattr(mcp_server.time, "sleep", lambda *_: None)
+
+
+def _routes(valid=True, statuses=("RUNNING", "COMPLETED")):
+    respx.post(f"{BASE}/strategies/validate").mock(
+        return_value=httpx.Response(200, json={"valid": valid, "errors": [] if valid else ["bad trigger"],
+                                               "human_readable_summary": "x"}))
+    respx.get(f"{BASE}/candles").mock(
+        return_value=httpx.Response(200, json={"candles": CANDLES, "symbol": "X", "interval": "1h"}))
+    submit = respx.post(f"{BASE}/backtests").mock(
+        return_value=httpx.Response(200, json={"backtest_id": "bt_1", "status": "RUNNING"}))
+    seq = [httpx.Response(200, json={"backtest_id": "bt_1", "status": st,
+                                     "results": ({"total_return_pct": 4.2, "sharpe_ratio": 1.1,
+                                                  "max_drawdown_pct": -2.0, "total_trades": 7,
+                                                  "profit_factor": 1.8, "extra": True}
+                                                 if st == "COMPLETED" else None)})
+           for st in statuses]
+    respx.get(f"{BASE}/backtests/bt_1").mock(side_effect=seq)
+    return submit
+
+
+@respx.mock
+def test_backtest_fetches_candles_normalises_keys_and_returns_summary(stored_creds):
+    submit = _routes()
+    out = mcp_server.backtest("BTC", DSL, days=1, interval="1h")
+    assert out["status"] == "COMPLETED" and out["backtest_id"] == "bt_1"
+    body = json.loads(submit.calls[0].request.content)
+    assert body["mode"] == "fast" and body["trading_pair"] == "BTC-USD"
+    assert body["dsl"]["config"]["trading_pair"] == "BTC-USD"
+    assert body["dsl"]["config"]["exchange"] == "hyperliquid_perpetual"
+    assert set(body["candles"][0]) == {"timestamp", "open", "high", "low", "close", "volume"}
+    assert body["start_ts"] == CANDLES[0]["t"] and body["end_ts"] == CANDLES[-1]["t"]
+    # cross-asset candles for the ETH-USD reference, never for the primary
+    assert set(body["cross_asset_candles"]) == {"ETH-USD"}
+    assert out["cross_assets"] == ["ETH-USD"]
+    assert out["summary"] == {"total_return_pct": 4.2, "sharpe_ratio": 1.1, "max_drawdown_pct": -2.0,
+                              "total_trades": 7, "profit_factor": 1.8}
+    assert out["window"]["candles"] == 3 and out["window"]["capped_to_venue_window"] is False
+    assert "create_strategy" in out["next"]
+
+
+@respx.mock
+def test_invalid_dsl_never_reaches_the_backtester(stored_creds):
+    submit = _routes(valid=False)
+    out = mcp_server.backtest("BTC", DSL, days=1)
+    assert out["valid"] is False and out["errors"] == ["bad trigger"]
+    assert not submit.called
+
+
+@respx.mock
+def test_long_windows_are_capped_and_reported(stored_creds):
+    _routes()
+    out = mcp_server.backtest("BTC", DSL, days=365, interval="1m")
+    assert out["window"]["capped_to_venue_window"] is True
+    assert out["window"]["requested_days"] == 365
+
+
+@respx.mock
+def test_still_running_returns_a_pointer_not_an_error(stored_creds):
+    _routes(statuses=("RUNNING", "RUNNING", "RUNNING"))
+    out = mcp_server.backtest("BTC", DSL, days=1, timeout_seconds=0)
+    assert out["status"] == "RUNNING" and "GET /backtests/bt_1" in out["note"]
+
+
+def test_bad_interval_is_rejected_before_any_network(stored_creds):
+    with pytest.raises(ValueError, match="interval"):
+        mcp_server.backtest("BTC", DSL, interval="7m")
+
+
+def test_backtest_is_registered_and_read_only():
+    assert mcp_server.backtest in mcp_server.TOOL_FUNCTIONS
+    import inspect
+    assert "paper" not in inspect.signature(mcp_server.backtest).parameters
+    assert "confirm_real_money" not in inspect.signature(mcp_server.backtest).parameters