chartpipe 0.1.0__py3-none-any.whl

chartpipe/__init__.py

@@ -0,0 +1,6 @@
+"""ChartPipe - Chart visualization toolkit for quantitative trading analysis.
+
+Designed to work seamlessly with seamflux CLI and quantpipe.
+"""
+
+__version__ = '0.1.0'

chartpipe/__main__.py

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

chartpipe/cli.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""CLI entry point for ChartPipe."""
+
+import logging
+import sys
+
+import click
+
+from .cli_exit import EXIT_CODE_HELP
+from .commands.ohlcv import ohlcv_command
+from .commands.backtest import backtest_chart_command
+from .commands.indicators import indicators_command
+from .commands.stats import stats_command
+
+
+def _configure_verbose(verbose: bool) -> None:
+    if verbose:
+        logging.basicConfig(
+            level=logging.DEBUG,
+            format="%(levelname)s %(name)s: %(message)s",
+            stream=sys.stderr,
+        )
+    else:
+        logging.basicConfig(level=logging.WARNING, handlers=[logging.NullHandler()])
+
+
+@click.group(epilog=EXIT_CODE_HELP)
+@click.version_option(version="0.1.0", prog_name="chartpipe")
+@click.option(
+    "--json",
+    "json_output",
+    is_flag=True,
+    default=False,
+    help="Output results as JSON for pipeline integration",
+)
+@click.option(
+    "--output-dir",
+    "-o",
+    default="./charts",
+    help="Directory to save generated charts",
+)
+@click.option("--verbose", "-v", is_flag=True, help="Debug logs on stderr")
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Validate input only; do not write chart files (subcommands may still parse data)",
+)
+@click.pass_context
+def cli(ctx, json_output, output_dir, verbose, dry_run):
+    """ChartPipe - Chart visualization toolkit for quantitative trading.
+
+    Designed to work seamlessly with seamflux CLI and quantpipe via Unix pipes.
+
+    Auto-detects data formats: Binance, Polymarket, Uniswap, generic OHLCV.
+
+    See repository rule.md for pipeline JSON contract (schemaVersion, artifacts, exit codes).
+
+    Examples:
+
+        seamflux service invoke binance fetchOhlcv --params symbol=BTCUSDT | chartpipe ohlcv --stdin
+
+        quantpipe backtest ... --run-dir runs/id --json
+        chartpipe backtest --run-dir runs/id --json
+
+        chartpipe ohlcv --stdin --json
+    """
+    _configure_verbose(verbose)
+    ctx.ensure_object(dict)
+    ctx.obj["json_output"] = json_output
+    ctx.obj["output_dir"] = output_dir
+    ctx.obj["verbose"] = verbose
+    ctx.obj["dry_run"] = dry_run
+
+
+# Register commands
+cli.add_command(ohlcv_command)
+cli.add_command(backtest_chart_command)
+cli.add_command(indicators_command)
+cli.add_command(stats_command)
+
+
+if __name__ == "__main__":
+    cli()

chartpipe/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. missing optional package)
+"""

chartpipe/commands/__init__.py

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

chartpipe/commands/backtest.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Backtest visualization command."""
+
+import logging
+import os
+import sys
+
+import click
+
+from ..cli_exit import EXIT_GENERAL, EXIT_SCHEMA
+from ..core.backtest_input import (
+    load_from_run_dir,
+    parse_backtest_payload,
+    title_from_summary,
+)
+from ..core.charts import ChartEngine
+from ..core.pipeline_json import emit_json_line, failure_envelope, success_envelope, utc_now_iso
+
+log = logging.getLogger(__name__)
+
+
+@click.command(name="backtest")
+@click.option("--data", "-d", type=click.Path(exists=True), help="Path to backtest result file (JSON)")
+@click.option("--input", "input_file", type=click.Path(exists=True), help="Alias for --data")
+@click.option("--stdin", "use_stdin", is_flag=True, help="Read data from stdin")
+@click.option(
+    "--run-dir",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=str),
+    default=None,
+    help="Load equity.csv and optional trades.csv from a runs/<id>/ directory",
+)
+@click.option("--title", "-t", default=None, help="Chart title (default: from summary.json or generic)")
+@click.option("--theme", default="dark", type=click.Choice(["dark", "light"]), help="Chart theme")
+@click.option(
+    "--output-dir",
+    "-o",
+    "output_dir_flag",
+    default=None,
+    help="Same as global chartpipe --output-dir (directory to save charts)",
+)
+@click.option(
+    "--json",
+    "json_flag",
+    is_flag=True,
+    default=False,
+    help="Same as global chartpipe --json (machine-readable stdout)",
+)
+@click.option(
+    "--dry-run",
+    "dry_run_flag",
+    is_flag=True,
+    default=False,
+    help="Same as global chartpipe --dry-run (validate only, no chart file)",
+)
+@click.pass_context
+def backtest_chart_command(
+    ctx,
+    data,
+    input_file,
+    use_stdin,
+    run_dir,
+    title,
+    theme,
+    output_dir_flag,
+    json_flag,
+    dry_run_flag,
+):
+    """Generate backtest visualization with equity curve, drawdown, and trades."""
+    json_output = bool(ctx.obj.get("json_output", False) or json_flag)
+    output_dir = output_dir_flag or ctx.obj.get("output_dir", "./charts")
+    dry_run = bool(ctx.obj.get("dry_run", False) or dry_run_flag)
+    command = "backtest"
+    path = input_file or data
+    cwd = os.getcwd()
+
+    def fail_json(code: str, msg: str, exit_code: int) -> None:
+        click.echo(msg, err=True)
+        if json_output:
+            emit_json_line(failure_envelope(command, code, msg))
+        ctx.exit(exit_code)
+
+    started = utc_now_iso()
+    df = None
+    trades = []
+    summary_block = None
+
+    try:
+        if run_dir:
+            df, trades, meta = load_from_run_dir(run_dir)
+            summary_block = meta.get("summary")
+            log.debug("Loaded backtest data from run-dir %s", run_dir)
+        elif use_stdin or not path:
+            input_text = sys.stdin.read()
+            if not input_text.strip():
+                fail_json(
+                    "INVALID_INPUT",
+                    "Error: No input data provided. Use --data, --run-dir, or pipe JSON via stdin.",
+                    EXIT_GENERAL,
+                )
+            df, trades, _meta = parse_backtest_payload(input_text, cwd=cwd)
+        else:
+            with open(path, encoding="utf-8") as f:
+                df, trades, _meta = parse_backtest_payload(f.read(), cwd=cwd)
+    except FileNotFoundError as e:
+        fail_json("MISSING_FILE", str(e), EXIT_GENERAL)
+    except ValueError as e:
+        fail_json("INVALID_INPUT", str(e), EXIT_SCHEMA)
+    except Exception as e:
+        log.exception("backtest input failed")
+        fail_json("INVALID_INPUT", str(e), EXIT_SCHEMA)
+
+    if df.empty or "equity" not in df.columns:
+        fail_json(
+            "INVALID_INPUT",
+            "Error: No valid equity series found (need 'equity' column).",
+            EXIT_SCHEMA,
+        )
+
+    chart_title = title or title_from_summary(summary_block, "Backtest Results")
+
+    if dry_run:
+        msg = f"Dry run OK: would plot backtest chart ({len(df)} points, {len(trades)} trades)"
+        click.echo(msg, err=True)
+        finished = utc_now_iso()
+        if json_output:
+            emit_json_line(
+                success_envelope(
+                    command,
+                    artifacts={},
+                    meta={"startedAt": started, "finishedAt": finished, "dryRun": True},
+                    data={"rows": len(df), "trades": len(trades)},
+                )
+            )
+        return
+
+    engine = ChartEngine(output_dir=output_dir, theme=theme)
+    try:
+        chart_path = engine.plot_backtest(df, trades=trades, title=chart_title)
+    except Exception as e:
+        log.exception("plot_backtest failed")
+        fail_json("PLOT_ERROR", str(e), EXIT_GENERAL)
+
+    finished = utc_now_iso()
+    rel = os.path.relpath(chart_path, cwd)
+    if json_output:
+        emit_json_line(
+            success_envelope(
+                command,
+                artifacts={"chart": rel},
+                meta={"startedAt": started, "finishedAt": finished},
+            )
+        )
+    else:
+        click.echo(f"Chart saved: {chart_path}")

chartpipe/commands/indicators.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+"""Technical indicators chart command."""
+
+import logging
+import os
+import sys
+
+import click
+
+from ..cli_exit import EXIT_GENERAL, EXIT_SCHEMA, EXIT_UPSTREAM
+from ..core.charts import ChartEngine
+from ..core.input_data import (
+    json_payload_to_dataframe,
+    normalize_ohlcv_columns,
+    normalize_timestamp_column_to_index,
+    parse_input_text,
+)
+from ..core.pipeline_json import emit_json_line, failure_envelope, success_envelope, utc_now_iso
+
+log = logging.getLogger(__name__)
+
+
+def parse_input_data(input_data):
+    """Parse input data from various formats."""
+    data = parse_input_text(input_data)
+    df = json_payload_to_dataframe(data)
+    df = normalize_ohlcv_columns(df)
+    return normalize_timestamp_column_to_index(df)
+
+
+def calculate_rsi(prices, period=14):
+    """Calculate RSI indicator."""
+    delta = prices.diff()
+    gain = (delta.where(delta > 0, 0)).rolling(window=period).mean()
+    loss = (-delta.where(delta < 0, 0)).rolling(window=period).mean()
+    rs = gain / loss
+    rsi = 100 - (100 / (1 + rs))
+    return rsi
+
+
+def calculate_macd(prices, fast=12, slow=26, signal=9):
+    """Calculate MACD indicator."""
+    ema_fast = prices.ewm(span=fast).mean()
+    ema_slow = prices.ewm(span=slow).mean()
+    macd = ema_fast - ema_slow
+    macd_signal = macd.ewm(span=signal).mean()
+    histogram = macd - macd_signal
+    return macd, macd_signal, histogram
+
+
+def calculate_bollinger(prices, period=20, std_dev=2):
+    """Calculate Bollinger Bands."""
+    middle = prices.rolling(window=period).mean()
+    std = prices.rolling(window=period).std()
+    upper = middle + (std * std_dev)
+    lower = middle - (std * std_dev)
+    return upper, middle, lower
+
+
+@click.command(name="indicators")
+@click.option("--data", "-d", type=click.Path(exists=True), help="Path to OHLCV data file (JSON)")
+@click.option("--input", "input_file", type=click.Path(exists=True), help="Alias for --data")
+@click.option("--stdin", "use_stdin", is_flag=True, help="Read data from standard input")
+@click.option(
+    "--indicator",
+    "-i",
+    "indicator_type",
+    type=click.Choice(["rsi", "macd", "bb", "all"]),
+    default="rsi",
+    help="Indicator type to plot",
+)
+@click.option("--title", "-t", help="Chart title (auto-generated if not provided)")
+@click.option("--period", "-p", default=14, help="Indicator period (for RSI)")
+@click.option("--theme", default="dark", type=click.Choice(["dark", "light"]), help="Chart theme")
+@click.option(
+    "--output-dir",
+    "-o",
+    "output_dir_flag",
+    default=None,
+    help="Same as global chartpipe --output-dir (directory to save charts)",
+)
+@click.option(
+    "--json",
+    "json_flag",
+    is_flag=True,
+    default=False,
+    help="Same as global chartpipe --json (machine-readable stdout)",
+)
+@click.option(
+    "--dry-run",
+    "dry_run_flag",
+    is_flag=True,
+    default=False,
+    help="Same as global chartpipe --dry-run (validate only, no chart file)",
+)
+@click.pass_context
+def indicators_command(
+    ctx,
+    data,
+    input_file,
+    use_stdin,
+    indicator_type,
+    title,
+    period,
+    theme,
+    output_dir_flag,
+    json_flag,
+    dry_run_flag,
+):
+    """Generate technical indicator charts."""
+    json_output = bool(ctx.obj.get("json_output", False) or json_flag)
+    output_dir = output_dir_flag or ctx.obj.get("output_dir", "./charts")
+    dry_run = bool(ctx.obj.get("dry_run", False) or dry_run_flag)
+    command = "indicators"
+    path = input_file or data
+    cwd = os.getcwd()
+
+    def fail_json(code: str, msg: str, exit_code: int) -> None:
+        click.echo(msg, err=True)
+        if json_output:
+            emit_json_line(failure_envelope(command, code, msg))
+        ctx.exit(exit_code)
+
+    started = utc_now_iso()
+
+    try:
+        if use_stdin or not path:
+            input_text = sys.stdin.read()
+            if not input_text.strip():
+                fail_json(
+                    "INVALID_INPUT",
+                    "Error: No input data provided. Use --data or pipe data via stdin.",
+                    EXIT_GENERAL,
+                )
+            df = parse_input_data(input_text)
+        else:
+            with open(path, encoding="utf-8") as f:
+                df = parse_input_data(f.read())
+    except (ValueError, OSError) as e:
+        fail_json("INVALID_INPUT", str(e), EXIT_SCHEMA)
+
+    if df.empty:
+        fail_json("INVALID_INPUT", "Error: No valid data found.", EXIT_SCHEMA)
+
+    if "close" in df.columns:
+        if indicator_type == "rsi" or indicator_type == "all":
+            if "rsi" not in df.columns:
+                df["rsi"] = calculate_rsi(df["close"], period)
+
+        if indicator_type == "macd" or indicator_type == "all":
+            if "macd" not in df.columns:
+                df["macd"], df["signal"], df["histogram"] = calculate_macd(df["close"])
+
+        if indicator_type == "bb" or indicator_type == "all":
+            if "bb_upper" not in df.columns:
+                df["bb_upper"], df["bb_middle"], df["bb_lower"] = calculate_bollinger(df["close"])
+
+    if dry_run:
+        click.echo(
+            f"Dry run OK: would plot indicator chart(s) type={indicator_type} ({len(df)} rows)",
+            err=True,
+        )
+        finished = utc_now_iso()
+        if json_output:
+            emit_json_line(
+                success_envelope(
+                    command,
+                    artifacts={},
+                    meta={"startedAt": started, "finishedAt": finished, "dryRun": True},
+                    data={"rows": len(df), "indicator": indicator_type},
+                )
+            )
+        return
+
+    engine = ChartEngine(output_dir=output_dir, theme=theme)
+
+    try:
+        if indicator_type == "all":
+            results = {}
+            for ind in ["rsi", "macd", "bb"]:
+                chart_title = title or f"{ind.upper()} Indicator"
+                results[ind] = engine.plot_indicator(df, indicator=ind, title=chart_title)
+            finished = utc_now_iso()
+            artifacts = {k: os.path.relpath(v, cwd) for k, v in results.items()}
+            if json_output:
+                emit_json_line(
+                    success_envelope(
+                        command,
+                        artifacts=artifacts,
+                        meta={"startedAt": started, "finishedAt": finished},
+                    )
+                )
+            else:
+                for ind, pth in results.items():
+                    click.echo(f"{ind.upper()} chart saved: {pth}")
+        else:
+            chart_title = title or f"{indicator_type.upper()} Indicator"
+            chart_path = engine.plot_indicator(df, indicator=indicator_type, title=chart_title)
+            finished = utc_now_iso()
+            if json_output:
+                emit_json_line(
+                    success_envelope(
+                        command,
+                        artifacts={"chart": os.path.relpath(chart_path, cwd)},
+                        meta={"startedAt": started, "finishedAt": finished},
+                    )
+                )
+            else:
+                click.echo(f"Chart saved: {chart_path}")
+    except ImportError as e:
+        fail_json("MISSING_DEPENDENCY", str(e), EXIT_UPSTREAM)
+    except Exception as e:
+        log.exception("plot_indicator failed")
+        fail_json("PLOT_ERROR", str(e), EXIT_GENERAL)

chartpipe/commands/ohlcv.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""OHLCV candlestick chart command."""
+
+import logging
+import os
+import sys
+
+import click
+
+from ..cli_exit import EXIT_GENERAL, EXIT_SCHEMA, EXIT_UPSTREAM
+from ..core.charts import ChartEngine
+from ..core.input_data import (
+    json_payload_to_dataframe,
+    normalize_ohlcv_columns,
+    parse_input_text,
+)
+from ..core.pipeline_json import emit_json_line, failure_envelope, success_envelope, utc_now_iso
+
+log = logging.getLogger(__name__)
+
+
+def parse_input_data(input_data):
+    """Parse input data from various formats."""
+    data = parse_input_text(input_data)
+    df = json_payload_to_dataframe(data)
+    return normalize_ohlcv_columns(df)
+
+
+@click.command(name="ohlcv")
+@click.option("--data", "-d", type=click.Path(exists=True), help="Path to OHLCV data file (JSON)")
+@click.option("--input", "input_file", type=click.Path(exists=True), help="Alias for --data")
+@click.option("--stdin", "use_stdin", is_flag=True, help="Read data from standard input")
+@click.option("--title", "-t", default="Price Chart", help="Chart title")
+@click.option("--volume/--no-volume", default=True, help="Show volume subplot")
+@click.option(
+    "--ma",
+    "ma_periods",
+    multiple=True,
+    type=int,
+    default=[20, 50],
+    help="Moving average periods (can be used multiple times)",
+)
+@click.option("--theme", default="dark", type=click.Choice(["dark", "light"]), help="Chart theme")
+@click.option(
+    "--output-dir",
+    "-o",
+    "output_dir_flag",
+    default=None,
+    help="Same as global chartpipe --output-dir (directory to save charts)",
+)
+@click.option(
+    "--json",
+    "json_flag",
+    is_flag=True,
+    default=False,
+    help="Same as global chartpipe --json (machine-readable stdout)",
+)
+@click.option(
+    "--dry-run",
+    "dry_run_flag",
+    is_flag=True,
+    default=False,
+    help="Same as global chartpipe --dry-run (validate only, no chart file)",
+)
+@click.pass_context
+def ohlcv_command(
+    ctx,
+    data,
+    input_file,
+    use_stdin,
+    title,
+    volume,
+    ma_periods,
+    theme,
+    output_dir_flag,
+    json_flag,
+    dry_run_flag,
+):
+    """Generate OHLCV candlestick chart."""
+    json_output = bool(ctx.obj.get("json_output", False) or json_flag)
+    output_dir = output_dir_flag or ctx.obj.get("output_dir", "./charts")
+    dry_run = bool(ctx.obj.get("dry_run", False) or dry_run_flag)
+    command = "ohlcv"
+    path = input_file or data
+    cwd = os.getcwd()
+
+    def fail_json(code: str, msg: str, exit_code: int) -> None:
+        click.echo(msg, err=True)
+        if json_output:
+            emit_json_line(failure_envelope(command, code, msg))
+        ctx.exit(exit_code)
+
+    started = utc_now_iso()
+
+    try:
+        if use_stdin or not path:
+            input_text = sys.stdin.read()
+            if not input_text.strip():
+                fail_json(
+                    "INVALID_INPUT",
+                    "Error: No input data provided. Use --data or pipe data via stdin.",
+                    EXIT_GENERAL,
+                )
+            df = parse_input_data(input_text)
+        else:
+            with open(path, encoding="utf-8") as f:
+                df = parse_input_data(f.read())
+    except (ValueError, OSError) as e:
+        fail_json("INVALID_INPUT", str(e), EXIT_SCHEMA)
+
+    if df.empty:
+        fail_json("INVALID_INPUT", "Error: No valid data found.", EXIT_SCHEMA)
+
+    if dry_run:
+        click.echo(
+            f"Dry run OK: would plot OHLCV chart ({len(df)} rows)", err=True
+        )
+        finished = utc_now_iso()
+        if json_output:
+            emit_json_line(
+                success_envelope(
+                    command,
+                    artifacts={},
+                    meta={"startedAt": started, "finishedAt": finished, "dryRun": True},
+                    data={"rows": len(df)},
+                )
+            )
+        return
+
+    engine = ChartEngine(output_dir=output_dir, theme=theme)
+    try:
+        chart_path = engine.plot_ohlcv(
+            df,
+            title=title,
+            volume=volume,
+            ma_periods=list(ma_periods) if ma_periods else None,
+        )
+    except ImportError as e:
+        fail_json("MISSING_DEPENDENCY", str(e), EXIT_UPSTREAM)
+    except Exception as e:
+        log.exception("plot_ohlcv failed")
+        fail_json("PLOT_ERROR", str(e), EXIT_GENERAL)
+
+    finished = utc_now_iso()
+    rel = os.path.relpath(chart_path, cwd)
+    if json_output:
+        emit_json_line(
+            success_envelope(
+                command,
+                artifacts={"chart": rel},
+                meta={"startedAt": started, "finishedAt": finished},
+            )
+        )
+    else:
+        click.echo(f"Chart saved: {chart_path}")