quantrail 0.1.0__py3-none-any.whl

quantrail/__init__.py

@@ -0,0 +1,17 @@
+"""QuantRail: quantitative research you can trust.
+
+Importing QuantRail never downloads data, writes files or contacts a broker.
+"""
+
+from .backtest import BacktestResult, backtest
+from .core import UNKNOWN, Declaration, Instrument, Money, PriceBasis, Provenance, TrustReport
+from .datasets import export_dataset, ingest, list_versions, load_dataset
+from .research.trials import TrialRegistry
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "UNKNOWN", "BacktestResult", "Declaration", "Instrument", "Money", "PriceBasis", "Provenance",
+    "TrialRegistry", "TrustReport", "backtest", "export_dataset", "ingest", "list_versions",
+    "load_dataset",
+]

quantrail/accounting/__init__.py

@@ -0,0 +1 @@
+"""Accounting: ledger and settlement."""

quantrail/accounting/ledger.py

@@ -0,0 +1,159 @@
+"""Multi-currency ledger with Decimal quantities and settlement-dated cash.
+
+Positions change when a fill is booked; cash changes only when an obligation settles.
+Receivables (unsettled sales, declared dividends) count towards net asset value but
+are never spendable. Buying power is the lowest projected cash balance over future
+settlement dates, so an order can never be funded by money that arrives later.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass
+from datetime import date
+from decimal import Decimal
+
+from ..core import Instrument, to_decimal
+
+ZERO = Decimal("0")
+
+
+class InsufficientCash(RuntimeError):
+    """An order or settlement would need cash the account does not have."""
+
+
+@dataclass(frozen=True)
+class Obligation:
+    settles_on: date
+    currency: str
+    amount: Decimal  # positive: receivable, negative: payable
+    reference: str
+
+
+@dataclass(frozen=True)
+class Fill:
+    instrument: Instrument
+    side: str  # "BUY" or "SELL"
+    quantity: Decimal
+    price: Decimal
+    trade_date: date
+    settles_on: date
+    commission: Decimal = ZERO
+    tax: Decimal = ZERO
+    reference: str = ""
+
+    @property
+    def value(self) -> Decimal:
+        return self.quantity * self.price
+
+    @property
+    def cash_delta(self) -> Decimal:
+        fees = self.commission + self.tax
+        return -(self.value + fees) if self.side == "BUY" else self.value - fees
+
+
+@dataclass(frozen=True)
+class CashSnapshot:
+    currency: str
+    settled: Decimal
+    receivable: Decimal
+    payable: Decimal
+
+    @property
+    def net(self) -> Decimal:
+        return self.settled + self.receivable - self.payable
+
+
+class Ledger:
+    def __init__(self, cash: dict[str, object]):
+        self._cash = {ccy: to_decimal(v, f"cash[{ccy}]") for ccy, v in cash.items()}
+        if any(v < 0 for v in self._cash.values()):
+            raise ValueError("Initial cash must be non-negative.")
+        self._positions: dict[str, Decimal] = defaultdict(lambda: ZERO)
+        self._pending: dict[str, Obligation] = {}
+        self.journal: list[dict] = []
+
+    # Queries -----------------------------------------------------------------
+    def position(self, instrument_id: str) -> Decimal:
+        return self._positions.get(instrument_id, ZERO)
+
+    def snapshot(self, currency: str) -> CashSnapshot:
+        pending = [o for o in self._pending.values() if o.currency == currency]
+        return CashSnapshot(currency, self._cash.get(currency, ZERO),
+                            sum((o.amount for o in pending if o.amount > 0), ZERO),
+                            -sum((o.amount for o in pending if o.amount < 0), ZERO))
+
+    def buying_power(self, currency: str) -> Decimal:
+        """Lowest projected settled cash over the pending settlement dates."""
+        projected = lowest = self._cash.get(currency, ZERO)
+        by_date: dict[date, Decimal] = defaultdict(lambda: ZERO)
+        for o in self._pending.values():
+            if o.currency == currency:
+                by_date[o.settles_on] += o.amount
+        for day in sorted(by_date):
+            projected += by_date[day]
+            lowest = min(lowest, projected)
+        return lowest
+
+    # Events ------------------------------------------------------------------
+    def _add_obligation(self, obligation: Obligation) -> None:
+        if obligation.reference in self._pending:
+            raise ValueError(f"Duplicate obligation reference {obligation.reference}")
+        self._pending[obligation.reference] = obligation
+
+    def book_fill(self, fill: Fill) -> None:
+        q = fill.instrument.validate_quantity(fill.quantity)
+        if q == 0:
+            raise ValueError("A fill needs a positive quantity.")
+        if fill.side not in {"BUY", "SELL"}:
+            raise ValueError(f"Unknown side {fill.side!r}")
+        currency = fill.instrument.quote_currency
+        if fill.side == "SELL" and q > self.position(fill.instrument.id):
+            raise ValueError("Sell exceeds position; short selling is not modelled.")
+        if fill.side == "BUY" and -fill.cash_delta > self.buying_power(currency):
+            raise InsufficientCash(f"Buy of {-fill.cash_delta} {currency} exceeds buying power.")
+        self._positions[fill.instrument.id] += q if fill.side == "BUY" else -q
+        self._add_obligation(Obligation(fill.settles_on, currency, fill.cash_delta, f"fill:{fill.reference}"))
+        self.journal.append({"type": "FILL", "date": fill.trade_date, "instrument": fill.instrument.id,
+                             "side": fill.side, "quantity": q, "price": fill.price,
+                             "commission": fill.commission, "tax": fill.tax, "settles_on": fill.settles_on})
+
+    def entitle_cash_dividend(self, instrument: Instrument, per_unit, ex_date: date, payment_date: date,
+                              reference: str) -> Decimal:
+        """Entitlement on units held at the close before ex_date; cash arrives on payment_date."""
+        amount = self.position(instrument.id) * to_decimal(per_unit, "per_unit")
+        if amount > 0:
+            self._add_obligation(Obligation(payment_date, instrument.quote_currency, amount,
+                                            f"div:{reference}"))
+        self.journal.append({"type": "DIVIDEND_ENTITLEMENT", "date": ex_date, "instrument": instrument.id,
+                             "units": self.position(instrument.id), "per_unit": per_unit, "amount": amount,
+                             "payment_date": payment_date})
+        return amount
+
+    def split(self, instrument: Instrument, new_per_old, effective: date) -> Decimal:
+        ratio = to_decimal(new_per_old, "split ratio")
+        if ratio <= 0:
+            raise ValueError("Split ratio must be positive.")
+        old = self.position(instrument.id)
+        new = old * ratio
+        if new != instrument.floor_quantity(new) and new != 0:
+            raise ValueError("Fractional split entitlement needs an explicit cash-in-lieu event.")
+        self._positions[instrument.id] = new
+        self.journal.append({"type": "SPLIT", "date": effective, "instrument": instrument.id,
+                             "before": old, "after": new})
+        return new
+
+    def settle_through(self, day: date) -> list[Obligation]:
+        due = sorted((o for o in self._pending.values() if o.settles_on <= day),
+                     key=lambda o: (o.settles_on, o.reference))
+        projected = dict(self._cash)
+        for o in due:
+            projected[o.currency] = projected.get(o.currency, ZERO) + o.amount
+            if projected[o.currency] < 0:
+                raise InsufficientCash(f"Cannot settle {o.reference} on {o.settles_on}.")
+        self._cash = projected
+        for o in due:
+            del self._pending[o.reference]
+            self.journal.append({"type": "SETTLEMENT", "date": o.settles_on, "currency": o.currency,
+                                 "amount": o.amount, "reference": o.reference})
+        return due

quantrail/backtest.py

@@ -0,0 +1,116 @@
+"""One-call backtest from an ingested dataset, with the trust report attached.
+
+This adapter turns a dataset produced by `ingest()` into the engine's tables and adds
+the caveats that come from the data itself:
+
+- no open prices: fills use the next session's close (EXECUTION_NEXT_CLOSE_PROXY);
+- sessions inferred from the price dates (CALENDAR_FROM_PRICES): exchange holidays and
+  suspensions without a row cannot be told apart;
+- total-return prices together with dividend events would count dividends twice and
+  are refused.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import pandas as pd
+
+from .core import Instrument, PriceBasis, Severity, TrustFlag, TrustReport
+from .datasets import Dataset
+from .engine import Result, run_target_weights
+from .stats import metrics
+
+ACTION_COLUMNS = {"action_id", "action_type", "effective_date", "ex_date", "payment_date",
+                  "split_new_per_old", "cash_per_entitled_unit"}
+
+
+@dataclass
+class BacktestResult:
+    result: Result
+    trust: TrustReport
+    summary: dict
+
+    @property
+    def daily(self) -> pd.DataFrame:
+        return self.result.daily
+
+    @property
+    def orders(self) -> pd.DataFrame:
+        return self.result.orders
+
+    @property
+    def events(self) -> pd.DataFrame:
+        return self.result.events
+
+    def report(self) -> str:
+        lines = [self.trust.render(), "", "Summary:"]
+        for key in ("start", "end", "final_nav", "cagr", "annual_volatility", "sharpe", "max_drawdown"):
+            value = self.summary[key]
+            lines.append(f"  {key}: {value:.4f}" if isinstance(value, float) else f"  {key}: {value}")
+        return "\n".join(lines)
+
+
+def _sessions(n: int):
+    """Settlement helper: T+n on the dataset's own sessions."""
+    def make(sessions):
+        ordered = sorted(sessions)
+
+        def settle(day):
+            if n == 0:
+                return day
+            future = [s for s in ordered if s > day]
+            if len(future) < n:
+                # Beyond the data: settle n calendar days later; affects only the last sessions.
+                return day + pd.Timedelta(n, unit="D").to_pytimedelta()
+            return future[n - 1]
+        return settle
+    return make
+
+
+def backtest(dataset: Dataset, *, instrument: Instrument, costs, capital, initial_target=1.0,
+             decisions=None, no_trade_band=0.0, slippage_bps=0.0, settlement_lag=0,
+             start=None, end=None) -> BacktestResult:
+    """Run a target-weight backtest of one instrument on an ingested dataset."""
+    prices = dataset.tables["prices"]
+    if prices["instrument"].nunique() != 1:
+        raise ValueError("backtest() handles one instrument per dataset for now.")
+    flags = []
+    table = pd.DataFrame({"session_date": pd.to_datetime(prices["date"]),
+                          "close": prices["close"].astype(float),
+                          "quote_valid": prices["quote_valid"].astype(bool)})
+    if "open" in prices:
+        table["open"] = prices["open"].astype(float)
+    else:
+        table["open"] = table["close"]
+        flags.append(TrustFlag("EXECUTION_NEXT_CLOSE_PROXY", Severity.WARNING,
+                               "No open prices: orders fill at the next session's close."))
+    calendar = pd.DataFrame({"session_date": table["session_date"], "asset_tradable": True, "reason": ""})
+    flags.append(TrustFlag("CALENDAR_FROM_PRICES", Severity.INFO,
+                           "Sessions are inferred from price dates; missing sessions cannot be detected."))
+
+    actions = dataset.tables.get("corporate_actions")
+    if actions is None:
+        actions = pd.DataFrame(columns=sorted(ACTION_COLUMNS))
+    else:
+        missing = ACTION_COLUMNS - set(actions.columns)
+        if missing:
+            raise ValueError(f"corporate_actions is missing columns: {sorted(missing)}")
+        actions = actions.copy()
+        for column in ("effective_date", "ex_date", "payment_date"):
+            actions[column] = pd.to_datetime(actions[column])
+        has_dividends = (actions["action_type"] == "CASH_DISTRIBUTION").any()
+        if dataset.declaration.price_basis is PriceBasis.TOTAL_RETURN and has_dividends:
+            raise ValueError("Total-return prices already include dividends; supplying dividend events "
+                             "too would count them twice.")
+
+    first, last = table["session_date"].min(), table["session_date"].max()
+    start, end = pd.Timestamp(start) if start else first, pd.Timestamp(end) if end else last
+    sessions = [d.date() for d in table["session_date"]]
+    result = run_target_weights(
+        instrument=instrument, costs=costs, settle=_sessions(settlement_lag)(sessions),
+        prices=table, calendar=calendar, actions=actions, start=start, end=end, capital=capital,
+        initial_target=initial_target, decisions=decisions, no_trade_band=no_trade_band,
+        slippage_bps=slippage_bps, label=dataset.dataset_id)
+    trust = dataset.trust.merge(TrustReport(tuple(flags)))
+    return BacktestResult(result, trust, metrics.summary(result.daily["nav"], float(capital)))

quantrail/core.py

@@ -0,0 +1,218 @@
+"""Core types shared by every layer: provenance, declarations, trust flags, instruments, money.
+
+Nothing here knows about a particular market. See docs/adr/0002 and docs/adr/0003.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from decimal import Decimal, InvalidOperation
+from enum import StrEnum
+
+UNKNOWN = "unknown"
+
+
+class Severity(StrEnum):
+    INFO = "info"
+    WARNING = "warning"
+    BLOCKING = "blocking"
+
+
+@dataclass(frozen=True)
+class TrustFlag:
+    """A machine-readable caveat that travels with a dataset into every result."""
+
+    code: str
+    severity: Severity
+    message: str
+
+
+@dataclass(frozen=True)
+class TrustReport:
+    flags: tuple[TrustFlag, ...] = ()
+
+    @property
+    def clean(self) -> bool:
+        return not self.flags
+
+    @property
+    def blocking(self) -> tuple[TrustFlag, ...]:
+        return tuple(f for f in self.flags if f.severity is Severity.BLOCKING)
+
+    def merge(self, *others: TrustReport) -> TrustReport:
+        seen = {f.code: f for f in self.flags}
+        for other in others:
+            for flag in other.flags:
+                seen.setdefault(flag.code, flag)
+        return TrustReport(tuple(seen.values()))
+
+    def render(self) -> str:
+        if self.clean:
+            return "Trust report: no caveats recorded."
+        marks = {Severity.INFO: "i", Severity.WARNING: "!", Severity.BLOCKING: "x"}
+        lines = ["Trust report:"]
+        lines += [f"  [{marks[f.severity]}] {f.code}: {f.message}" for f in self.flags]
+        return "\n".join(lines)
+
+
+@dataclass(frozen=True)
+class Provenance:
+    """Where data came from and under what terms. Every field may be unknown (ADR 0002)."""
+
+    source: str = UNKNOWN
+    license: str = UNKNOWN
+    terms_url: str | None = None
+    retrieved_at: str | None = None
+    notes: str = ""
+
+    @property
+    def license_known(self) -> bool:
+        return self.license.strip().lower() != UNKNOWN and bool(self.license.strip())
+
+    def trust(self) -> TrustReport:
+        flags = []
+        if self.source.strip().lower() in {"", UNKNOWN}:
+            flags.append(TrustFlag("SOURCE_UNKNOWN", Severity.WARNING,
+                                   "Data source is not recorded."))
+        if not self.license_known:
+            flags.append(TrustFlag("LICENCE_UNKNOWN", Severity.WARNING,
+                                   "Licence is unknown: private research only; "
+                                   "exporting or sharing requires an explicit acknowledgement."))
+        return TrustReport(tuple(flags))
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Provenance:
+        return cls(**data)
+
+
+class PriceBasis(StrEnum):
+    RAW = "raw"
+    SPLIT_ADJUSTED = "split_adjusted"
+    TOTAL_RETURN = "total_return"
+    UNKNOWN = UNKNOWN
+
+
+@dataclass(frozen=True)
+class Declaration:
+    """What a dataset claims about itself.
+
+    availability: when each row becomes known, e.g. "close" (after the session close),
+    "column:published_at" (per-row timestamp column) or "unknown".
+    corporate_actions: True if dividend/split events are supplied, False if known to be
+    absent, None if not stated.
+    """
+
+    price_basis: PriceBasis = PriceBasis.UNKNOWN
+    availability: str = UNKNOWN
+    corporate_actions: bool | None = None
+
+    def trust(self) -> TrustReport:
+        flags = []
+        if self.price_basis is PriceBasis.UNKNOWN:
+            flags.append(TrustFlag(
+                "PRICE_BASIS_UNKNOWN", Severity.WARNING,
+                "Prices may be raw or adjusted; accounting uses a conservative approximation."))
+        if self.price_basis is not PriceBasis.RAW or self.corporate_actions is not True:
+            flags.append(TrustFlag(
+                "ACCOUNTING_APPROXIMATE", Severity.WARNING,
+                "Ledger-accurate accounting needs raw prices plus dividend and split events."))
+        if self.availability.strip().lower() in {"", UNKNOWN}:
+            flags.append(TrustFlag(
+                "AVAILABILITY_UNVERIFIED", Severity.WARNING,
+                "Availability time is not declared; results may use data before it was known."))
+        return TrustReport(tuple(flags))
+
+    def to_dict(self) -> dict:
+        return {"price_basis": self.price_basis.value, "availability": self.availability,
+                "corporate_actions": self.corporate_actions}
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Declaration:
+        return cls(PriceBasis(data["price_basis"]), data["availability"], data["corporate_actions"])
+
+
+def to_decimal(value, name: str = "value") -> Decimal:
+    """Exact conversion; floats go through str() so 0.1 stays 0.1."""
+    try:
+        result = value if isinstance(value, Decimal) else Decimal(str(value))
+    except (InvalidOperation, ValueError, TypeError) as error:
+        raise ValueError(f"{name} is not a number: {value!r}") from error
+    if not result.is_finite():
+        raise ValueError(f"{name} must be finite: {value!r}")
+    return result
+
+
+@dataclass(frozen=True)
+class Money:
+    amount: Decimal
+    currency: str
+
+    def __post_init__(self):
+        object.__setattr__(self, "amount", to_decimal(self.amount, "amount"))
+        if not self.currency or self.currency != self.currency.upper():
+            raise ValueError(f"currency must be an upper-case code: {self.currency!r}")
+
+    def _same(self, other: Money) -> None:
+        if not isinstance(other, Money) or other.currency != self.currency:
+            raise ValueError("Money arithmetic needs the same currency; convert explicitly first.")
+
+    def __add__(self, other: Money) -> Money:
+        self._same(other)
+        return Money(self.amount + other.amount, self.currency)
+
+    def __sub__(self, other: Money) -> Money:
+        self._same(other)
+        return Money(self.amount - other.amount, self.currency)
+
+    def __neg__(self) -> Money:
+        return Money(-self.amount, self.currency)
+
+
+@dataclass(frozen=True)
+class Instrument:
+    """A tradable thing. Quantity rules belong to the instrument, not to the core.
+
+    quantity_step: smallest increment (1 share, 1000 shares, 0.00001 BTC).
+    min_quantity: smallest order size; defaults to one step.
+    """
+
+    id: str
+    venue: str
+    asset_class: str
+    quote_currency: str
+    quantity_step: Decimal = Decimal("1")
+    min_quantity: Decimal | None = None
+    price_tick: Decimal | None = None
+    attributes: dict = field(default_factory=dict, compare=False)
+
+    def __post_init__(self):
+        step = to_decimal(self.quantity_step, "quantity_step")
+        if step <= 0:
+            raise ValueError("quantity_step must be positive")
+        object.__setattr__(self, "quantity_step", step)
+        minimum = step if self.min_quantity is None else to_decimal(self.min_quantity, "min_quantity")
+        if minimum < step or (minimum / step) % 1 != 0:
+            raise ValueError("min_quantity must be a positive multiple of quantity_step")
+        object.__setattr__(self, "min_quantity", minimum)
+
+    def validate_quantity(self, quantity) -> Decimal:
+        """Return the quantity as Decimal if it is on the step grid, else raise."""
+        q = to_decimal(quantity, "quantity")
+        if q < 0:
+            raise ValueError("quantity must be non-negative")
+        if (q / self.quantity_step) % 1 != 0:
+            raise ValueError(f"{q} is not a multiple of {self.quantity_step} for {self.id}")
+        if 0 < q < self.min_quantity:
+            raise ValueError(f"{q} is below the minimum {self.min_quantity} for {self.id}")
+        return q
+
+    def floor_quantity(self, quantity) -> Decimal:
+        """Largest valid quantity not above `quantity` (0 if below the minimum)."""
+        q = to_decimal(quantity, "quantity")
+        if q <= 0:
+            return Decimal("0")
+        floored = (q // self.quantity_step) * self.quantity_step
+        return floored if floored >= self.min_quantity else Decimal("0")