bigdata-smart-batching 1.2.0__tar.gz → 1.2.1__tar.gz

{bigdata_smart_batching-1.2.0 → bigdata_smart_batching-1.2.1}/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.1] - 2026-05-12
+
+### Fixed
+
+- Modified README.md file to add latest changes
+
 ## [1.2.0] - 2026-05-12
 
 ### Added

{bigdata_smart_batching-1.2.0 → bigdata_smart_batching-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bigdata-smart-batching
-Version: 1.2.0
+Version: 1.2.1
 Summary: High-performance semantic search with intelligent company grouping and parallel execution
 Project-URL: homepage, https://bigdata.com/api
 Author-email: "Bigdata.com" <support@ravenpack.com>
@@ -29,6 +29,8 @@ This module provides a two-step pipeline for efficient semantic search:
 - **Parallel execution** -- rate-limited concurrent requests with semaphore-controlled concurrency.
 - **Proportional sampling** -- retrieve a percentage of results while preserving the distribution across baskets.
 - **Category filtering** -- restrict searches to specific document categories (news, transcripts, filings, ...).
+- **Sentiment filtering** -- restrict searches to one or more inclusive document-level sentiment ranges.
+- **Throughput controls** -- shared sliding-window rate limiter and concurrency semaphore across all planning HTTP work, with shared exponential backoff on `429` / `403` / timeout retries.
 - **Deterministic plans** -- every request stays within service limits; plans can be saved and replayed.
 - **Scalable** -- handles universes with 10,000+ companies efficiently.
 
@@ -162,6 +164,41 @@ Valid category values are exposed via `VALID_CATEGORY_VALUES` and include:
 `news_public`, `podcasts`, `research`, `research_academic_journals`,
 `research_investment_research`, `transcripts`.
 
+### Sentiment Filtering
+
+Restrict searches to documents whose sentiment falls inside one or more
+inclusive `min` / `max` ranges using the `sentiment` argument. It accepts a
+single `SentimentRange` / dict, or a list of them (multiple disjoint ranges).
+The filter is emitted as `query.filters.sentiment.ranges` on co-mention,
+volume, and search payloads.
+
+```python
+from bigdata_smart_batching import SentimentRange, plan_search
+
+plan = plan_search(
+    universe="id_name_mapping_us_top_3000.csv",
+    start_date="2023-01-01",
+    end_date="2023-12-31",
+    text="earnings revenue profit",
+    sentiment=SentimentRange(min=0.3, max=1.0),
+)
+
+plan = plan_search(
+    universe="id_name_mapping_us_top_3000.csv",
+    start_date="2023-01-01",
+    end_date="2023-12-31",
+    text="earnings revenue profit",
+    sentiment=[
+        {"min": -1.0, "max": -0.5},
+        {"min": 0.5, "max": 1.0},
+    ],
+)
+```
+
+Each range must satisfy `min <= max`. Use
+`validate_sentiment_range(sentiment)` to validate and normalize input into the
+list-of-dicts shape the API expects.
+
 ### Save and Load Plans
 
 ```python
@@ -226,7 +263,10 @@ Step 2: EXECUTION
 | `min_period_days` | `int` | `30` | Minimum days per sub-period |
 | `min_entities_per_basket` | `int` | `1` | Lower bound on entities per basket |
 | `category` | `CategoryFilter \| dict \| None` | `None` | Optional category filter (`mode` + `values`) |
+| `sentiment` | `SentimentRange \| dict \| list \| None` | `None` | Optional sentiment filter: one inclusive `{min, max}` range or a list of disjoint ranges |
 | `content_diversification` | `bool` | `True` | Enable/disable content diversification in ranking |
+| `requests_per_minute` | `int` | `100` | Global rate limit shared across all planning HTTP work (co-mention + volume) |
+| `max_workers` | `int` | `40` | Maximum concurrent in-flight planning requests (shared semaphore) |
 
 ### `execute_search()`
 
@@ -249,6 +289,7 @@ Step 2: EXECUTION
 - `load_universe_from_csv(csv_path)` -- load entity IDs from a CSV only.
 - `save_plan(plan, path)` / `load_plan(path)` -- persist plans as JSON.
 - `validate_category_filter(category)` -- validate and normalize a category filter to the API dict shape.
+- `validate_sentiment_range(sentiment)` -- validate and normalize sentiment range(s) into the list-of-`{min, max}` dicts emitted as `filters.sentiment.ranges`.
 - `build_comention_payload(...)`, `build_volume_payload(...)`, `build_search_query(...)` -- low-level payload builders used by the planner; useful if you need to construct custom requests.
 
 ### Public Types
@@ -256,6 +297,8 @@ Step 2: EXECUTION
 - `CategoryFilter` -- frozen dataclass with `mode: CategoryMode` and `values: tuple[str, ...]`.
 - `CategoryMode` -- `StrEnum` with `INCLUDE` and `EXCLUDE` values.
 - `CategoryFilterInput` -- type alias: `CategoryFilter | dict[str, str | list[str]]`.
+- `SentimentRange` -- frozen dataclass with inclusive `min: float` and `max: float`.
+- `SentimentRangeInput` -- type alias for one `SentimentRange` / `{min, max}` dict, or a non-empty list of either.
 - `UniverseInput` -- type alias: `str | list[str]`.
 - `VALID_CATEGORY_VALUES` -- `frozenset[str]` of allowed category strings.
 
@@ -331,7 +374,7 @@ Ties are resolved using `VOLUME_BUCKET_PRIORITY`: `high > medium > low > very_lo
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for release notes. The package is currently at
-version **1.0.1**.
+version **1.2.0**.
 
 ## License
 

{bigdata_smart_batching-1.2.0 → bigdata_smart_batching-1.2.1}/README.md

@@ -13,6 +13,8 @@ This module provides a two-step pipeline for efficient semantic search:
 - **Parallel execution** -- rate-limited concurrent requests with semaphore-controlled concurrency.
 - **Proportional sampling** -- retrieve a percentage of results while preserving the distribution across baskets.
 - **Category filtering** -- restrict searches to specific document categories (news, transcripts, filings, ...).
+- **Sentiment filtering** -- restrict searches to one or more inclusive document-level sentiment ranges.
+- **Throughput controls** -- shared sliding-window rate limiter and concurrency semaphore across all planning HTTP work, with shared exponential backoff on `429` / `403` / timeout retries.
 - **Deterministic plans** -- every request stays within service limits; plans can be saved and replayed.
 - **Scalable** -- handles universes with 10,000+ companies efficiently.
 
@@ -146,6 +148,41 @@ Valid category values are exposed via `VALID_CATEGORY_VALUES` and include:
 `news_public`, `podcasts`, `research`, `research_academic_journals`,
 `research_investment_research`, `transcripts`.
 
+### Sentiment Filtering
+
+Restrict searches to documents whose sentiment falls inside one or more
+inclusive `min` / `max` ranges using the `sentiment` argument. It accepts a
+single `SentimentRange` / dict, or a list of them (multiple disjoint ranges).
+The filter is emitted as `query.filters.sentiment.ranges` on co-mention,
+volume, and search payloads.
+
+```python
+from bigdata_smart_batching import SentimentRange, plan_search
+
+plan = plan_search(
+    universe="id_name_mapping_us_top_3000.csv",
+    start_date="2023-01-01",
+    end_date="2023-12-31",
+    text="earnings revenue profit",
+    sentiment=SentimentRange(min=0.3, max=1.0),
+)
+
+plan = plan_search(
+    universe="id_name_mapping_us_top_3000.csv",
+    start_date="2023-01-01",
+    end_date="2023-12-31",
+    text="earnings revenue profit",
+    sentiment=[
+        {"min": -1.0, "max": -0.5},
+        {"min": 0.5, "max": 1.0},
+    ],
+)
+```
+
+Each range must satisfy `min <= max`. Use
+`validate_sentiment_range(sentiment)` to validate and normalize input into the
+list-of-dicts shape the API expects.
+
 ### Save and Load Plans
 
 ```python
@@ -210,7 +247,10 @@ Step 2: EXECUTION
 | `min_period_days` | `int` | `30` | Minimum days per sub-period |
 | `min_entities_per_basket` | `int` | `1` | Lower bound on entities per basket |
 | `category` | `CategoryFilter \| dict \| None` | `None` | Optional category filter (`mode` + `values`) |
+| `sentiment` | `SentimentRange \| dict \| list \| None` | `None` | Optional sentiment filter: one inclusive `{min, max}` range or a list of disjoint ranges |
 | `content_diversification` | `bool` | `True` | Enable/disable content diversification in ranking |
+| `requests_per_minute` | `int` | `100` | Global rate limit shared across all planning HTTP work (co-mention + volume) |
+| `max_workers` | `int` | `40` | Maximum concurrent in-flight planning requests (shared semaphore) |
 
 ### `execute_search()`
 
@@ -233,6 +273,7 @@ Step 2: EXECUTION
 - `load_universe_from_csv(csv_path)` -- load entity IDs from a CSV only.
 - `save_plan(plan, path)` / `load_plan(path)` -- persist plans as JSON.
 - `validate_category_filter(category)` -- validate and normalize a category filter to the API dict shape.
+- `validate_sentiment_range(sentiment)` -- validate and normalize sentiment range(s) into the list-of-`{min, max}` dicts emitted as `filters.sentiment.ranges`.
 - `build_comention_payload(...)`, `build_volume_payload(...)`, `build_search_query(...)` -- low-level payload builders used by the planner; useful if you need to construct custom requests.
 
 ### Public Types
@@ -240,6 +281,8 @@ Step 2: EXECUTION
 - `CategoryFilter` -- frozen dataclass with `mode: CategoryMode` and `values: tuple[str, ...]`.
 - `CategoryMode` -- `StrEnum` with `INCLUDE` and `EXCLUDE` values.
 - `CategoryFilterInput` -- type alias: `CategoryFilter | dict[str, str | list[str]]`.
+- `SentimentRange` -- frozen dataclass with inclusive `min: float` and `max: float`.
+- `SentimentRangeInput` -- type alias for one `SentimentRange` / `{min, max}` dict, or a non-empty list of either.
 - `UniverseInput` -- type alias: `str | list[str]`.
 - `VALID_CATEGORY_VALUES` -- `frozenset[str]` of allowed category strings.
 
@@ -315,7 +358,7 @@ Ties are resolved using `VOLUME_BUCKET_PRIORITY`: `high > medium > low > very_lo
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for release notes. The package is currently at
-version **1.0.1**.
+version **1.2.0**.
 
 ## License
 

{bigdata_smart_batching-1.2.0 → bigdata_smart_batching-1.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bigdata-smart-batching"
-version = "1.2.0"
+version = "1.2.1"
 description = "High-performance semantic search with intelligent company grouping and parallel execution"
 readme = "README.md"
 authors = [{ name = "Bigdata.com", email = "support@ravenpack.com" }]

{bigdata_smart_batching-1.2.0 → bigdata_smart_batching-1.2.1}/uv.lock

@@ -12,7 +12,7 @@ resolution-markers = [
 
 [[package]]
 name = "bigdata-smart-batching"
-version = "1.2.0"
+version = "1.2.1"
 source = { editable = "." }
 dependencies = [
     { name = "matplotlib" },