Qubx 3.22.1__tar.gz → 4.0.0.dev1__tar.gz

{qubx-3.22.1 → qubx-4.0.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: Qubx
-Version: 3.22.1
+Version: 4.0.0.dev1
 Summary: Qubx - Quantitative Trading Framework
 Project-URL: homepage, https://xlydian.com
 Project-URL: repository, https://github.com/xLydianSoftware/Qubx
@@ -34,7 +34,6 @@ Requires-Dist: psycopg<4,>=3.1.18
 Requires-Dist: pyarrow>=15.0.0
 Requires-Dist: pydantic-settings<3,>=2.4.0
 Requires-Dist: pydantic<3,>=2.9.2
-Requires-Dist: pymongo<5,>=4.6.1
 Requires-Dist: python-dotenv<2,>=1.0.0
 Requires-Dist: pyyaml<7,>=6.0.2
 Requires-Dist: questdb<3,>=2.0.3

{qubx-3.22.1 → qubx-4.0.0.dev1}/pyproject.toml

@@ -62,7 +62,6 @@ dependencies = [
     "statsmodels>=0.14.6,<0.15",
 
     # - - - Database backends - - - 
-    "pymongo>=4.6.1,<5",
     "redis>=5.2.1,<6",
     "psycopg>=3.1.18,<4",
     "psycopg-binary>=3.1.19,<4",
@@ -177,7 +176,6 @@ dev = [
     "pytest-cov>=4.1.0,<5",
     "pytest-xdist>=3.6.1,<4",
     "pytest-textual-snapshot>=1.1.0,<2",
-    "mongomock>=4.3.0,<5",
     "pyiceberg[pyarrow,sql-sqlite,pyiceberg-core]==0.12.0",
 
     # - - - Linting & formatting - - - 

{qubx-3.22.1 → qubx-4.0.0.dev1}/src/qubx/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '3.22.1'
-__version_tuple__ = version_tuple = (3, 22, 1)
+__version__ = version = '4.0.0.dev1'
+__version_tuple__ = version_tuple = (4, 0, 0, 'dev1')
 
 __commit_id__ = commit_id = None

{qubx-3.22.1 → qubx-4.0.0.dev1}/src/qubx/backtester/simulator.py

@@ -259,13 +259,13 @@ def _run_setup(
         # Adjust the start date for the simulation to the onboard date of the instrument with the minimum onboard date.
         # TODO: this can be removed once we add some artificial data stream to move the simulation
         if setup.setup_type in [SetupTypes.SIGNAL, SetupTypes.SIGNAL_AND_TRACKER]:
-            onboard_dates = [
-                to_utc_naive(to_timestamp(instrument.onboard_date))
+            listed_dates = [
+                to_utc_naive(to_timestamp(instrument.listed_at))
                 for instrument in setup.instruments
-                if instrument.onboard_date is not None
+                if instrument.listed_at is not None
             ]
-            if onboard_dates:
-                start = max(start, min(onboard_dates))
+            if listed_dates:
+                start = max(start, min(listed_dates))
 
         runner = SimulationRunner(
             setup=setup,

{qubx-3.22.1 → qubx-4.0.0.dev1}/src/qubx/config.py

@@ -22,7 +22,7 @@ from functools import lru_cache
 from pathlib import Path
 from typing import Any, ClassVar
 
-from pydantic import BaseModel
+from pydantic import BaseModel, field_validator
 from pydantic_settings import BaseSettings, PydanticBaseSettingsSource
 
 
@@ -47,8 +47,18 @@ class IcebergAccount(BaseModel):
 class LookupConfig(BaseModel):
     """Configuration for instrument/fees lookups."""
 
-    type: str = "file"
-    mongo_url: str | None = None
+    type: str = "file"  # "file" or "service"
+    url: str | None = None  # instrument-service base, e.g. http://control-api.platform.svc/internal/instrument-service
+    token: str | None = None  # bearer token for the gateway route
+    exchanges: list[str] | None = None  # service: snapshot only these exchanges (env: JSON list or comma-separated)
+
+    @field_validator("exchanges", mode="before")
+    @classmethod
+    def _split_exchanges(cls, v: Any) -> Any:
+        if isinstance(v, str):
+            return [e.strip() for e in v.split(",") if e.strip()]
+        return v
+
     reload_interval: str | None = None
     path: str | None = None
 

{qubx-3.22.1 → qubx-4.0.0.dev1}/src/qubx/connectors/ccxt/utils.py

@@ -318,8 +318,7 @@ def ccxt_convert_position(info: dict, ccxt_exchange_name: str, markets: dict[str
             pos.update_market_price(_pts, info["markPrice"], 1)
 
     # Use exchange-provided margins when reported — only the venue knows the configured leverage
-    # tier. The internal fallback cannot: with no instrument.initial_margin metadata (0.0 on
-    # BINANCE.UM) it yields 0.0, and with metadata it applies a static ratio that ignores the tier.
+    # tier. The internal fallback yields 0.0 initial margin and a flat maintenance rate.
     if info.get("maintenanceMargin") is not None:
         pos.set_external_maint_margin(float(info["maintenanceMargin"]))
 

{qubx-3.22.1 → qubx-4.0.0.dev1}/src/qubx/core/account_manager/config.py

@@ -1,5 +1,7 @@
 from dataclasses import dataclass
 
+from qubx.core.basics import DEFAULT_MAINTENANCE_MARGIN
+
 
 @dataclass
 class AccountManagerConfig:
@@ -21,3 +23,5 @@ class AccountManagerConfig:
 
     terminal_order_retention_ms: int = 30_000
     terminal_order_history_size: int = 10_000
+
+    maint_margin_rate: float = DEFAULT_MAINTENANCE_MARGIN  # - framework-computed maintenance margin (fraction of notional) when the venue reports none

{qubx-3.22.1 → qubx-4.0.0.dev1}/src/qubx/core/account_manager/manager.py

@@ -161,6 +161,7 @@ class AccountManager(IAccountViewer, IAccountConfigurator):
                 exchange=ex,
                 base_currency=base_currencies[ex],
                 terminal_history_size=self._cfg.terminal_order_history_size,
+                maint_margin_rate=self._cfg.maint_margin_rate,
             )
             for ex in connectors
         }

{qubx-3.22.1 → qubx-4.0.0.dev1}/src/qubx/core/account_manager/state.py

@@ -19,7 +19,16 @@ from dataclasses import dataclass
 import numpy as np
 
 from qubx import logger
-from qubx.core.basics import STABLE_CURRENCIES, Balance, Deal, Instrument, Order, OrderStatus, Position
+from qubx.core.basics import (
+    DEFAULT_MAINTENANCE_MARGIN,
+    STABLE_CURRENCIES,
+    Balance,
+    Deal,
+    Instrument,
+    Order,
+    OrderStatus,
+    Position,
+)
 
 # Bounded per-exchange funding-bucket dedup (insertion order ≈ funding-event time order):
 # old buckets evict once the cap is hit so the set can't grow unbounded over long-running
@@ -57,6 +66,7 @@ class AccountState:
     __slots__ = (
         "exchange",
         "base_currency",
+        "maint_margin_rate",
         "_active_orders",
         "_positions",
         "_balances",
@@ -77,9 +87,17 @@ class AccountState:
         "_position_deal_booked_at",
     )
 
-    def __init__(self, exchange: str, base_currency: str, *, terminal_history_size: int = 10_000):
+    def __init__(
+        self,
+        exchange: str,
+        base_currency: str,
+        *,
+        terminal_history_size: int = 10_000,
+        maint_margin_rate: float = DEFAULT_MAINTENANCE_MARGIN,
+    ):
         self.exchange: str = exchange
         self.base_currency: str = base_currency.upper()
+        self.maint_margin_rate: float = maint_margin_rate
 
         # ---- primary data ------------------------------------------------
         self._active_orders: dict[str, Order] = {}  # client_order_id -> Order
@@ -471,6 +489,7 @@ class AccountState:
         # the framework hold references to it), never swapped for a new object.
         existing = self._positions.get(instrument)
         if existing is None:
+            position.maint_margin_rate = self.maint_margin_rate
             self._positions[instrument] = position
         else:
             existing.reset_by_position(position)
@@ -645,6 +664,7 @@ class AccountState:
         pos = self._positions.get(instrument)
         if pos is None:
             pos = Position(instrument=instrument)
+            pos.maint_margin_rate = self.maint_margin_rate
             self._positions[instrument] = pos
         return pos
 

{qubx-3.22.1 → qubx-4.0.0.dev1}/src/qubx/core/basics.py

@@ -1,8 +1,8 @@
 import re
-from dataclasses import dataclass, field
+from dataclasses import KW_ONLY, dataclass, field
 from datetime import datetime
 from enum import StrEnum
-from functools import cache
+from functools import cache, total_ordering
 from queue import Empty, Queue
 from threading import Event
 from typing import Any, Literal, TypeAlias
@@ -347,10 +347,47 @@ def multiplier_coin(base: str) -> str:
     return base
 
 
-@dataclass(order=True)
+class AssetKind(StrEnum):
+    CRYPTO = "CRYPTO"
+    EQUITY = "EQUITY"
+    ETF = "ETF"
+    INDEX = "INDEX"
+    COMMODITY = "COMMODITY"
+    FX = "FX"
+    EVENT = "EVENT"
+
+
+@dataclass(frozen=True)
+class Underlying:
+    """What a listing is a contract on: (kind, code) is its identity, e.g. (EQUITY, NVDA.XNAS), (CRYPTO, PEPE)."""
+
+    kind: AssetKind
+    code: str
+
+    def __post_init__(self):
+        object.__setattr__(self, "kind", AssetKind(self.kind))
+
+    def __str__(self) -> str:
+        return f"{self.kind}:{self.code}"
+
+
+class VenueAttributes(dict):
+    """Read-only venue labels (Binance contractType, HL dex, ...): filter on them, never branch."""
+
+    def _readonly(self, *args, **kwargs):
+        raise TypeError("venue_attributes is read-only")
+
+    __setitem__ = __delitem__ = clear = pop = popitem = setdefault = update = __ior__ = _readonly  # type: ignore
+
+    def __reduce__(self):
+        return (VenueAttributes, (dict(self),))
+
+
+@total_ordering
+@dataclass(eq=False)
 class Instrument:
     """
-    Instrument class.
+    A tradable listing: identity (eq/hash/str) is (exchange, market_type, symbol).
 
      - 2025-06-11: Important change for FUTURE type: now instrument's symbol contains delivery date in format YYYYMMDD.
         So now for let's say september's BTCUSDT future, symbol would be BTCUSD.20250914
@@ -368,24 +405,28 @@ class Instrument:
     lot_size: float  # minimal position size
     min_size: float  # minimal allowed position size
     min_notional: float = 0.0  # minimal notional value
-    initial_margin: float = 0.0  # initial margin
-    maint_margin: float = 0.0  # maintenance margin
-    liquidation_fee: float = 0.0  # liquidation fee
-    contract_size: float = 1.0  # contract size (tokens per contract)
-    contract_multiplier: float = 1.0  # contract multiplier (additional multiplier, always 1 for crypto)
-    onboard_date: datetime | None = None  # date when instrument was listed on the exchange
-    delivery_date: datetime | None = None  # date when instrument is delivered
-    delist_date: datetime | None = None  # date when instrument is delisted
-    inverse: bool = False  # if true, then the future is inverse
+    _: KW_ONLY
+    contract_size: float = 1.0  # quantity per contract: base units (linear) or quote units (inverse)
+    inverse: bool = False
+    listing_id: str | None = None  # instrument-service listing id, stable through renames
+    underlying: Underlying | None = None
+    calendar: str | None = None  # when this listing trades: "24/7", a MIC ("XNAS") or None
+    expiry: datetime | None = None
+    strike: float | None = None
+    option_right: str | None = None  # CALL / PUT
+    listed_at: datetime | None = None
+    delisted_at: datetime | None = None  # a future value is a scheduled delisting
+    margin_tradable: bool = False
+    venue_attributes: VenueAttributes = field(default_factory=VenueAttributes)
 
     def __post_init__(self):
-        # define how ordering works
-        object.__setattr__(self, "sort_index", f"{self.exchange}:{self.market_type}:{self.symbol}")
+        if not isinstance(self.venue_attributes, VenueAttributes):
+            self.venue_attributes = VenueAttributes(self.venue_attributes or {})
 
     @property
     def quantity_multiplier(self) -> float:
-        """Combined multiplier: contract_size * contract_multiplier. Multiply contracts by this to get token quantity."""
-        return self.contract_size * self.contract_multiplier
+        """Multiply contracts by this to get token quantity (alias of contract_size)."""
+        return self.contract_size
 
     @property
     def price_precision(self):
@@ -401,8 +442,15 @@ class Instrument:
 
     @property
     def asset(self) -> str:
+        """The venue coin, multiplier stripped (1000PEPE -> PEPE): a function of the listing alone, so
+        connector-built and lookup-built instruments agree. Economic exposure is `exposure_code`."""
         return multiplier_coin(self.base)
 
+    @property
+    def exposure_code(self) -> str:
+        """What the listing is a contract on (NVDA.XNAS for a bStock, XAU for PAXG); `asset` when the underlying is unknown."""
+        return self.underlying.code if self.underlying is not None else self.asset
+
     def is_futures(self) -> bool:
         return self.market_type in [MarketType.FUTURE, MarketType.SWAP]
 
@@ -521,6 +569,11 @@ class Instrument:
             return False
         return str(self) == str(other)
 
+    def __lt__(self, other: "Instrument") -> bool:
+        if not isinstance(other, Instrument):
+            return NotImplemented
+        return (self.symbol, self.market_type, self.exchange) < (other.symbol, other.market_type, other.exchange)
+
     def __str__(self) -> str:
         return ":".join([self.exchange, self.market_type, self.symbol])
 
@@ -574,11 +627,10 @@ class Instrument:
   Min Size:          {self.min_size}
   Min Notional:      {self.min_notional}
   Contract Size:     {self.contract_size}
-  Contract Mult:     {self.contract_multiplier}
-  Initial Margin:    {self.initial_margin}
-  Maint. Margin:     {self.maint_margin}
-  Onboard Date:      {self.onboard_date}
-  Delist Date:       {self.delist_date}
+  Underlying:        {self.underlying}
+  Calendar:          {self.calendar}
+  Listed At:         {self.listed_at}
+  Delisted At:       {self.delisted_at}
 """
         print(info_str)
 
@@ -1186,6 +1238,7 @@ class Position:
     _initial_margin_external: bool = False  # If True, initial_margin is managed by exchange (skip recalculation)
     maint_margin: float = 0.0
     _maint_margin_external: bool = False  # If True, maint_margin is managed by exchange (skip recalculation)
+    maint_margin_rate: float = DEFAULT_MAINTENANCE_MARGIN  # fraction of notional, set from the account config
 
     # ADL queue position from the exchange (None if not reported).
     # Lower values = more likely to be auto-deleveraged.
@@ -1711,8 +1764,9 @@ class Position:
         # Only apply maintenance margin for leveraged instruments (futures/swaps)
         # Spot positions don't have margin requirements since you own the actual asset
         if self.instrument.is_futures():
-            maint_margin = self.instrument.maint_margin or DEFAULT_MAINTENANCE_MARGIN
-            self.maint_margin = maint_margin * abs(self.quantity) * self._qty_multiplier * self.last_update_price
+            self.maint_margin = (
+                self.maint_margin_rate * abs(self.quantity) * self._qty_multiplier * self.last_update_price
+            )
         else:
             self.maint_margin = 0.0
 
@@ -1727,17 +1781,9 @@ class Position:
         if self._initial_margin_external:
             return
 
-        # Only apply initial margin for leveraged instruments (futures/swaps).
-        # Use the per-asset initial_margin fraction from instrument metadata when
-        # populated; otherwise leave at 0.0 (the framework can't infer a sensible
-        # default without the per-instrument leverage setting, which lives on
-        # the account processor).
-        if self.instrument.is_futures() and self.instrument.initial_margin > 0:
-            self.initial_margin = (
-                self.instrument.initial_margin * abs(self.quantity) * self._qty_multiplier * self.last_update_price
-            )
-        else:
-            self.initial_margin = 0.0
+        # Without a venue-reported value the framework can't infer one: it depends on the
+        # per-instrument leverage setting, which lives on the account processor.
+        self.initial_margin = 0.0
 
 
 VENUE_SETTINGS_EVENT = "venue_settings"
@@ -2094,24 +2140,24 @@ class InstrumentsLookup:
             i
             for i in self.get_lookup().values()
             if i.exchange == exchange
-            and (base is None or i.base == base or multiplier_coin(i.base) == base)
+            and (base is None or i.base == base or i.asset == base)
             and (quote is None or i.quote == quote)
             and (market_type is None or i.market_type == market_type)
             and (
                 _limit_time is None
-                or (i.onboard_date is None or pd.Timestamp(i.onboard_date).tz_localize(None) <= _limit_time)
+                or (i.listed_at is None or pd.Timestamp(i.listed_at).tz_localize(None) <= _limit_time)
             )
             and (
                 _limit_time is None
-                or (i.delist_date is None or pd.Timestamp(i.delist_date).tz_localize(None) >= _limit_time)
+                or (i.delisted_at is None or pd.Timestamp(i.delisted_at).tz_localize(None) >= _limit_time)
             )
         ]
         if base is not None:
             aliases = sorted({i.base for i in matched} - {base})
             if aliases and any(i.base == base for i in matched):
                 logger.warning(
-                    f"[lookup] {exchange} base <y>{base}</y> also matches {aliases} through a contract "
-                    f"multiplier; the exact base is listed first — pass the venue base to disambiguate"
+                    f"[lookup] {exchange} <y>{base}</y> is ambiguous: it also names the multiplier contracts "
+                    f"{aliases}; exact-base matches come first, pass a venue base (e.g. 1000{base}) to select one"
                 )
                 matched.sort(key=lambda i: i.base != base)
         return matched

{qubx-3.22.1 → qubx-4.0.0.dev1}/src/qubx/core/detectors/delisting.py

@@ -38,11 +38,11 @@ class DelistingDetector:
 
         delisting = []
         for instrument in instruments:
-            if instrument.delist_date is None:
+            if instrument.delisted_at is None:
                 continue
 
             try:
-                delist_timestamp = to_timestamp(instrument.delist_date).replace(tzinfo=None)
+                delist_timestamp = to_timestamp(instrument.delisted_at).replace(tzinfo=None)
                 if bool(pd.isna(delist_timestamp)):
                     continue
 
@@ -73,7 +73,7 @@ class DelistingDetector:
 
         # Log instruments being filtered out
         for instrument in delisting_instruments:
-            self._info(f"Filtering out {instrument.symbol} - delisting on {instrument.delist_date}")
+            self._info(f"Filtering out {instrument.symbol} - delisting on {instrument.delisted_at}")
 
         # Return instruments that are NOT in the delisting set
         return [instrument for instrument in instruments if instrument not in delisting_set]

{qubx-3.22.1 → qubx-4.0.0.dev1}/src/qubx/core/interfaces.py

@@ -516,11 +516,10 @@ class IAccountViewer:
         In live this is the venue-reported figure when the venue provides one
         (e.g. Binance ``availableBalance``); otherwise it derives as
         ``total_capital - total_initial_margin``. For an accurate derivation,
-        the connector must populate ``Position.initial_margin`` either via
+        the connector must populate ``Position.initial_margin`` via
         ``set_external_initial_margin(...)`` from venue data (e.g. HPL
-        ``marginUsed``) or via ``instrument.initial_margin`` in the metadata.
-        Connectors that populate neither will see this method return the full
-        capital.
+        ``marginUsed``). Connectors that don't will see this method return the
+        full capital.
 
         Returns:
             float: Available balance
@@ -2665,7 +2664,7 @@ class IStrategyInitializer:
         """
         Set the number of days ahead to check for delisting.
 
-        When an instrument has a delist_date set, this configuration determines how many
+        When an instrument has a delisted_at set, this configuration determines how many
         days before the delisting date the framework should:
         1. Filter the instrument out from universe updates
         2. Close positions and remove the instrument during the daily delisting check