scanlang 0.1.0__tar.gz

scanlang-0.1.0/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 Volker Lorrmann

scanlang-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: scanlang
+Version: 0.1.0
+Summary: Screener DSL and scan compiler: signal definitions -> polars/duckdb pushdown filters.
+Keywords: screener,scanner,stock-screening,polars,duckdb,finance
+Author: Volker Lorrmann
+Author-email: Volker Lorrmann <volker.lorrmann@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Dist: polars>=1.44.0
+Requires-Dist: ta-lib>=0.7.1 ; extra == 'talib'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/legout/scanlang
+Project-URL: Repository, https://github.com/legout/scanlang
+Project-URL: Issues, https://github.com/legout/scanlang/issues
+Provides-Extra: talib
+Description-Content-Type: text/markdown
+
+# scanlang
+
+Screener DSL and scan compiler: signal definitions -> polars pushdown filters.
+
+A scan definition is a plain dict — JSON from a UI, a Python literal from a
+notebook — that `scanlang` compiles into a single validated polars predicate.
+There is no string interpolation, so there is no injection surface. Filters
+run on any eager `DataFrame` or lazy `LazyFrame`; window semantics
+(indicators, crosses) are computed per partition, so 10 symbols or 10,000
+behave the same.
+
+Status: v0.1. The IR is frozen — see `docs/IR_FREEZE.md` for the exact
+contract (additive changes only). Consumers: marketdata-screens (Lab UI),
+REPL, jupyter/marimo.
+
+## Install
+
+```sh
+uv add scanlang          # or: pip install scanlang
+```
+
+Requires Python >= 3.11 and polars >= 1.44. The optional `talib` extra
+(`uv add scanlang --optional talib`) is reserved for a future value-parity
+indicator module.
+
+## Quickstart
+
+`score_bars` turns OHLCV bars into one scored row per symbol; `apply`
+filters/orders/limits that frame with a scan definition. (Data setup elided —
+full runnable version in `docs/examples/01_quickstart.py`.)
+
+```python
+>>> from scanlang import apply, compile, score_bars, validate
+>>> scored = score_bars(bars.lazy()).collect()   # lazy in, lazy out — collect at your edge
+>>> scored.select("symbol", "close", "score", "phase")
+shape: (2, 4)
+┌────────┬───────┬───────┬───────┐
+│ symbol ┆ close ┆ score ┆ phase │
+│ ---    ┆ ---   ┆ ---   ┆ ---   │
+│ str    ┆ f64   ┆ i16   ┆ str   │
+╞════════╪═══════╪═══════╪═══════╡
+│ AAA    ┆ 69.0  ┆ 60    ┆ BASE  │
+│ BBB    ┆ 1.0   ┆ 20    ┆ NONE  │
+└────────┴───────┴───────┴───────┘
+```
+
+A scan definition is a plain dict. `validate` returns `[]` when it's valid;
+`apply` runs it; `compile` hands you the bare polars expression:
+
+```python
+>>> scan_def = {
+...     "filters": [
+...         {"property": "score", "op": ">=", "value": 40},
+...         {"any": [
+...             {"property": "phase", "op": "in", "value": ["BREAKOUT", "TREND"]},
+...             {"not": {"property": "phase", "op": "==", "value": "NONE"}},
+...         ]},
+...     ],
+...     "order_by": [{"property": "score", "dir": "desc"}],
+...     "limit": 5,
+... }
+>>> validate(scan_def)
+[]
+>>> apply(scored, scan_def).select("symbol", "score", "phase")
+shape: (1, 3)
+┌────────┬───────┬───────┐
+│ symbol ┆ score ┆ phase │
+│ ---    ┆ ---   ┆ ---   │
+│ str    ┆ f64   ┆ i16   ┆ str   │
+╞════════╪═══════╪═══════╡
+│ AAA    ┆ 60    ┆ BASE  │
+└────────┴───────┴───────┘
+>>> expr = compile(scan_def)     # a single polars predicate
+```
+
+(Transcript above is machine-generated from a live REPL —
+`scripts/gen_repl.py` regenerates it.)
+
+## The scan definition (the IR)
+
+Top level: `{"filters": [node, ...], "order_by": [...], "limit": int}` —
+`order_by` and `limit` are optional; a bare `filters` list of leaves is
+valid, so today's flat defs keep working.
+
+**Nodes** nest arbitrarily:
+
+- `{"all": [node, ...]}` — AND (nonempty)
+- `{"any": [node, ...]}` — OR (nonempty)
+- `{"not": {node}}` — unary NOT
+- leaf: `{"property": <prop>, "op": <op>, "value": <operand>}`
+
+**Ops:** `>= <= > < == != between in contains`, plus `cross_above` /
+`cross_below`, which compile to `a > b AND shift(a,1) <= shift(b,1)` over the
+partition (mirrored for below).
+
+**Properties and operands** — a `property` is a catalog column name or a
+computed operand; comparison `value`s are operands too (`in`/`between`/
+`contains` values stay literal-only):
+
+- bare scalar — literal: `60`, `"BREAKOUT"`, `False`
+- `{"col": "close"}` — column ref
+- `{"fn": "sma", "args": [operand, ...]}` — indicator call, args recursive
+  (`sma(rsi(close,14), 5)` is legal)
+- `{"+": [a, b]}`, `"-"`, `"*"`, `"/"` — arithmetic fold (n-ary;
+  `{"-": [x]}` negates)
+
+**Indicators** (`INDICATORS`, extensible by insertion): `sma`, `ema`, `rsi`,
+`atr`, `rmin`, `rmax`, `shift`. Window ops are computed `.over(partition)`
+(default `"symbol"`).
+
+**Validation split:** literal leaves are totally validated — malformed defs
+raise `ValueError` from `compile`/`apply` and return error strings from
+`validate`, never a polars `ComputeError` at filter time. Computed operands
+are structurally validated (known fn, known col, arg types, required cols);
+dtype mismatches there surface at collect time.
+
+**Nulls:** comparisons and `not` on null yield null, and filter drops null
+rows. Documented behavior, not worked around.
+
+## Any LazyFrame, any catalog
+
+`score_bars` output mirrors `PROPERTY_CATALOG`, but nothing is tied to it:
+derive a catalog from any frame's schema and point `partition` at your group
+column.
+
+```python
+>>> import polars as pl
+>>> from scanlang import apply, catalog_from_schema
+>>> lf = bars.rename({"symbol": "ticker"}).lazy()          # rename at your edge
+>>> cat = catalog_from_schema(lf)                          # schema -> catalog
+>>> rsi_hot = {"filters": [{
+...     "property": {"fn": "rsi", "args": [{"col": "close"}, 14]},
+...     "op": ">", "value": 70,
+... }]}
+>>> apply(lf, rsi_hot, catalog=cat, partition="ticker").collect().head(3)
+shape: (3, 3)
+┌────────┬────────────┬───────┐
+│ ticker ┆ session    ┆ close │
+│ ---    ┆ ---        ┆ ---   │
+│ str    ┆ date       ┆ f64   │
+╞════════╪════════════╪═══════╡
+│ AAA    ┆ 2026-01-15 ┆ 24.0  │
+│ AAA    ┆ 2026-01-16 ┆ 25.0  │
+│ AAA    ┆ 2026-01-17 ┆ 26.0  │
+└────────┴────────────┴───────┘
+# 46 rows total: the uptrend clears RSI 70 from bar 15 on; the downtrend never
+```
+
+## API
+
+| Function | Purpose |
+| --- | --- |
+| `compile(scan_def, *, catalog=PROPERTY_CATALOG, partition="symbol")` | scan def -> one polars predicate `Expr` |
+| `validate(scan_def, *, catalog=...)` | `list[str]` of errors; empty = valid |
+| `apply(frame, scan_def, *, catalog=..., partition=...)` | filter + order_by + limit (eager or lazy) |
+| `catalog_from_schema(frame)` | polars schema -> catalog dict; unmapped dtypes skipped |
+| `score_bars(bars, *, min_bars=30, freshness_days=5)` | phase/scan scoring over OHLCV; lazy in, lazy out |
+| `forward_stats` / `backtest_summary` (+ `HORIZONS`) | forward-return evidence for a scan's past runs |
+
+Caller contract: the frame is sorted `(partition, time)` ascending.
+Nonstandard column names are renamed at your edge (`lf.rename({"date": "session"})`).
+
+## Examples
+
+Runnable scripts in `docs/examples/` (each block is a notebook cell if you
+paste into marimo/jupyter):
+
+1. `01_quickstart.py` — score_bars + validate + apply
+2. `02_groups.py` — flat defs, all/any/not groups
+3. `03_computed_operands.py` — col refs, indicators, arithmetic, EMA cross
+4. `04_custom_partition_and_registry.py` — custom catalog + partition, extending INDICATORS
+5. `05_score_and_stats.py` — apply on a LazyFrame + forward_stats/backtest_summary
+
+Run them with `.venv/bin/python docs/examples/01_quickstart.py` (or your
+project interpreter). `docs/EXAMPLES.md` walks through them with real output.
+
+## Docs
+
+- `docs/IR_FREEZE.md` — the frozen IR contract (spec)
+- `docs/EXAMPLES.md` — annotated walkthroughs with verified output
+- `docs/RESEARCH_DUCKDB.md` — why compile targets polars, not SQL
+
+## Development
+
+```sh
+uv sync                                   # create .venv
+.venv/bin/python -m pytest tests/ -q      # tests
+.venv/bin/python -m ruff check src tests  # lint
+```
+
+## License
+
+MIT

scanlang-0.1.0/README.md

@@ -0,0 +1,193 @@
+# scanlang
+
+Screener DSL and scan compiler: signal definitions -> polars pushdown filters.
+
+A scan definition is a plain dict — JSON from a UI, a Python literal from a
+notebook — that `scanlang` compiles into a single validated polars predicate.
+There is no string interpolation, so there is no injection surface. Filters
+run on any eager `DataFrame` or lazy `LazyFrame`; window semantics
+(indicators, crosses) are computed per partition, so 10 symbols or 10,000
+behave the same.
+
+Status: v0.1. The IR is frozen — see `docs/IR_FREEZE.md` for the exact
+contract (additive changes only). Consumers: marketdata-screens (Lab UI),
+REPL, jupyter/marimo.
+
+## Install
+
+```sh
+uv add scanlang          # or: pip install scanlang
+```
+
+Requires Python >= 3.11 and polars >= 1.44. The optional `talib` extra
+(`uv add scanlang --optional talib`) is reserved for a future value-parity
+indicator module.
+
+## Quickstart
+
+`score_bars` turns OHLCV bars into one scored row per symbol; `apply`
+filters/orders/limits that frame with a scan definition. (Data setup elided —
+full runnable version in `docs/examples/01_quickstart.py`.)
+
+```python
+>>> from scanlang import apply, compile, score_bars, validate
+>>> scored = score_bars(bars.lazy()).collect()   # lazy in, lazy out — collect at your edge
+>>> scored.select("symbol", "close", "score", "phase")
+shape: (2, 4)
+┌────────┬───────┬───────┬───────┐
+│ symbol ┆ close ┆ score ┆ phase │
+│ ---    ┆ ---   ┆ ---   ┆ ---   │
+│ str    ┆ f64   ┆ i16   ┆ str   │
+╞════════╪═══════╪═══════╪═══════╡
+│ AAA    ┆ 69.0  ┆ 60    ┆ BASE  │
+│ BBB    ┆ 1.0   ┆ 20    ┆ NONE  │
+└────────┴───────┴───────┴───────┘
+```
+
+A scan definition is a plain dict. `validate` returns `[]` when it's valid;
+`apply` runs it; `compile` hands you the bare polars expression:
+
+```python
+>>> scan_def = {
+...     "filters": [
+...         {"property": "score", "op": ">=", "value": 40},
+...         {"any": [
+...             {"property": "phase", "op": "in", "value": ["BREAKOUT", "TREND"]},
+...             {"not": {"property": "phase", "op": "==", "value": "NONE"}},
+...         ]},
+...     ],
+...     "order_by": [{"property": "score", "dir": "desc"}],
+...     "limit": 5,
+... }
+>>> validate(scan_def)
+[]
+>>> apply(scored, scan_def).select("symbol", "score", "phase")
+shape: (1, 3)
+┌────────┬───────┬───────┐
+│ symbol ┆ score ┆ phase │
+│ ---    ┆ ---   ┆ ---   │
+│ str    ┆ f64   ┆ i16   ┆ str   │
+╞════════╪═══════╪═══════╡
+│ AAA    ┆ 60    ┆ BASE  │
+└────────┴───────┴───────┘
+>>> expr = compile(scan_def)     # a single polars predicate
+```
+
+(Transcript above is machine-generated from a live REPL —
+`scripts/gen_repl.py` regenerates it.)
+
+## The scan definition (the IR)
+
+Top level: `{"filters": [node, ...], "order_by": [...], "limit": int}` —
+`order_by` and `limit` are optional; a bare `filters` list of leaves is
+valid, so today's flat defs keep working.
+
+**Nodes** nest arbitrarily:
+
+- `{"all": [node, ...]}` — AND (nonempty)
+- `{"any": [node, ...]}` — OR (nonempty)
+- `{"not": {node}}` — unary NOT
+- leaf: `{"property": <prop>, "op": <op>, "value": <operand>}`
+
+**Ops:** `>= <= > < == != between in contains`, plus `cross_above` /
+`cross_below`, which compile to `a > b AND shift(a,1) <= shift(b,1)` over the
+partition (mirrored for below).
+
+**Properties and operands** — a `property` is a catalog column name or a
+computed operand; comparison `value`s are operands too (`in`/`between`/
+`contains` values stay literal-only):
+
+- bare scalar — literal: `60`, `"BREAKOUT"`, `False`
+- `{"col": "close"}` — column ref
+- `{"fn": "sma", "args": [operand, ...]}` — indicator call, args recursive
+  (`sma(rsi(close,14), 5)` is legal)
+- `{"+": [a, b]}`, `"-"`, `"*"`, `"/"` — arithmetic fold (n-ary;
+  `{"-": [x]}` negates)
+
+**Indicators** (`INDICATORS`, extensible by insertion): `sma`, `ema`, `rsi`,
+`atr`, `rmin`, `rmax`, `shift`. Window ops are computed `.over(partition)`
+(default `"symbol"`).
+
+**Validation split:** literal leaves are totally validated — malformed defs
+raise `ValueError` from `compile`/`apply` and return error strings from
+`validate`, never a polars `ComputeError` at filter time. Computed operands
+are structurally validated (known fn, known col, arg types, required cols);
+dtype mismatches there surface at collect time.
+
+**Nulls:** comparisons and `not` on null yield null, and filter drops null
+rows. Documented behavior, not worked around.
+
+## Any LazyFrame, any catalog
+
+`score_bars` output mirrors `PROPERTY_CATALOG`, but nothing is tied to it:
+derive a catalog from any frame's schema and point `partition` at your group
+column.
+
+```python
+>>> import polars as pl
+>>> from scanlang import apply, catalog_from_schema
+>>> lf = bars.rename({"symbol": "ticker"}).lazy()          # rename at your edge
+>>> cat = catalog_from_schema(lf)                          # schema -> catalog
+>>> rsi_hot = {"filters": [{
+...     "property": {"fn": "rsi", "args": [{"col": "close"}, 14]},
+...     "op": ">", "value": 70,
+... }]}
+>>> apply(lf, rsi_hot, catalog=cat, partition="ticker").collect().head(3)
+shape: (3, 3)
+┌────────┬────────────┬───────┐
+│ ticker ┆ session    ┆ close │
+│ ---    ┆ ---        ┆ ---   │
+│ str    ┆ date       ┆ f64   │
+╞════════╪════════════╪═══════╡
+│ AAA    ┆ 2026-01-15 ┆ 24.0  │
+│ AAA    ┆ 2026-01-16 ┆ 25.0  │
+│ AAA    ┆ 2026-01-17 ┆ 26.0  │
+└────────┴────────────┴───────┘
+# 46 rows total: the uptrend clears RSI 70 from bar 15 on; the downtrend never
+```
+
+## API
+
+| Function | Purpose |
+| --- | --- |
+| `compile(scan_def, *, catalog=PROPERTY_CATALOG, partition="symbol")` | scan def -> one polars predicate `Expr` |
+| `validate(scan_def, *, catalog=...)` | `list[str]` of errors; empty = valid |
+| `apply(frame, scan_def, *, catalog=..., partition=...)` | filter + order_by + limit (eager or lazy) |
+| `catalog_from_schema(frame)` | polars schema -> catalog dict; unmapped dtypes skipped |
+| `score_bars(bars, *, min_bars=30, freshness_days=5)` | phase/scan scoring over OHLCV; lazy in, lazy out |
+| `forward_stats` / `backtest_summary` (+ `HORIZONS`) | forward-return evidence for a scan's past runs |
+
+Caller contract: the frame is sorted `(partition, time)` ascending.
+Nonstandard column names are renamed at your edge (`lf.rename({"date": "session"})`).
+
+## Examples
+
+Runnable scripts in `docs/examples/` (each block is a notebook cell if you
+paste into marimo/jupyter):
+
+1. `01_quickstart.py` — score_bars + validate + apply
+2. `02_groups.py` — flat defs, all/any/not groups
+3. `03_computed_operands.py` — col refs, indicators, arithmetic, EMA cross
+4. `04_custom_partition_and_registry.py` — custom catalog + partition, extending INDICATORS
+5. `05_score_and_stats.py` — apply on a LazyFrame + forward_stats/backtest_summary
+
+Run them with `.venv/bin/python docs/examples/01_quickstart.py` (or your
+project interpreter). `docs/EXAMPLES.md` walks through them with real output.
+
+## Docs
+
+- `docs/IR_FREEZE.md` — the frozen IR contract (spec)
+- `docs/EXAMPLES.md` — annotated walkthroughs with verified output
+- `docs/RESEARCH_DUCKDB.md` — why compile targets polars, not SQL
+
+## Development
+
+```sh
+uv sync                                   # create .venv
+.venv/bin/python -m pytest tests/ -q      # tests
+.venv/bin/python -m ruff check src tests  # lint
+```
+
+## License
+
+MIT

scanlang-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "scanlang"
+version = "0.1.0"
+description = "Screener DSL and scan compiler: signal definitions -> polars/duckdb pushdown filters."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Volker Lorrmann", email = "volker.lorrmann@gmail.com" }]
+requires-python = ">=3.11"
+keywords = ["screener", "scanner", "stock-screening", "polars", "duckdb", "finance"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = ["polars>=1.44.0"]
+
+[project.urls]
+Homepage = "https://github.com/legout/scanlang"
+Repository = "https://github.com/legout/scanlang"
+Issues = "https://github.com/legout/scanlang/issues"
+
+[project.optional-dependencies]
+talib = ["ta-lib>=0.7.1"]
+
+[dependency-groups]
+dev = ["pytest>=8.0.0", "ruff>=0.8.0"]
+
+[build-system]
+requires = ["uv_build>=0.11.8,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "scanlang"
+module-root = "src"

scanlang-0.1.0/src/scanlang/__init__.py

@@ -0,0 +1,35 @@
+"""Screener DSL and scan compiler.
+
+Signal dict (IR) -> validated polars expressions -> lazy pushdown over any
+LazyFrame source. Optional text DSL parses to the same IR (deferred).
+
+>>> import polars as pl
+>>> from scanlang import compile, apply
+>>> scan_def = {"filters": [{"property": "score", "op": ">=", "value": 50}]}
+"""
+
+from scanlang.compiler import (
+    PROPERTY_CATALOG,
+    apply,
+    catalog_from_schema,
+    compile,
+    validate,
+)
+from scanlang.indicators import INDICATORS
+from scanlang.scoring import score_bars
+from scanlang.stats import HORIZONS, backtest_summary, forward_stats
+
+__all__ = [
+    "HORIZONS",
+    "INDICATORS",
+    "PROPERTY_CATALOG",
+    "apply",
+    "backtest_summary",
+    "catalog_from_schema",
+    "compile",
+    "forward_stats",
+    "score_bars",
+    "validate",
+]
+
+__version__ = "0.1.0"

scanlang-0.1.0/src/scanlang/compiler.py

@@ -0,0 +1,371 @@
+"""Compile scan-definition dicts into polars predicates.
+
+A scan definition is a plain dict (JSON from the Lab UI, REPL, notebooks)::
+
+    {"filters": [
+        {"property": "rsi", "op": ">=", "value": 60},
+        {"property": "phase", "op": "in", "value": ["BREAKOUT"]},
+        {"any": [
+            {"property": "score", "op": "between", "value": [50, 90]},
+            {"not": {"property": "spring", "op": "==", "value": False}},
+        ]},
+        # computed operands: {"col": x} refs, {"fn": name, "args": [...]}
+        # indicators, {"+": [a, b]} arithmetic; scalars stay literals
+        {"property": {"fn": "ema", "args": [{"col": "close"}, 5]},
+         "op": "cross_above",
+         "value": {"fn": "ema", "args": [{"col": "close"}, 20]}},
+     ],
+     "order_by": [{"property": "score", "dir": "desc"}],
+     "limit": 50}
+
+See docs/IR_FREEZE.md for the full contract. Nothing is string-interpolated,
+so there is no injection surface. Validation is total for literal leaves
+(never a polars ComputeError at filter time) and structural for computed
+operands — dtype mismatches there surface at collect time.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import operator
+from functools import reduce
+
+import polars as pl
+
+from scanlang.indicators import INDICATORS
+
+__all__ = ["PROPERTY_CATALOG", "apply", "catalog_from_schema", "compile", "validate"]
+
+# Mirrors scoring.score_bars() output columns. dtype: str, int, float, bool, date.
+PROPERTY_CATALOG: dict[str, dict[str, str]] = {
+    "symbol": {"label": "Symbol", "dtype": "str"},
+    "session": {"label": "Session", "dtype": "date"},
+    "close": {"label": "Close", "dtype": "float"},
+    "score": {"label": "Score", "dtype": "int"},
+    "phase": {"label": "Phase", "dtype": "str"},
+    "vol_ratio": {"label": "Vol Ratio", "dtype": "float"},
+    "atr_ratio": {"label": "ATR Ratio", "dtype": "float"},
+    "rsi": {"label": "RSI", "dtype": "float"},
+    "acc_score": {"label": "Accumulation", "dtype": "float"},
+    "spring": {"label": "Spring", "dtype": "bool"},
+    "ema_stack": {"label": "EMA Stack", "dtype": "bool"},
+    "recent_cross": {"label": "Recent Cross", "dtype": "bool"},
+    "upper_wick_pct": {"label": "Upper Wick %", "dtype": "float"},
+    "near_52w_low": {"label": "Near 52w Low", "dtype": "bool"},
+    "bars": {"label": "Bars", "dtype": "int"},
+}
+
+# op -> builder(lhs, rhs) -> pl.Expr
+_OPS = {
+    ">=": lambda col, v: col >= v,
+    "<=": lambda col, v: col <= v,
+    ">": lambda col, v: col > v,
+    "<": lambda col, v: col < v,
+    "==": lambda col, v: col == v,
+    "!=": lambda col, v: col != v,
+    "between": lambda col, v: col.is_between(v[0], v[1], closed="both"),
+    "in": lambda col, v: col.is_in(v),
+    "contains": lambda col, v: col.str.contains(v, literal=True),
+}
+_CROSS = ("cross_above", "cross_below")
+_ARITH = {
+    "+": operator.add,
+    "-": operator.sub,
+    "*": operator.mul,
+    "/": operator.truediv,
+}
+_LIST_OPS = ("in", "between", "contains")
+
+
+def _ok_date(v) -> bool:
+    if not isinstance(v, str):
+        return False
+    try:
+        dt.date.fromisoformat(v)
+    except ValueError:
+        return False
+    return True
+
+
+def _is(dtype: str, value) -> bool:
+    """JSON value type-check against a catalog dtype (bool is not int)."""
+    if dtype == "int":
+        return isinstance(value, int) and not isinstance(value, bool)
+    if dtype == "float":
+        return isinstance(value, (int, float)) and not isinstance(value, bool)
+    if dtype == "bool":
+        return isinstance(value, bool)
+    return isinstance(value, str)  # str and date both arrive as JSON strings
+
+
+# --- operand parsing -------------------------------------------------------
+
+
+def _operand(spec, *, catalog: dict, partition: str) -> pl.Expr:
+    """Operand dict/scalar -> pl.Expr. Assumes validate() already passed."""
+    if isinstance(spec, dict):
+        if "col" in spec:
+            return pl.col(spec["col"])
+        if "fn" in spec:
+            arg_spec, builder, _req = INDICATORS[spec["fn"]]
+            parsed = [
+                a if tag == "int" else _operand(a, catalog=catalog, partition=partition)
+                for tag, a in zip(arg_spec, spec["args"])
+            ]
+            return builder(*parsed, partition=partition)
+        key = next(k for k in spec if k in _ARITH)
+        vals = [_operand(a, catalog=catalog, partition=partition) for a in spec[key]]
+        if len(vals) == 1:  # unary fold; freeze names only negate: {"-": [x]}
+            return -vals[0] if key == "-" else vals[0]
+        return reduce(_ARITH[key], vals)
+    return pl.lit(spec)
+
+
+def _operand_errors(spec, where: str, catalog: dict, errors: list[str]) -> None:
+    if spec is None:
+        errors.append(f"{where}: operand must not be null")
+    elif isinstance(spec, (bool, int, float, str)):
+        pass  # literal
+    elif not isinstance(spec, dict):
+        errors.append(f"{where}: operand must be scalar, col, fn, or arithmetic, got {spec!r}")
+    elif "col" in spec:
+        name = spec["col"]
+        if not isinstance(name, str) or name not in catalog:
+            errors.append(f"{where}.col: unknown column: {name!r}")
+    elif "fn" in spec:
+        name = spec["fn"]
+        entry = INDICATORS.get(name) if isinstance(name, str) else None
+        if entry is None:
+            errors.append(f"{where}.fn: unknown indicator: {name!r}")
+            return
+        arg_spec, _builder, required = entry
+        args = spec.get("args")
+        if not isinstance(args, list) or len(args) != len(arg_spec):
+            got = len(args) if isinstance(args, list) else args
+            errors.append(f"{where}: {name!r} takes {len(arg_spec)} args, got {got}")
+            return
+        for i, (tag, a) in enumerate(zip(arg_spec, args)):
+            if tag == "int":
+                if not isinstance(a, int) or isinstance(a, bool) or a < 1:
+                    errors.append(f"{where}.args[{i}]: must be an int >= 1, got {a!r}")
+            else:
+                _operand_errors(a, f"{where}.args[{i}]", catalog, errors)
+        for col in required:
+            if col not in catalog:
+                errors.append(f"{where}: indicator {name!r} requires column {col!r}")
+    elif len(ks := [k for k in spec if k in _ARITH]) == 1:
+        vals = spec[ks[0]]
+        if not isinstance(vals, list) or not vals:
+            errors.append(f"{where}.{ks[0]} must be a nonempty list")
+        elif len(vals) == 1 and ks[0] != "-":
+            errors.append(f"{where}.{ks[0]} must have >= 2 operands")
+        else:
+            for i, a in enumerate(vals):
+                _operand_errors(a, f"{where}.{ks[0]}[{i}]", catalog, errors)
+    else:
+        errors.append(f"{where}: operand must be col, fn, or arithmetic, got keys {sorted(spec)}")
+
+
+# --- node validation -------------------------------------------------------
+
+
+def _val_ok(dtype: str, value) -> bool:
+    return _ok_date(value) if dtype == "date" else _is(dtype, value)
+
+
+def _leaf_errors(f, where: str, catalog: dict, errors: list[str]) -> None:
+    prop = f.get("property")
+    op = f.get("op")
+    computed_lhs = isinstance(prop, dict)
+    spec = catalog.get(prop) if isinstance(prop, str) else None
+    if computed_lhs:
+        _operand_errors(prop, f"{where}.property", catalog, errors)
+    elif spec is None:
+        errors.append(f"{where}: unknown property: {prop!r}")
+    if op not in _OPS and op not in _CROSS:
+        errors.append(f"{where}: unknown operator: {op!r}")
+        return
+    value = f.get("value")
+    if op in _CROSS:
+        _operand_errors(value, f"{where}.value", catalog, errors)
+    elif op in _LIST_OPS:
+        if computed_lhs:
+            errors.append(f"{where}: computed left side not supported for {op!r}")
+        if spec is None:
+            return
+        dtype = spec["dtype"]
+        if op == "contains":
+            if dtype != "str" or not isinstance(value, str):
+                errors.append(f"{where}: 'contains' needs a string value on a string property")
+        elif op == "between":
+            if not isinstance(value, (list, tuple)) or len(value) != 2:
+                errors.append(f"{where}: 'between' needs [lo, hi]")
+            elif not all(_val_ok(dtype, v) for v in value):
+                errors.append(f"{where}: 'between' bounds must be {dtype} values")
+        elif not isinstance(value, list) or not value:
+            errors.append(f"{where}: 'in' needs a nonempty list of values")
+        elif not all(_val_ok(dtype, v) for v in value):
+            errors.append(f"{where}: 'in' values must be {dtype} values")
+    elif isinstance(value, dict):
+        _operand_errors(value, f"{where}.value", catalog, errors)
+    elif value is None:
+        errors.append(f"{where}: value must not be null")
+    elif spec is not None and not _val_ok(spec["dtype"], value):
+        dtype = spec["dtype"]
+        if dtype == "date":
+            errors.append(
+                f"{where}: value for {prop!r} (date) must be an ISO date string, got {value!r}"
+            )
+        else:
+            errors.append(f"{where}: value for {prop!r} ({dtype}) must be {dtype}, got {value!r}")
+
+
+def _node_errors(node, where: str, catalog: dict, errors: list[str]) -> None:
+    if not isinstance(node, dict):
+        errors.append(f"{where}: node must be an object, got {node!r}")
+    elif "all" in node or "any" in node:
+        key = "all" if "all" in node else "any"
+        kids = node[key]
+        if not isinstance(kids, list) or not kids:
+            errors.append(f"{where}.{key} must be a nonempty list")
+        else:
+            for i, kid in enumerate(kids):
+                _node_errors(kid, f"{where}.{key}[{i}]", catalog, errors)
+    elif "not" in node:
+        if not isinstance(node["not"], dict):
+            errors.append(f"{where}.not must be an object")
+        else:
+            _node_errors(node["not"], f"{where}.not", catalog, errors)
+    else:
+        _leaf_errors(node, where, catalog, errors)
+
+
+def _collect(scan_def, *, catalog: dict) -> list[str]:
+    """Collect every validation error in the definition (empty list = valid)."""
+    if not isinstance(scan_def, dict):
+        return [f"scan definition must be an object, got {scan_def!r}"]
+    errors: list[str] = []
+    filters = scan_def.get("filters") or []
+    if not isinstance(filters, list):
+        errors.append("filters must be a list")
+    else:
+        for i, node in enumerate(filters):
+            _node_errors(node, f"filters[{i}]", catalog, errors)
+    order_by = scan_def.get("order_by") or []
+    if not isinstance(order_by, list):
+        errors.append("order_by must be a list")
+    else:
+        for ob in order_by:
+            if not isinstance(ob, dict):
+                errors.append(f"order entry must be an object, got {ob!r}")
+                continue
+            if ob.get("property") not in catalog:
+                errors.append(f"unknown property: {ob.get('property')!r}")
+            if ob.get("dir", "asc") not in ("asc", "desc"):
+                errors.append(f"unknown direction: {ob.get('dir')!r}")
+    limit = scan_def.get("limit")
+    if limit is not None and (not isinstance(limit, int) or isinstance(limit, bool) or limit < 0):
+        errors.append("limit must be a nonnegative integer")
+    return errors
+
+
+def validate(scan_def, *, catalog: dict = PROPERTY_CATALOG) -> list[str]:
+    """Return error strings (empty = valid); human-facing, keyed to fields."""
+    return _collect(scan_def, catalog=catalog)
+
+
+# --- compilation -----------------------------------------------------------
+
+
+def _compile_leaf(f, *, catalog: dict, partition: str) -> pl.Expr:
+    prop = f["property"]
+    op = f["op"]
+    lhs = _operand(prop, catalog=catalog, partition=partition) if isinstance(prop, dict) else pl.col(prop)
+    value = f["value"]
+    spec = catalog.get(prop) if isinstance(prop, str) else None
+    if (
+        op in _OPS
+        and spec is not None
+        and spec["dtype"] == "date"
+        and isinstance(value, (str, list, tuple))
+    ):
+        # date literals arrive as ISO strings; parse so polars compares
+        # date-to-date (parseability validated in _leaf_errors)
+        value = (
+            dt.date.fromisoformat(value)
+            if isinstance(value, str)
+            else [dt.date.fromisoformat(v) for v in value]
+        )
+    if op in _CROSS:
+        rhs = _operand(f["value"], catalog=catalog, partition=partition)
+        prev_lhs, prev_rhs = lhs.shift(1).over(partition), rhs.shift(1).over(partition)
+        return (lhs > rhs) & (prev_lhs <= prev_rhs) if op == "cross_above" else (lhs < rhs) & (prev_lhs >= prev_rhs)
+    if op in _LIST_OPS:
+        # in/between/contains values are validated literal-only: raw scalars,
+        # never operand exprs, so the raw value is the compiled form.
+        return _OPS[op](lhs, value)
+    return _OPS[op](lhs, _operand(value, catalog=catalog, partition=partition))
+
+
+def _compile_node(node, *, catalog: dict, partition: str) -> pl.Expr:
+    if "all" in node:
+        return reduce(operator.and_, (_compile_node(n, catalog=catalog, partition=partition) for n in node["all"]))
+    if "any" in node:
+        return reduce(operator.or_, (_compile_node(n, catalog=catalog, partition=partition) for n in node["any"]))
+    if "not" in node:
+        return ~_compile_node(node["not"], catalog=catalog, partition=partition)
+    return _compile_leaf(node, catalog=catalog, partition=partition)
+
+
+def compile(scan_def, *, catalog: dict = PROPERTY_CATALOG, partition: str = "symbol") -> pl.Expr:
+    """AND all top-level filter nodes into one polars predicate expression."""
+    errors = _collect(scan_def, catalog=catalog)
+    if errors:
+        raise ValueError(errors[0])
+    expr = pl.lit(True)
+    for node in scan_def.get("filters") or []:
+        expr = expr & _compile_node(node, catalog=catalog, partition=partition)
+    return expr
+
+
+def apply(frame, scan_def, *, catalog: dict = PROPERTY_CATALOG, partition: str = "symbol"):
+    """Filter + order_by + limit a frame (eager or lazy) by a scan definition."""
+    out = frame.filter(compile(scan_def, catalog=catalog, partition=partition))
+    order_by = scan_def.get("order_by") or []
+    if order_by:
+        keys = [ob["property"] for ob in order_by]
+        dirs = [ob.get("dir", "asc") == "desc" for ob in order_by]
+        out = out.sort(keys, descending=dirs)
+    limit = scan_def.get("limit")
+    if limit is not None:
+        out = out.head(limit)
+    return out
+
+
+# --- catalogs --------------------------------------------------------------
+
+
+def catalog_from_schema(frame) -> dict[str, dict[str, str]]:
+    """polars schema (DataFrame or LazyFrame) -> catalog; unmapped dtypes skipped."""
+    mapping = (
+        (pl.Boolean, "bool"),
+        (pl.Int64, "int"),
+        (pl.Int32, "int"),
+        (pl.Int16, "int"),
+        (pl.Int8, "int"),
+        (pl.UInt64, "int"),
+        (pl.UInt32, "int"),
+        (pl.UInt16, "int"),
+        (pl.UInt8, "int"),
+        (pl.Float64, "float"),
+        (pl.Float32, "float"),
+        (pl.String, "str"),
+        (pl.Date, "date"),
+        (pl.Datetime, "date"),
+    )
+    return {
+        name: {"label": name, "dtype": dtype}
+        for name, dt in frame.collect_schema().items()
+        for base, dtype in mapping
+        if isinstance(dt, base)
+    }

scanlang-0.1.0/src/scanlang/indicators.py

@@ -0,0 +1,71 @@
+"""Indicator registry: name -> (arg_spec, builder, required_cols).
+
+Each entry:
+- ``arg_spec``: tuple with one tag per positional arg — ``"expr"`` (any operand) or
+  ``"int"`` (literal int >= 1).
+- ``builder(*parsed, partition) -> pl.Expr``: polars-native; every window op uses
+  ``.over(partition)``.
+- ``required_cols``: columns that must exist in the catalog (e.g. ``atr`` needs
+  ``high, low, close``).
+
+Extend by inserting entries; this shape is the contract. A future
+``scanlang.talib`` module (pyproject ``talib`` extra) populates the same dict for
+exact-value parity on collected results — it cannot participate in lazy pushdown.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import polars as pl
+
+__all__ = ["INDICATORS"]
+
+
+def _rsi(e: pl.Expr, n: int, partition: str) -> pl.Expr:
+    delta = e.diff().over(partition)
+    gain = delta.clip(lower_bound=0).rolling_mean(n).over(partition)
+    loss = (-delta.clip(upper_bound=0)).rolling_mean(n).over(partition)
+    return (100 - 100 / (1 + gain / loss)).fill_null(50.0)
+
+
+def _atr(n: int, partition: str) -> pl.Expr:
+    pc = pl.col("close").shift(1).over(partition)
+    tr = pl.max_horizontal(
+        pl.col("high") - pl.col("low"),
+        (pl.col("high") - pc).abs(),
+        (pc - pl.col("low")).abs(),
+    )
+    return tr.rolling_mean(n).over(partition)
+
+
+# name -> (arg_spec, builder, required_cols)
+INDICATORS: dict[str, tuple[tuple[str, ...], Callable, tuple[str, ...]]] = {
+    "sma": (
+        ("expr", "int"),
+        lambda e, n, partition: e.rolling_mean(n).over(partition),
+        (),
+    ),
+    "ema": (
+        ("expr", "int"),
+        lambda e, span, partition: e.ewm_mean(span=span, adjust=False).over(partition),
+        (),
+    ),
+    "rsi": (("expr", "int"), _rsi, ()),
+    "atr": (("int",), _atr, ("high", "low", "close")),
+    "rmin": (
+        ("expr", "int"),
+        lambda e, n, partition: e.rolling_min(n).over(partition),
+        (),
+    ),
+    "rmax": (
+        ("expr", "int"),
+        lambda e, n, partition: e.rolling_max(n).over(partition),
+        (),
+    ),
+    "shift": (
+        ("expr", "int"),
+        lambda e, n, partition: e.shift(n).over(partition),
+        (),
+    ),
+}

scanlang-0.1.0/src/scanlang/scoring.py

@@ -0,0 +1,176 @@
+"""Parabolic breakout scoring: vectorized polars over OHLCV bars.
+
+Detects BASE / BREAKOUT / TREND / CLIMAX phases per symbol using EMA
+alignment, ATR expansion, volume confirmation, accumulation, spring
+patterns, and RSI. One lazy polars pass over all symbols.
+
+Input: LazyFrame (eager DataFrame accepted, coerced) with columns
+``symbol, session, open, high, low, close, volume``, sorted
+``symbol, session`` ascending (caller guarantees the sort, caller
+collects at its edge — the return is lazy). Output columns mirror
+``compiler.PROPERTY_CATALOG``.
+
+Composite weights: spring +15, accumulation +10, volume +5/+15, EMA stack
++10/+20, fresh EMA5/20 cross +15, EMA50 rising +10, price>EMA5 +5, ATR
+expansion +10/+15, wide range +5, RSI>70 +5, upper wick +10, near-52w-low
++5. Phase thresholds: CLIMAX >=70 with a blow-off condition, TREND >=60
+with stack+ATR, BREAKOUT >=50 with volume or spring + EMA5>EMA20, BASE >=40.
+"""
+
+from __future__ import annotations
+
+import polars as pl
+
+__all__ = ["FRESHNESS_DAYS", "MIN_BARS", "score_bars"]
+
+# Skip symbols with too little history for ATR/EMA50 to be meaningful.
+MIN_BARS = 30
+# Only score symbols whose latest bar is this close to the lake's max date.
+FRESHNESS_DAYS = 5
+
+
+def score_bars(
+    bars: pl.LazyFrame | pl.DataFrame,
+    *,
+    min_bars: int = MIN_BARS,
+    freshness_days: int = FRESHNESS_DAYS,
+) -> pl.LazyFrame:
+    """Score every symbol's latest bar in ``bars`` and classify its phase."""
+    bars = bars.lazy()
+    c = pl.col
+
+    ind = (
+        bars.with_columns(
+            ema5=c("close").ewm_mean(span=5, adjust=False).over("symbol"),
+            ema20=c("close").ewm_mean(span=20, adjust=False).over("symbol"),
+            ema50=c("close").ewm_mean(span=50, adjust=False).over("symbol"),
+            _pc=c("close").shift(1).over("symbol"),
+            _up=c("close") > c("open"),
+            _dn=c("close") < c("open"),
+            _n=c("close").count().over("symbol"),
+        )
+        .with_columns(
+            _tr=pl.max_horizontal(
+                c("high") - c("low"),
+                (c("high") - c("_pc")).abs(),
+                (c("low") - c("_pc")).abs(),
+            ),
+        )
+        .with_columns(atr=c("_tr").rolling_mean(14).over("symbol"))
+        .with_columns(
+            baseline_atr=c("atr").rolling_mean(20, min_samples=1).over("symbol"),
+            avg_vol=c("volume").cast(pl.Float64).rolling_mean(20, min_samples=1).over("symbol"),
+            _delta=c("close").diff().over("symbol"),
+        )
+        .with_columns(
+            avg_up_vol=pl.when(c("_up"))
+            .then(c("volume").cast(pl.Float64))
+            .otherwise(None)
+            .rolling_mean(20, min_samples=1)
+            .over("symbol"),
+            avg_dn_vol=pl.when(c("_dn"))
+            .then(c("volume").cast(pl.Float64))
+            .otherwise(None)
+            .rolling_mean(20, min_samples=1)
+            .over("symbol"),
+            _gain=c("_delta").clip(lower_bound=0).rolling_mean(14).over("symbol"),
+            _loss=(-c("_delta").clip(upper_bound=0)).rolling_mean(14).over("symbol"),
+        )
+        .with_columns(
+            acc_score=pl.when(c("avg_vol") == 0)
+            .then(0.0)
+            .when(c("_dn").cast(pl.UInt8).rolling_sum(20, min_samples=1).over("symbol") == 0)
+            .then(1.0)
+            .otherwise((c("avg_up_vol").fill_null(0.0) - c("avg_dn_vol").fill_null(0.0)) / c("avg_vol")),
+            rsi=(100 - 100 / (1 + c("_gain") / c("_loss"))).fill_null(50.0),
+            vol_ratio=pl.when(c("avg_vol") > 0).then(c("volume") / c("avg_vol")).otherwise(1.0),
+            atr_ratio=pl.when(c("baseline_atr") > 0)
+            .then(c("atr").fill_null(c("baseline_atr")) / c("baseline_atr"))
+            .otherwise(1.0),
+            _spring=(c("low").shift(1).over("symbol") < c("low").shift(2).over("symbol"))
+            .and_(c("close").shift(1).over("symbol") > c("open").shift(1).over("symbol"))
+            .and_(c("close").shift(1).over("symbol") > c("low").shift(2).over("symbol")),
+            _ema_stack=(c("ema5") > c("ema20")).and_(c("ema20") > c("ema50")),
+            _cross=(c("ema5") > c("ema20")).and_(
+                c("ema5").shift(1).over("symbol") <= c("ema20").shift(1).over("symbol")
+            ),
+        )
+        .with_columns(
+            recent_cross=c("_cross")
+            .fill_null(False)
+            .cast(pl.UInt8)
+            .rolling_sum(5, min_samples=1)
+            .over("symbol")
+            > 0,
+            ema50_rising=c("ema50") > c("ema50").shift(1).over("symbol"),
+            _low52=c("low").rolling_min(252, min_samples=1).over("symbol"),
+            _range=c("high") - c("low"),
+            _last=c("session").max().over("symbol"),
+        )
+        .with_columns(
+            upper_wick_pct=pl.when(c("_range") > 0)
+            .then((c("high") - pl.max_horizontal(c("close"), c("open"))) / c("_range"))
+            .otherwise(0.0),
+            near_52w_low=(c("_low52") > 0).and_(c("close") < c("_low52") * 1.30),
+            is_latest=c("session") == c("_last"),
+        )
+    )
+
+    score = (
+        pl.when(c("_spring")).then(15).otherwise(0)
+        + pl.when(c("acc_score") > 0.10).then(10).otherwise(0)
+        + pl.when(c("vol_ratio") > 1.5).then(15).when(c("vol_ratio") > 1.0).then(5).otherwise(0)
+        + pl.when(c("_ema_stack")).then(20).when(c("ema5") > c("ema20")).then(10).otherwise(0)
+        + pl.when(c("recent_cross")).then(15).otherwise(0)
+        + pl.when(c("ema50_rising")).then(10).otherwise(0)
+        + pl.when(c("close") > c("ema5")).then(5).otherwise(0)
+        + pl.when(c("atr_ratio") > 2.0).then(15).when(c("atr_ratio") > 1.5).then(10).otherwise(0)
+        + pl.when(c("_range") > 2 * c("atr").fill_null(c("baseline_atr"))).then(5).otherwise(0)
+        + pl.when(c("rsi") > 70).then(5).otherwise(0)
+        + pl.when(c("upper_wick_pct") > 0.4).then(10).otherwise(0)
+        + pl.when(c("near_52w_low")).then(5).otherwise(0)
+    )
+
+    return (
+        ind.with_columns(score=score.cast(pl.Int16))
+        .with_columns(
+            phase=pl.when(
+                (c("score") >= 70).and_((c("vol_ratio") > 3).or_(c("atr_ratio") > 2.5).or_(c("rsi") > 85))
+            )
+            .then(pl.lit("CLIMAX"))
+            .when((c("score") >= 60).and_(c("_ema_stack")).and_(c("atr_ratio") > 1.5))
+            .then(pl.lit("TREND"))
+            .when(
+                (c("score") >= 50)
+                .and_((c("vol_ratio") > 1.5).or_(c("_spring")))
+                .and_(c("ema5") > c("ema20"))
+            )
+            .then(pl.lit("BREAKOUT"))
+            .when(c("score") >= 40)
+            .then(pl.lit("BASE"))
+            .otherwise(pl.lit("NONE")),
+        )
+        .filter(c("is_latest"))
+        .filter(c("_n") >= min_bars)
+        # freshness: the symbol's latest bar must be within N days of the
+        # GLOBAL max session in the frame (not its own max — that's always 0)
+        .filter((c("session").max() - c("session")).dt.total_days() <= freshness_days)
+        .select(
+            "symbol",
+            "session",
+            "close",
+            "score",
+            "phase",
+            vol_ratio=c("vol_ratio").round(2),
+            atr_ratio=c("atr_ratio").round(2),
+            rsi=c("rsi").round(1),
+            acc_score=c("acc_score").round(3),
+            spring=c("_spring"),
+            ema_stack=c("_ema_stack"),
+            recent_cross=c("recent_cross"),
+            upper_wick_pct=c("upper_wick_pct").round(2),
+            near_52w_low=c("near_52w_low"),
+            bars=c("_n"),
+        )
+        .sort(["score", "symbol"], descending=[True, False])
+    )

scanlang-0.1.0/src/scanlang/stats.py

@@ -0,0 +1,60 @@
+"""Forward-return evidence for a scan's past runs. Pure — no frame deps."""
+
+from __future__ import annotations
+
+import datetime as dt
+from bisect import bisect_left
+
+__all__ = ["HORIZONS", "backtest_summary", "forward_stats"]
+
+HORIZONS = (("5d", 5), ("10d", 10), ("20d", 20))
+
+
+def forward_stats(
+    sessions: list[dt.date], closes: list[float], ran_on: dt.date
+) -> dict[str, float] | None:
+    """+5/+10/+20d return of the run's entry price vs the latest lake close.
+
+    Entry anchors at the first session on/after ``ran_on`` (a scan picked
+    symbols at that day's close; the next session is the first tradable).
+    ``sessions``/``closes`` are ascending and aligned. Returns None when the
+    20d forward window hasn't elapsed in the lake yet (fresh run) or the run
+    predates the lake window — the caller excludes the run.
+    """
+    i = bisect_left(sessions, ran_on)
+    if i + HORIZONS[-1][1] >= len(closes):
+        return None
+    entry = closes[i]
+    return {label: (closes[i + n] / entry - 1) * 100 for label, n in HORIZONS}
+
+
+def backtest_summary(runs: list[dict], stats_fn) -> dict:
+    """Aggregate forward returns across a scan's runs: hit-rate + avg per horizon.
+
+    ``runs`` are run records (``ran_at`` text + ``symbols`` list).
+    ``stats_fn(symbol, ran_on)`` returns ``{label: return%}`` or None when the
+    symbol has no evaluable bars. Runs whose forward window hasn't elapsed are
+    excluded — caller surfaces "n included / m total".
+    """
+    total = len(runs)
+    picks = 0
+    per: dict[str, list[float]] = {label: [] for label, _ in HORIZONS}
+    for run in runs:
+        ran_on = dt.date.fromisoformat((run["ran_at"] or " ")[:10])
+        for symbol in run["symbols"]:
+            st = stats_fn(symbol, ran_on)
+            if st is None:
+                continue
+            picks += 1
+            for label, ret in st.items():
+                per[label].append(ret)
+    horizons = [
+        (
+            label,
+            100.0 * sum(r > 0 for r in rets) / len(rets) if rets else 0.0,
+            sum(rets) / len(rets) if rets else 0.0,
+            len(rets),
+        )
+        for label, rets in per.items()
+    ]
+    return {"included": picks, "total": total, "horizons": horizons}