gnomepy 2.2.4__tar.gz → 2.3.0__tar.gz

{gnomepy-2.2.4 → gnomepy-2.3.0}/PKG-INFO

@@ -1,21 +1,25 @@
 Metadata-Version: 2.4
 Name: gnomepy
-Version: 2.2.4
+Version: 2.3.0
 Summary: 
 Author: mprey
 Author-email: masonprey7@gmail.com
 Requires-Python: >=3.13,<3.14
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: backtest
+Requires-Dist: anthropic (>=0.40.0,<1.0.0) ; extra == "backtest"
 Requires-Dist: boto3 (>=1.36.18,<2.0.0)
+Requires-Dist: boto3-stubs (>=1.42.73,<1.43.0) ; extra == "backtest"
 Requires-Dist: click (>=8.1,<9.0)
-Requires-Dist: dash (>=2.18,<3.0)
-Requires-Dist: dash-bootstrap-components (>=1.6,<2.0)
-Requires-Dist: jpype1 (>=1.5.0,<2.0.0)
-Requires-Dist: numpy (>=2.2.4,<3.0.0)
-Requires-Dist: pandas (>=2.2.3,<3.0.0)
-Requires-Dist: plotly (>=6.6.0,<6.7.0)
-Requires-Dist: pyarrow (>=23.0.1,<24.0.0)
+Requires-Dist: dash (>=2.18,<3.0) ; extra == "backtest"
+Requires-Dist: dash-bootstrap-components (>=1.6,<2.0) ; extra == "backtest"
+Requires-Dist: jpype1 (>=1.5.0,<2.0.0) ; extra == "backtest"
+Requires-Dist: numpy (>=2.2.4,<3.0.0) ; extra == "backtest"
+Requires-Dist: pandas (>=2.2.3,<3.0.0) ; extra == "backtest"
+Requires-Dist: pandas-stubs (>=2.3.3,<2.4.0) ; extra == "backtest"
+Requires-Dist: plotly (>=6.6.0,<6.7.0) ; extra == "backtest"
+Requires-Dist: pyarrow (>=23.0.1,<24.0.0) ; extra == "backtest"
 Requires-Dist: pytz (>=2025.1,<2026.0)
 Requires-Dist: pyyaml (>=6.0,<7.0)
 Requires-Dist: requests (>=2.32.3,<3.0.0)

gnomepy-2.3.0/gnomepy/__init__.py

@@ -0,0 +1,83 @@
+"""gnomepy — backtesting infrastructure for the gnome trading system.
+
+Public API:
+
+    from gnomepy import (
+        Strategy, Backtest, run_backtest,
+        BacktestConfig, ListingSimConfig, ExchangeProfileConfig,
+        StrategyConfig, RiskConfig,
+        StaticFeeConfig, StaticLatencyConfig, GaussianLatencyConfig,
+        OptimisticQueueConfig, RiskAverseQueueConfig, ProbabilisticQueueConfig,
+        Intent, ExecutionReport, OmsView,
+        SchemaType, Side, Action,
+        Mbp10Schema, ...
+    )
+"""
+import importlib
+
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    "BacktestConfig": ("gnomepy.java.backtest.config", "BacktestConfig"),
+    "ExchangeProfileConfig": ("gnomepy.java.backtest.config", "ExchangeProfileConfig"),
+    "GaussianLatencyConfig": ("gnomepy.java.backtest.config", "GaussianLatencyConfig"),
+    "ListingSimConfig": ("gnomepy.java.backtest.config", "ListingSimConfig"),
+    "OptimisticQueueConfig": ("gnomepy.java.backtest.config", "OptimisticQueueConfig"),
+    "ProbabilisticQueueConfig": ("gnomepy.java.backtest.config", "ProbabilisticQueueConfig"),
+    "RiskAverseQueueConfig": ("gnomepy.java.backtest.config", "RiskAverseQueueConfig"),
+    "RiskConfig": ("gnomepy.java.backtest.config", "RiskConfig"),
+    "StaticFeeConfig": ("gnomepy.java.backtest.config", "StaticFeeConfig"),
+    "StaticLatencyConfig": ("gnomepy.java.backtest.config", "StaticLatencyConfig"),
+    "StrategyConfig": ("gnomepy.java.backtest.config", "StrategyConfig"),
+    "ExecutionReport": ("gnomepy.java.backtest.orders", "ExecutionReport"),
+    "Backtest": ("gnomepy.java.backtest.runner", "Backtest"),
+    "run_backtest": ("gnomepy.java.backtest.runner", "run_backtest"),
+    "MarketDataCache": ("gnomepy.java.cache", "MarketDataCache"),
+    "Strategy": ("gnomepy.java.backtest.strategy", "Strategy"),
+    "DataStore": ("gnomepy.java.datastore", "DataStore"),
+    "Action": ("gnomepy.java.enums", "Action"),
+    "ExecType": ("gnomepy.java.enums", "ExecType"),
+    "OrderStatus": ("gnomepy.java.enums", "OrderStatus"),
+    "OrderType": ("gnomepy.java.enums", "OrderType"),
+    "SchemaType": ("gnomepy.java.enums", "SchemaType"),
+    "Side": ("gnomepy.java.enums", "Side"),
+    "TimeInForce": ("gnomepy.java.enums", "TimeInForce"),
+    "Intent": ("gnomepy.java.oms", "Intent"),
+    "OmsView": ("gnomepy.java.oms", "OmsView"),
+    "PositionInfo": ("gnomepy.java.oms", "PositionInfo"),
+    "TrackedOrderInfo": ("gnomepy.java.oms", "TrackedOrderInfo"),
+    "BacktestResults": ("gnomepy.java.recorder", "BacktestResults"),
+    "Bbo1mSchema": ("gnomepy.java.schemas", "Bbo1mSchema"),
+    "Bbo1sSchema": ("gnomepy.java.schemas", "Bbo1sSchema"),
+    "BboSchema": ("gnomepy.java.schemas", "BboSchema"),
+    "MboSchema": ("gnomepy.java.schemas", "MboSchema"),
+    "Mbp1Schema": ("gnomepy.java.schemas", "Mbp1Schema"),
+    "Mbp10Schema": ("gnomepy.java.schemas", "Mbp10Schema"),
+    "Ohlcv1hSchema": ("gnomepy.java.schemas", "Ohlcv1hSchema"),
+    "Ohlcv1mSchema": ("gnomepy.java.schemas", "Ohlcv1mSchema"),
+    "Ohlcv1sSchema": ("gnomepy.java.schemas", "Ohlcv1sSchema"),
+    "OhlcvSchema": ("gnomepy.java.schemas", "OhlcvSchema"),
+    "Schema": ("gnomepy.java.schemas", "Schema"),
+    "TradesSchema": ("gnomepy.java.schemas", "TradesSchema"),
+    "wrap_schema": ("gnomepy.java.schemas", "wrap_schema"),
+    "Scales": ("gnomepy.java.statics", "Scales"),
+    "BacktestMetadata": ("gnomepy.metadata", "BacktestMetadata"),
+    "BacktestReport": ("gnomepy.reporting", "BacktestReport"),
+    "Curves": ("gnomepy.reporting.metrics", "Curves"),
+    "build_curves": ("gnomepy.reporting.metrics", "build_curves"),
+    "compute_sharpe": ("gnomepy.reporting.metrics", "compute_sharpe"),
+    "ReportSection": ("gnomepy.reporting.plots", "ReportSection"),
+    "generate_backtest_id": ("gnomepy.utils", "generate_backtest_id"),
+    "uuid7": ("gnomepy.utils", "uuid7"),
+}
+
+
+def __getattr__(name: str):
+    if name in _LAZY_IMPORTS:
+        mod_path, attr = _LAZY_IMPORTS[name]
+        mod = importlib.import_module(mod_path)
+        val = getattr(mod, attr)
+        globals()[name] = val
+        return val
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = list(_LAZY_IMPORTS.keys())

{gnomepy-2.2.4 → gnomepy-2.3.0}/gnomepy/cli.py

@@ -170,6 +170,49 @@ def _human_size(n: int) -> str:
     return f"{n:.1f} PB"
 
 
+# ---------------------------------------------------------------------------
+# Import commands
+# ---------------------------------------------------------------------------
+
+@main.group("import")
+def import_cmd() -> None:
+    """Import historical market data from external vendors."""
+
+
+@import_cmd.command("tardis")
+@click.option("--exchange", required=True, help="Tardis exchange name (e.g., binance-futures, deribit)")
+@click.option("--symbols", required=True, help="Comma-separated symbols (e.g., BTCUSDT,ETHUSDT)")
+@click.option("--start", required=True, type=click.DateTime(formats=["%Y-%m-%d"]), help="Start date inclusive")
+@click.option("--end", required=True, type=click.DateTime(formats=["%Y-%m-%d"]), help="End date inclusive")
+@click.option("--dry-run", is_flag=True, help="Validate without uploading to S3")
+@click.option("--bucket", default=None, help="Override S3 bucket")
+def import_tardis(
+    exchange: str,
+    symbols: str,
+    start,
+    end,
+    dry_run: bool,
+    bucket: str | None,
+) -> None:
+    """Import Tardis incremental L2 + trades data as MBP_10 into gnome market data."""
+    from gnomepy.importer.tardis import TardisImporter, TardisImportRequest
+
+    request = TardisImportRequest(
+        exchange=exchange,
+        symbols=[s.strip() for s in symbols.split(",")],
+        start_date=start.date(),
+        end_date=end.date(),
+        bucket=bucket,
+        dry_run=dry_run,
+    )
+    results = TardisImporter().run(request)
+    for r in results:
+        click.echo(f"{r.exchange} / {r.symbol}  (security_id={r.security_id}, exchange_id={r.exchange_id})")
+        click.echo(f"  processed: {r.days_processed}  skipped: {r.days_skipped}  records: {r.total_records}")
+        for err in r.errors:
+            click.echo(f"  error: {err}", err=True)
+
+
 # ---------------------------------------------------------------------------
 # Backtest commands
 # ---------------------------------------------------------------------------

gnomepy-2.3.0/gnomepy/importer/__init__.py

@@ -0,0 +1,10 @@
+from gnomepy.importer.import_job import DryRunResult, ImportJob, ImportResult
+from gnomepy.importer.mapping import FieldMapping, ImportConfig
+
+__all__ = [
+    "FieldMapping",
+    "ImportConfig",
+    "ImportJob",
+    "ImportResult",
+    "DryRunResult",
+]

gnomepy-2.3.0/gnomepy/importer/chunker.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+import pandas as pd
+
+
+def chunk_by_minute(df: pd.DataFrame, ts_ns: pd.Series) -> dict[datetime, pd.DataFrame]:
+    """Split df into per-minute buckets using ts_ns (int64 nanoseconds UTC).
+
+    Returns a dict mapping naive UTC datetime (truncated to minute) → subset of df,
+    sorted by timestamp within each bucket.
+    """
+    _MINUTE_NS = 60_000_000_000
+
+    minute_ns = (ts_ns // _MINUTE_NS) * _MINUTE_NS
+    df = df.copy()
+    df["__ts_ns"] = ts_ns
+    df["__minute_ns"] = minute_ns
+
+    result: dict[datetime, pd.DataFrame] = {}
+    for bucket_ns, group in df.groupby("__minute_ns", sort=True):
+        group = group.sort_values("__ts_ns").drop(columns=["__ts_ns", "__minute_ns"])
+        # Naive UTC datetime matching Java LocalDateTime used in MarketDataEntry
+        dt = datetime.fromtimestamp(int(bucket_ns) / 1e9, tz=timezone.utc).replace(tzinfo=None)
+        result[dt] = group
+
+    return result

gnomepy-2.3.0/gnomepy/importer/encoder.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from gnomepy.importer.mapping import FieldMapping, ImportConfig
+from gnomepy.importer.scaling import parse_timestamp_ns, scale_price, scale_size
+
+
+def _apply_mapping(value, mapping: FieldMapping) -> Any:
+    if pd.isna(value):
+        return None
+    if mapping.transform == "none":
+        return int(value)
+    if mapping.transform == "price":
+        return scale_price(value)
+    if mapping.transform in ("size", "volume"):
+        return scale_size(value)
+    if mapping.transform == "timestamp":
+        return parse_timestamp_ns(value, mapping.timestamp_format, mapping.timestamp_tz)
+    if mapping.transform == "enum":
+        mapped = mapping.enum_map.get(str(value))
+        if mapped is None:
+            raise ValueError(f"enum_map has no entry for value {value!r} in field {mapping.target_field!r}")
+        return mapped
+    raise ValueError(f"Unknown transform {mapping.transform!r} for field {mapping.target_field!r}")
+
+
+def encode_chunk(chunk: pd.DataFrame, config: ImportConfig) -> bytes:
+    """Encode a minute-chunk DataFrame to concatenated SBE bytes.
+
+    Requires the JVM to be started before calling.
+    """
+    from gnomepy.java.schemas import get_schema_class
+
+    schema_cls = get_schema_class(config.schema_type)
+    parts: list[bytes] = []
+
+    for _, row in chunk.iterrows():
+        # Build kwargs: config-level IDs, then defaults, then per-row field mappings
+        kwargs: dict[str, Any] = {
+            "exchange_id": config.exchange_id,
+            "security_id": config.security_id,
+        }
+        kwargs.update(config.defaults)
+        for mapping in config.field_mappings:
+            kwargs[mapping.target_field] = _apply_mapping(row[mapping.source_column], mapping)
+
+        schema = schema_cls(**kwargs)
+        parts.append(schema.encode())
+
+    return b"".join(parts)

gnomepy-2.3.0/gnomepy/importer/import_job.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+import pandas as pd
+
+from gnomepy.importer.chunker import chunk_by_minute
+from gnomepy.importer.encoder import encode_chunk
+from gnomepy.importer.mapping import ImportConfig
+from gnomepy.importer.scaling import apply_timestamp_transform
+from gnomepy.importer.uploader import build_s3_key, compress, default_merged_bucket, upload
+from gnomepy.importer.validators import validate
+
+
+@dataclass
+class ImportResult:
+    files_uploaded: int
+    total_records: int
+    minutes_covered: int
+
+
+@dataclass
+class DryRunResult:
+    is_valid: bool
+    errors: list[str]
+    minutes_count: int
+    total_records: int
+    sample_keys: list[str] = field(default_factory=list)
+
+
+class ImportJob:
+    """Orchestrates converting a CSV/Parquet file into the gnome market data format and uploading to S3."""
+
+    def __init__(self, config: ImportConfig, s3_client=None):
+        self.config = config
+        self._s3 = s3_client
+
+    def _s3_client(self):
+        if self._s3 is None:
+            import boto3
+            self._s3 = boto3.client("s3")
+        return self._s3
+
+    def _load(self, source, file_format: str = "auto") -> pd.DataFrame:
+        if isinstance(source, pd.DataFrame):
+            return source.copy()
+        path = str(source)
+        fmt = file_format
+        if fmt == "auto":
+            fmt = "parquet" if path.endswith(".parquet") else "csv"
+        if fmt == "parquet":
+            return pd.read_parquet(path)
+        return pd.read_csv(path)
+
+    def _timestamp_ns(self, df: pd.DataFrame) -> pd.Series:
+        ts_mapping = next(
+            m for m in self.config.field_mappings if m.target_field == self.config.timestamp_field
+        )
+        return apply_timestamp_transform(
+            df[ts_mapping.source_column], ts_mapping.timestamp_format, ts_mapping.timestamp_tz
+        )
+
+    def _bucket(self) -> str:
+        return self.config.bucket or default_merged_bucket()
+
+    def dry_run(self, source, file_format: str = "auto") -> DryRunResult:
+        """Validate the config and source data without uploading anything."""
+        df = self._load(source, file_format)
+        errors = validate(self.config, df)
+        if errors:
+            return DryRunResult(is_valid=False, errors=errors, minutes_count=0, total_records=0)
+
+        ts_ns = self._timestamp_ns(df)
+        chunks = chunk_by_minute(df, ts_ns)
+        config = self.config
+        sample_keys = [
+            build_s3_key(config.security_id, config.exchange_id, config.schema_type, dt)
+            for dt in sorted(chunks)[:5]
+        ]
+        return DryRunResult(
+            is_valid=True,
+            errors=[],
+            minutes_count=len(chunks),
+            total_records=len(df),
+            sample_keys=sample_keys,
+        )
+
+    def run(self, source, file_format: str = "auto") -> ImportResult:
+        """Encode source data and upload to S3.
+
+        Validates first; raises ValueError if config is invalid.
+        Requires the JVM to be started before calling (for SBE encoding).
+        """
+        from gnomepy.java._jvm import ensure_jvm_started
+
+        df = self._load(source, file_format)
+        errors = validate(self.config, df)
+        if errors:
+            raise ValueError("Import config validation failed:\n" + "\n".join(f"  - {e}" for e in errors))
+
+        ensure_jvm_started()
+        ts_ns = self._timestamp_ns(df)
+        chunks = chunk_by_minute(df, ts_ns)
+
+        bucket = self._bucket()
+        s3 = self._s3_client()
+        files_uploaded = 0
+        total_records = 0
+
+        for minute_dt, chunk_df in sorted(chunks.items()):
+            raw = encode_chunk(chunk_df, self.config)
+            compressed = compress(raw)
+            key = build_s3_key(
+                self.config.security_id,
+                self.config.exchange_id,
+                self.config.schema_type,
+                minute_dt,
+            )
+            upload(s3, bucket, key, compressed)
+            files_uploaded += 1
+            total_records += len(chunk_df)
+
+        return ImportResult(
+            files_uploaded=files_uploaded,
+            total_records=total_records,
+            minutes_covered=len(chunks),
+        )

gnomepy-2.3.0/gnomepy/importer/mapping.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from gnomepy.java.enums import SchemaType
+
+
+@dataclass
+class FieldMapping:
+    """Maps one vendor column to one SBE schema field.
+
+    transform types:
+        "none"      — pass through as int (e.g. a pre-scaled integer field)
+        "price"     — float → int64 * 1e9
+        "size"      — float → int64 * 1e6  (covers size and volume fields)
+        "timestamp" — various formats → int64 nanoseconds since epoch
+        "enum"      — string → string via enum_map (e.g. "buy" → "Bid")
+    """
+
+    source_column: str
+    target_field: str
+    transform: str = "none"
+    # Required when transform="timestamp"
+    timestamp_format: str | None = None  # "epoch_s", "epoch_ms", "epoch_us", "epoch_ns", "iso8601", or strftime
+    timestamp_tz: str | None = None      # tz name for tz-naive string sources, e.g. "US/Eastern"
+    # Required when transform="enum"
+    enum_map: dict[str, str] | None = None
+
+
+@dataclass
+class ImportConfig:
+    """Complete configuration for one import job (one security, exchange, schema type)."""
+
+    schema_type: SchemaType
+    security_id: int
+    exchange_id: int
+    field_mappings: list[FieldMapping]
+    # Which target_field holds the event timestamp used for minute-chunking
+    timestamp_field: str = "timestamp_event"
+    # Override the default merged bucket (gnome-market-data-merged-{STAGE})
+    bucket: str | None = None
+    # Constant values for SBE fields not present in the source data
+    defaults: dict[str, Any] = field(default_factory=dict)

gnomepy-2.3.0/gnomepy/importer/scaling.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import pandas as pd
+
+_PRICE_SCALE = 1_000_000_000
+_SIZE_SCALE = 1_000_000
+
+
+def scale_price(value: float | int) -> int:
+    return int(round(float(value) * _PRICE_SCALE))
+
+
+def scale_size(value: float | int) -> int:
+    return int(round(float(value) * _SIZE_SCALE))
+
+
+def parse_timestamp_ns(value, fmt: str, tz: str | None = None) -> int:
+    """Convert a value to nanoseconds since UTC epoch.
+
+    fmt: "epoch_s", "epoch_ms", "epoch_us", "epoch_ns", "iso8601", or a strftime pattern.
+    tz:  timezone name for tz-naive string sources (e.g. "US/Eastern"). Ignored for epoch formats.
+    """
+    if fmt == "epoch_ns":
+        return int(value)
+    if fmt == "epoch_us":
+        return int(float(value) * 1_000)
+    if fmt == "epoch_ms":
+        return int(float(value) * 1_000_000)
+    if fmt == "epoch_s":
+        return int(float(value) * 1_000_000_000)
+
+    # String / datetime-like formats
+    ts = pd.to_datetime(value, format=None if fmt == "iso8601" else fmt, utc=False)
+    if ts.tzinfo is None and tz is not None:
+        ts = ts.tz_localize(tz).tz_convert("UTC")
+    elif ts.tzinfo is not None:
+        ts = ts.tz_convert("UTC")
+    # pd.Timestamp.value is nanoseconds since epoch
+    return ts.value
+
+
+def apply_price_transform(series: pd.Series) -> pd.Series:
+    return (series.astype(float) * _PRICE_SCALE).round().astype("int64")
+
+
+def apply_size_transform(series: pd.Series) -> pd.Series:
+    return (series.astype(float) * _SIZE_SCALE).round().astype("int64")
+
+
+def apply_timestamp_transform(series: pd.Series, fmt: str, tz: str | None) -> pd.Series:
+    """Vectorized timestamp conversion → int64 nanoseconds since epoch."""
+    if fmt == "epoch_ns":
+        return series.astype("int64")
+    if fmt == "epoch_us":
+        return (series.astype(float) * 1_000).round().astype("int64")
+    if fmt == "epoch_ms":
+        return (series.astype(float) * 1_000_000).round().astype("int64")
+    if fmt == "epoch_s":
+        return (series.astype(float) * 1_000_000_000).round().astype("int64")
+
+    # String-based: use pd.to_datetime then extract ns value
+    fmt_arg = None if fmt == "iso8601" else fmt
+    parsed = pd.to_datetime(series, format=fmt_arg, utc=False)
+    if parsed.dt.tz is None and tz is not None:
+        parsed = parsed.dt.tz_localize(tz).dt.tz_convert("UTC")
+    elif parsed.dt.tz is not None:
+        parsed = parsed.dt.tz_convert("UTC")
+    return parsed.astype("int64")

gnomepy-2.3.0/gnomepy/importer/tardis/__init__.py

@@ -0,0 +1,7 @@
+from gnomepy.importer.tardis.importer import TardisImportRequest, TardisImportResult, TardisImporter
+
+__all__ = [
+    "TardisImportRequest",
+    "TardisImportResult",
+    "TardisImporter",
+]

gnomepy-2.3.0/gnomepy/importer/tardis/book.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+
+class L2Book:
+    """Reconstructs a top-N order book from incremental L2 updates.
+
+    Mirrors the depth computation in the Java MbpBufferBook/Mbp10Book gateways:
+    depth = the shallowest (minimum) level index where the top-N changed.
+    Returns None when the update falls entirely outside the top-N visible levels.
+    """
+
+    NUM_LEVELS = 10
+
+    def __init__(self) -> None:
+        self._bids: dict[float, float] = {}
+        self._asks: dict[float, float] = {}
+        self._top_bids: list[tuple[float, float]] = []
+        self._top_asks: list[tuple[float, float]] = []
+
+    def clear(self) -> None:
+        self._bids.clear()
+        self._asks.clear()
+        self._top_bids = []
+        self._top_asks = []
+
+    def update(self, side: str, price: float, amount: float) -> int | None:
+        """Apply one L2 update. Returns depth if the top-N changed, else None."""
+        book = self._bids if side == "bid" else self._asks
+        if amount == 0.0:
+            book.pop(price, None)
+        else:
+            book[price] = amount
+
+        new_bids = sorted(self._bids.items(), reverse=True)[: self.NUM_LEVELS]
+        new_asks = sorted(self._asks.items())[: self.NUM_LEVELS]
+
+        depth = self._shallowest_change(self._top_bids, new_bids, self._top_asks, new_asks)
+
+        self._top_bids = new_bids
+        self._top_asks = new_asks
+        return depth
+
+    def top_levels(self) -> tuple[list[tuple[float, float]], list[tuple[float, float]]]:
+        """Return (top_bids, top_asks) as lists of (price, amount), sorted best-first."""
+        return self._top_bids, self._top_asks
+
+    def _shallowest_change(
+        self,
+        prev_bids: list[tuple[float, float]],
+        new_bids: list[tuple[float, float]],
+        prev_asks: list[tuple[float, float]],
+        new_asks: list[tuple[float, float]],
+    ) -> int | None:
+        for i in range(self.NUM_LEVELS):
+            prev_bid = prev_bids[i] if i < len(prev_bids) else None
+            new_bid = new_bids[i] if i < len(new_bids) else None
+            prev_ask = prev_asks[i] if i < len(prev_asks) else None
+            new_ask = new_asks[i] if i < len(new_asks) else None
+            if prev_bid != new_bid or prev_ask != new_ask:
+                return i
+        return None

gnomepy-2.3.0/gnomepy/importer/tardis/client.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import os
+from datetime import date, timedelta
+from pathlib import Path
+
+
+class TardisClient:
+    """Thin wrapper around the tardis-dev Python package for downloading market data CSV files."""
+
+    def __init__(self, api_key: str | None = None):
+        try:
+            import tardis_dev  # noqa: F401
+        except ImportError:
+            raise ImportError(
+                "tardis-dev is required for Tardis market data imports. "
+                "Install it with: poetry install -E tardis"
+            )
+        self._api_key = api_key or os.environ.get("TARDIS_API_KEY", "")
+
+    def download(
+        self,
+        exchange: str,
+        data_types: list[str],
+        day: date,
+        symbols: list[str],
+        dest_dir: Path,
+    ) -> None:
+        """Download all data_types for a single day to dest_dir.
+
+        Uses tardis-dev's download_datasets which handles auth, retries, and file naming.
+        """
+        from tardis_dev import download_datasets
+
+        from_date = day.strftime("%Y-%m-%d")
+        to_date = (day + timedelta(days=1)).strftime("%Y-%m-%d")
+
+        download_datasets(
+            exchange=exchange,
+            data_types=data_types,
+            from_date=from_date,
+            to_date=to_date,
+            symbols=symbols,
+            api_key=self._api_key,
+            download_dir=str(dest_dir),
+        )
+
+    def get_exchange_details(self, exchange: str) -> dict:
+        """Return exchange metadata from the Tardis API (available symbols, date ranges)."""
+        from tardis_dev import get_exchange_details
+        return get_exchange_details(exchange)