clawquant 0.1.0__py3-none-any.whl

clawquant/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

clawquant/clawquant_cli.py

@@ -0,0 +1,303 @@
+"""ClawQuant Trader - CLI entry point.
+
+Usage:
+    python -m clawquant.clawquant_cli --help
+"""
+
+from typing import Optional
+
+import typer
+
+from clawquant import __version__
+
+# ---------------------------------------------------------------------------
+# Main app
+# ---------------------------------------------------------------------------
+app = typer.Typer(
+    name="clawquant",
+    help="ClawQuant Trader - Quantitative Research Infrastructure",
+    add_completion=False,
+    no_args_is_help=True,
+)
+
+# ---------------------------------------------------------------------------
+# Global state (stored in shared module to survive python -m re-import)
+# ---------------------------------------------------------------------------
+from clawquant.core.utils.state import get_json_mode as _get_json_mode, set_json_mode
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"ClawQuant Trader v{__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Optional[bool] = typer.Option(
+        None, "--version", "-V", help="Show version and exit.",
+        callback=_version_callback, is_eager=True,
+    ),
+    json_output: bool = typer.Option(
+        False, "--json", help="Output results as JSON instead of Rich tables.",
+    ),
+) -> None:
+    """ClawQuant Trader - Quantitative Research Infrastructure."""
+    set_json_mode(json_output)
+
+
+# ---------------------------------------------------------------------------
+# Sub-app: data
+# ---------------------------------------------------------------------------
+data_app = typer.Typer(help="Data management commands", no_args_is_help=True)
+
+
+@data_app.command("pull")
+def data_pull(
+    symbols: str = typer.Argument(..., help="Comma-separated symbols, e.g. BTC/USDT,ETH/USDT"),
+    interval: str = typer.Option("1h", "--interval", "-i", help="Bar interval"),
+    days: int = typer.Option(10, "--days", "-d", help="Number of days to fetch"),
+    exchange: str = typer.Option("binance", "--exchange", "-e", help="Exchange name"),
+) -> None:
+    """Pull OHLCV data for one or more symbols."""
+    from clawquant.cli.data_cli import pull
+    pull(symbols=symbols, interval=interval, days=days, exchange=exchange, json_mode=_get_json_mode())
+
+
+@data_app.command("inspect")
+def data_inspect(
+    symbol: str = typer.Argument(..., help="Symbol to check, e.g. BTC/USDT"),
+    interval: str = typer.Option("1h", "--interval", "-i", help="Bar interval"),
+) -> None:
+    """Run data quality checks on a cached dataset."""
+    from clawquant.cli.data_cli import inspect
+    inspect(symbol=symbol, interval=interval, json_mode=_get_json_mode())
+
+
+@data_app.command("cache-status")
+def data_cache_status() -> None:
+    """Show all cached data files."""
+    from clawquant.cli.data_cli import cache_status
+    cache_status(json_mode=_get_json_mode())
+
+
+app.add_typer(data_app, name="data")
+
+# ---------------------------------------------------------------------------
+# Sub-app: strategy (delegated)
+# ---------------------------------------------------------------------------
+from clawquant.cli.strategy_cli import strategy_app  # noqa: E402
+
+app.add_typer(strategy_app, name="strategy")
+
+# ---------------------------------------------------------------------------
+# Sub-app: backtest
+# ---------------------------------------------------------------------------
+backtest_app = typer.Typer(help="Backtesting commands", no_args_is_help=True)
+
+
+@backtest_app.command("run")
+def backtest_run(
+    strategy: str = typer.Argument(..., help="Strategy name"),
+    symbol: str = typer.Option("BTC/USDT", "--symbol", "-s", help="Trading pair"),
+    interval: str = typer.Option("1h", "--interval", "-i", help="Bar interval"),
+    days: int = typer.Option(30, "--days", "-d", help="Backtest window in days"),
+    capital: float = typer.Option(10000.0, "--capital", "-c", help="Initial capital in USDT"),
+    fee_bps: int = typer.Option(10, "--fee-bps", help="Fee in basis points"),
+    slippage_bps: int = typer.Option(5, "--slippage-bps", help="Slippage in basis points"),
+    params: Optional[str] = typer.Option(None, "--params", "-p", help='Strategy params JSON, e.g. \'{"fast_period": 10}\''),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Check readiness without running"),
+) -> None:
+    """Run a single backtest."""
+    from clawquant.cli.backtest_cli import run
+    run(strategy=strategy, symbol=symbol, interval=interval, days=days,
+        capital=capital, fee_bps=fee_bps, slippage_bps=slippage_bps,
+        params=params, dry_run=dry_run, json_mode=_get_json_mode())
+
+
+@backtest_app.command("batch")
+def backtest_batch(
+    strategies: str = typer.Argument(..., help="Comma-separated strategy names"),
+    symbols: str = typer.Option("BTC/USDT", "--symbols", "-s", help="Comma-separated symbols"),
+    interval: str = typer.Option("1h", "--interval", "-i", help="Bar interval"),
+    days: int = typer.Option(30, "--days", "-d", help="Backtest window in days"),
+    capital: float = typer.Option(10000.0, "--capital", "-c", help="Initial capital"),
+) -> None:
+    """Run batch backtests across strategies and symbols."""
+    from clawquant.cli.backtest_cli import batch
+    batch(strategies=strategies, symbols=symbols, interval=interval, days=days,
+          capital=capital, json_mode=_get_json_mode())
+
+
+@backtest_app.command("sweep")
+def backtest_sweep(
+    strategy: str = typer.Argument(..., help="Strategy name"),
+    symbol: str = typer.Option("BTC/USDT", "--symbol", "-s", help="Trading pair"),
+    interval: str = typer.Option("1h", "--interval", "-i", help="Bar interval"),
+    days: int = typer.Option(30, "--days", "-d", help="Backtest window"),
+    param_grid: Optional[str] = typer.Option(None, "--grid", "-g", help='Param grid JSON, e.g. \'{"fast_period": [5,10,20]}\''),
+    mode: str = typer.Option("grid", "--mode", "-m", help="Sweep mode: grid or random"),
+    n_random: int = typer.Option(20, "--n-random", help="Number of random samples"),
+) -> None:
+    """Run parameter sweep over a strategy."""
+    from clawquant.cli.backtest_cli import sweep
+    sweep(strategy=strategy, symbol=symbol, interval=interval, days=days,
+          param_grid=param_grid, mode=mode, n_random=n_random, json_mode=_get_json_mode())
+
+
+@backtest_app.command("walkforward")
+def backtest_walkforward(
+    strategy: str = typer.Argument(..., help="Strategy name"),
+    symbol: str = typer.Option("BTC/USDT", "--symbol", "-s", help="Trading pair"),
+    interval: str = typer.Option("1h", "--interval", "-i", help="Bar interval"),
+    days: int = typer.Option(90, "--days", "-d", help="Total data window"),
+    train_pct: float = typer.Option(0.7, "--train-pct", help="Training fraction"),
+    n_splits: int = typer.Option(3, "--splits", "-n", help="Number of rolling splits"),
+    param_grid: Optional[str] = typer.Option(None, "--grid", "-g", help="Param grid JSON"),
+) -> None:
+    """Run walk-forward validation."""
+    from clawquant.cli.backtest_cli import walkforward
+    walkforward(strategy=strategy, symbol=symbol, interval=interval, days=days,
+                train_pct=train_pct, n_splits=n_splits, param_grid=param_grid,
+                json_mode=_get_json_mode())
+
+
+app.add_typer(backtest_app, name="backtest")
+
+# ---------------------------------------------------------------------------
+# Sub-app: radar
+# ---------------------------------------------------------------------------
+radar_app = typer.Typer(help="Opportunity scanning commands", no_args_is_help=True)
+
+
+@radar_app.command("scan")
+def radar_scan(
+    symbols: str = typer.Option("BTC/USDT,ETH/USDT", "--symbols", "-s", help="Comma-separated symbols"),
+    strategies: str = typer.Option("ma_crossover,dca", "--strategies", help="Comma-separated strategies"),
+    interval: str = typer.Option("1h", "--interval", "-i", help="Bar interval"),
+    days: int = typer.Option(10, "--days", "-d", help="Data window"),
+    exchange: str = typer.Option("binance", "--exchange", "-e", help="Exchange"),
+    top_n: int = typer.Option(10, "--top", "-n", help="Top N results"),
+) -> None:
+    """Scan for trading opportunities."""
+    from clawquant.cli.radar_cli import scan
+    scan(symbols=symbols, strategies=strategies, interval=interval, days=days,
+         exchange=exchange, top_n=top_n, json_mode=_get_json_mode())
+
+
+@radar_app.command("explain")
+def radar_explain(
+    symbol: str = typer.Argument(..., help="Symbol to explain"),
+    strategy: str = typer.Argument(..., help="Strategy name"),
+    interval: str = typer.Option("1h", "--interval", "-i", help="Bar interval"),
+    days: int = typer.Option(10, "--days", "-d", help="Data window"),
+) -> None:
+    """Explain a specific opportunity."""
+    from clawquant.cli.radar_cli import explain
+    explain(symbol=symbol, strategy=strategy, interval=interval, days=days,
+            json_mode=_get_json_mode())
+
+
+app.add_typer(radar_app, name="radar")
+
+# ---------------------------------------------------------------------------
+# Sub-app: report
+# ---------------------------------------------------------------------------
+report_app = typer.Typer(help="Report generation commands", no_args_is_help=True)
+
+
+@report_app.command("generate")
+def report_generate(
+    run_id: str = typer.Argument(..., help="Run ID to generate report for"),
+    formats: Optional[str] = typer.Option(None, "--formats", "-f", help="Comma-separated: json,md,charts"),
+) -> None:
+    """Generate reports for a backtest run."""
+    from clawquant.cli.report_cli import generate
+    generate(run_id=run_id, formats=formats, json_mode=_get_json_mode())
+
+
+@report_app.command("batch")
+def report_batch(
+    run_ids: str = typer.Argument(..., help="Comma-separated run IDs"),
+) -> None:
+    """Generate and compare reports for multiple runs."""
+    from clawquant.cli.report_cli import batch_generate
+    batch_generate(run_ids=run_ids, json_mode=_get_json_mode())
+
+
+app.add_typer(report_app, name="report")
+
+# ---------------------------------------------------------------------------
+# Sub-app: deploy
+# ---------------------------------------------------------------------------
+deploy_app = typer.Typer(help="Deployment commands", no_args_is_help=True)
+
+
+@deploy_app.command("paper")
+def deploy_paper(
+    strategy: str = typer.Argument(..., help="Strategy name"),
+    symbol: str = typer.Option("BTC/USDT", "--symbol", "-s", help="Trading pair"),
+    interval: str = typer.Option("1h", "--interval", "-i", help="Bar interval"),
+    capital: float = typer.Option(10000.0, "--capital", "-c", help="Initial capital"),
+    params: Optional[str] = typer.Option(None, "--params", "-p", help="Strategy params JSON"),
+    exchange: str = typer.Option("binance", "--exchange", "-e", help="Exchange"),
+) -> None:
+    """Start paper trading."""
+    from clawquant.cli.deploy_cli import paper
+    paper(strategy=strategy, symbol=symbol, interval=interval, capital=capital,
+          params=params, exchange=exchange, json_mode=_get_json_mode())
+
+
+@deploy_app.command("live")
+def deploy_live(
+    strategy: str = typer.Argument(..., help="Strategy name"),
+    symbol: str = typer.Option("BTC/USDT", "--symbol", "-s", help="Trading pair"),
+    interval: str = typer.Option("1h", "--interval", "-i", help="Bar interval"),
+    capital: float = typer.Option(10000.0, "--capital", "-c", help="Initial capital"),
+    params: Optional[str] = typer.Option(None, "--params", "-p", help="Strategy params JSON"),
+    exchange: str = typer.Option("binance", "--exchange", "-e", help="Exchange"),
+    i_know_what_im_doing: bool = typer.Option(False, "--i-know-what-im-doing", help="Confirm live trading risks"),
+) -> None:
+    """Start live trading (requires --i-know-what-im-doing)."""
+    from clawquant.cli.deploy_cli import live
+    live(strategy=strategy, symbol=symbol, interval=interval, capital=capital,
+         params=params, exchange=exchange, confirm=i_know_what_im_doing,
+         json_mode=_get_json_mode())
+
+
+@deploy_app.command("status")
+def deploy_status() -> None:
+    """Show deployment statuses."""
+    from clawquant.cli.deploy_cli import status
+    status(json_mode=_get_json_mode())
+
+
+@deploy_app.command("stop")
+def deploy_stop(
+    strategy: str = typer.Argument(..., help="Strategy name"),
+    symbol: str = typer.Option("BTC/USDT", "--symbol", "-s", help="Trading pair"),
+    mode: str = typer.Option("paper", "--mode", "-m", help="paper or live"),
+) -> None:
+    """Stop a deployment."""
+    from clawquant.cli.deploy_cli import stop
+    stop(strategy=strategy, symbol=symbol, mode=mode, json_mode=_get_json_mode())
+
+
+@deploy_app.command("flatten")
+def deploy_flatten(
+    strategy: str = typer.Argument(..., help="Strategy name"),
+    symbol: str = typer.Option("BTC/USDT", "--symbol", "-s", help="Trading pair"),
+    mode: str = typer.Option("paper", "--mode", "-m", help="paper or live"),
+) -> None:
+    """Flatten positions and stop a deployment."""
+    from clawquant.cli.deploy_cli import flatten
+    flatten(strategy=strategy, symbol=symbol, mode=mode, json_mode=_get_json_mode())
+
+
+app.add_typer(deploy_app, name="deploy")
+
+# ---------------------------------------------------------------------------
+# Module entry-point
+# ---------------------------------------------------------------------------
+if __name__ == "__main__":
+    app()

clawquant/cli/backtest_cli.py

@@ -0,0 +1,233 @@
+"""Backtest CLI command implementations."""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+from clawquant.core.utils.output import print_error, print_result, print_table
+
+
+def run(
+    strategy: str,
+    symbol: str = "BTC/USDT",
+    interval: str = "1h",
+    days: int = 30,
+    capital: float = 10000.0,
+    fee_bps: int = 10,
+    slippage_bps: int = 5,
+    params: Optional[str] = None,
+    dry_run: bool = False,
+    json_mode: bool = False,
+) -> None:
+    """Run a single backtest."""
+    from clawquant.core.backtest.config import BacktestConfig
+    from clawquant.core.backtest.engine import BacktestEngine
+    from clawquant.core.data.fetcher import fetch_data
+    from clawquant.core.data.models import DataPullRequest
+    from clawquant.core.runtime.loader import load_strategy
+
+    # Parse strategy params
+    strategy_params = {}
+    if params:
+        try:
+            strategy_params = json.loads(params)
+        except json.JSONDecodeError as e:
+            print_error("ConfigError", f"Invalid params JSON: {e}", "Use valid JSON, e.g. '{\"fast_period\": 10}'")
+            return
+
+    # Load strategy
+    try:
+        strat = load_strategy(strategy)
+    except Exception as e:
+        print_error("StrategyError", f"Failed to load strategy '{strategy}': {e}", "Check strategy name with 'clawquant strategy list'")
+        return
+
+    # Build config
+    config = BacktestConfig(
+        initial_capital=capital,
+        fee_bps=fee_bps,
+        slippage_bps=slippage_bps,
+        strategy_name=strategy,
+        strategy_params=strategy_params,
+        symbol=symbol,
+        interval=interval,
+        days=days,
+    )
+
+    # Fetch data
+    try:
+        request = DataPullRequest(symbols=[symbol], interval=interval, days=days)
+        dfs = fetch_data(request)
+        df = dfs.get(symbol)
+        if df is None or df.empty:
+            print_error("DataError", f"No data for {symbol}", "Try 'clawquant data pull' first")
+            return
+    except Exception as e:
+        print_error("DataError", f"Failed to fetch data: {e}", "Check network or try 'clawquant data pull' first")
+        return
+
+    # Dry run check
+    if dry_run:
+        from clawquant.core.data.inspector import inspect_data
+        report = inspect_data(df, symbol, interval)
+        meta = strat.metadata()
+        result_data = {
+            "ready": report.passed,
+            "strategy": meta.name,
+            "data_bars": report.total_bars,
+            "data_quality": "PASS" if report.passed else "FAIL",
+            "issues": report.issues,
+        }
+        print_result(result_data, json_mode=json_mode)
+        return
+
+    # Run backtest
+    engine = BacktestEngine(config, strat, df)
+    result = engine.run()
+
+    if not result.success:
+        print_error(result.error_type or "Error", result.message or "Unknown error")
+        return
+
+    # Display results
+    summary = {
+        "run_id": result.run_id,
+        "strategy": strategy,
+        "symbol": symbol,
+        "total_return": f"{result.total_return_pct:.2f}%",
+        "max_drawdown": f"{result.max_drawdown_pct:.2f}%",
+        "sharpe_ratio": f"{result.sharpe_ratio:.4f}",
+        "win_rate": f"{result.win_rate:.1f}%",
+        "total_trades": result.total_trades,
+        "profit_factor": f"{result.profit_factor:.4f}",
+        "avg_trade_pnl": f"${result.avg_trade_pnl:.2f}",
+        "warnings": result.warnings,
+    }
+
+    if json_mode:
+        print_result(result.model_dump(mode="json"), json_mode=True)
+    else:
+        print_table(
+            headers=["Metric", "Value"],
+            rows=[[k, str(v)] for k, v in summary.items() if k != "warnings"],
+            title=f"Backtest Result: {result.run_id}",
+            json_mode=False,
+        )
+        if result.warnings:
+            from rich.console import Console
+            console = Console()
+            for w in result.warnings:
+                console.print(f"  [yellow]⚠ {w}[/yellow]")
+
+
+def batch(
+    strategies: str,
+    symbols: str,
+    interval: str = "1h",
+    days: int = 30,
+    capital: float = 10000.0,
+    json_mode: bool = False,
+) -> None:
+    """Run batch backtest (delegates to batch module)."""
+    from clawquant.core.backtest.batch import run_batch
+
+    strategy_list = [s.strip() for s in strategies.split(",")]
+    symbol_list = [s.strip() for s in symbols.split(",")]
+
+    results = run_batch(strategy_list, symbol_list, interval, days, capital)
+
+    if json_mode:
+        print_result([r.model_dump(mode="json") for r in results], json_mode=True)
+    else:
+        rows = []
+        for r in results:
+            rows.append([
+                r.run_id[:40],
+                r.run_meta.strategy["name"] if r.run_meta else "?",
+                r.run_meta.data["symbol"] if r.run_meta else "?",
+                f"{r.total_return_pct:.2f}%",
+                f"{r.max_drawdown_pct:.2f}%",
+                str(r.total_trades),
+                f"{r.win_rate:.1f}%",
+            ])
+        print_table(
+            headers=["Run ID", "Strategy", "Symbol", "Return", "MaxDD", "Trades", "WinRate"],
+            rows=rows,
+            title="Batch Backtest Results",
+            json_mode=False,
+        )
+
+
+def sweep(
+    strategy: str,
+    symbol: str = "BTC/USDT",
+    interval: str = "1h",
+    days: int = 30,
+    param_grid: Optional[str] = None,
+    mode: str = "grid",
+    n_random: int = 20,
+    json_mode: bool = False,
+) -> None:
+    """Run parameter sweep (delegates to sweep module)."""
+    from clawquant.core.backtest.sweep import run_sweep
+
+    grid = {}
+    if param_grid:
+        try:
+            grid = json.loads(param_grid)
+        except json.JSONDecodeError as e:
+            print_error("ConfigError", f"Invalid param_grid JSON: {e}")
+            return
+
+    results = run_sweep(strategy, symbol, interval, days, grid, mode, n_random)
+
+    if json_mode:
+        print_result([r.model_dump(mode="json") for r in results], json_mode=True)
+    else:
+        rows = []
+        for r in results:
+            params_str = json.dumps(r.run_meta.strategy["params"]) if r.run_meta else "?"
+            rows.append([
+                params_str[:50],
+                f"{r.total_return_pct:.2f}%",
+                f"{r.max_drawdown_pct:.2f}%",
+                str(r.total_trades),
+                f"{r.win_rate:.1f}%",
+                f"{r.stability_score:.1f}",
+            ])
+        print_table(
+            headers=["Params", "Return", "MaxDD", "Trades", "WinRate", "Score"],
+            rows=rows,
+            title=f"Parameter Sweep: {strategy} on {symbol}",
+            json_mode=False,
+        )
+
+
+def walkforward(
+    strategy: str,
+    symbol: str = "BTC/USDT",
+    interval: str = "1h",
+    days: int = 90,
+    train_pct: float = 0.7,
+    n_splits: int = 3,
+    param_grid: Optional[str] = None,
+    json_mode: bool = False,
+) -> None:
+    """Run walk-forward validation (delegates to walkforward module)."""
+    from clawquant.core.backtest.walkforward import run_walkforward
+
+    grid = {}
+    if param_grid:
+        try:
+            grid = json.loads(param_grid)
+        except json.JSONDecodeError as e:
+            print_error("ConfigError", f"Invalid param_grid JSON: {e}")
+            return
+
+    results = run_walkforward(strategy, symbol, interval, days, train_pct, n_splits, grid)
+
+    if json_mode:
+        print_result(results, json_mode=True)
+    else:
+        print_result(results, json_mode=False)

clawquant/cli/data_cli.py

@@ -0,0 +1,101 @@
+"""CLI commands for the ``data`` sub-app.
+
+These functions are wired into the main Typer application in
+:pymod:`clawquant.clawquant_cli`.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from clawquant.core.utils.output import print_error, print_result, print_table
+
+
+def pull(
+    symbols: str,
+    interval: str,
+    days: int,
+    exchange: str,
+    json_mode: bool,
+) -> None:
+    """Pull OHLCV data for one or more symbols."""
+    from clawquant.core.data.fetcher import fetch_data
+    from clawquant.core.data.models import DataPullRequest
+
+    symbol_list = [s.strip() for s in symbols.split(",")]
+    typer.echo(
+        f"[data pull] Fetching {symbol_list} | interval={interval} "
+        f"| days={days} | exchange={exchange}"
+    )
+
+    request = DataPullRequest(
+        symbols=symbol_list,
+        interval=interval,
+        days=days,
+        exchange=exchange,
+    )
+
+    try:
+        result = fetch_data(request)
+    except Exception as exc:
+        print_error("FetchError", str(exc), suggestion="Check your network or API keys.")
+        raise typer.Exit(code=1)
+
+    rows = []
+    for sym, df in result.items():
+        bar_count = len(df)
+        start = str(df["timestamp"].min()) if bar_count else "-"
+        end = str(df["timestamp"].max()) if bar_count else "-"
+        rows.append((sym, interval, bar_count, start, end))
+
+    print_table(
+        headers=["Symbol", "Interval", "Bars", "Start", "End"],
+        rows=rows,
+        title="Data Pull Results",
+        json_mode=json_mode,
+    )
+
+
+def inspect(
+    symbol: str,
+    interval: str,
+    json_mode: bool,
+) -> None:
+    """Run data quality checks on cached data for a single symbol."""
+    from clawquant.core.data.cache import read_cache
+    from clawquant.core.data.inspector import inspect_data
+
+    typer.echo(f"[data inspect] Checking {symbol} @ {interval} ...")
+
+    df = read_cache(symbol, interval)
+    if df is None or df.empty:
+        print_error(
+            "DataNotFound",
+            f"No cached data for {symbol}/{interval}.",
+            suggestion="Run 'clawquant data pull' first.",
+        )
+        raise typer.Exit(code=1)
+
+    report = inspect_data(df, symbol, interval)
+    print_result(report, json_mode=json_mode)
+
+
+def cache_status(json_mode: bool) -> None:
+    """Show information about all cached data files."""
+    from clawquant.core.data.cache import cache_status as _cache_status
+
+    entries = _cache_status()
+    if not entries:
+        typer.echo("[data cache-status] Cache is empty.")
+        return
+
+    rows = [
+        (e["file"], e["rows"], e["start"], e["end"], e["size_kb"])
+        for e in entries
+    ]
+    print_table(
+        headers=["File", "Rows", "Start", "End", "Size (KB)"],
+        rows=rows,
+        title="Cached Datasets",
+        json_mode=json_mode,
+    )