Add feature helpers and insights to Python client

Author: darshild1024-cpu

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.0] - 2025-12-28
+
+### Added
+- Feature helpers: `add_features()` for lags, rolling stats, MoM/YoY %, and z-scores
+- ML-ready bundles: `get_ml_ready()` to fetch multiple series, align dates, impute gaps, and add per-series features
+- Lightweight insights: `get_insight()` returns summary text with latest value, MoM/YoY changes, volatility, and trend
+- Semantic search option: `search(..., mode="semantic")` (where supported by the API)
+- Documentation updates for the new helpers and quotas mapped to existing plans
+
+### Changed
+- Expose new helpers via top-level package; version bump to 0.2.0
+- README updated with examples for features, insights, ML-ready bundles, and search modes
+
 ## [0.1.1] - 2025-12-17
 
 ### Fixed

README.md

@@ -111,6 +111,7 @@ Search for datasets by keyword.
 - `query` (str): Search term (searches titles, descriptions, IDs)
 - `limit` (int): Max results to return (default: `10`, max: `10`)
 - `offset` (int): Pagination offset (default: `0`)
+- `mode` (str): `"keyword"` (default) or `"semantic"` (where supported by API)
 
 **Returns:** `pd.DataFrame` with columns: `id`, `slug`, `title`, `description`, `provider`, `frequency`, `start_date`, `end_date`, `last_updated`
 
@@ -127,6 +128,54 @@ print(results[["id", "title", "provider"]])
 
 ---
 
+### Feature Engineering Helpers
+
+#### `add_features(series, lags=(1,3,12), windows=(3,6,12), include=None, dropna=False)`
+
+Generate common modeling features (lags, rolling stats, MoM/YoY %, z-scores) for a single series.
+
+```python
+df = iq.add_features("fred-cpi", lags=[1, 3, 12], windows=[3, 12])
+print(df[["value", "value_yoy_pct", "value_mom_pct", "value_lag_1"]].tail())
+```
+
+---
+
+### Lightweight Insights
+
+#### `get_insight(series, window="1y")`
+
+Return a small dict with summary text + key metrics (latest value, MoM, YoY, volatility, trend).
+
+```python
+insight = iq.get_insight("fred-cpi", window="1y")
+print(insight["summary"])
+# fred-cpi: latest 311.17 on 2023-12-01 | +0.24% vs prior | +3.12% YoY | trend upward | volatility (std) 1.23
+```
+
+---
+
+### ML-Ready Bundles
+
+#### `get_ml_ready(series_ids, align="inner", impute="ffill+median", features="default")`
+
+Fetch multiple series, align on date, impute gaps, and add per-series features (lags, rolling stats, MoM/YoY %, z-score).
+
+```python
+df = iq.get_ml_ready(
+    ["fred-cpi", "fred-gdp"],
+    align="inner",
+    impute="ffill+median",
+    features="default",
+    lags=[1, 3, 12],
+    windows=[3, 12],
+)
+
+print(df.head())
+```
+
+---
+
 ### Configuration
 
 #### `set_api_key(api_key)`

datasetiq/__init__.py

@@ -21,12 +21,13 @@
     - Pricing: https://www.datasetiq.com/pricing
 """
 
-__version__ = "0.1.2"
+__version__ = "0.2.0"
 
 # Public API exports
 from .client import get, search
 from .config import configure, set_api_key
 from .cache import clear as clear_cache, get_cache_size
+from .features import add_features, get_insight, get_ml_ready
 
 # Exception exports (for type checking)
 from .exceptions import (
@@ -45,6 +46,9 @@
     # Core functions
     "get",
     "search",
+    "add_features",
+    "get_insight",
+    "get_ml_ready",
     "configure",
     "set_api_key",
     # Cache management

datasetiq/client.py

@@ -402,6 +402,7 @@ def search(
     query: str,
     limit: int = 10,
     offset: int = 0,
+    mode: str = "keyword",
 ) -> pd.DataFrame:
     """
     Search for datasets by keyword.
@@ -410,6 +411,7 @@ def search(
         query: Search query (searches titles, descriptions, IDs)
         limit: Maximum results to return (default: 10, max: 10)
         offset: Pagination offset (default: 0)
+        mode: Search mode ('keyword' default, or 'semantic' where supported)
     
     Returns:
         DataFrame with columns: id, slug, title, description, provider,
@@ -438,7 +440,7 @@ def search(
 
     # Make request
     url = f"{config.base_url}/search"
-    params = {"q": query, "limit": min(limit, 10), "offset": offset}
+    params = {"q": query, "limit": min(limit, 10), "offset": offset, "mode": mode}
 
     response = _make_request_with_retry("GET", url, headers=headers, params=params)
     result = response.json()