friction-engine 0.1.0__py3-none-any.whl

friction_engine/__init__.py

@@ -0,0 +1,48 @@
+"""friction-engine: realistic backtest friction modeling.
+
+Four orthogonal pieces, composable:
+
+- :mod:`friction_engine.slippage`  -- volume-aware slippage models
+- :mod:`friction_engine.fees`      -- multi-market fee & tax schedules (US/TW/JP)
+- :mod:`friction_engine.liquidity` -- participation-rate liquidity constraints
+- :mod:`friction_engine.mae_mfe`   -- MAE/MFE excursion analytics
+
+Pure standard library, no third-party dependencies.
+"""
+
+from .fees import FeeSchedule, Market, fee_for, FEE_SCHEDULES
+from .liquidity import LiquidityConstraint, ParticipationCap
+from .mae_mfe import Excursion, ExcursionStats, TradePath, excursion, excursion_stats, mae, mfe
+from .models import Fill, Order, Side
+from .slippage import (
+    FixedSlippage,
+    SlippageModel,
+    VolumeShareSlippage,
+    ZeroSlippage,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "FEE_SCHEDULES",
+    "Excursion",
+    "ExcursionStats",
+    "FeeSchedule",
+    "Fill",
+    "FixedSlippage",
+    "LiquidityConstraint",
+    "Market",
+    "Order",
+    "ParticipationCap",
+    "Side",
+    "SlippageModel",
+    "TradePath",
+    "VolumeShareSlippage",
+    "ZeroSlippage",
+    "excursion",
+    "excursion_stats",
+    "fee_for",
+    "mae",
+    "mfe",
+    "__version__",
+]

friction_engine/fees.py

@@ -0,0 +1,131 @@
+"""Multi-market fee & tax schedules (US / TW / JP presets, all configurable).
+
+Rates below are publicly documented, commonly-cited figures as of mid-2026,
+chosen as *conservative defaults* — they are NOT a substitute for checking
+your broker's current schedule. Every number is a plain constructor argument
+so you can (and should) override them.
+
+Design notes:
+- Commissions are per-side (charged on both buy and sell).
+- Transaction taxes are per-market and usually sell-side only.
+- US: no transaction tax on stocks; regulatory fees (SEC fee on sells,
+  FINRA TAF on sells) are tiny but included for completeness.
+- TW: broker commission 0.1425% (statutory max, discounts common) +
+  securities transaction tax 0.3% on stock sells (0.1% for ETF sells).
+- JP: no transaction tax on shares; commission is broker-negotiated, so the
+  preset is a representative flat bps; consumption tax (10%) applies to the
+  *commission*, modeled via `commission_tax_bps`.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, replace
+
+from .models import Order, Side
+
+
+class Market(enum.Enum):
+    US = "US"
+    TW = "TW"
+    JP = "JP"
+
+
+@dataclass(frozen=True)
+class FeeSchedule:
+    """A complete per-market cost schedule.
+
+    Attributes:
+        commission_bps: Broker commission in basis points of gross, per side.
+        min_commission: Minimum commission per order (account currency).
+        sell_tax_bps: Transaction tax on sells, in basis points of gross.
+        buy_tax_bps: Transaction tax on buys, in basis points of gross
+            (0 for US/TW/JP stocks; present for markets that need it).
+        sell_reg_fee_bps: Regulatory fees on sells in basis points
+            (e.g. US SEC fee + TAF combined approximation).
+        commission_tax_bps: Tax levied on the commission itself
+            (e.g. JP consumption tax = 1000 bps = 10%).
+    """
+
+    commission_bps: float
+    min_commission: float = 0.0
+    sell_tax_bps: float = 0.0
+    buy_tax_bps: float = 0.0
+    sell_reg_fee_bps: float = 0.0
+    commission_tax_bps: float = 0.0
+
+    def fee_and_tax(self, order: Order, gross_amount: float) -> tuple[float, float]:
+        """Return (fee, tax) in account currency for a fill of `gross_amount`."""
+        if gross_amount < 0:
+            raise ValueError("gross_amount must be >= 0")
+        raw_commission = gross_amount * self.commission_bps / 10_000.0
+        commission = max(raw_commission, self.min_commission) if gross_amount > 0 else 0.0
+        commission_tax = commission * self.commission_tax_bps / 10_000.0
+        fee = commission + commission_tax
+
+        if order.side is Side.SELL:
+            tax = gross_amount * (self.sell_tax_bps + self.sell_reg_fee_bps) / 10_000.0
+        else:
+            tax = gross_amount * self.buy_tax_bps / 10_000.0
+        return fee, tax
+
+    def with_overrides(self, **changes: float) -> "FeeSchedule":
+        """Return a new schedule with selected fields replaced (immutable update)."""
+        return replace(self, **changes)
+
+
+# --- Presets (publicly documented typical values; verify before live use) ---
+
+# US: zero-commission brokers exist; 0 default + tiny sell-side regulatory
+# fees (SEC fee ~0.278 bps of sell gross + FINRA TAF; rounded, mid-2020s).
+_US = FeeSchedule(
+    commission_bps=0.0,
+    min_commission=0.0,
+    sell_tax_bps=0.0,
+    sell_reg_fee_bps=0.3,
+)
+
+# TW stocks: commission 0.1425% (14.25 bps, statutory max before discounts),
+# sell-side securities transaction tax 0.3% (30 bps).
+_TW_STOCK = FeeSchedule(
+    commission_bps=14.25,
+    min_commission=0.0,  # many TW brokers have a NT$20 minimum — set it if yours does
+    sell_tax_bps=30.0,
+)
+
+# TW ETFs: same commission, reduced 0.1% (10 bps) sell tax.
+_TW_ETF = replace(_TW_STOCK, sell_tax_bps=10.0)
+
+# JP: representative commission 10 bps (broker-negotiated), 10% consumption
+# tax on commission, no share transaction tax.
+_JP = FeeSchedule(
+    commission_bps=10.0,
+    min_commission=0.0,
+    sell_tax_bps=0.0,
+    commission_tax_bps=1000.0,
+)
+
+FEE_SCHEDULES: dict[Market, FeeSchedule] = {
+    Market.US: _US,
+    Market.TW: _TW_STOCK,
+    Market.JP: _JP,
+}
+
+TW_ETF_SCHEDULE = _TW_ETF
+
+
+def fee_for(
+    order: Order,
+    gross_amount: float,
+    market: Market | None = None,
+    schedule: FeeSchedule | None = None,
+) -> tuple[float, float]:
+    """Compute (fee, tax) for an order.
+
+    Pass either a `market` (uses the built-in preset) or an explicit
+    `schedule` (recommended for anything real). Exactly one is required.
+    """
+    if (market is None) == (schedule is None):
+        raise ValueError("pass exactly one of market= or schedule=")
+    sched = schedule if schedule is not None else FEE_SCHEDULES[market]  # type: ignore[index]
+    return sched.fee_and_tax(order, gross_amount)

friction_engine/liquidity.py

@@ -0,0 +1,41 @@
+"""Liquidity constraints: how much of an order can realistically fill.
+
+The classic backtest lie is "buy 1,000,000 shares of a stock that trades
+200,000 shares a day, at the close price." These constraints cap executable
+quantity at a fraction of observed market volume (participation rate), so
+your backtest can't trade size the market couldn't absorb.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from .models import Order
+
+
+class LiquidityConstraint(ABC):
+    """Interface: cap an order's quantity given market volume."""
+
+    @abstractmethod
+    def cap(self, order: Order, *, bar_volume: float) -> float:
+        """Return the maximum executable quantity for `order` (>= 0)."""
+
+
+class ParticipationCap(LiquidityConstraint):
+    """Cap quantity at a fixed fraction of bar volume.
+
+    Args:
+        max_participation: Maximum share of bar volume your order may be,
+            e.g. 0.10 = at most 10% of the day's volume. Industry heuristics
+            for "low-impact" execution typically live in the 1-20% range.
+    """
+
+    def __init__(self, max_participation: float = 0.10) -> None:
+        if not 0 < max_participation <= 1:
+            raise ValueError("max_participation must be in (0, 1]")
+        self.max_participation = max_participation
+
+    def cap(self, order: Order, *, bar_volume: float) -> float:
+        if bar_volume < 0:
+            raise ValueError("bar_volume must be >= 0")
+        return min(order.quantity, self.max_participation * bar_volume)

friction_engine/mae_mfe.py

@@ -0,0 +1,184 @@
+"""MAE / MFE excursion analytics.
+
+MAE (Maximum Adverse Excursion): the worst open-loss a trade experienced
+while it was on. MFE (Maximum Favorable Excursion): the best open-profit.
+Together they answer questions a single entry/exit pair cannot:
+
+- "My stop is -5%; how often did winners dip below -5% first?" (MAE distribution)
+- "My target is +8%; how often did trades reach +8% but close lower?" (MFE distribution)
+- "Am I exiting too early/late?" (compare exit return to MFE — give-back ratio)
+
+These are descriptive statistics over a trade's price path — a measurement
+tool, not a strategy. Everything here is computed from post-entry highs/lows
+the caller supplies, so point-in-time correctness is the caller's job (use
+quant-lint on the strategy that produced the paths).
+"""
+
+from __future__ import annotations
+
+import statistics
+from dataclasses import dataclass
+from typing import Sequence
+
+from .models import Side
+
+
+@dataclass(frozen=True)
+class TradePath:
+    """One trade's lifecycle for excursion analysis.
+
+    Attributes:
+        entry_price: Actual fill price at entry.
+        side: BUY for long trades, SELL for short trades.
+        highs: Post-entry period high prices, in time order (include the
+            entry bar's high if the trade was open for the rest of that bar).
+        lows: Post-entry period low prices, aligned with `highs`.
+        exit_price: Actual fill price at exit. If omitted, the last period's
+            low/high is NOT used as a fallback — realized-return fields are
+            simply unavailable (None).
+    """
+
+    entry_price: float
+    side: Side
+    highs: Sequence[float]
+    lows: Sequence[float]
+    exit_price: float | None = None
+
+    def __post_init__(self) -> None:
+        if self.entry_price <= 0:
+            raise ValueError("entry_price must be positive")
+        if len(self.highs) == 0:
+            raise ValueError("highs/lows must contain at least one period")
+        if len(self.highs) != len(self.lows):
+            raise ValueError("highs and lows must have equal length")
+        for h, l in zip(self.highs, self.lows):
+            if h < l:
+                raise ValueError(f"period high {h} below period low {l}")
+
+
+def _signed_return(price: float, entry: float, side: Side) -> float:
+    """Return from `entry` to `price`, signed so profit is positive."""
+    raw = (price - entry) / entry
+    return raw if side is Side.BUY else -raw
+
+
+def mae(path: TradePath) -> float:
+    """Maximum Adverse Excursion as a signed return (<= 0 for any losing dip).
+
+    Long: worst case is the minimum post-entry low.
+    Short: worst case is the maximum post-entry high.
+    """
+    if path.side is Side.BUY:
+        worst = min(path.lows)
+    else:
+        worst = max(path.highs)
+    return min(0.0, _signed_return(worst, path.entry_price, path.side))
+
+
+def mfe(path: TradePath) -> float:
+    """Maximum Favorable Excursion as a signed return (>= 0 for any gain)."""
+    if path.side is Side.BUY:
+        best = max(path.highs)
+    else:
+        best = min(path.lows)
+    return max(0.0, _signed_return(best, path.entry_price, path.side))
+
+
+@dataclass(frozen=True)
+class Excursion:
+    """Full excursion record for one trade.
+
+    Attributes:
+        mae: Maximum Adverse Excursion (signed return, <= 0).
+        mfe: Maximum Favorable Excursion (signed return, >= 0).
+        realized_return: Exit-vs-entry signed return, or None if no exit_price.
+        giveback: Fraction of MFE surrendered at exit,
+            (mfe - realized) / mfe; None when mfe == 0 or exit unknown.
+            0.0 = exited at the peak; 1.0 = gave back everything; >1 = the
+            trade round-tripped through zero into a loss.
+        end_up_winning: True when realized_return > 0; None if exit unknown.
+    """
+
+    mae: float
+    mfe: float
+    realized_return: float | None
+    giveback: float | None
+    end_up_winning: bool | None
+
+
+def excursion(path: TradePath) -> Excursion:
+    """Compute the full excursion record for one trade."""
+    a = mae(path)
+    f = mfe(path)
+    realized: float | None = None
+    giveback: float | None = None
+    winning: bool | None = None
+    if path.exit_price is not None:
+        realized = _signed_return(path.exit_price, path.entry_price, path.side)
+        winning = realized > 0
+        if f > 0:
+            giveback = (f - realized) / f
+    return Excursion(mae=a, mfe=f, realized_return=realized, giveback=giveback, end_up_winning=winning)
+
+
+@dataclass(frozen=True)
+class ExcursionStats:
+    """Aggregate statistics over a set of trades."""
+
+    n: int
+    mae_mean: float
+    mae_median: float
+    mae_p05: float  # 5th percentile (worst tail) of MAE
+    mfe_mean: float
+    mfe_median: float
+    mfe_p95: float  # 95th percentile (best tail) of MFE
+    giveback_mean: float | None  # over trades with mfe > 0 and known exit
+    win_rate: float | None  # over trades with known exit
+    mae_of_winners_mean: float | None  # how deep winners dipped first
+    mfe_of_losers_mean: float | None  # how high losers climbed before failing
+
+
+def _percentile(sorted_vals: Sequence[float], q: float) -> float:
+    """Linear-interpolation percentile; q in [0, 1]."""
+    if not sorted_vals:
+        raise ValueError("empty sequence")
+    if len(sorted_vals) == 1:
+        return float(sorted_vals[0])
+    pos = q * (len(sorted_vals) - 1)
+    lo = int(pos)
+    hi = min(lo + 1, len(sorted_vals) - 1)
+    frac = pos - lo
+    return float(sorted_vals[lo] * (1 - frac) + sorted_vals[hi] * frac)
+
+
+def excursion_stats(paths: Sequence[TradePath]) -> ExcursionStats:
+    """Aggregate MAE/MFE statistics over many trades.
+
+    Use it to sanity-check stops/targets: if `mae_of_winners_mean` is deeper
+    than your stop, your stop would have killed trades that later won.
+    """
+    if not paths:
+        raise ValueError("paths must be non-empty")
+    recs = [excursion(p) for p in paths]
+
+    maes = sorted(r.mae for r in recs)
+    mfes = sorted(r.mfe for r in recs)
+
+    with_exit = [r for r in recs if r.realized_return is not None]
+    wins = [r for r in with_exit if r.end_up_winning]
+    losses = [r for r in with_exit if not r.end_up_winning]
+    givebacks = [r.giveback for r in with_exit if r.giveback is not None]
+
+    return ExcursionStats(
+        n=len(recs),
+        mae_mean=statistics.fmean(maes),
+        mae_median=statistics.median(maes),
+        mae_p05=_percentile(maes, 0.05),
+        mfe_mean=statistics.fmean(mfes),
+        mfe_median=statistics.median(mfes),
+        mfe_p95=_percentile(mfes, 0.95),
+        giveback_mean=statistics.fmean(givebacks) if givebacks else None,
+        win_rate=len(wins) / len(with_exit) if with_exit else None,
+        mae_of_winners_mean=statistics.fmean(r.mae for r in wins) if wins else None,
+        mfe_of_losers_mean=statistics.fmean(r.mfe for r in losses) if losses else None,
+    )

friction_engine/models.py

@@ -0,0 +1,88 @@
+"""Core value types shared across friction-engine modules."""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+
+
+class Side(enum.Enum):
+    """Order/trade direction."""
+
+    BUY = "buy"
+    SELL = "sell"
+
+    @property
+    def sign(self) -> int:
+        """+1 for BUY, -1 for SELL — handy for signed cash-flow math."""
+        return 1 if self is Side.BUY else -1
+
+
+@dataclass(frozen=True)
+class Order:
+    """A desired trade, before friction is applied.
+
+    Attributes:
+        symbol: Instrument identifier (free-form string).
+        side: BUY or SELL.
+        quantity: Number of shares/units requested (positive).
+        limit_price: Optional limit price; informational only — this library
+            models cost, it does not decide whether a limit order fills.
+    """
+
+    symbol: str
+    side: Side
+    quantity: float
+    limit_price: float | None = None
+
+    def __post_init__(self) -> None:
+        if self.quantity <= 0:
+            raise ValueError(f"quantity must be positive, got {self.quantity}")
+
+
+@dataclass(frozen=True)
+class Fill:
+    """A trade after friction has been applied.
+
+    Attributes:
+        symbol: Instrument identifier.
+        side: BUY or SELL.
+        quantity: Shares/units actually filled (may be capped by liquidity).
+        base_price: Reference price before slippage (e.g. bar close).
+        fill_price: Effective execution price after slippage.
+        slippage_cost: Total slippage cost in account currency (always >= 0;
+            for sells the fill price moves *down*, but cost stays positive).
+        fee: Commission/fee amount in account currency.
+        tax: Transaction tax amount in account currency.
+    """
+
+    symbol: str
+    side: Side
+    quantity: float
+    base_price: float
+    fill_price: float
+    slippage_cost: float
+    fee: float
+    tax: float
+
+    @property
+    def gross_amount(self) -> float:
+        """fill_price * quantity — cash before fee/tax."""
+        return self.fill_price * self.quantity
+
+    @property
+    def total_cost(self) -> float:
+        """All friction in account currency: slippage + fee + tax."""
+        return self.slippage_cost + self.fee + self.tax
+
+    @property
+    def net_cash_flow(self) -> float:
+        """Signed cash impact on the account.
+
+        BUY: negative (cash out) = -(gross + fee + tax).
+        SELL: positive (cash in) = gross - fee - tax.
+        Slippage is already embedded in fill_price, so it is not added again.
+        """
+        if self.side is Side.BUY:
+            return -(self.gross_amount + self.fee + self.tax)
+        return self.gross_amount - self.fee - self.tax

friction_engine/slippage.py

@@ -0,0 +1,132 @@
+"""Slippage models.
+
+Slippage = the gap between the reference price your backtest *assumes* and
+the price you would actually get. Models here are deliberately simple,
+public, and auditable. The volume-aware model is the classic square-root
+market-impact form published widely in the market-microstructure literature
+(e.g. Almgren-style impact): impact grows with the square root of your
+participation rate in the day's volume.
+
+Convention: slippage always works *against* the trader — buys fill higher,
+sells fill lower.
+"""
+
+from __future__ import annotations
+
+import math
+from abc import ABC, abstractmethod
+
+from .models import Order, Side
+
+
+class SlippageModel(ABC):
+    """Interface: given an order and market context, return the fill price."""
+
+    @abstractmethod
+    def fill_price(
+        self,
+        order: Order,
+        reference_price: float,
+        *,
+        bar_volume: float | None = None,
+        volatility: float | None = None,
+    ) -> float:
+        """Return the effective execution price for `order`.
+
+        Args:
+            order: The desired trade.
+            reference_price: Price the backtest would naively use (e.g. close).
+            bar_volume: Total market volume in the execution bar/day, in the
+                same units as order quantity. Required by volume-aware models.
+            volatility: Daily return volatility (e.g. 0.02 for 2%). Used by
+                impact-style models; ignored by fixed models.
+        """
+
+
+class ZeroSlippage(SlippageModel):
+    """No slippage — the naive-backtest default, provided for completeness."""
+
+    def fill_price(
+        self,
+        order: Order,
+        reference_price: float,
+        *,
+        bar_volume: float | None = None,
+        volatility: float | None = None,
+    ) -> float:
+        return reference_price
+
+
+class FixedSlippage(SlippageModel):
+    """Constant basis-point slippage per trade.
+
+    Args:
+        bps: Slippage in basis points (1 bps = 0.01%). Applied against the
+            trader on every fill.
+    """
+
+    def __init__(self, bps: float) -> None:
+        if bps < 0:
+            raise ValueError("bps must be >= 0")
+        self.bps = bps
+
+    def fill_price(
+        self,
+        order: Order,
+        reference_price: float,
+        *,
+        bar_volume: float | None = None,
+        volatility: float | None = None,
+    ) -> float:
+        direction = 1.0 if order.side is Side.BUY else -1.0
+        return reference_price * (1.0 + direction * self.bps / 10_000.0)
+
+
+class VolumeShareSlippage(SlippageModel):
+    """Volume-aware slippage: half-spread + square-root temporary impact.
+
+    fill_price = reference * (1 + dir * (spread/2 + eta * sigma * sqrt(q/V)))
+
+    where ``q/V`` is your participation rate (order quantity over bar volume),
+    ``sigma`` is daily volatility, and ``eta`` is an impact coefficient you
+    calibrate to your market/execution style (0.1 = gentle, 1.0 = harsh).
+
+    Why square root: it is the most widely published empirically-supported
+    shape for temporary market impact across equities markets. It punishes
+    large orders convexly in *rate* terms while keeping small orders near
+    the half-spread floor — exactly the behavior naive backtests ignore.
+
+    Args:
+        spread_bps: Assumed bid-ask spread in basis points. You pay half.
+        eta: Impact coefficient (dimensionless), >= 0.
+    """
+
+    def __init__(self, spread_bps: float = 5.0, eta: float = 0.5) -> None:
+        if spread_bps < 0:
+            raise ValueError("spread_bps must be >= 0")
+        if eta < 0:
+            raise ValueError("eta must be >= 0")
+        self.spread_bps = spread_bps
+        self.eta = eta
+
+    def fill_price(
+        self,
+        order: Order,
+        reference_price: float,
+        *,
+        bar_volume: float | None = None,
+        volatility: float | None = None,
+    ) -> float:
+        if bar_volume is None or bar_volume <= 0:
+            raise ValueError(
+                "VolumeShareSlippage requires positive bar_volume; "
+                "use FixedSlippage if volume data is unavailable"
+            )
+        sigma = volatility if volatility is not None else 0.02
+        if sigma < 0:
+            raise ValueError("volatility must be >= 0")
+        participation = order.quantity / bar_volume
+        half_spread = self.spread_bps / 2.0 / 10_000.0
+        impact = self.eta * sigma * math.sqrt(participation)
+        direction = 1.0 if order.side is Side.BUY else -1.0
+        return reference_price * (1.0 + direction * (half_spread + impact))

friction_engine-0.1.0.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: friction-engine
+Version: 0.1.0
+Summary: Realistic backtest friction modeling: volume-aware slippage, multi-market fees & taxes (US/TW/JP), liquidity constraints, and MAE/MFE trade analytics.
+Author: friction-engine contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/jalano0i9u8y7-lab/friction-engine
+Keywords: backtest,slippage,transaction-costs,MAE,MFE,trading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# friction-engine
+
+**Your backtest is lying to you — this library measures how much.**
+
+`friction-engine` models the four costs naive backtests ignore, as small,
+composable, fully-auditable pieces:
+
+| Module | What it fixes | The naive-backtest lie |
+|---|---|---|
+| `slippage` | Volume-aware slippage (half-spread + square-root impact) | "I filled 200k shares at the close price" |
+| `fees` | Multi-market fees & taxes (US / TW / JP presets, all configurable) | "Commissions are round-off error" |
+| `liquidity` | Participation-rate caps on executable quantity | "The market absorbed my 10× ADV order instantly" |
+| `mae_mfe` | MAE/MFE excursion analytics | "The trade returned +5%" — but it dipped -8% first; would your stop have survived? |
+
+Pure Python standard library. **Zero third-party dependencies.** Every model
+is one short file you can read end-to-end before trusting it.
+
+## Install
+
+```bash
+pip install friction-engine
+```
+
+Or from source:
+
+```bash
+pip install .
+pip install ".[dev]"   # with pytest for running the test suite
+```
+
+## Quick start
+
+```python
+from friction_engine import (
+    Market, Order, ParticipationCap, Side, TradePath,
+    VolumeShareSlippage, excursion, fee_for,
+)
+
+order = Order(symbol="2330.TW", side=Side.BUY, quantity=20_000)
+
+# 1. Liquidity: can the market absorb this?
+allowed = ParticipationCap(0.10).cap(order, bar_volume=150_000)
+
+# 2. Slippage: volume-aware fill price (not the close you assumed)
+slip = VolumeShareSlippage(spread_bps=5, eta=0.5)
+fill_price = slip.fill_price(order, 100.0, bar_volume=150_000, volatility=0.02)
+
+# 3. Fees & taxes: TW stocks = 14.25 bps commission + 30 bps sell tax
+fee, tax = fee_for(order, fill_price * order.quantity, market=Market.TW)
+
+# 4. MAE/MFE: what happened inside the trade, not just entry→exit
+path = TradePath(
+    entry_price=fill_price, side=Side.BUY,
+    highs=[101, 103, 106], lows=[97.5, 99, 102], exit_price=105.0,
+)
+rec = excursion(path)
+print(rec.mae, rec.mfe, rec.giveback)   # -0.025 … +0.06 … how much you gave back
+```
+
+Run the full worked example:
+
+```bash
+python examples/basic_usage.py
+```
+
+## The models, honestly
+
+**Volume-aware slippage** — `fill = ref × (1 + dir × (spread/2 + η·σ·√(q/V)))`.
+The square-root temporary-impact shape is the most widely published
+empirical form in the market-microstructure literature. `η` (eta) is a
+calibration knob: 0.1 gentle, 0.5 typical, 1.0 harsh. If you don't know your
+`η`, run all three and treat the spread of outcomes as your uncertainty.
+
+**Fee presets** — US (zero commission + ~0.3 bps sell-side regulatory fees),
+TW stocks (14.25 bps commission both sides + 30 bps sell tax), TW ETF
+(10 bps sell tax), JP (10 bps commission + 10% consumption tax *on the
+commission*, no share transaction tax). These are publicly documented
+typical values as of mid-2026 and **will go stale** — brokers discount,
+regulators re-price. Treat presets as starting points:
+
+```python
+from friction_engine import FEE_SCHEDULES, Market
+my_tw = FEE_SCHEDULES[Market.TW].with_overrides(commission_bps=6.0, min_commission=20.0)
+```
+
+**Liquidity cap** — `min(quantity, max_participation × bar_volume)`. Simple,
+brutal, and the single most common way backtests overstate capacity.
+
+**MAE/MFE** — descriptive statistics over a trade's post-entry high/low
+path (Sweeney-style excursion analysis). Aggregates (`excursion_stats`)
+answer: *is my stop inside the noise band of my winners?* (`mae_of_winners_mean`)
+and *how much do my losers climb before failing?* (`mfe_of_losers_mean`).
+
+## What this library is NOT
+
+- Not a backtester. It computes friction; you bring the loop, the data, and
+  the point-in-time discipline. (Pair it with `quant-lint` to audit the
+  strategy code feeding it.)
+- Not a broker simulator. Fill *decisions* (partial fills, limit queues,
+  halts) are out of scope; it prices the fills you assume.
+- Not financial advice, and presets are not a fee-quote service. Verify
+  current rates with your broker/exchange before trading real money.
+
+## Development
+
+```bash
+python -m pytest            # run the test suite
+```
+
+Layout:
+
+```
+src/friction_engine/
+  models.py      # Order / Fill / Side value types
+  slippage.py    # Zero / Fixed / VolumeShare slippage models
+  fees.py        # FeeSchedule + US/TW/JP presets
+  liquidity.py   # ParticipationCap
+  mae_mfe.py     # TradePath, mae/mfe, excursion, excursion_stats
+tests/           # pytest suite, no network, no data files
+examples/        # runnable worked example
+```
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE). Clean-room provenance: see
+[CLEANROOM.md](CLEANROOM.md).

friction_engine-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+friction_engine/__init__.py,sha256=p2BCX9finMbVrAcZLA5H0ZHkynZ27bzSJPzfNxzL1us,1233
+friction_engine/fees.py,sha256=NZU3VYjqFCZUXyNSMJOdugIip9tngBYutJp-yET6o28,4775
+friction_engine/liquidity.py,sha256=0RscV4VCMork3qVJp_AzvXrZiFyX_Au_tthosNlnuaw,1510
+friction_engine/mae_mfe.py,sha256=EUNoE4aQtFsfHzvqOr5IcT9Y6YVqnFER-DcZfzooC7s,6836
+friction_engine/models.py,sha256=YJtKG5IN6m2mWuM8rNAjLjDrOLUGXQ84piEox7vF-es,2646
+friction_engine/slippage.py,sha256=TZkSq_PX7OOQrnmxt47SFvCWZ7cBGiJfSXm6yvBnJ54,4534
+friction_engine-0.1.0.dist-info/licenses/LICENSE,sha256=v0c51XRi_dXfvYrmUzGU47xaSEMVLNH_w1IeddCzq_k,10550
+friction_engine-0.1.0.dist-info/METADATA,sha256=3zC9dD-dcPwxMeLRYVUXV2PW7am89cyv2TmJOOx6CuU,5832
+friction_engine-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+friction_engine-0.1.0.dist-info/top_level.txt,sha256=8ytBfkfhKRfEqqGhKZKcY_mHHSYyomF_ADq5CWnAIOA,16
+friction_engine-0.1.0.dist-info/RECORD,,

friction_engine-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

friction_engine-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,189 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate as
+      of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a file titled "NOTICE" file in the root directory of
+          the Derivative Works; or within a file titled "NOTICE" file in
+          the root directory of the Source form. You may copy and
+          distribute Derivative Works of the Work only under this License,
+          in which the Licensor agrees to place attribution notices
+          contained in such NOTICE file. You may reproduce and distribute
+          copies of the Work for any purpose, provided that You also meet
+          the conditions of the License for Derivative Works as set forth
+          in the NOTICE file.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of this
+      License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Work) on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
+      including, without limitation, any warranties or conditions of
+      TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, will any Contributor be
+      liable to You for any loss or damage, as a result of any such
+      Contributor's exercise of permissions under this License, even if
+      such Contributor has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations. However, in accepting such
+      obligations, You may act only on Your own behalf and on Your sole
+      responsibility, not on behalf of any Contributor, and only if You
+      agree to indemnify, defend, and hold each Contributor harmless for
+      any liability incurred by each such Contributor in performing its
+      obligations under this License.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+Keith Infinity
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

friction_engine-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+friction_engine