v0.3.0: add live options screener endpoint

Add fa.screener() method wrapping POST /v1/screener/live. Supports
filters (recursive AND/OR groups, cascading on expiries/strikes/contracts),
sort, select, formulas, limit, offset. Growth tier gets the 10-symbol
universe; Alpha tier adds ~250 symbols, formulas, and harvest/dealer-flow
scores.

Bump version to 0.3.0. Add SEO keywords (options-screener, VRP,
harvest-score, vol-selling, etc.).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: tdobrowolski1

README.md

@@ -5,7 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/FlashAlpha-lab/flashalpha-python/actions/workflows/ci.yml/badge.svg)](https://github.com/FlashAlpha-lab/flashalpha-python/actions/workflows/ci.yml)
 
-**Python client for the FlashAlpha options analytics API.** Access real-time gamma exposure (GEX), delta exposure (DEX), vanna exposure (VEX), charm exposure (CHEX), 0DTE analytics, Black-Scholes greeks, implied volatility, volatility surfaces, dealer positioning, Kelly criterion sizing, and more — all from Python.
+**Python client for the FlashAlpha options analytics API.** Access a **live options screener** (filter/rank symbols by gamma exposure, VRP, IV, greeks, harvest scores, and custom formulas), real-time gamma exposure (GEX), delta exposure (DEX), vanna exposure (VEX), charm exposure (CHEX), 0DTE analytics, Black-Scholes greeks, implied volatility, volatility surfaces, dealer positioning, Kelly criterion sizing, and more — all from Python.
 
 ```bash
 pip install flashalpha
@@ -31,6 +31,45 @@ Get your free API key at [flashalpha.com](https://flashalpha.com) — no credit
 
 ## Features
 
+### Live Options Screener
+
+Filter and rank symbols in real time across your universe by gamma exposure,
+VRP, implied volatility, greeks, harvest scores, dealer flow risk, and custom
+formulas. Data is live from an in-memory store refreshed every 5-10 seconds.
+
+```python
+# Harvestable VRP setups with low dealer flow risk
+result = fa.screener(
+    filters={
+        "op": "and",
+        "conditions": [
+            {"field": "regime", "operator": "eq", "value": "positive_gamma"},
+            {"field": "vrp_regime", "operator": "eq", "value": "harvestable"},
+            {"field": "dealer_flow_risk", "operator": "lte", "value": 40},
+            {"field": "harvest_score", "operator": "gte", "value": 65},
+        ],
+    },
+    sort=[{"field": "harvest_score", "direction": "desc"}],
+    select=["symbol", "price", "harvest_score", "dealer_flow_risk"],
+)
+for row in result["data"]:
+    print(f"{row['symbol']}: score={row['harvest_score']} risk={row['dealer_flow_risk']}")
+
+# Custom formula — rank by IV premium over realized vol
+result = fa.screener(
+    formulas=[{"alias": "iv_premium", "expression": "atm_iv - rv_20d"}],
+    sort=[{"formula": "iv_premium", "direction": "desc"}],
+    select=["symbol", "atm_iv", "rv_20d", "iv_premium"],
+    limit=20,
+)
+```
+
+Cascading filters on expiries, strikes, and contracts (e.g. `expiries.days_to_expiry`,
+`strikes.call_oi`, `contracts.delta`) trim the tree at each level and return only the
+matching subtree. See the [Screener spec](https://flashalpha.com/docs/lab-api-screener)
+and [cookbook](https://flashalpha.com/docs/lab-api-screener-cookbook) for all fields,
+operators, and recipes.
+
 ### Options Exposure Analytics
 
 Gamma exposure, delta exposure, vanna exposure, and charm exposure by strike. See where dealers are positioned and how they need to hedge.
@@ -202,6 +241,7 @@ Get your API key at **[flashalpha.com](https://flashalpha.com)**
 | `fa.greeks(...)` | BSM greeks (1st, 2nd, 3rd order) | Free+ |
 | `fa.iv(...)` | Implied volatility solver | Free+ |
 | `fa.kelly(...)` | Kelly criterion sizing | Growth+ |
+| `fa.screener(...)` | **Live options screener** — filter/rank by GEX, VRP, IV, greeks, formulas | Growth+ |
 | `fa.volatility(symbol)` | Comprehensive volatility analytics | Growth+ |
 | `fa.adv_volatility(symbol)` | SVI, variance surface, arb detection | Alpha+ |
 | `fa.tickers()` | All available stock tickers | Free+ |
@@ -210,14 +250,24 @@ Get your API key at **[flashalpha.com](https://flashalpha.com)**
 | `fa.account()` | Account info and quota | Free+ |
 | `fa.health()` | Health check | Public |
 
+## Other SDKs
+
+| Language | Package | Repository |
+|----------|---------|------------|
+| JavaScript | `npm i flashalpha` | [flashalpha-js](https://github.com/FlashAlpha-lab/flashalpha-js) |
+| .NET | `dotnet add package FlashAlpha` | [flashalpha-dotnet](https://github.com/FlashAlpha-lab/flashalpha-dotnet) |
+| Java | Maven Central | [flashalpha-java](https://github.com/FlashAlpha-lab/flashalpha-java) |
+| Go | `go get github.com/FlashAlpha-lab/flashalpha-go` | [flashalpha-go](https://github.com/FlashAlpha-lab/flashalpha-go) |
+| MCP | Claude / LLM tool server | [flashalpha-mcp](https://github.com/FlashAlpha-lab/flashalpha-mcp) |
+
 ## Links
 
 - [FlashAlpha](https://flashalpha.com) — API keys, docs, pricing
 - [API Documentation](https://flashalpha.com/docs)
+- [Examples](https://github.com/FlashAlpha-lab/flashalpha-examples) — runnable tutorials
 - [GEX Explained](https://github.com/FlashAlpha-lab/gex-explained) — gamma exposure theory and code
 - [0DTE Options Analytics](https://github.com/FlashAlpha-lab/0dte-options-analytics) — 0DTE pin risk, expected move, dealer hedging
 - [Volatility Surface Python](https://github.com/FlashAlpha-lab/volatility-surface-python) — SVI calibration, variance swap, skew analysis
-- [Examples](https://github.com/FlashAlpha-lab/flashalpha-examples) — runnable tutorials
 - [Awesome Options Analytics](https://github.com/FlashAlpha-lab/awesome-options-analytics) — curated resource list
 
 ## License

pyproject.toml

@@ -4,14 +4,16 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flashalpha"
-version = "0.2.1"
-description = "Python SDK for the FlashAlpha options analytics API — gamma exposure (GEX), delta, vanna, charm, greeks, 0DTE analytics, volatility surfaces, and more."
+version = "0.3.0"
+description = "Python SDK for the FlashAlpha options analytics API — live options screener, gamma exposure (GEX), VRP, delta, vanna, charm, greeks, 0DTE analytics, volatility surfaces, and more."
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
 authors = [{ name = "FlashAlpha", email = "tom@flashalpha.com" }]
 keywords = [
     "options",
+    "options screener",
+    "live options screener",
     "gamma exposure",
     "gex",
     "greeks",
@@ -34,6 +36,12 @@ keywords = [
     "vol surface",
     "SVI",
     "variance swap",
+    "variance risk premium",
+    "VRP",
+    "harvest score",
+    "short vol",
+    "vol selling",
+    "dealer flow",
 ]
 classifiers = [
     "Development Status :: 3 - Alpha",

src/flashalpha/__init__.py

@@ -10,7 +10,7 @@
     TierRestrictedError,
 )
 
-__version__ = "0.2.1"
+__version__ = "0.3.0"
 __all__ = [
     "FlashAlpha",
     "FlashAlphaError",

src/flashalpha/client.py

@@ -45,6 +45,11 @@ def _get(self, path: str, params: dict[str, Any] | None = None) -> dict:
         resp = self._session.get(url, params=params, timeout=self.timeout)
         return self._handle(resp)
 
+    def _post(self, path: str, json_body: dict[str, Any] | None = None) -> dict:
+        url = f"{self.base_url}{path}"
+        resp = self._session.post(url, json=json_body, timeout=self.timeout)
+        return self._handle(resp)
+
     def _handle(self, resp: requests.Response) -> dict:
         if resp.status_code == 200:
             return resp.json()
@@ -294,6 +299,84 @@ def symbols(self) -> dict:
         """Currently queried symbols with live data."""
         return self._get("/v1/symbols")
 
+    # ── Screener ────────────────────────────────────────────────────
+
+    def screener(
+        self,
+        *,
+        filters: dict[str, Any] | None = None,
+        sort: list[dict[str, Any]] | None = None,
+        select: list[str] | None = None,
+        formulas: list[dict[str, str]] | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> dict:
+        """Live options screener — filter/rank symbols by gamma exposure, VRP,
+        volatility, greeks, and more.
+
+        Powered by an in-memory store updated every 5-10s from live market data.
+        Growth: 10-symbol universe, up to 10 rows. Alpha: ~250 symbols, up to 50
+        rows, formulas, and harvest/dealer-flow-risk scores.
+
+        Parameters
+        ----------
+        filters : dict, optional
+            Recursive filter tree. Leaf: {"field": "atm_iv", "operator": "gte",
+            "value": 20}. Group: {"op": "and", "conditions": [...]}. Supports
+            dotted prefixes `expiries.X`, `strikes.X`, `contracts.X` for
+            cascading filters.
+        sort : list of dict, optional
+            Sort specs (primary first), e.g.
+            [{"field": "harvest_score", "direction": "desc"}].
+            Also accepts {"formula": "alias_name", ...}.
+        select : list of str, optional
+            Field names to return, or ["*"] for the full flat object.
+        formulas : list of dict, optional
+            Computed fields (Alpha only), e.g.
+            [{"alias": "vrp_ratio", "expression": "atm_iv / rv_20d"}].
+        limit : int, optional
+            Row cap. 1-10 on Growth, 1-50 on Alpha. Default 50.
+        offset : int, optional
+            Pagination offset (Alpha only).
+
+        Returns
+        -------
+        dict
+            {"meta": {"total_count": ..., "tier": ..., ...},
+             "data": [{"symbol": ..., ...}, ...]}
+
+        Examples
+        --------
+        Harvestable VRP screen:
+
+        >>> fa.screener(
+        ...     filters={
+        ...         "op": "and",
+        ...         "conditions": [
+        ...             {"field": "regime", "operator": "eq", "value": "positive_gamma"},
+        ...             {"field": "vrp_regime", "operator": "eq", "value": "harvestable"},
+        ...             {"field": "harvest_score", "operator": "gte", "value": 65},
+        ...         ],
+        ...     },
+        ...     sort=[{"field": "harvest_score", "direction": "desc"}],
+        ...     select=["symbol", "price", "harvest_score", "dealer_flow_risk"],
+        ... )
+        """
+        body: dict[str, Any] = {}
+        if filters is not None:
+            body["filters"] = filters
+        if sort is not None:
+            body["sort"] = sort
+        if select is not None:
+            body["select"] = select
+        if formulas is not None:
+            body["formulas"] = formulas
+        if limit is not None:
+            body["limit"] = limit
+        if offset is not None:
+            body["offset"] = offset
+        return self._post("/v1/screener/live", body)
+
     # ── Account & System ────────────────────────────────────────────
 
     def account(self) -> dict:

tests/test_client.py

@@ -321,6 +321,61 @@ def test_health(fa):
     assert result["status"] == "Healthy"
 
 
+# ── Screener ───────────────────────────────────────────────────────
+
+
+@responses.activate
+def test_screener_empty(fa):
+    payload = {
+        "meta": {"total_count": 10, "returned_count": 10, "tier": "growth"},
+        "data": [{"symbol": "SPY", "price": 656.01}],
+    }
+    responses.post(f"{BASE}/v1/screener/live", json=payload)
+    result = fa.screener()
+    assert result["meta"]["tier"] == "growth"
+    assert result["data"][0]["symbol"] == "SPY"
+
+
+@responses.activate
+def test_screener_with_filters(fa):
+    payload = {"meta": {"total_count": 2, "tier": "alpha"}, "data": []}
+    responses.post(f"{BASE}/v1/screener/live", json=payload)
+    fa.screener(
+        filters={
+            "op": "and",
+            "conditions": [
+                {"field": "regime", "operator": "eq", "value": "positive_gamma"},
+                {"field": "harvest_score", "operator": "gte", "value": 65},
+            ],
+        },
+        sort=[{"field": "harvest_score", "direction": "desc"}],
+        select=["symbol", "price", "harvest_score"],
+        limit=20,
+    )
+    # Verify request body
+    import json as _json
+    body = _json.loads(responses.calls[0].request.body)
+    assert body["filters"]["op"] == "and"
+    assert len(body["filters"]["conditions"]) == 2
+    assert body["limit"] == 20
+    assert body["select"] == ["symbol", "price", "harvest_score"]
+
+
+@responses.activate
+def test_screener_with_formulas(fa):
+    payload = {"meta": {"total_count": 1, "tier": "alpha"}, "data": []}
+    responses.post(f"{BASE}/v1/screener/live", json=payload)
+    fa.screener(
+        formulas=[{"alias": "vrp_ratio", "expression": "atm_iv / rv_20d"}],
+        filters={"formula": "vrp_ratio", "operator": "gte", "value": 1.2},
+        sort=[{"formula": "vrp_ratio", "direction": "desc"}],
+    )
+    import json as _json
+    body = _json.loads(responses.calls[0].request.body)
+    assert body["formulas"][0]["alias"] == "vrp_ratio"
+    assert body["filters"]["formula"] == "vrp_ratio"
+
+
 # ── Client config ──────────────────────────────────────────────────