quantpipe 0.1.0__py3-none-any.whl

quantpipe/__init__.py

@@ -0,0 +1,3 @@
+"""QuantPipe - Quantitative trading toolkit for LLM AI."""
+
+__version__ = "0.1.0"

quantpipe/__main__.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+"""Entry point for python -m quantpipe."""
+
+from .cli import cli
+
+if __name__ == '__main__':
+    cli()

quantpipe/cli.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""CLI entry point for QuantPipe."""
+
+import click
+
+from .cli_exit import EXIT_CODE_HELP
+from .commands.backtest import backtest_command
+from .commands.signal import signal_command
+from .commands.scan import scan_command
+from .commands.paper import paper_command
+
+
+@click.group(epilog=EXIT_CODE_HELP)
+@click.version_option(version='0.1.0', prog_name='quantpipe')
+def cli():
+    """QuantPipe - Quantitative trading toolkit for LLM AI.
+    
+    Designed to work seamlessly with seamflux CLI for market data via Unix pipes.
+    
+    Auto-detects data formats: Binance, Polymarket, Uniswap, generic OHLCV.
+    
+    Examples:
+        # Generate signal from Binance
+        seamflux invoke binance fetchOhlcv -p symbol=BTC/USDT -p timeframe=1h | quantpipe signal --strategy ma_cross --stdin
+        
+        # Generate signal from Polymarket
+        seamflux invoke polymarket getPriceHistory -p market=<token_id> -p interval=1h | quantpipe signal --strategy rsi --stdin
+        
+        # Run backtest
+        quantpipe backtest --data btc_history.json --strategy rsi --json
+        
+        # Scan multiple symbols
+        seamflux invoke binance fetchTickers | quantpipe scan --strategy ma_cross --filter-signal BUY
+        
+        # Paper trading with Polymarket
+        quantpipe paper --exec "seamflux invoke polymarket getMarket -p slug=<market_slug>" --strategy ma_cross
+    """
+    pass
+
+
+# Register commands
+cli.add_command(backtest_command)
+cli.add_command(signal_command)
+cli.add_command(scan_command)
+cli.add_command(paper_command)
+
+
+if __name__ == '__main__':
+    cli()

quantpipe/cli_exit.py

@@ -0,0 +1,15 @@
+"""Process exit codes aligned with repo rule.md (§3.3)."""
+
+# 0 success; 1 generic (args, IO); 2 input/schema mismatch; 3 upstream unavailable
+EXIT_OK = 0
+EXIT_GENERAL = 1
+EXIT_SCHEMA = 2
+EXIT_UPSTREAM = 3
+
+EXIT_CODE_HELP = """
+Exit codes:
+  0  Success
+  1  General failure (invalid arguments, I/O error)
+  2  Input format / schema mismatch
+  3  Upstream dependency unavailable (e.g. subprocess failed, missing external tool)
+"""

quantpipe/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI commands for QuantPipe."""

quantpipe/commands/backtest.py

@@ -0,0 +1,285 @@
+"""Backtest command for QuantPipe."""
+
+import json
+import logging
+import os
+import sys
+from typing import Any, Dict, Optional
+
+import click
+import pandas as pd
+
+from ..cli_exit import EXIT_GENERAL, EXIT_SCHEMA
+from ..core.backtest import BacktestEngine
+from ..core.data import prepare_data
+from ..core.pipeline_json import emit_json_line, failure_envelope, success_envelope, utc_now_iso
+from ..strategies import STRATEGIES
+from .io_util import QuantpipeCliError, configure_verbose, load_cli_input_dict
+
+log = logging.getLogger(__name__)
+
+
+def _parse_strategy_params(params: tuple) -> dict:
+    strategy_params = {}
+    for param in params:
+        if "=" not in param:
+            raise QuantpipeCliError(EXIT_GENERAL, f"Invalid param format '{param}'. Use key=value", "INVALID_PARAM")
+        key, value = param.split("=", 1)
+        try:
+            if "." in value:
+                value = float(value)
+            else:
+                value = int(value)
+        except ValueError:
+            pass
+        strategy_params[key] = value
+    return strategy_params
+
+
+def _resolve_run_output_dir(run_dir: Optional[str], run_id: Optional[str]) -> Optional[str]:
+    if run_dir:
+        return os.path.abspath(run_dir)
+    if run_id:
+        return os.path.abspath(os.path.join(os.getcwd(), "runs", run_id))
+    return None
+
+
+def _artifact_rel_paths(files: Dict[str, str]) -> Dict[str, str]:
+    cwd = os.getcwd()
+    out: Dict[str, str] = {}
+    for k, p in files.items():
+        try:
+            out[k] = os.path.relpath(p, cwd)
+        except ValueError:
+            out[k] = p
+    return out
+
+
+def _write_equity_csv(engine: BacktestEngine, path: str) -> None:
+    idx = engine.df.index
+    eq = engine.equity_curve
+    if len(idx) == 0:
+        pd.DataFrame(columns=["timestamp", "equity"]).to_csv(path, index=False)
+        return
+    if len(eq) != len(idx):
+        n = min(len(idx), len(eq))
+        idx = idx[:n]
+        eq = eq[:n]
+    df = pd.DataFrame({"timestamp": idx, "equity": eq})
+    df.to_csv(path, index=False)
+
+
+def _write_trades_csv(engine: BacktestEngine, path: str) -> None:
+    rows = []
+    for t in engine.trades:
+        rows.append(
+            {
+                "timestamp": t.exit_time.isoformat(),
+                "entry_time": t.entry_time.isoformat(),
+                "side": t.side,
+                "price": t.exit_price,
+                "entry_price": t.entry_price,
+                "exit_price": t.exit_price,
+                "size": t.size,
+                "pnl": t.pnl,
+                "pnl_pct": t.pnl_pct,
+            }
+        )
+    pd.DataFrame(rows).to_csv(path, index=False)
+
+
+def _package_version() -> str:
+    try:
+        import importlib.metadata as im
+
+        return im.version("quantpipe")
+    except Exception:
+        return "0.1.0"
+
+
+@click.command(name="backtest")
+@click.option("--data", "-d", "data_path", type=str, default=None, help="Data file path (JSON)")
+@click.option("--input", "-i", "input_path", type=str, default=None, help="Alias for --data")
+@click.option("--stdin", "use_stdin", is_flag=True, help="Read data from stdin")
+@click.option("--strategy", "-s", required=True, help="Strategy name")
+@click.option("--param", "params", multiple=True, help="Strategy parameters (key=value)")
+@click.option("--json", "output_json", is_flag=True, help="Machine-readable JSON envelope on stdout")
+@click.option("--pretty", is_flag=True, help="Pretty-print JSON (not for pipes)")
+@click.option("--verbose", "-v", is_flag=True, help="Debug logs on stderr")
+@click.option("--dry-run", is_flag=True, help="Validate input and strategy; do not run backtest or write files")
+@click.option(
+    "--run-dir",
+    type=click.Path(file_okay=False, dir_okay=True, writable=True, path_type=str),
+    default=None,
+    help="Write trades.csv, equity.csv, summary.json, manifest.json under this directory",
+)
+@click.option("--run-id", type=str, default=None, help="Write artifacts to runs/<run-id>/ (ignored if --run-dir set)")
+def backtest_command(
+    data_path: Optional[str],
+    input_path: Optional[str],
+    use_stdin: bool,
+    strategy: str,
+    params: tuple,
+    output_json: bool,
+    pretty: bool,
+    verbose: bool,
+    dry_run: bool,
+    run_dir: Optional[str],
+    run_id: Optional[str],
+):
+    """Run backtest on historical data."""
+    configure_verbose(verbose)
+    command = "backtest"
+    path = input_path or data_path
+
+    try:
+        strategy_params = _parse_strategy_params(params)
+    except QuantpipeCliError as e:
+        click.echo(e.message, err=True)
+        if output_json or pretty:
+            emit_json_line(failure_envelope(command, e.error_code, e.message), pretty=pretty)
+        sys.exit(e.exit_code)
+
+    try:
+        input_data = load_cli_input_dict(use_stdin=use_stdin, path=path)
+    except QuantpipeCliError as e:
+        click.echo(e.message, err=True)
+        if output_json or pretty:
+            emit_json_line(failure_envelope(command, e.error_code, e.message), pretty=pretty)
+        sys.exit(e.exit_code)
+
+    try:
+        df, metadata = prepare_data(input_data)
+    except Exception as e:
+        click.echo(f"Error preparing data: {e}", err=True)
+        if output_json or pretty:
+            emit_json_line(failure_envelope(command, "INVALID_INPUT", str(e)), pretty=pretty)
+        sys.exit(EXIT_SCHEMA)
+
+    if strategy not in STRATEGIES:
+        msg = f"Unknown strategy '{strategy}'. Available: {', '.join(STRATEGIES.keys())}"
+        click.echo(f"Error: {msg}", err=True)
+        if output_json or pretty:
+            emit_json_line(failure_envelope(command, "INVALID_INPUT", msg), pretty=pretty)
+        sys.exit(EXIT_GENERAL)
+
+    StrategyClass = STRATEGIES[strategy]
+    strat = StrategyClass(params=strategy_params)
+
+    started = utc_now_iso()
+    out_dir = _resolve_run_output_dir(run_dir, run_id)
+    effective_run_id = run_id if run_id else None
+
+    data_body: Dict[str, Any] = {
+        "source": {
+            "symbol": metadata.get("symbol"),
+            "market_type": metadata.get("market_type", "unknown"),
+            "type": metadata.get("type"),
+            "bars": len(df),
+            "period": {
+                "start": metadata.get("start"),
+                "end": metadata.get("end"),
+            },
+        },
+        "strategy": {"name": strategy, "params": strat.params},
+    }
+
+    if dry_run:
+        data_body["dryRun"] = True
+        if output_json or pretty:
+            emit_json_line(
+                success_envelope(
+                    command,
+                    data_body,
+                    run_id=effective_run_id,
+                    meta={"startedAt": started, "finishedAt": utc_now_iso()},
+                ),
+                pretty=pretty,
+            )
+        else:
+            click.echo("\nDry run OK")
+            click.echo(f"Strategy: {strategy} {strat.params}")
+            click.echo(f"Bars: {len(df)}")
+        return
+
+    engine = BacktestEngine(strat, df)
+    metrics = engine.run()
+    data_body["performance"] = metrics
+
+    artifacts_abs: Dict[str, str] = {}
+    if out_dir:
+        os.makedirs(out_dir, exist_ok=True)
+        trades_p = os.path.join(out_dir, "trades.csv")
+        equity_p = os.path.join(out_dir, "equity.csv")
+        summary_p = os.path.join(out_dir, "summary.json")
+        manifest_p = os.path.join(out_dir, "manifest.json")
+
+        _write_trades_csv(engine, trades_p)
+        _write_equity_csv(engine, equity_p)
+        artifacts_abs["trades"] = trades_p
+        artifacts_abs["equity"] = equity_p
+
+        summary_payload = dict(data_body)
+        with open(summary_p, "w", encoding="utf-8") as f:
+            json.dump(summary_payload, f, indent=2, default=str)
+        artifacts_abs["summary"] = summary_p
+
+        manifest = {
+            "schemaVersion": 1,
+            "tool": "quantpipe",
+            "command": command,
+            "quantpipeVersion": _package_version(),
+            "strategy": strategy,
+            "strategyParams": strat.params,
+            "input": {"stdin": use_stdin, "path": path},
+            "runId": effective_run_id,
+        }
+        with open(manifest_p, "w", encoding="utf-8") as f:
+            json.dump(manifest, f, indent=2, default=str)
+        artifacts_abs["manifest"] = manifest_p
+        log.debug("Wrote artifacts under %s", out_dir)
+
+    finished = utc_now_iso()
+    artifacts_rel = _artifact_rel_paths(artifacts_abs) if artifacts_abs else None
+
+    if output_json or pretty:
+        emit_json_line(
+            success_envelope(
+                command,
+                data_body,
+                run_id=effective_run_id,
+                artifacts=artifacts_rel,
+                meta={"startedAt": started, "finishedAt": finished},
+            ),
+            pretty=pretty,
+        )
+    else:
+        click.echo(f"\nBacktest Results")
+        click.echo(f"================")
+        click.echo(f"Strategy: {strategy} {strat.params}")
+        click.echo(f"Data Format: {metadata.get('format', 'unknown')}")
+        click.echo(f"Market Type: {metadata.get('market_type', 'unknown')}")
+        click.echo(f"Symbol: {metadata.get('symbol', 'N/A')}")
+        click.echo(f"Period: {metadata.get('start')} to {metadata.get('end')}")
+        click.echo(f"Bars: {len(df)}")
+        if metadata.get("synthesized"):
+            click.echo(
+                f"Synthesized: {metadata.get('original_points')} price points -> OHLCV ({metadata.get('interval')})"
+            )
+        click.echo(f"")
+        click.echo(f"Performance:")
+        click.echo(f"  Total Trades: {metrics['total_trades']}")
+        click.echo(f"  Win Rate: {metrics['win_rate']:.2%}")
+        click.echo(f"  Total Return: {metrics['total_return']:.2%}")
+        click.echo(f"  Max Drawdown: {metrics['max_drawdown']:.2%}")
+        click.echo(f"  Sharpe Ratio: {metrics['sharpe_ratio']:.2f}")
+        pf = metrics.get("profit_factor")
+        if pf is not None:
+            click.echo(f"  Profit Factor: {pf:.2f}")
+        else:
+            click.echo(f"  Profit Factor: N/A (no losing trades)")
+        if artifacts_abs:
+            click.echo("")
+            click.echo("Artifacts:")
+            for k, v in _artifact_rel_paths(artifacts_abs).items():
+                click.echo(f"  {k}: {v}")

quantpipe/commands/io_util.py

@@ -0,0 +1,60 @@
+"""Shared CLI input loading and logging setup."""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from typing import Any, Dict, Optional
+
+from ..cli_exit import EXIT_GENERAL, EXIT_SCHEMA
+from ..core.pipeline_json import unwrap_upstream_json
+
+
+class QuantpipeCliError(Exception):
+    """Raised for predictable CLI failures (carry exit code for rule.md)."""
+
+    def __init__(self, exit_code: int, message: str, error_code: str = "ERROR") -> None:
+        self.exit_code = exit_code
+        self.message = message
+        self.error_code = error_code
+        super().__init__(message)
+
+
+def configure_verbose(verbose: bool) -> None:
+    """Route debug logs to stderr; avoid polluting stdout JSON."""
+    if verbose:
+        logging.basicConfig(
+            level=logging.DEBUG,
+            format="%(levelname)s %(message)s",
+            stream=sys.stderr,
+            force=True,
+        )
+    else:
+        logging.basicConfig(level=logging.WARNING, stream=sys.stderr, force=True)
+
+
+def load_cli_input_dict(*, use_stdin: bool, path: Optional[str]) -> Dict[str, Any]:
+    """
+    Load JSON object from stdin or file; unwrap seamflux ``{"result": {...}}`` once.
+    """
+    try:
+        if use_stdin or path is None:
+            raw: Any = json.load(sys.stdin)
+        else:
+            with open(path, "r", encoding="utf-8") as f:
+                raw = json.load(f)
+    except FileNotFoundError as e:
+        raise QuantpipeCliError(EXIT_GENERAL, str(e), "IO_ERROR") from e
+    except json.JSONDecodeError as e:
+        raise QuantpipeCliError(EXIT_SCHEMA, f"Invalid JSON: {e}", "INVALID_JSON") from e
+    except OSError as e:
+        raise QuantpipeCliError(EXIT_GENERAL, f"I/O error: {e}", "IO_ERROR") from e
+
+    if not isinstance(raw, dict):
+        raise QuantpipeCliError(EXIT_SCHEMA, "Top-level JSON must be an object", "INVALID_INPUT")
+
+    unwrapped = unwrap_upstream_json(raw)
+    if not isinstance(unwrapped, dict):
+        raise QuantpipeCliError(EXIT_SCHEMA, "Unwrapped payload must be an object", "INVALID_INPUT")
+    return unwrapped