sabia 0.1.0__tar.gz

sabia-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antônio Salomão
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sabia-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: sabia
+Version: 0.1.0
+Summary: Polars-native technical features for trading pipelines — pure, point-in-time, online-ready
+Keywords: finance,features,trading,technical-analysis,polars,backtesting
+Author: Antônio Salomão
+Author-email: Antônio Salomão <83646729+aexsalomao@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Requires-Dist: polars==1.39.3
+Requires-Dist: numpy>=1.26
+Requires-Dist: tzdata
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0 ; extra == 'dev'
+Requires-Dist: pytest-benchmark>=4.0 ; extra == 'dev'
+Requires-Dist: hypothesis>=6.100 ; extra == 'dev'
+Requires-Dist: ruff>=0.8.0 ; extra == 'dev'
+Requires-Dist: mypy>=1.10.0 ; extra == 'dev'
+Requires-Dist: pre-commit>=3.7.0 ; extra == 'dev'
+Requires-Dist: mkdocs>=1.6.0 ; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.5.0 ; extra == 'dev'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://aexsalomao.github.io/sabia
+Project-URL: Documentation, https://aexsalomao.github.io/sabia
+Project-URL: Repository, https://github.com/aexsalomao/sabia
+Project-URL: Issues, https://github.com/aexsalomao/sabia/issues
+Project-URL: Changelog, https://github.com/aexsalomao/sabia/blob/master/CHANGELOG.md
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# sabia
+
+> Polars-native technical features for trading pipelines — pure, point-in-time, online-ready.
+
+`sabia` reads price/volume into features, grounded in the trading & finance literature. It is the
+**features** brick in a layered stack:
+
+```
+marketgoblin (data in) → sabia (features) → quale (signals)
+```
+
+Runtime dependencies are just `polars` and `numpy`. (The stack's calendar brick
+[`quando`](https://github.com/aexsalomao/quando) will be wired in when calendar-aware seasonality or
+the microstructure tier needs it — v1 seasonality is pure vectorized datetime.) Risk/eval math lives
+in `ruin`; signals live in `quale`. sabia computes features and nothing else.
+
+## What it is
+
+Pure functions over OHLCV bars that return Polars expressions (`pl.Expr`) — strictly trailing,
+point-in-time correct, deterministic. **Batch-first, online-ready**: nothing streams in v1, but every
+feature declares the history it needs and is covered by a windowed-recompute parity test, so a future
+online engine is a thin wrapper rather than a rewrite.
+
+## Install
+
+```bash
+uv sync --extra dev
+```
+
+## Quickstart
+
+```python
+import polars as pl
+import sabia
+
+frame = ...  # OHLCV LazyFrame/DataFrame; see sabia.validate for the input contract
+
+# Features are pl.Expr — compose them lazily, or materialize eagerly:
+df = sabia.compute(frame, sabia.momentum.rsi(period=14), sabia.volatility.vol_yz(window=21))
+
+# Query the registry by horizon or data tier:
+reg = sabia.Registry.default()
+reg.where(lambda s: sabia.Horizon.MEDIUM in s.native_band)
+reg.available(sabia.DataTier.DAILY)
+```
+
+## Invariants
+
+Causality · point-in-time correctness · purity (no I/O, clocks, randomness) · Polars-native
+(no pandas) · determinism within a declared tolerance. All enforced by tests, not convention. See
+`FEATURES.md` for the full spec.
+
+## License
+
+MIT

sabia-0.1.0/README.md

@@ -0,0 +1,55 @@
+# sabia
+
+> Polars-native technical features for trading pipelines — pure, point-in-time, online-ready.
+
+`sabia` reads price/volume into features, grounded in the trading & finance literature. It is the
+**features** brick in a layered stack:
+
+```
+marketgoblin (data in) → sabia (features) → quale (signals)
+```
+
+Runtime dependencies are just `polars` and `numpy`. (The stack's calendar brick
+[`quando`](https://github.com/aexsalomao/quando) will be wired in when calendar-aware seasonality or
+the microstructure tier needs it — v1 seasonality is pure vectorized datetime.) Risk/eval math lives
+in `ruin`; signals live in `quale`. sabia computes features and nothing else.
+
+## What it is
+
+Pure functions over OHLCV bars that return Polars expressions (`pl.Expr`) — strictly trailing,
+point-in-time correct, deterministic. **Batch-first, online-ready**: nothing streams in v1, but every
+feature declares the history it needs and is covered by a windowed-recompute parity test, so a future
+online engine is a thin wrapper rather than a rewrite.
+
+## Install
+
+```bash
+uv sync --extra dev
+```
+
+## Quickstart
+
+```python
+import polars as pl
+import sabia
+
+frame = ...  # OHLCV LazyFrame/DataFrame; see sabia.validate for the input contract
+
+# Features are pl.Expr — compose them lazily, or materialize eagerly:
+df = sabia.compute(frame, sabia.momentum.rsi(period=14), sabia.volatility.vol_yz(window=21))
+
+# Query the registry by horizon or data tier:
+reg = sabia.Registry.default()
+reg.where(lambda s: sabia.Horizon.MEDIUM in s.native_band)
+reg.available(sabia.DataTier.DAILY)
+```
+
+## Invariants
+
+Causality · point-in-time correctness · purity (no I/O, clocks, randomness) · Polars-native
+(no pandas) · determinism within a declared tolerance. All enforced by tests, not convention. See
+`FEATURES.md` for the full spec.
+
+## License
+
+MIT

sabia-0.1.0/pyproject.toml

@@ -0,0 +1,97 @@
+[project]
+name = "sabia"
+version = "0.1.0"
+description = "Polars-native technical features for trading pipelines — pure, point-in-time, online-ready"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Antônio Salomão", email = "83646729+aexsalomao@users.noreply.github.com" }
+]
+keywords = ["finance", "features", "trading", "technical-analysis", "polars", "backtesting"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial",
+]
+requires-python = ">=3.13"
+dependencies = [
+    # Polars is pinned exactly: the §3.4 immutability / fingerprint guarantee depends on it.
+    "polars==1.39.3",
+    "numpy>=1.26",
+    # sabia's input contract is tz-aware UTC timestamps; tzdata provides the IANA zone database
+    # where the OS lacks one (Windows, slim containers), so zone resolution never fails at runtime.
+    "tzdata",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "pytest-benchmark>=4.0",
+    "hypothesis>=6.100",
+    "ruff>=0.8.0",
+    "mypy>=1.10.0",
+    "pre-commit>=3.7.0",
+    "mkdocs>=1.6.0",
+    "mkdocs-material>=9.5.0",
+]
+
+[project.urls]
+Homepage = "https://aexsalomao.github.io/sabia"
+Documentation = "https://aexsalomao.github.io/sabia"
+Repository = "https://github.com/aexsalomao/sabia"
+Issues = "https://github.com/aexsalomao/sabia/issues"
+Changelog = "https://github.com/aexsalomao/sabia/blob/master/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Default run is the fast unit suite; calibration (integration) and benchmarks (slow) are separate
+# gates, run explicitly with `pytest -m integration` / `pytest -m slow`.
+addopts = "-m 'not slow and not integration'"
+markers = [
+    "integration: calibration / cross-subsystem tests (local fixture, no network)",
+    "slow: performance benchmarks (pytest-benchmark)",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "SIM", # flake8-simplify
+]
+ignore = [
+    "B904", # raise-without-from-inside-except — sometimes intentional
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["sabia"]
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+ignore_missing_imports = true
+exclude = ["tests/"]
+
+[tool.coverage.run]
+source = ["sabia"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false

sabia-0.1.0/src/sabia/__init__.py

@@ -0,0 +1,87 @@
+"""
+sabia -- Polars-native technical features for trading pipelines.
+
+Pure functions over OHLCV bars that return strictly-trailing, point-in-time-correct ``pl.Expr``
+features. Batch-first, online-ready. See ``FEATURES.md`` for the full specification.
+
+    import polars as pl
+    import sabia
+
+    sabia.validate(frame, required=[sabia.Column.CLOSE])
+    df = sabia.compute(frame, sabia.momentum.rsi(period=14), sabia.volatility.vol_yz(window=21))
+
+    reg = sabia.Registry.default()
+    reg.where(lambda s: sabia.Horizon.MEDIUM in s.native_band)
+    reg.available(sabia.DataTier.DAILY)
+
+Time-series features compose as ``pl.Expr`` via ``compute``. Cross-sectional features are two-pass;
+evaluate them through ``sabia.evaluate(frame, feature)`` or the registry.
+"""
+
+from __future__ import annotations
+
+import polars as pl
+
+from sabia import (
+    cross_sectional,
+    distribution,
+    mean_reversion,
+    momentum,
+    normalize,
+    returns,
+    seasonality,
+    trend,
+    volatility,
+    volume,
+)
+from sabia.registry import RegisteredFeature, Registry, evaluate, make_feature
+from sabia.spec import (
+    Column,
+    Cost,
+    DataTier,
+    Family,
+    FeatureSpec,
+    Horizon,
+    Recurrence,
+)
+from sabia.validate import SabiaValidationError, validate
+
+__version__ = "0.1.0"
+
+
+def compute(frame: pl.DataFrame | pl.LazyFrame, *exprs: pl.Expr) -> pl.DataFrame:
+    """Materialize feature expressions into a DataFrame -- a ``select`` over the same expressions.
+
+    For time-series and normalization features (``pl.Expr``). Cross-sectional features are two-pass;
+    use ``evaluate`` (or the registry) for those.
+    """
+    return frame.lazy().select(*exprs).collect()
+
+
+__all__ = [
+    "Column",
+    "Cost",
+    "DataTier",
+    "Family",
+    "FeatureSpec",
+    "Horizon",
+    "RegisteredFeature",
+    "Registry",
+    "Recurrence",
+    "SabiaValidationError",
+    "__version__",
+    "compute",
+    "cross_sectional",
+    "distribution",
+    "evaluate",
+    "make_feature",
+    "mean_reversion",
+    "momentum",
+    "normalize",
+    "returns",
+    "seasonality",
+    "trend",
+    "validate",
+    "volatility",
+    "volume",
+]

sabia-0.1.0/src/sabia/_math.py

@@ -0,0 +1,25 @@
+# Shared expression guards enforcing the no-inf/no-NaN policy (FEATURES.md 3.5): degenerate inputs
+# yield null, never inf or NaN. Used across feature families wherever a divide, log, or sqrt could
+# otherwise escape into downstream math.
+
+from __future__ import annotations
+
+import polars as pl
+
+
+def safe_div(numerator: pl.Expr, denominator: pl.Expr) -> pl.Expr:
+    """``numerator / denominator``, or null where the denominator is zero."""
+    return pl.when(denominator == 0).then(None).otherwise(numerator / denominator)
+
+
+def safe_log(expr: pl.Expr) -> pl.Expr:
+    """Natural log, or null where the argument is non-positive (log-domain breach)."""
+    return pl.when(expr <= 0).then(None).otherwise(expr.log())
+
+
+def safe_sqrt(expr: pl.Expr) -> pl.Expr:
+    """Square root, or null where the argument is negative."""
+    return pl.when(expr < 0).then(None).otherwise(expr.sqrt())
+
+
+__all__ = ["safe_div", "safe_log", "safe_sqrt"]

sabia-0.1.0/src/sabia/cross_sectional.py

@@ -0,0 +1,94 @@
+# Cross-sectional family: rank / standardize a per-symbol signal across the universe at each
+# timestamp. Evaluated in two passes (registry.evaluate): the per-symbol SIGNAL (trailing,
+# .over(symbol)) is materialized first, then the cross-sectional REDUCTION runs within each
+# timestamp slice (.over(timestamp)) -- Polars cannot nest those two groupings in one expression.
+# The frame must carry the complete cross-section at each timestamp (validate cross_sectional=True).
+
+from __future__ import annotations
+
+from functools import partial
+
+import polars as pl
+
+from sabia._math import safe_log
+from sabia.normalize import xs_rank, xs_zscore
+from sabia.registry import XS_SIGNAL_COLUMN, RegisteredFeature, make_feature
+from sabia.spec import Column, Cost, Family, Horizon, Recurrence
+
+
+def momentum_signal(
+    close: str = Column.CLOSE, *, window: int, symbol: str = Column.SYMBOL
+) -> pl.Expr:
+    """Per-symbol ``window``-bar log-return signal (the input to a cross-sectional reduction)."""
+    return safe_log(pl.col(close) / pl.col(close).shift(window)).over(symbol)
+
+
+def volatility_signal(
+    close: str = Column.CLOSE, *, window: int, symbol: str = Column.SYMBOL
+) -> pl.Expr:
+    """Per-symbol realized-volatility signal over ``window`` bars."""
+    log_return = safe_log(pl.col(close) / pl.col(close).shift(1))
+    return log_return.rolling_std(window, min_samples=window).over(symbol)
+
+
+def _xs_rank(name: str, timestamp: str = Column.TIMESTAMP) -> pl.Expr:
+    return xs_rank(pl.col(XS_SIGNAL_COLUMN), over=timestamp).alias(name)
+
+
+def _xs_zscore(name: str, timestamp: str = Column.TIMESTAMP) -> pl.Expr:
+    return xs_zscore(pl.col(XS_SIGNAL_COLUMN), over=timestamp).alias(name)
+
+
+FEATURES: tuple[RegisteredFeature, ...] = (
+    make_feature(
+        momentum_signal,
+        build=partial(_xs_rank, "xs_rank_mom_252"),
+        signal=partial(momentum_signal, window=252),
+        name="xs_rank_mom_252",
+        family=Family.CROSS_SECTIONAL,
+        native_band=(Horizon.LONG,),
+        lookback=252,
+        min_history=253,
+        recurrence=Recurrence.FINITE,
+        effective_warmup=253,
+        cost_class=Cost.LINEAR,
+        inputs=(Column.CLOSE,),
+        citation="Jegadeesh & Titman (1993)",
+        params={"window": 252, "reduction": "rank"},
+    ),
+    make_feature(
+        momentum_signal,
+        build=partial(_xs_zscore, "xs_zscore_ret_21"),
+        signal=partial(momentum_signal, window=21),
+        name="xs_zscore_ret_21",
+        family=Family.CROSS_SECTIONAL,
+        native_band=(Horizon.MEDIUM,),
+        lookback=21,
+        min_history=22,
+        recurrence=Recurrence.FINITE,
+        effective_warmup=22,
+        cost_class=Cost.LINEAR,
+        inputs=(Column.CLOSE,),
+        citation="cross-sectional relative strength",
+        params={"window": 21, "reduction": "zscore"},
+    ),
+    make_feature(
+        volatility_signal,
+        build=partial(_xs_rank, "xs_rank_vol_63"),
+        signal=partial(volatility_signal, window=63),
+        name="xs_rank_vol_63",
+        family=Family.CROSS_SECTIONAL,
+        native_band=(Horizon.MEDIUM,),
+        lookback=63,
+        min_history=64,
+        recurrence=Recurrence.FINITE,
+        effective_warmup=64,
+        cost_class=Cost.LINEAR,
+        inputs=(Column.CLOSE,),
+        citation="low-volatility anomaly",
+        params={"window": 63, "reduction": "rank"},
+    ),
+)
+
+
+__all__ = ["FEATURES", "momentum_signal", "volatility_signal"]

sabia-0.1.0/src/sabia/distribution.py

@@ -0,0 +1,97 @@
+# Distribution family: rolling shape and downside moments of the return distribution. All FINITE,
+# strictly trailing, panel-safe via .over(symbol). Zero-variance windows yield null, never NaN.
+
+from __future__ import annotations
+
+from functools import partial
+
+import polars as pl
+
+from sabia._math import safe_log, safe_sqrt
+from sabia.registry import RegisteredFeature, make_feature
+from sabia.spec import Column, Cost, Family, Horizon, Recurrence
+
+_BANDS = (Horizon.SHORT, Horizon.MEDIUM)
+
+
+def _log_return(close: str) -> pl.Expr:
+    return safe_log(pl.col(close) / pl.col(close).shift(1))
+
+
+def skew(close: str = Column.CLOSE, *, window: int = 63, symbol: str = Column.SYMBOL) -> pl.Expr:
+    """Rolling skewness of log returns over ``window`` bars. FINITE. A flat window yields null."""
+    value = _log_return(close).rolling_skew(window, min_samples=window).fill_nan(None)
+    return value.over(symbol).alias(f"skew_{window}")
+
+
+def kurtosis(
+    close: str = Column.CLOSE, *, window: int = 63, symbol: str = Column.SYMBOL
+) -> pl.Expr:
+    """Rolling excess kurtosis of log returns over ``window`` bars. FINITE. Flat window -> null."""
+    value = _log_return(close).rolling_kurtosis(window, min_samples=window).fill_nan(None)
+    return value.over(symbol).alias(f"kurtosis_{window}")
+
+
+def downside_dev(
+    close: str = Column.CLOSE, *, window: int = 21, symbol: str = Column.SYMBOL
+) -> pl.Expr:
+    """Downside deviation: RMS of negative log returns over ``window`` bars. FINITE.
+
+    The semivariance behind the Sortino ratio -- only losses contribute. Citation: Sortino (1991).
+    """
+    # clip (not min_horizontal) so a null return stays null instead of being imputed to 0.
+    downside = _log_return(close).clip(upper_bound=0.0)
+    variance = (downside**2).rolling_mean(window, min_samples=window)
+    return safe_sqrt(variance).over(symbol).alias(f"downside_dev_{window}")
+
+
+FEATURES: tuple[RegisteredFeature, ...] = (
+    make_feature(
+        skew,
+        build=partial(skew, window=63),
+        name="skew_63",
+        family=Family.DISTRIBUTION,
+        native_band=_BANDS,
+        lookback=63,
+        min_history=64,
+        recurrence=Recurrence.FINITE,
+        effective_warmup=64,
+        cost_class=Cost.LINEAR,
+        inputs=(Column.CLOSE,),
+        citation="rolling third moment",
+        params={"window": 63},
+    ),
+    make_feature(
+        kurtosis,
+        build=partial(kurtosis, window=63),
+        name="kurtosis_63",
+        family=Family.DISTRIBUTION,
+        native_band=_BANDS,
+        lookback=63,
+        min_history=64,
+        recurrence=Recurrence.FINITE,
+        effective_warmup=64,
+        cost_class=Cost.LINEAR,
+        inputs=(Column.CLOSE,),
+        citation="rolling fourth moment",
+        params={"window": 63},
+    ),
+    make_feature(
+        downside_dev,
+        build=partial(downside_dev, window=21),
+        name="downside_dev_21",
+        family=Family.DISTRIBUTION,
+        native_band=_BANDS,
+        lookback=21,
+        min_history=22,
+        recurrence=Recurrence.FINITE,
+        effective_warmup=22,
+        cost_class=Cost.LINEAR,
+        inputs=(Column.CLOSE,),
+        citation="Sortino (1991)",
+        params={"window": 21},
+    ),
+)
+
+
+__all__ = ["FEATURES", "downside_dev", "kurtosis", "skew"]