koval-engine 0.9.0__py3-none-any.whl

koval/__init__.py

@@ -0,0 +1,7 @@
+"""Open engine for building and validating trading strategies."""
+
+from __future__ import annotations
+
+from koval._version import __version__
+
+__all__ = ["__version__"]

koval/_version.py

@@ -0,0 +1,7 @@
+"""Package version, read from installed distribution metadata."""
+
+from __future__ import annotations
+
+from importlib import metadata
+
+__version__ = metadata.version("koval-engine")

koval/cli/__init__.py

@@ -0,0 +1,7 @@
+"""Command-line interface for the Koval engine."""
+
+from __future__ import annotations
+
+from koval.cli.main import main
+
+__all__ = ["main"]

koval/cli/data.py

@@ -0,0 +1,27 @@
+"""CSV candle loading for offline CLI runs."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from koval.exchanges.base import OHLCV_COLUMNS
+
+
+def load_csv_candles(path: Path) -> np.ndarray:
+    """Read a chronological OHLCV CSV into an ``(N, 6)`` float array.
+
+    The file must have a header row naming exactly the OHLCV columns; extra
+    columns are ignored, missing ones are an error.
+    """
+    frame = pd.read_csv(path)
+    missing = [column for column in OHLCV_COLUMNS if column not in frame.columns]
+    if missing:
+        raise ValueError(f"{path}: missing required columns: {', '.join(missing)}")
+    candles = frame.loc[:, list(OHLCV_COLUMNS)].to_numpy(dtype=np.float64)
+    timestamps = candles[:, 0]
+    if np.any(np.diff(timestamps) <= 0):
+        raise ValueError(f"{path}: rows must be chronological with strictly increasing timestamps")
+    return candles

koval/cli/main.py

@@ -0,0 +1,239 @@
+"""Argument parsing and command dispatch for the ``koval`` console script."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from koval import __version__
+from koval.exchanges import get_exchange_adapter
+from koval.exchanges.ohlcv_cache import OhlcvCache
+
+
+def _load_graph(path: str) -> dict[str, Any]:
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def _cmd_blocks(args: argparse.Namespace) -> int:
+    from koval.strategy.registry import BLOCK_CATALOG
+
+    specs = sorted(BLOCK_CATALOG.values(), key=lambda spec: spec.type)
+    if args.json:
+        print(
+            json.dumps(
+                [
+                    {
+                        "type": spec.type,
+                        "category": str(spec.category),
+                        "display_name": spec.display_name,
+                        "description": spec.description,
+                    }
+                    for spec in specs
+                ],
+                indent=2,
+            )
+        )
+        return 0
+    width = max(len(spec.type) for spec in specs)
+    for spec in specs:
+        print(f"{spec.type:<{width}}  {spec.description}")
+    return 0
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    from koval.strategy.block_assembler import GraphValidationError, assemble_from_graph
+
+    try:
+        payload = _load_graph(args.graph)
+    except FileNotFoundError:
+        print(f"error: graph file not found: {args.graph}", file=sys.stderr)
+        return 1
+    except json.JSONDecodeError as exc:
+        print(f"error: {args.graph} is not valid JSON: {exc}", file=sys.stderr)
+        return 1
+    try:
+        assemble_from_graph(payload.get("graph", payload))
+    except GraphValidationError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    print("graph is valid")
+    return 0
+
+
+def _cmd_examples(args: argparse.Namespace) -> int:
+    import shutil
+
+    from koval.examples import EXAMPLES_DIR
+
+    if args.copy is None:
+        print(EXAMPLES_DIR)
+        return 0
+
+    destination = Path(args.copy).expanduser() / "koval-examples"
+    if destination.exists():
+        print(
+            f"error: {destination} already exists; remove it or choose another directory",
+            file=sys.stderr,
+        )
+        return 1
+    shutil.copytree(EXAMPLES_DIR, destination, ignore=shutil.ignore_patterns("__pycache__", "*.py"))
+    print(f"copied bundled examples to {destination}")
+    return 0
+
+
+def _cmd_backtest(args: argparse.Namespace) -> int:
+    from koval.cli.data import load_csv_candles
+    from koval.engine.backtest_engine import (
+        EngineRunSpec,
+        NoBacktestEngineError,
+        load_backtest_engine,
+    )
+    from koval.engine.time_range import date_to_ms
+    from koval.strategy.block_assembler import GraphValidationError
+
+    try:
+        payload = _load_graph(args.graph)
+    except FileNotFoundError:
+        print(f"error: graph file not found: {args.graph}", file=sys.stderr)
+        return 1
+    except json.JSONDecodeError as exc:
+        print(f"error: {args.graph} is not valid JSON: {exc}", file=sys.stderr)
+        return 1
+    graph = payload.get("graph", payload)
+
+    if args.data and args.symbol:
+        print("error: pass either --data or --symbol, not both", file=sys.stderr)
+        return 1
+    if not args.data and not args.symbol:
+        print(
+            "error: pass either --data <csv> for an offline run "
+            "or --symbol <symbol> to fetch candles",
+            file=sys.stderr,
+        )
+        return 1
+
+    if args.data:
+        try:
+            candles = load_csv_candles(Path(args.data))
+        except (FileNotFoundError, ValueError) as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+    else:
+        if not (args.start_date and args.end_date):
+            print("error: --symbol requires --from and --to", file=sys.stderr)
+            return 1
+        cache = OhlcvCache(root=Path(args.cache_dir))
+        try:
+            candles = cache.get(
+                get_exchange_adapter(args.exchange),
+                exchange=args.exchange,
+                symbol=args.symbol,
+                timeframe=args.timeframe,
+                start_ms=date_to_ms(args.start_date),
+                end_ms=date_to_ms(args.end_date),
+            )
+        except ValueError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+        if candles.shape[0] == 0:
+            print(
+                f"error: no candles for {args.symbol} {args.timeframe} in the requested range",
+                file=sys.stderr,
+            )
+            return 1
+
+    spec = EngineRunSpec(
+        graph=graph,
+        feeds={args.timeframe: candles},
+        initial_capital=args.capital,
+        execution_config={"exchange": args.exchange, "exchange_type": "future"},
+    )
+    override = os.getenv("KOVAL_BACKTEST_ENGINE")
+    try:
+        engine = load_backtest_engine()
+    except NoBacktestEngineError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except ImportError as exc:
+        print(
+            f"error: cannot import the backtest engine module '{override}' "
+            f"named by KOVAL_BACKTEST_ENGINE: {exc}",
+            file=sys.stderr,
+        )
+        return 1
+    except AttributeError:
+        print(
+            f"error: module '{override}' named by KOVAL_BACKTEST_ENGINE "
+            "does not define create_engine()",
+            file=sys.stderr,
+        )
+        return 1
+
+    try:
+        result = engine.run(spec)
+    except GraphValidationError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(
+            json.dumps({"metrics": result.metrics, "trades": result.trades}, indent=2, default=str)
+        )
+        return 0
+    for key in sorted(result.metrics):
+        print(f"{key:<24} {result.metrics[key]}")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="koval", description="Koval trading-strategy engine")
+    parser.add_argument("--version", action="version", version=f"koval-engine {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    blocks = subparsers.add_parser("blocks", help="list the available strategy blocks")
+    blocks.add_argument("--json", action="store_true", help="emit machine-readable JSON")
+    blocks.set_defaults(handler=_cmd_blocks)
+
+    validate = subparsers.add_parser("validate", help="validate a strategy graph file")
+    validate.add_argument("graph", help="path to a strategy graph JSON file")
+    validate.set_defaults(handler=_cmd_validate)
+
+    examples = subparsers.add_parser("examples", help="locate or copy the bundled examples")
+    examples.add_argument(
+        "--copy",
+        metavar="DIR",
+        help="copy the bundled examples into DIR/koval-examples/ so they can be edited",
+    )
+    examples.set_defaults(handler=_cmd_examples)
+
+    backtest = subparsers.add_parser("backtest", help="run a backtest over OHLCV candles")
+    backtest.add_argument("graph", help="path to a strategy graph JSON file")
+    backtest.add_argument("--data", help="path to an OHLCV CSV file (offline run)")
+    backtest.add_argument("--symbol", help="symbol to fetch, e.g. BTCUSDT")
+    backtest.add_argument("--from", dest="start_date", help="inclusive start date, YYYY-MM-DD")
+    backtest.add_argument("--to", dest="end_date", help="exclusive end date, YYYY-MM-DD")
+    backtest.add_argument(
+        "--cache-dir", default="data_cache", help="directory for cached OHLCV Parquet files"
+    )
+    backtest.add_argument(
+        "--timeframe", required=True, help="timeframe label for the candles, e.g. 1h"
+    )
+    backtest.add_argument("--capital", type=float, default=10_000.0, help="initial capital")
+    backtest.add_argument("--exchange", default="binance", help="venue used for the fee model")
+    backtest.add_argument("--json", action="store_true", help="emit machine-readable JSON")
+    backtest.set_defaults(handler=_cmd_backtest)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    return int(args.handler(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

koval/engine/account_state.py

@@ -0,0 +1,105 @@
+"""Platform Account State — per-run runtime service.
+
+Source of truth for balance/equity/margin/drawdown surfaced read-only on
+``BarContext.account``. Equity is fed from the broker each bar;
+daily PnL, drawdown and margin are derived here. Holds only plain data so it
+survives the process-pool job queue. Not a graph node — updated via GraphStrategy
+hooks (``on_bar`` / ``on_open`` / ``on_close``).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+_MS_PER_DAY = 86_400_000
+
+
+@dataclass(frozen=True)
+class OpenPosition:
+    side: str  # "buy" | "sell"
+    entry_price: float
+    quantity: float
+    current_stop: float
+    margin: float
+
+
+@dataclass(frozen=True)
+class AccountSnapshot:
+    balance: float
+    equity: float
+    free_margin: float
+    margin_used: float
+    unrealized_pnl: float
+    realized_pnl: float
+    daily_pnl: float
+    peak_equity: float
+    drawdown_pct: float
+    open_positions: int
+    open_position: OpenPosition | None
+
+
+class PlatformAccountState:
+    def __init__(self, starting_balance: float = 0.0) -> None:
+        bal = float(starting_balance)
+        self._starting = bal
+        self._realized = 0.0
+        self._equity = bal
+        self._peak_equity = bal
+        self._margin_used = 0.0
+        self._position: OpenPosition | None = None
+        self._current_day: int | None = None
+        self._day_start_equity = bal
+
+    def on_bar(self, *, equity: float, timestamp_ms: int) -> None:
+        equity = float(equity)
+        day = int(timestamp_ms) // _MS_PER_DAY
+        if self._current_day is None or day != self._current_day:
+            # daily_pnl baseline is the FIRST bar's equity of the new UTC day, so
+            # any overnight gap between days is excluded from both days' daily_pnl.
+            self._current_day = day
+            self._day_start_equity = equity
+        self._equity = equity
+        if equity > self._peak_equity:
+            self._peak_equity = equity
+
+    def on_open(
+        self,
+        *,
+        side: str,
+        entry_price: float,
+        quantity: float,
+        current_stop: float,
+        margin: float,
+    ) -> None:
+        self._position = OpenPosition(
+            side=side,
+            entry_price=float(entry_price),
+            quantity=float(quantity),
+            current_stop=float(current_stop),
+            margin=float(margin),
+        )
+        self._margin_used += float(margin)
+
+    def on_close(self, *, realized_pnl: float) -> None:
+        self._realized += float(realized_pnl)
+        if self._position is not None:
+            self._margin_used = max(0.0, self._margin_used - self._position.margin)
+        self._position = None
+
+    def snapshot(self) -> AccountSnapshot:
+        balance = self._starting + self._realized
+        peak = self._peak_equity if self._peak_equity > 0 else self._equity
+        drawdown = (peak - self._equity) / peak * 100.0 if peak > 0 else 0.0
+        return AccountSnapshot(
+            balance=balance,
+            equity=self._equity,
+            free_margin=self._equity - self._margin_used,
+            margin_used=self._margin_used,
+            unrealized_pnl=self._equity - balance,
+            realized_pnl=self._realized,
+            daily_pnl=self._equity - self._day_start_equity,
+            peak_equity=peak,
+            drawdown_pct=max(0.0, drawdown),
+            open_positions=1 if self._position is not None else 0,
+            open_position=self._position,
+        )

koval/engine/backtest_engine.py

@@ -0,0 +1,114 @@
+"""Backtest-engine plugin contract for independently distributed engines.
+
+Concrete engines are discovered through Python entry points or loaded from an
+explicit module path. This MIT package does not import an implementation.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from importlib import metadata
+from typing import Any, Protocol
+
+import numpy as np
+
+_ENTRY_POINT_GROUP = "koval.backtest_engines"
+_DEFAULT_ENGINE_NAME = "backtrader"
+
+# Bump when EngineRunSpec / BacktestResult change in a breaking way so external
+# engines can negotiate compatibility.
+ENGINE_PROTOCOL_VERSION = 1
+
+
+@dataclass
+class EngineRunSpec:
+    """Everything the engine needs for one run — pure, picklable data.
+
+    ``execution_config`` is an optional dict describing the venue (``exchange``,
+    ``exchange_type``) so the engine can mark realistic fees on the broker. When
+    omitted the run is fee-free — kept that way for unit tests that assert on
+    raw price action.
+    """
+
+    graph: dict[str, Any]
+    feeds: dict[str, np.ndarray]
+    initial_capital: float
+    execution_config: dict[str, Any] | None = None
+    protocol_version: int = ENGINE_PROTOCOL_VERSION
+
+
+@dataclass
+class BacktestResult:
+    """Engine output — plain Python only, no Backtrader objects."""
+
+    metrics: dict[str, Any] = field(default_factory=dict)
+    trades: list[dict[str, Any]] = field(default_factory=list)
+    equity_curve: list[dict[str, Any]] = field(default_factory=list)
+
+
+class BacktestEngineProtocol(Protocol):
+    """The contract every backtest engine plugin implements."""
+
+    def run(
+        self,
+        spec: EngineRunSpec,
+        on_event: Callable[[dict], None] | None = None,
+    ) -> BacktestResult: ...
+
+
+class ProtocolVersionError(RuntimeError):
+    """Raised when a spec's protocol version is not supported by the engine."""
+
+
+def check_protocol_version(spec: EngineRunSpec) -> None:
+    if spec.protocol_version != ENGINE_PROTOCOL_VERSION:
+        raise ProtocolVersionError(
+            f"spec protocol_version={spec.protocol_version} unsupported; "
+            f"engine speaks {ENGINE_PROTOCOL_VERSION}"
+        )
+
+
+class NoBacktestEngineError(RuntimeError):
+    """Raised when no backtest engine can be resolved."""
+
+
+def _discover_entry_points() -> dict[str, metadata.EntryPoint]:
+    return {ep.name: ep for ep in metadata.entry_points(group=_ENTRY_POINT_GROUP)}
+
+
+def _resolve_engine_target(name: str | None) -> Callable[[], BacktestEngineProtocol]:
+    """Resolve the engine factory: an explicit module override wins, then the
+    requested entry point."""
+    override = os.getenv("KOVAL_BACKTEST_ENGINE")
+    if override:
+        return importlib.import_module(override).create_engine
+    requested = name or _DEFAULT_ENGINE_NAME
+    entry_points = _discover_entry_points()
+    chosen = entry_points.get(requested)
+    if chosen is not None:
+        return chosen.load()
+    available = ", ".join(sorted(entry_points)) or "none"
+    if requested != _DEFAULT_ENGINE_NAME:
+        raise NoBacktestEngineError(
+            f"No backtest engine named '{requested}' is registered "
+            f"(available: {available}). Install/register a compatible plugin "
+            "or set KOVAL_BACKTEST_ENGINE to an engine module path."
+        )
+    raise NoBacktestEngineError(
+        f"No backtest engine named '{requested}' is registered "
+        f"(available: {available}) — install or register a compatible backtest "
+        "engine plugin through the 'koval.backtest_engines' entry-point group, "
+        "or set KOVAL_BACKTEST_ENGINE to an engine module path."
+    )
+
+
+def load_backtest_engine(name: str | None = None) -> BacktestEngineProtocol:
+    """Resolve and instantiate a backtest engine via the
+    ``koval.backtest_engines`` entry-point group. ``KOVAL_BACKTEST_ENGINE``
+    (a module path) overrides discovery; ``name`` selects a registered engine
+    (default ``backtrader``). The env is read on every call so callers can
+    switch engines without clearing a cache."""
+    return _resolve_engine_target(name)()

koval/engine/broker.py

@@ -0,0 +1,151 @@
+"""Broker port for paper and sandbox live order routing.
+
+This module is intentionally framework-free: no FastAPI, MongoDB, requests, or
+Backtrader imports belong in the broker contract.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal, Protocol
+
+OrderSide = Literal["buy", "sell"]
+OrderStatus = Literal["accepted", "rejected", "partial", "filled", "canceled", "expired"]
+OrderRole = Literal["entry", "stop", "target", "flatten", "cancel", "protection"]
+
+
+@dataclass(frozen=True)
+class BrokerOrderIntent:
+    session_id: str
+    intent_id: str
+    client_order_id: str
+    symbol: str
+    side: OrderSide
+    order_type: str
+    quantity: str
+    target: str
+    price: str | None = None
+    stop_price: str | None = None
+    target_price: str | None = None
+    role: OrderRole = "entry"
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class BrokerOrderAck:
+    session_id: str
+    client_order_id: str
+    exchange_order_id: str | None
+    status: OrderStatus
+    target: str
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class BrokerFill:
+    session_id: str
+    client_order_id: str
+    exchange_order_id: str | None
+    symbol: str
+    side: OrderSide
+    status: Literal["partial", "filled", "canceled", "expired"]
+    role: OrderRole
+    quantity: str | None
+    price: str | None
+    timestamp_ms: int
+    realized_pnl: str | None = None
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ProtectiveOrderIntent:
+    session_id: str
+    entry_client_order_id: str
+    stop_client_order_id: str
+    target_client_order_id: str
+    symbol: str
+    side: OrderSide
+    quantity: str
+    stop_price: str
+    target_price: str
+    target: str
+    reduce_only: bool = True
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ProtectiveOrderState:
+    session_id: str
+    entry_client_order_id: str
+    stop_client_order_id: str | None
+    target_client_order_id: str | None
+    status: str
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class BrokerPositionSnapshot:
+    symbol: str
+    side: str
+    quantity: str
+    entry_price: str | None = None
+    position_id: str | None = None
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class BrokerReconciliationReport:
+    session_id: str
+    target: str
+    open_orders: list[BrokerOrderAck] = field(default_factory=list)
+    fills: list[BrokerFill] = field(default_factory=list)
+    positions: list[BrokerPositionSnapshot] = field(default_factory=list)
+    incidents: list[str] = field(default_factory=list)
+    metadata: dict[str, object] = field(default_factory=dict)
+
+    @property
+    def safe_to_trade(self) -> bool:
+        return not self.incidents
+
+
+class BrokerPositionView(Protocol):
+    """Minimum position state the engine needs from every broker."""
+
+    side: str
+    entry_price: float | str
+    quantity: float | str
+
+
+class Broker(Protocol):
+    target: str
+
+    @property
+    def pending(self) -> bool:
+        """Whether an entry order is still working."""
+
+    @property
+    def position(self) -> BrokerPositionView | None:
+        """Current reconciled/open position, if any."""
+
+    def submit_entry(self, intent: BrokerOrderIntent) -> BrokerOrderAck:
+        """Submit an entry order after the caller has persisted the intent."""
+
+    def place_protection(self, intent: ProtectiveOrderIntent) -> list[BrokerOrderAck]:
+        """Place or replace protective reduce-only stop/target orders."""
+
+    def poll_fills(self, session_id: str) -> list[BrokerFill]:
+        """Poll venue order state and return new fill/terminal events."""
+
+    def reconcile(
+        self, session_id: str, intents: list[BrokerOrderIntent]
+    ) -> BrokerReconciliationReport:
+        """Reconcile persisted intents against venue state before trading."""
+
+    def cancel_all(self, symbol: str, session_id: str) -> list[BrokerOrderAck]:
+        """Cancel all known working orders for a symbol/session."""
+
+    def flatten(self, symbol: str, session_id: str) -> BrokerOrderAck | None:
+        """Flatten or reduce open exposure if the venue has any."""
+
+    def modify_stop(self, stop_price: float) -> BrokerOrderAck | None:
+        """Replace the active protective stop without increasing exposure."""

koval/engine/client_order_id.py

@@ -0,0 +1,22 @@
+"""Deterministic, venue-safe client order identifiers."""
+
+from __future__ import annotations
+
+import hashlib
+
+
+def make_client_order_id(
+    session_id: str,
+    intent_id: str,
+    venue: str,
+    role: str,
+    *,
+    max_len: int = 32,
+) -> str:
+    """Return a stable idempotency key safe for Binance and WhiteBIT."""
+
+    if max_len < 16:
+        raise ValueError("max_len must be at least 16")
+    raw = "\x1f".join((session_id, intent_id, venue, role)).encode("utf-8")
+    digest = hashlib.sha256(raw).hexdigest()
+    return f"kv-{digest}"[:max_len]