orderwave 0.1.0__tar.gz

orderwave-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: orderwave
+Version: 0.1.0
+Summary: An order-flow-driven synthetic market simulator.
+Project-URL: Homepage, https://github.com/smturtle2/quoteflow
+Project-URL: Repository, https://github.com/smturtle2/quoteflow
+Project-URL: Issues, https://github.com/smturtle2/quoteflow/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# orderwave
+
+`orderwave` is an order-flow-driven market simulator.
+
+It does not random-walk price directly. Instead, it simulates a limit order book with stochastic limit arrivals, marketable flow, cancellations, and inside-spread quote improvement, then lets price emerge from those book changes.
+
+## Installation
+
+```bash
+pip install orderwave
+```
+
+For local development:
+
+```bash
+pip install -e .[dev]
+```
+
+## Quick Start
+
+```python
+from orderwave import Market
+
+market = Market(seed=42)
+
+market.step()
+market.gen(steps=1_000)
+
+snapshot = market.get()
+history = market.get_history()
+
+print(snapshot["mid_price"], snapshot["best_bid"], snapshot["best_ask"])
+print(history.tail())
+```
+
+## Why orderwave
+
+- Minimal public API: `from orderwave import Market`
+- Price is an outcome of book dynamics, not a separately sampled process
+- Hidden fair value and regime shifts bias order flow without directly overwriting price
+- Deterministic paths under the same seed
+
+## API
+
+```python
+from orderwave import Market
+
+market = Market(
+    init_price=100.0,
+    tick_size=0.01,
+    levels=5,
+    seed=42,
+    config={"preset": "balanced"},
+)
+```
+
+Methods:
+
+- `step()` returns the latest snapshot after one micro-batch
+- `gen(steps=n)` advances `n` steps and returns the latest snapshot
+- `get()` returns the current snapshot
+- `get_history()` returns a compact `pandas.DataFrame`
+
+Supported presets:
+
+- `balanced`
+- `trend`
+- `volatile`
+
+`config` accepts either a plain `dict` or `orderwave.config.MarketConfig`.
+
+## Snapshot
+
+`Market.get()` returns:
+
+```python
+{
+    "step": int,
+    "last_price": float,
+    "mid_price": float,
+    "microprice": float,
+    "best_bid": float,
+    "best_ask": float,
+    "spread": float,
+    "bids": [{"price": float, "qty": float}, ...],
+    "asks": [{"price": float, "qty": float}, ...],
+    "last_trade_side": "buy" | "sell" | None,
+    "last_trade_qty": float,
+    "buy_aggr_volume": float,
+    "sell_aggr_volume": float,
+    "trade_strength": float,
+    "depth_imbalance": float,
+    "regime": str,
+}
+```
+
+`last_price` is the last executed trade price. If the book changes without a trade, `mid_price` can move while `last_price` stays fixed.
+
+## Model
+
+Each `step()` is a micro-batch:
+
+1. Compute state features from the current book
+2. Update regime: `calm`, `directional`, or `stressed`
+3. Update hidden fair value
+4. Sample limit orders, marketable flow, and cancellations
+5. Shuffle events and apply them to the book
+6. Record the snapshot and compact history row
+
+Price moves only through book mechanics:
+
+- market buy removes ask liquidity
+- market sell removes bid liquidity
+- cancellation depletes the best quote
+- a new limit order improves the quote inside the spread
+
+## Diagnostics Example
+
+```python
+from orderwave import Market
+
+market = Market(seed=7, config={"preset": "trend"})
+market.gen(steps=5_000)
+history = market.get_history()
+
+mid_ret = history["mid_price"].diff().fillna(0.0)
+abs_ret = mid_ret.abs()
+spread_mean = history["spread"].mean()
+imbalance_lead_corr = history["depth_imbalance"].corr(mid_ret.shift(-1).fillna(0.0))
+vol_cluster = abs_ret.autocorr(lag=1)
+
+print("spread mean:", spread_mean)
+print("imbalance -> next return corr:", imbalance_lead_corr)
+print("|return| lag-1 autocorr:", vol_cluster)
+```
+
+## Maintainer Release
+
+PyPI publishing is wired through [`workflow.yml`](https://github.com/smturtle2/quoteflow/blob/main/.github/workflows/workflow.yml).
+
+On 2026-03-06, [GitHub Actions release event docs](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#release) document that `release.types: [published]` triggers when a release is published, while drafts themselves do not trigger workflows. [PyPI trusted publishing docs](https://docs.pypi.org/trusted-publishers/using-a-publisher/) document the `id-token: write` flow used by the publish job.
+
+Release flow:
+
+1. Update `version` in `pyproject.toml`
+2. Commit and push to `main`
+3. In GitHub, open `Releases`
+4. Click `Draft a new release`
+5. Create a tag like `v0.1.0`
+6. Set the release title, then click `Publish release`
+7. GitHub Actions runs tests, builds the distributions, and publishes to PyPI
+
+Trusted Publisher settings for PyPI:
+
+- PyPI project name: `orderwave`
+- Repository owner: `smturtle2`
+- Repository name: `quoteflow`
+- Workflow filename: `.github/workflows/workflow.yml`
+- Environment name: `pypi`
+
+If `orderwave` does not exist on PyPI yet, create the project through a pending publisher first. PyPI notes that a pending publisher does not reserve the name until the first successful publish.

orderwave-0.1.0/README.md

@@ -0,0 +1,161 @@
+# orderwave
+
+`orderwave` is an order-flow-driven market simulator.
+
+It does not random-walk price directly. Instead, it simulates a limit order book with stochastic limit arrivals, marketable flow, cancellations, and inside-spread quote improvement, then lets price emerge from those book changes.
+
+## Installation
+
+```bash
+pip install orderwave
+```
+
+For local development:
+
+```bash
+pip install -e .[dev]
+```
+
+## Quick Start
+
+```python
+from orderwave import Market
+
+market = Market(seed=42)
+
+market.step()
+market.gen(steps=1_000)
+
+snapshot = market.get()
+history = market.get_history()
+
+print(snapshot["mid_price"], snapshot["best_bid"], snapshot["best_ask"])
+print(history.tail())
+```
+
+## Why orderwave
+
+- Minimal public API: `from orderwave import Market`
+- Price is an outcome of book dynamics, not a separately sampled process
+- Hidden fair value and regime shifts bias order flow without directly overwriting price
+- Deterministic paths under the same seed
+
+## API
+
+```python
+from orderwave import Market
+
+market = Market(
+    init_price=100.0,
+    tick_size=0.01,
+    levels=5,
+    seed=42,
+    config={"preset": "balanced"},
+)
+```
+
+Methods:
+
+- `step()` returns the latest snapshot after one micro-batch
+- `gen(steps=n)` advances `n` steps and returns the latest snapshot
+- `get()` returns the current snapshot
+- `get_history()` returns a compact `pandas.DataFrame`
+
+Supported presets:
+
+- `balanced`
+- `trend`
+- `volatile`
+
+`config` accepts either a plain `dict` or `orderwave.config.MarketConfig`.
+
+## Snapshot
+
+`Market.get()` returns:
+
+```python
+{
+    "step": int,
+    "last_price": float,
+    "mid_price": float,
+    "microprice": float,
+    "best_bid": float,
+    "best_ask": float,
+    "spread": float,
+    "bids": [{"price": float, "qty": float}, ...],
+    "asks": [{"price": float, "qty": float}, ...],
+    "last_trade_side": "buy" | "sell" | None,
+    "last_trade_qty": float,
+    "buy_aggr_volume": float,
+    "sell_aggr_volume": float,
+    "trade_strength": float,
+    "depth_imbalance": float,
+    "regime": str,
+}
+```
+
+`last_price` is the last executed trade price. If the book changes without a trade, `mid_price` can move while `last_price` stays fixed.
+
+## Model
+
+Each `step()` is a micro-batch:
+
+1. Compute state features from the current book
+2. Update regime: `calm`, `directional`, or `stressed`
+3. Update hidden fair value
+4. Sample limit orders, marketable flow, and cancellations
+5. Shuffle events and apply them to the book
+6. Record the snapshot and compact history row
+
+Price moves only through book mechanics:
+
+- market buy removes ask liquidity
+- market sell removes bid liquidity
+- cancellation depletes the best quote
+- a new limit order improves the quote inside the spread
+
+## Diagnostics Example
+
+```python
+from orderwave import Market
+
+market = Market(seed=7, config={"preset": "trend"})
+market.gen(steps=5_000)
+history = market.get_history()
+
+mid_ret = history["mid_price"].diff().fillna(0.0)
+abs_ret = mid_ret.abs()
+spread_mean = history["spread"].mean()
+imbalance_lead_corr = history["depth_imbalance"].corr(mid_ret.shift(-1).fillna(0.0))
+vol_cluster = abs_ret.autocorr(lag=1)
+
+print("spread mean:", spread_mean)
+print("imbalance -> next return corr:", imbalance_lead_corr)
+print("|return| lag-1 autocorr:", vol_cluster)
+```
+
+## Maintainer Release
+
+PyPI publishing is wired through [`workflow.yml`](https://github.com/smturtle2/quoteflow/blob/main/.github/workflows/workflow.yml).
+
+On 2026-03-06, [GitHub Actions release event docs](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#release) document that `release.types: [published]` triggers when a release is published, while drafts themselves do not trigger workflows. [PyPI trusted publishing docs](https://docs.pypi.org/trusted-publishers/using-a-publisher/) document the `id-token: write` flow used by the publish job.
+
+Release flow:
+
+1. Update `version` in `pyproject.toml`
+2. Commit and push to `main`
+3. In GitHub, open `Releases`
+4. Click `Draft a new release`
+5. Create a tag like `v0.1.0`
+6. Set the release title, then click `Publish release`
+7. GitHub Actions runs tests, builds the distributions, and publishes to PyPI
+
+Trusted Publisher settings for PyPI:
+
+- PyPI project name: `orderwave`
+- Repository owner: `smturtle2`
+- Repository name: `quoteflow`
+- Workflow filename: `.github/workflows/workflow.yml`
+- Environment name: `pypi`
+
+If `orderwave` does not exist on PyPI yet, create the project through a pending publisher first. PyPI notes that a pending publisher does not reserve the name until the first successful publish.

orderwave-0.1.0/orderwave/__init__.py

@@ -0,0 +1,3 @@
+from orderwave.market import Market
+
+__all__ = ["Market"]

orderwave-0.1.0/orderwave/book.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+BookSide = Literal["bid", "ask"]
+AggressorSide = Literal["buy", "sell"]
+
+
+@dataclass
+class ExecutionResult:
+    aggressor_side: AggressorSide
+    requested_qty: int
+    filled_qty: int = 0
+    last_fill_tick: int | None = None
+    fills: list[tuple[int, int]] = field(default_factory=list)
+
+
+class OrderBook:
+    def __init__(self, tick_size: float) -> None:
+        self.tick_size = float(tick_size)
+        self.bid_book: dict[int, int] = {}
+        self.ask_book: dict[int, int] = {}
+        self.bid_staleness: dict[int, int] = {}
+        self.ask_staleness: dict[int, int] = {}
+        self.best_bid_tick: int | None = None
+        self.best_ask_tick: int | None = None
+
+    @property
+    def spread_ticks(self) -> int:
+        if self.best_bid_tick is None or self.best_ask_tick is None:
+            return 0
+        return self.best_ask_tick - self.best_bid_tick
+
+    def set_level(self, side: BookSide, tick: int, qty: int) -> None:
+        book, staleness = self._book_and_age(side)
+        if qty <= 0:
+            book.pop(tick, None)
+            staleness.pop(tick, None)
+            self._refresh_best(side)
+            return
+        book[tick] = int(qty)
+        staleness[tick] = 0
+        self._refresh_best(side)
+
+    def add_limit(self, side: BookSide, tick: int, qty: int) -> None:
+        if qty <= 0:
+            return
+        book, staleness = self._book_and_age(side)
+        book[tick] = int(book.get(tick, 0) + qty)
+        staleness[tick] = 0
+        self._refresh_best(side)
+
+    def apply_limit_relative(self, side: BookSide, level: int, qty: int) -> int | None:
+        tick = self.resolve_limit_tick(side, level)
+        if tick is None:
+            return None
+        self.add_limit(side, tick, qty)
+        return tick
+
+    def resolve_limit_tick(self, side: BookSide, level: int) -> int | None:
+        if self.best_bid_tick is None or self.best_ask_tick is None:
+            return None
+
+        if side == "bid":
+            if level == -1:
+                if self.spread_ticks <= 1:
+                    return None
+                target_tick = self.best_bid_tick + 1
+            else:
+                target_tick = self.best_bid_tick - int(level)
+            if target_tick < 0 or target_tick >= self.best_ask_tick:
+                return None
+            return target_tick
+
+        if level == -1:
+            if self.spread_ticks <= 1:
+                return None
+            target_tick = self.best_ask_tick - 1
+        else:
+            target_tick = self.best_ask_tick + int(level)
+        if target_tick <= self.best_bid_tick:
+            return None
+        return target_tick
+
+    def cancel_level(self, side: BookSide, tick: int, qty: int) -> int:
+        if qty <= 0:
+            return 0
+        book, staleness = self._book_and_age(side)
+        resting = book.get(tick, 0)
+        canceled = min(resting, int(qty))
+        if canceled <= 0:
+            return 0
+        remaining = resting - canceled
+        if remaining > 0:
+            book[tick] = remaining
+            staleness[tick] = 0
+        else:
+            book.pop(tick, None)
+            staleness.pop(tick, None)
+        self._refresh_best(side)
+        return canceled
+
+    def execute_market(self, aggressor_side: AggressorSide, qty: int) -> ExecutionResult:
+        result = ExecutionResult(aggressor_side=aggressor_side, requested_qty=int(qty))
+        if qty <= 0:
+            return result
+
+        if aggressor_side == "buy":
+            book = self.ask_book
+            staleness = self.ask_staleness
+            side = "ask"
+            best_key = lambda: self.best_ask_tick
+        else:
+            book = self.bid_book
+            staleness = self.bid_staleness
+            side = "bid"
+            best_key = lambda: self.best_bid_tick
+
+        remaining = int(qty)
+        while remaining > 0:
+            best_tick = best_key()
+            if best_tick is None:
+                break
+
+            resting = book[best_tick]
+            taken = min(resting, remaining)
+            remaining -= taken
+            result.filled_qty += taken
+            result.last_fill_tick = best_tick
+            result.fills.append((best_tick, taken))
+
+            new_qty = resting - taken
+            if new_qty > 0:
+                book[best_tick] = new_qty
+                staleness[best_tick] = 0
+            else:
+                book.pop(best_tick, None)
+                staleness.pop(best_tick, None)
+                self._refresh_best(side)
+
+        return result
+
+    def increment_staleness(self) -> None:
+        for staleness in (self.bid_staleness, self.ask_staleness):
+            for tick in list(staleness):
+                staleness[tick] += 1
+
+    def top_levels(self, side: BookSide, depth: int) -> list[tuple[int, int]]:
+        return self.all_levels(side)[: max(0, depth)]
+
+    def all_levels(self, side: BookSide) -> list[tuple[int, int]]:
+        book, _ = self._book_and_age(side)
+        ticks = sorted(book, reverse=(side == "bid"))
+        return [(tick, int(book[tick])) for tick in ticks]
+
+    def best_qty(self, side: BookSide) -> int:
+        if side == "bid":
+            if self.best_bid_tick is None:
+                return 0
+            return int(self.bid_book[self.best_bid_tick])
+        if self.best_ask_tick is None:
+            return 0
+        return int(self.ask_book[self.best_ask_tick])
+
+    def total_depth(self, side: BookSide, depth: int) -> int:
+        return sum(qty for _, qty in self.top_levels(side, depth))
+
+    def level_age(self, side: BookSide, tick: int) -> int:
+        _, staleness = self._book_and_age(side)
+        return int(staleness.get(tick, 0))
+
+    def _book_and_age(self, side: BookSide) -> tuple[dict[int, int], dict[int, int]]:
+        if side == "bid":
+            return self.bid_book, self.bid_staleness
+        return self.ask_book, self.ask_staleness
+
+    def _refresh_best(self, side: BookSide) -> None:
+        if side == "bid":
+            self.best_bid_tick = max(self.bid_book) if self.bid_book else None
+            return
+        self.best_ask_tick = min(self.ask_book) if self.ask_book else None