speculo 0.1.0__tar.gz

speculo-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: speculo
+Version: 0.1.0
+Summary: Speculo Studio CLI — backtest your trading strategies locally and sync results.
+Author: Speculo
+License: Proprietary
+Project-URL: Homepage, https://speculotrading.com
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Speculo CLI
+
+Run Speculo Studio backtests on your own machine — your hardware, your data, results
+synced to your Studio history.
+
+## Install
+
+```bash
+pip install speculo
+```
+
+## Authenticate
+
+Create a CLI token in Studio → Settings → CLI tokens, then:
+
+```bash
+speculo login --token spk_xxxxxxxxxxxx
+# self-hosted / staging:
+speculo login --token spk_xxx --api https://api.staging.speculotrading.com
+```
+
+Credentials are stored in `~/.speculo/config.json` (mode 600). You can also set
+`SPECULO_TOKEN` / `SPECULO_API` in the environment.
+
+## Backtest
+
+```bash
+# real historical data (fetched via the platform's cached proxy)
+speculo backtest strategy.py --symbol AAPL --timeframe 1d --capital 100000
+
+# your own OHLCV CSV
+speculo backtest strategy.py --csv mydata.csv
+
+# synthetic demo series
+speculo backtest strategy.py --bars 500
+```
+
+Add `--no-sync` to keep a run private (compute locally, don't upload).
+
+## Strategy contract
+
+A strategy defines `on_bar(ctx)` and optionally `initialize(ctx)` — identical to the
+web editor:
+
+```python
+def initialize(ctx):
+    ctx.state["fast"], ctx.state["slow"] = 5, 20
+
+def on_bar(ctx):
+    c = ctx.closes()
+    if len(c) < ctx.state["slow"]:
+        return
+    fast = sum(c[-ctx.state["fast"]:]) / ctx.state["fast"]
+    slow = sum(c[-ctx.state["slow"]:]) / ctx.state["slow"]
+    if fast > slow and ctx.position == 0:
+        ctx.broker.place_order(symbol=ctx.symbol, quantity=10, side="BUY", order_type="MARKET")
+    elif fast < slow and ctx.position > 0:
+        ctx.broker.place_order(symbol=ctx.symbol, quantity=10, side="SELL", order_type="MARKET")
+```
+
+The backtest engine itself is fetched from the platform at runtime, so the CLI always
+runs the exact same engine as the web app.

speculo-0.1.0/README.md

@@ -0,0 +1,62 @@
+# Speculo CLI
+
+Run Speculo Studio backtests on your own machine — your hardware, your data, results
+synced to your Studio history.
+
+## Install
+
+```bash
+pip install speculo
+```
+
+## Authenticate
+
+Create a CLI token in Studio → Settings → CLI tokens, then:
+
+```bash
+speculo login --token spk_xxxxxxxxxxxx
+# self-hosted / staging:
+speculo login --token spk_xxx --api https://api.staging.speculotrading.com
+```
+
+Credentials are stored in `~/.speculo/config.json` (mode 600). You can also set
+`SPECULO_TOKEN` / `SPECULO_API` in the environment.
+
+## Backtest
+
+```bash
+# real historical data (fetched via the platform's cached proxy)
+speculo backtest strategy.py --symbol AAPL --timeframe 1d --capital 100000
+
+# your own OHLCV CSV
+speculo backtest strategy.py --csv mydata.csv
+
+# synthetic demo series
+speculo backtest strategy.py --bars 500
+```
+
+Add `--no-sync` to keep a run private (compute locally, don't upload).
+
+## Strategy contract
+
+A strategy defines `on_bar(ctx)` and optionally `initialize(ctx)` — identical to the
+web editor:
+
+```python
+def initialize(ctx):
+    ctx.state["fast"], ctx.state["slow"] = 5, 20
+
+def on_bar(ctx):
+    c = ctx.closes()
+    if len(c) < ctx.state["slow"]:
+        return
+    fast = sum(c[-ctx.state["fast"]:]) / ctx.state["fast"]
+    slow = sum(c[-ctx.state["slow"]:]) / ctx.state["slow"]
+    if fast > slow and ctx.position == 0:
+        ctx.broker.place_order(symbol=ctx.symbol, quantity=10, side="BUY", order_type="MARKET")
+    elif fast < slow and ctx.position > 0:
+        ctx.broker.place_order(symbol=ctx.symbol, quantity=10, side="SELL", order_type="MARKET")
+```
+
+The backtest engine itself is fetched from the platform at runtime, so the CLI always
+runs the exact same engine as the web app.

speculo-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "speculo"
+version = "0.1.0"
+description = "Speculo Studio CLI — backtest your trading strategies locally and sync results."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "Speculo" }]
+license = { text = "Proprietary" }
+dependencies = []  # stdlib-only: the portable engine is fetched from the server at runtime.
+
+[project.scripts]
+speculo = "speculo.cli:main"
+
+[project.urls]
+Homepage = "https://speculotrading.com"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["speculo*"]

speculo-0.1.0/setup.cfg

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

speculo-0.1.0/speculo/__init__.py

@@ -0,0 +1,6 @@
+"""Speculo Studio CLI — run backtests on your own machine and sync results.
+
+The heavy lifting (the backtest engine) is the same portable ``speculo_engine`` that
+powers the web app; the CLI fetches it from the server at runtime so it never drifts.
+"""
+__version__ = "0.1.0"

speculo-0.1.0/speculo/cli.py

@@ -0,0 +1,127 @@
+"""`speculo` CLI entrypoint.
+
+Commands:
+    speculo login --token <tok> [--api URL]   save credentials
+    speculo backtest STRATEGY.py [--symbol AAPL --timeframe 1d | --csv data.csv
+                                  | --bars 250] [--capital 1000000] [--no-sync]
+    speculo whoami                            show configured API / token prefix
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__, config
+from .client import ApiError, Client
+from .engine_loader import load_engine
+
+
+def _client() -> Client:
+    cfg = config.load()
+    if not cfg.get("token"):
+        print("Not logged in. Run:  speculo login --token <your-token>", file=sys.stderr)
+        raise SystemExit(2)
+    return Client(cfg["api"], cfg["token"])
+
+
+def cmd_login(args) -> int:
+    config.save(token=args.token, api=args.api)
+    print(f"Saved credentials for {args.api or config.DEFAULT_API}.")
+    return 0
+
+
+def cmd_whoami(args) -> int:
+    cfg = config.load()
+    tok = cfg.get("token") or ""
+    print(f"API:   {cfg['api']}")
+    print(f"Token: {tok[:10] + '…' if tok else '(none)'}")
+    return 0
+
+
+def cmd_backtest(args) -> int:
+    client = _client()
+    source = open(args.strategy, encoding="utf-8").read()
+    print("Fetching engine…")
+    engine = load_engine(client)
+
+    # Resolve bars: local CSV → real market data → synthetic demo.
+    if args.csv:
+        bars = engine.load_csv(open(args.csv, encoding="utf-8").read())
+        if not bars:
+            print("No valid OHLCV rows in the CSV.", file=sys.stderr)
+            return 1
+    elif args.symbol:
+        print(f"Fetching {args.symbol} ({args.timeframe})…")
+        md = client.market_data(args.symbol, args.timeframe)
+        bars = engine.load_csv(md["csv_text"])
+        print(f"  {md['rows']} bars from {md['source']}")
+    else:
+        bars = engine.synthetic(args.bars)
+
+    print("Running backtest locally…")
+    try:
+        result = engine.run_source(
+            source, bars, symbol=(args.symbol or "DEMO"),
+            starting_capital=args.capital,
+        )
+    except Exception as e:  # noqa: BLE001 — surface engine/strategy errors plainly
+        print(f"Backtest failed: {e}", file=sys.stderr)
+        return 1
+
+    m = result["metrics"]
+    print("\n-- Results --")
+    print(f"  Trades:        {m['total_trades']}")
+    print(f"  Win rate:      {m['win_rate']}%")
+    print(f"  Total return:  {m['total_return_pct']}%")
+    print(f"  Max drawdown:  {m['max_drawdown_pct']}%")
+    print(f"  Sharpe:        {m['sharpe']}")
+    print(f"  Final equity:  {result['final_equity']}")
+
+    if not args.no_sync:
+        try:
+            saved = client.submit_backtest({
+                "name": args.name, "source": source, "symbol": (args.symbol or "DEMO"),
+                "timeframe": args.timeframe, "starting_capital": args.capital,
+                "metrics": result["metrics"], "equity_curve": result["equity_curve"],
+                "trades": result["trades"],
+            })
+            print(f"\nSynced to your Studio history (id {saved['id']}).")
+        except ApiError as e:
+            print(f"\nRan locally but could not sync: {e}", file=sys.stderr)
+    return 0
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="speculo", description="Speculo Studio CLI")
+    p.add_argument("--version", action="version", version=f"speculo {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    pl = sub.add_parser("login", help="save your CLI token")
+    pl.add_argument("--token", required=True)
+    pl.add_argument("--api", default=None, help="control-plane base URL")
+    pl.set_defaults(func=cmd_login)
+
+    pw = sub.add_parser("whoami", help="show configured credentials")
+    pw.set_defaults(func=cmd_whoami)
+
+    pb = sub.add_parser("backtest", help="run a strategy backtest locally")
+    pb.add_argument("strategy", help="path to a Python strategy (on_bar/initialize)")
+    pb.add_argument("--symbol", default=None, help="fetch real data for this symbol")
+    pb.add_argument("--timeframe", default="1d", choices=["1d", "1w", "1mo"])
+    pb.add_argument("--csv", default=None, help="use a local OHLCV CSV instead of fetching")
+    pb.add_argument("--bars", type=int, default=250, help="synthetic demo bars (no symbol/csv)")
+    pb.add_argument("--capital", type=float, default=1_000_000.0)
+    pb.add_argument("--name", default=None, help="label for this run in your history")
+    pb.add_argument("--no-sync", action="store_true", help="don't upload results")
+    pb.set_defaults(func=cmd_backtest)
+
+    args = p.parse_args(argv)
+    try:
+        return args.func(args)
+    except ApiError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

speculo-0.1.0/speculo/client.py

@@ -0,0 +1,49 @@
+"""Tiny stdlib HTTP client for the Speculo control plane (CLI token auth)."""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+
+
+class ApiError(RuntimeError):
+    pass
+
+
+class Client:
+    def __init__(self, api: str, token: str):
+        self.api = api.rstrip("/")
+        self.token = token
+
+    def _req(self, method: str, path: str, body: dict | None = None) -> dict:
+        url = f"{self.api}{path}"
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(url, data=data, method=method)
+        req.add_header("X-Speculo-Token", self.token)
+        req.add_header("Accept", "application/json")
+        if data is not None:
+            req.add_header("Content-Type", "application/json")
+        try:
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                raw = resp.read().decode()
+                return json.loads(raw) if raw else {}
+        except urllib.error.HTTPError as e:
+            detail = e.read().decode(errors="replace")
+            try:
+                detail = json.loads(detail).get("detail", detail)
+            except ValueError:
+                pass
+            raise ApiError(f"{e.code} {detail}") from e
+        except urllib.error.URLError as e:
+            raise ApiError(f"Could not reach {self.api}: {e.reason}") from e
+
+    def engine_bundle(self) -> dict:
+        return self._req("GET", "/studio/engine-bundle")
+
+    def market_data(self, symbol: str, timeframe: str) -> dict:
+        from urllib.parse import urlencode
+        qs = urlencode({"symbol": symbol, "timeframe": timeframe})
+        return self._req("GET", f"/studio/market-data?{qs}")
+
+    def submit_backtest(self, payload: dict) -> dict:
+        return self._req("POST", "/studio/backtests/cli", payload)

speculo-0.1.0/speculo/config.py

@@ -0,0 +1,45 @@
+"""Local CLI config — token + API base, stored under ~/.speculo/config.json."""
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+
+DEFAULT_API = "https://speculotrading.com/cp"
+_DIR = pathlib.Path(os.path.expanduser("~")) / ".speculo"
+_FILE = _DIR / "config.json"
+
+
+def load() -> dict:
+    # Environment overrides the file so CI can run without `speculo login`.
+    cfg: dict = {}
+    if _FILE.exists():
+        try:
+            cfg = json.loads(_FILE.read_text(encoding="utf-8"))
+        except (ValueError, OSError):
+            cfg = {}
+    if os.environ.get("SPECULO_TOKEN"):
+        cfg["token"] = os.environ["SPECULO_TOKEN"]
+    if os.environ.get("SPECULO_API"):
+        cfg["api"] = os.environ["SPECULO_API"]
+    cfg.setdefault("api", DEFAULT_API)
+    return cfg
+
+
+def save(token: str | None = None, api: str | None = None) -> None:
+    cfg = {}
+    if _FILE.exists():
+        try:
+            cfg = json.loads(_FILE.read_text(encoding="utf-8"))
+        except (ValueError, OSError):
+            cfg = {}
+    if token is not None:
+        cfg["token"] = token
+    if api is not None:
+        cfg["api"] = api
+    _DIR.mkdir(parents=True, exist_ok=True)
+    _FILE.write_text(json.dumps(cfg, indent=2), encoding="utf-8")
+    try:  # best-effort: keep the token file private
+        os.chmod(_FILE, 0o600)
+    except OSError:
+        pass

speculo-0.1.0/speculo/engine_loader.py

@@ -0,0 +1,32 @@
+"""Fetch the portable engine bundle from the server and import it locally.
+
+Keeps the CLI in lock-step with the web app's engine (single source of truth) — the
+CLI ships no engine code of its own. The bundle is cached under ~/.speculo/engine/<ver>.
+"""
+from __future__ import annotations
+
+import importlib
+import os
+import pathlib
+import sys
+
+_CACHE = pathlib.Path(os.path.expanduser("~")) / ".speculo" / "engine"
+
+
+def load_engine(client):
+    """Return the imported ``speculo_engine`` module, fetching/caching as needed."""
+    bundle = client.engine_bundle()
+    version = bundle.get("version", "dev")
+    dest = _CACHE / version
+    pkg = dest / "speculo_engine"
+    if not pkg.exists():
+        pkg.mkdir(parents=True, exist_ok=True)
+        for name, src in bundle["files"].items():
+            (pkg / name).write_text(src, encoding="utf-8")
+
+    if str(dest) not in sys.path:
+        sys.path.insert(0, str(dest))
+    # Drop any previously-imported version so a server upgrade is picked up.
+    for mod in [m for m in list(sys.modules) if m.startswith("speculo_engine")]:
+        del sys.modules[mod]
+    return importlib.import_module("speculo_engine")

speculo-0.1.0/speculo.egg-info/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: speculo
+Version: 0.1.0
+Summary: Speculo Studio CLI — backtest your trading strategies locally and sync results.
+Author: Speculo
+License: Proprietary
+Project-URL: Homepage, https://speculotrading.com
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Speculo CLI
+
+Run Speculo Studio backtests on your own machine — your hardware, your data, results
+synced to your Studio history.
+
+## Install
+
+```bash
+pip install speculo
+```
+
+## Authenticate
+
+Create a CLI token in Studio → Settings → CLI tokens, then:
+
+```bash
+speculo login --token spk_xxxxxxxxxxxx
+# self-hosted / staging:
+speculo login --token spk_xxx --api https://api.staging.speculotrading.com
+```
+
+Credentials are stored in `~/.speculo/config.json` (mode 600). You can also set
+`SPECULO_TOKEN` / `SPECULO_API` in the environment.
+
+## Backtest
+
+```bash
+# real historical data (fetched via the platform's cached proxy)
+speculo backtest strategy.py --symbol AAPL --timeframe 1d --capital 100000
+
+# your own OHLCV CSV
+speculo backtest strategy.py --csv mydata.csv
+
+# synthetic demo series
+speculo backtest strategy.py --bars 500
+```
+
+Add `--no-sync` to keep a run private (compute locally, don't upload).
+
+## Strategy contract
+
+A strategy defines `on_bar(ctx)` and optionally `initialize(ctx)` — identical to the
+web editor:
+
+```python
+def initialize(ctx):
+    ctx.state["fast"], ctx.state["slow"] = 5, 20
+
+def on_bar(ctx):
+    c = ctx.closes()
+    if len(c) < ctx.state["slow"]:
+        return
+    fast = sum(c[-ctx.state["fast"]:]) / ctx.state["fast"]
+    slow = sum(c[-ctx.state["slow"]:]) / ctx.state["slow"]
+    if fast > slow and ctx.position == 0:
+        ctx.broker.place_order(symbol=ctx.symbol, quantity=10, side="BUY", order_type="MARKET")
+    elif fast < slow and ctx.position > 0:
+        ctx.broker.place_order(symbol=ctx.symbol, quantity=10, side="SELL", order_type="MARKET")
+```
+
+The backtest engine itself is fetched from the platform at runtime, so the CLI always
+runs the exact same engine as the web app.

speculo-0.1.0/speculo.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+speculo/__init__.py
+speculo/cli.py
+speculo/client.py
+speculo/config.py
+speculo/engine_loader.py
+speculo.egg-info/PKG-INFO
+speculo.egg-info/SOURCES.txt
+speculo.egg-info/dependency_links.txt
+speculo.egg-info/entry_points.txt
+speculo.egg-info/top_level.txt

speculo-0.1.0/speculo.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

speculo-0.1.0/speculo.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+speculo = speculo.cli:main

speculo-0.1.0/speculo.egg-info/top_level.txt

@@ -0,0 +1 @@
+speculo