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

{bigdata_smart_batching-1.0.2 → bigdata_smart_batching-1.2.0}/.gitignore

@@ -110,6 +110,3 @@ Thumbs.db
 *.csv
 
 benchmark/
-benchmark.py
-scatter_date_relevance.py
-simple.py

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

@@ -5,6 +5,30 @@ 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.0] - 2026-05-12
+
+### Added
+
+- Document-level **sentiment** filters: inclusive `min` / `max` range(s), validated with `validate_sentiment_range`, modeled as `SentimentRange` / `SentimentRangeInput`, serialized to `query.filters.sentiment.ranges` on co-mention, volume, and search payloads. `plan_search(..., sentiment=...)` and `sentiment_filter` plumbed through `SmartBatchingPlanner` co-mention and volume flows. Types and validator re-exported from the package root.
+- **Planning throughput controls**: `plan_search(..., requests_per_minute=..., max_workers=...)` and `SmartBatchingPlanner(..., requests_per_minute=..., max_workers=..., rate_limiter=..., concurrency_limiter=...)` so all planner HTTP work shares one sliding-window rate limiter and one concurrency semaphore across internal thread pools.
+- **`exponential_backoff`** helper in `search_function` (used by retry paths; capped via `MAX_RETRY_BACKOFF_SECONDS`).
+
+### Changed
+
+- **Retries:** co-mention / volume POST retries now use **shared exponential backoff** for `429`, `403`, timeouts, and other failures, instead of parsing `Retry-After` for `429` and separate ad-hoc `403` handling (constant renamed/clamped to `MAX_RETRY_BACKOFF_SECONDS`).
+- **Volume time-series merge:** when aggregating batch results per date, a **`sentiment`** value on each point is the arithmetic mean of batch sentiments for that date (batches without sentiment for that date are omitted from the mean).
+- **`SlidingWindowRateLimiter`:** window accounting aligned with **ceil-based** `max_per_window` expectations (tests updated for low rates and 450 rpm-style cases).
+
+
+
+## [1.1.0] - 2026-04-20
+
+### Added
+
+- `convert_to_dataframe` now includes a `detections` column: for each chunk row,
+  entity detections are taken from `chunk["detections"]` (entries with
+  `type == "entity"`); rows without chunks use an empty list.
+
 ## [1.0.2] - 2026-04-17
 
 ### Fixed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bigdata-smart-batching
-Version: 1.0.2
+Version: 1.2.0
 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>

{bigdata_smart_batching-1.0.2 → bigdata_smart_batching-1.2.0}/examples/example.py

@@ -55,21 +55,23 @@ def main() -> None:
             plan = load_plan("plan.json")
         else:
             plan = plan_search(
-                #universe=universe_csv,
-                universe=['54F271'],
+                universe=universe_csv,
+                #universe=['54F271'],
                 start_date="2025-01-01",
-                end_date="2025-12-12",
-                text="Decline in customer confidence in the company",
+                end_date="2025-12-31",
+                text="Company has significant pricing power",
                 volume_query_mode="iterative",
                 apply_volume_splits=True,
-                min_period_days=30,
-                min_entities_per_basket=10,
+                min_period_days=120,
+                min_entities_per_basket=20,
                 # Optional: filter by category to restrict document sources.
                 # Accepts a CategoryFilter instance or a plain dict:
                 category={"mode": "INCLUDE", "values": ["news_premium"]},
                 content_diversification=False,
+                sentiment=[{"min": -1, "max": -0.5},{"min": 0.5, "max": 1}],
             )
             plans.append(plan)
+            save_plan(plan, "plan.json")
             print(f"Chunk upper bound estimate: {plan['chunk_upper_bound_estimate']:,}")
 
             # Export plan
@@ -78,12 +80,12 @@ def main() -> None:
         print(f"Plan execution time: {plan_elapsed_s:.3f}s")
 
         # Step 2: Execute search with 10% of total chunks (preserves distribution)
-        if True:
+        if False:
             search_t0 = time.perf_counter()
             results_raw = execute_search(
                 search_plan=plan,
                 chunk_percentage=1,
-                requests_per_minute=400,
+                requests_per_minute=300,
             )
             search_elapsed_s = time.perf_counter() - search_t0
             print(f"Search execution time: {search_elapsed_s:.3f}s")
@@ -108,10 +110,10 @@ def main() -> None:
         #print(df.head())
         #results_dfs.append(results)
     # Merge dataframe 0 and 1 into a single dataframe using id and chunk index as keys using a full outer join
-    print(plans[0]==plans[1])
+    #print(plans[0]==plans[1])
     #merged = results_dfs[0].merge(results_dfs[1], on=['doc_id', 'chunk_cnum'], how='outer', indicator=True)
     #print(f"% overlapping chunks: {(len(merged[merged._merge!='both'])/2)/len(merged)*100:.2f}%")
-    print('a')
+    #print('a')
 
 
 if __name__ == "__main__":

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

@@ -1,6 +1,6 @@
 [project]
 name = "bigdata-smart-batching"
-version = "1.0.2"
+version = "1.2.0"
 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.0.2 → bigdata_smart_batching-1.2.0}/src/bigdata_smart_batching/__init__.py

@@ -13,6 +13,8 @@ from .search_function import (
     CategoryFilter,
     CategoryFilterInput,
     CategoryMode,
+    SentimentRange,
+    SentimentRangeInput,
     UniverseInput,
     build_comention_payload,
     build_search_query,
@@ -25,12 +27,15 @@ from .search_function import (
     resolve_universe,
     save_plan,
     validate_category_filter,
+    validate_sentiment_range,
 )
 
 __all__ = [
     "CategoryFilter",
     "CategoryFilterInput",
     "CategoryMode",
+    "SentimentRange",
+    "SentimentRangeInput",
     "UniverseInput",
     "VALID_CATEGORY_VALUES",
     "build_comention_payload",
@@ -45,4 +50,5 @@ __all__ = [
     "resolve_universe",
     "save_plan",
     "validate_category_filter",
+    "validate_sentiment_range",
 ]

{bigdata_smart_batching-1.0.2 → bigdata_smart_batching-1.2.0}/src/bigdata_smart_batching/output_converter.py

@@ -54,6 +54,7 @@ def convert_to_dataframe(raw_results: list[dict]) -> pd.DataFrame:
                     "chunk_sentiment": None,
                     # Entity
                     "entity_ids": [],
+                    "detections": [],
                     # Final
                     "url": url,
                     "reporting_entities": reporting_entities,
@@ -62,6 +63,8 @@ def convert_to_dataframe(raw_results: list[dict]) -> pd.DataFrame:
         else:
             for chunk in chunks:
                 # Entity IDs (added by execute_search)
+                detections = chunk.get("detections", [])
+                entity_detections = [d for d in detections if d.get("type") == "entity"]
                 entity_ids = chunk.get("entity_ids", [])
 
                 rows.append(
@@ -80,6 +83,7 @@ def convert_to_dataframe(raw_results: list[dict]) -> pd.DataFrame:
                         "chunk_sentiment": chunk.get("sentiment"),
                         # Entity
                         "entity_ids": entity_ids,
+                        "detections": entity_detections,
                         # Final
                         "url": url,
                         "reporting_entities": reporting_entities,

{bigdata_smart_batching-1.0.2 → bigdata_smart_batching-1.2.0}/src/bigdata_smart_batching/search_function.py

@@ -9,6 +9,7 @@ This module provides a two-step system for efficient semantic search:
 import csv
 import json
 import logging
+import math
 import os
 import sys
 import threading
@@ -43,9 +44,11 @@ SEARCH_ENDPOINT = "/v1/search"
 COMENTION_ENDPOINT = "/v1/search/co-mentions/entities"
 MAX_ENTITIES_IN_ANY_OF = 500
 MAX_CHUNKS_PER_BASKET = 1000
-DEFAULT_REQUESTS_PER_MINUTE = 100
+DEFAULT_REQUESTS_PER_MINUTE = int(os.getenv("BIGDATA_REQUESTS_PER_MINUTE", "450"))
 DEFAULT_MAX_WORKERS = 40
 DEFAULT_WINDOW_SIZE_SECONDS = 5
+DEFAULT_RETRY_BACKOFF_SECONDS = 1.0
+MAX_RETRY_BACKOFF_SECONDS = 60.0
 
 UniverseInput: TypeAlias = str | list[str]
 
@@ -95,7 +98,21 @@ class CategoryFilter:
         return {"mode": self.mode.value, "values": list(self.values)}
 
 
+@dataclass(frozen=True)
+class SentimentRange:
+    """Document-level sentiment filter as an inclusive min/max range."""
+
+    min: float
+    max: float
+
+    def to_dict(self) -> dict[str, float]:
+        """Serialize to one range object inside ``query.filters.sentiment.ranges``."""
+        return {"min": float(self.min), "max": float(self.max)}
+
+
 CategoryFilterInput: TypeAlias = CategoryFilter | dict[str, str | list[str]]
+SentimentOneInput: TypeAlias = SentimentRange | dict[str, float | int]
+SentimentRangeInput: TypeAlias = SentimentOneInput | list[SentimentOneInput]
 
 
 def validate_category_filter(
@@ -143,6 +160,53 @@ def validate_category_filter(
     return {"mode": mode_str, "values": values}
 
 
+def _validate_one_sentiment_range(item: SentimentOneInput) -> dict[str, float]:
+    """Validate a single inclusive min/max range."""
+    if isinstance(item, SentimentRange):
+        lo, hi = item.min, item.max
+    elif isinstance(item, dict):
+        if "min" not in item or "max" not in item:
+            raise ValueError("sentiment dict must include 'min' and 'max' keys")
+        lo, hi = item["min"], item["max"]
+    else:
+        raise TypeError(
+            f"each sentiment range must be a SentimentRange or dict, got {type(item).__name__}"
+        )
+
+    if not isinstance(lo, (int, float)) or isinstance(lo, bool):
+        raise TypeError(f"sentiment min must be a number, got {type(lo).__name__}")
+    if not isinstance(hi, (int, float)) or isinstance(hi, bool):
+        raise TypeError(f"sentiment max must be a number, got {type(hi).__name__}")
+
+    lo_f, hi_f = float(lo), float(hi)
+    if lo_f > hi_f:
+        raise ValueError(f"sentiment min ({lo_f}) must be <= max ({hi_f})")
+
+    return {"min": lo_f, "max": hi_f}
+
+
+def validate_sentiment_range(sentiment: SentimentRangeInput) -> list[dict[str, float]]:
+    """Validate and normalize sentiment range(s) for API payloads.
+
+    Accepts a single ``SentimentRange`` or ``{"min", "max"}`` dict, or a non-empty
+    list of those (multiple disjoint ranges).
+
+    Returns:
+        List of ``{"min", "max"}`` dicts — the ``ranges`` array for
+        ``query.filters.sentiment``.
+
+    Raises:
+        TypeError: If *sentiment* is not a supported type or a list contains invalid
+            elements.
+        ValueError: If a dict is missing keys, bounds are invalid, or the list is empty.
+    """
+    if isinstance(sentiment, list):
+        if not sentiment:
+            raise ValueError("sentiment list must not be empty")
+        return [_validate_one_sentiment_range(x) for x in sentiment]
+    return [_validate_one_sentiment_range(sentiment)]
+
+
 class SlidingWindowRateLimiter:
     """
     Thread-safe sliding window rate limiter with burst prevention.
@@ -166,7 +230,7 @@ class SlidingWindowRateLimiter:
         self.max_requests = max_requests
         self.period_seconds = period_seconds
         self.window_size = window_size
-        self.max_per_window = int(max_requests * window_size / period_seconds)
+        self.max_per_window = max(1, math.ceil(max_requests * window_size / period_seconds))
 
         # Track requests in sliding windows
         self.request_times = deque()
@@ -467,6 +531,7 @@ def build_comention_payload(
     end_iso: str,
     limit: int,
     category_filter: dict[str, str | list[str]] | None = None,
+    sentiment_filter: list[dict[str, float]] | None = None,
 ) -> dict:
     """Build a co-mention API request payload.
 
@@ -478,6 +543,8 @@ def build_comention_payload(
         end_iso: ISO-formatted end timestamp (e.g. ``2024-12-31T23:59:59Z``).
         limit: Maximum number of entities the API should return.
         category_filter: Optional category filter dict with ``mode`` and ``values``.
+        sentiment_filter: Optional list of ``{"min", "max"}`` ranges; emitted as
+            ``filters.sentiment.ranges``.
 
     Returns:
         Complete payload dict ready to be passed as ``json=`` to ``requests.post``.
@@ -493,6 +560,8 @@ def build_comention_payload(
     }
     if category_filter is not None:
         filters["category"] = category_filter
+    if sentiment_filter is not None:
+        filters["sentiment"] = {"ranges": sentiment_filter}
 
     query: dict = {
         "auto_enrich_filters": False,
@@ -513,6 +582,7 @@ def build_volume_payload(
     end_iso: str,
     category_filter: dict[str, str | list[str]] | None = None,
     content_diversification: bool = True,
+    sentiment_filter: list[dict[str, float]] | None = None,
 ) -> dict:
     """Build a volume endpoint request payload.
 
@@ -525,6 +595,8 @@ def build_volume_payload(
         category_filter: Optional category filter dict with ``mode`` and ``values``.
         content_diversification: Enable or disable content diversification in ranking
             (default ``True``).
+        sentiment_filter: Optional list of ``{"min", "max"}`` ranges; emitted as
+            ``filters.sentiment.ranges``.
 
     Returns:
         Complete payload dict ready to be passed as ``json=`` to ``requests.post``.
@@ -540,6 +612,8 @@ def build_volume_payload(
     }
     if category_filter is not None:
         filters["category"] = category_filter
+    if sentiment_filter is not None:
+        filters["sentiment"] = {"ranges": sentiment_filter}
 
     query: dict = {
         "auto_enrich_filters": False,
@@ -559,6 +633,7 @@ def build_search_query(
     max_chunks: int,
     category_filter: dict[str, str | list[str]] | None = None,
     content_diversification: bool = True,
+    sentiment_filter: list[dict[str, float]] | None = None,
 ) -> dict:
     """Build a semantic search query dict for the search endpoint.
 
@@ -575,6 +650,8 @@ def build_search_query(
         category_filter: Optional category filter dict with ``mode`` and ``values``.
         content_diversification: Enable or disable content diversification in ranking
             (default ``True``).
+        sentiment_filter: Optional list of ``{"min", "max"}`` ranges; emitted as
+            ``filters.sentiment.ranges``.
 
     Returns:
         Query dict suitable for ``make_search_request`` or embedding in a basket.
@@ -585,6 +662,8 @@ def build_search_query(
     }
     if category_filter is not None:
         filters["category"] = category_filter
+    if sentiment_filter is not None:
+        filters["sentiment"] = {"ranges": sentiment_filter}
 
     query: dict = {
         "auto_enrich_filters": False,
@@ -603,7 +682,12 @@ def build_search_query(
     return query
 
 
-def get_smart_batching_planner(api_key: str | None = None, api_base_url: str | None = None):
+def get_smart_batching_planner(
+    api_key: str | None = None,
+    api_base_url: str | None = None,
+    requests_per_minute: int = DEFAULT_REQUESTS_PER_MINUTE,
+    max_workers: int = DEFAULT_MAX_WORKERS,
+):
     """
     Get or create SmartBatchingPlanner instance.
     Tries to import from existing module, otherwise creates a simplified version.
@@ -611,6 +695,9 @@ def get_smart_batching_planner(api_key: str | None = None, api_base_url: str | N
     Args:
         api_key: API key for Bigdata API
         api_base_url: API base URL (if provided, will set in environment for config)
+        requests_per_minute: Global rate limit (requests/minute) shared across all
+            planner API calls (comention + volume).
+        max_workers: Maximum concurrent in-flight requests across the planner.
 
     Returns:
         SmartBatchingPlanner instance
@@ -627,7 +714,12 @@ def get_smart_batching_planner(api_key: str | None = None, api_base_url: str | N
         try:
             from .smart_batching import SmartBatchingPlanner
 
-            planner = SmartBatchingPlanner(api_key=api_key, api_base_url=api_base_url)
+            planner = SmartBatchingPlanner(
+                api_key=api_key,
+                api_base_url=api_base_url,
+                requests_per_minute=requests_per_minute,
+                max_workers=max_workers,
+            )
             return planner
         finally:
             # Restore original environment variable if we changed it
@@ -658,7 +750,10 @@ def plan_search(
     min_period_days: int = 30,
     min_entities_per_basket: int = 1,
     category: CategoryFilterInput | None = None,
+    sentiment: SentimentRangeInput | None = None,
     content_diversification: bool = True,
+    requests_per_minute: int = DEFAULT_REQUESTS_PER_MINUTE,
+    max_workers: int = DEFAULT_MAX_WORKERS,
 ) -> dict:
     """
     Plan a search using smart batching approach.
@@ -689,8 +784,19 @@ def plan_search(
         category: Optional category filter to restrict documents to specific categories.
                 Accepts a ``CategoryFilter`` instance or a dict with ``mode``
                 (``"INCLUDE"`` / ``"EXCLUDE"``) and ``values`` (list of category strings).
+        sentiment: Optional sentiment filter: one range or a list of ranges, each with
+                inclusive ``min`` and ``max`` (e.g. ``{"min": 0.3, "max": 1}`` or
+                ``[{"min": -1, "max": -0.5}, {"min": 0.5, "max": 1}]``). Accepts
+                ``SentimentRange`` instance(s) or dicts; emitted as
+                ``filters.sentiment.ranges`` on co-mention, volume, and search payloads.
         content_diversification: Enable or disable content diversification in the search
                 ranking parameters (default ``True``).
+        requests_per_minute: Global rate limit (requests/minute) applied across all
+                planning API calls (comention + volume endpoints). A single
+                rate limiter is built once and shared by every internal worker.
+        max_workers: Maximum concurrent in-flight requests across all planning
+                API calls. A single concurrency semaphore is built once and
+                shared by every internal worker.
 
     Returns:
         Dict with planning results:
@@ -705,6 +811,10 @@ def plan_search(
     if category is not None:
         category_filter_dict = validate_category_filter(category)
 
+    sentiment_ranges: list[dict[str, float]] | None = None
+    if sentiment is not None:
+        sentiment_ranges = validate_sentiment_range(sentiment)
+
     api_key = api_key or os.getenv("BIGDATA_API_KEY")
     if not api_key:
         raise ValueError("API key must be provided or set in BIGDATA_API_KEY environment variable")
@@ -722,7 +832,12 @@ def plan_search(
     logger.info(f"Loaded {len(companies)} companies from universe")
 
     # Try to use SmartBatchingPlanner if available
-    planner = get_smart_batching_planner(api_key=api_key, api_base_url=api_base_url)
+    planner = get_smart_batching_planner(
+        api_key=api_key,
+        api_base_url=api_base_url,
+        requests_per_minute=requests_per_minute,
+        max_workers=max_workers,
+    )
 
     if planner is None:
         # Simplified implementation without SmartBatchingPlanner
@@ -741,6 +856,7 @@ def plan_search(
             max_chunks=MAX_CHUNKS_PER_BASKET,
             category_filter=category_filter_dict,
             content_diversification=content_diversification,
+            sentiment_filter=sentiment_ranges,
         )
 
         # Estimate expected chunks (simplified - would need comention API for accurate)
@@ -782,6 +898,7 @@ def plan_search(
             min_period_days=min_period_days,
             min_entities_per_basket=min_entities_per_basket,
             category_filter=category_filter_dict,
+            sentiment_filter=sentiment_ranges,
         )
 
         smart = report.get("configurations", {}).get("smart", {})
@@ -815,6 +932,7 @@ def plan_search(
                     max_chunks=max_chunks_for_query,
                     category_filter=category_filter_dict,
                     content_diversification=content_diversification,
+                    sentiment_filter=sentiment_ranges,
                 )
                 basket = {
                     "basket_id": basket_raw["basket_id"],
@@ -847,6 +965,7 @@ def plan_search(
                     max_chunks=100,
                     category_filter=category_filter_dict,
                     content_diversification=content_diversification,
+                    sentiment_filter=sentiment_ranges,
                 )
                 basket = {
                     "basket_id": (f"basket_{global_basket_counter}_very_low_{ps_short}_{pe_short}"),
@@ -883,6 +1002,24 @@ def plan_search(
     return plan
 
 
+def exponential_backoff(
+    attempt: int,
+    *,
+    base: float = DEFAULT_RETRY_BACKOFF_SECONDS,
+    cap: float = MAX_RETRY_BACKOFF_SECONDS,
+) -> float:
+    """Compute an exponential backoff delay (in seconds) for a retry attempt.
+
+    The delay doubles with every attempt and is clamped to ``[0, cap]``. The
+    ``attempt`` argument is the zero-indexed retry number (i.e. ``0`` for the
+    first retry, ``1`` for the second, ...).
+    """
+    if attempt < 0:
+        attempt = 0
+    delay = base * (2**attempt)
+    return max(0.0, min(delay, cap))
+
+
 def make_search_request(
     query: dict,
     api_key: str,
@@ -912,42 +1049,33 @@ def make_search_request(
 
     retry_count = 0
     while retry_count < max_retries:
+        retry_wait: float | None = None
         try:
             with concurrency_limiter:
                 rate_limiter.acquire(timeout=120.0)
-
                 response = requests.post(url, headers=headers, json=payload, timeout=120)
 
-                if response.status_code == 200:
-                    return response.json()
-                elif response.status_code == 429:
-                    retry_count += 1
-                    if retry_count < max_retries:
-                        time.sleep(1.0)
-                        continue
-                elif response.status_code == 403:
-                    retry_count += 1
-                    if retry_count < max_retries:
-                        delay = min(1.0 * (1.5 ** (retry_count // 10)), 5.0)
-                        time.sleep(delay)
-                        continue
-                else:
-                    logger.error(f"API error {response.status_code}: {response.text[:200]}")
-                    return None
+            if response.status_code == 200:
+                return response.json()
+            if response.status_code in (429, 403):
+                retry_wait = exponential_backoff(retry_count)
+                retry_count += 1
+            else:
+                logger.error(f"API error {response.status_code}: {response.text[:200]}")
+                return None
 
         except requests.exceptions.Timeout:
+            retry_wait = exponential_backoff(retry_count)
             retry_count += 1
-            if retry_count < max_retries:
-                time.sleep(1.0)
-                continue
-            return None
         except Exception as e:
             logger.error(f"Request error: {e}")
+            retry_wait = exponential_backoff(retry_count)
             retry_count += 1
-            if retry_count < max_retries:
-                time.sleep(1.0)
-                continue
-            return None
+
+        if retry_count >= max_retries:
+            break
+        if retry_wait and retry_wait > 0:
+            time.sleep(retry_wait)
 
     logger.warning(f"Failed after {max_retries} retries")
     return None
@@ -1021,6 +1149,8 @@ def execute_search(
     max_workers: int = DEFAULT_MAX_WORKERS,
     overwrite_chunks_per_basket: int | None = None,
     second_pass: bool = False,
+    rate_limiter: SlidingWindowRateLimiter | None = None,
+    concurrency_limiter: ConcurrencySemaphore | None = None,
 ) -> list[dict]:
     """
     Execute search with proportional sampling.
@@ -1028,14 +1158,22 @@ def execute_search(
     Args:
         search_plan: Planning result from plan_search()
         chunk_percentage: Percentage of total chunks to retrieve (0.0 to 1.0)
-        requests_per_minute: Rate limit for API requests
+        requests_per_minute: Rate limit for API requests. Ignored when
+            ``rate_limiter`` is provided.
         api_key: API key (defaults to BIGDATA_API_KEY env var)
         api_base_url: API base URL
-        max_workers: Number of parallel workers
+        max_workers: Number of parallel workers. Ignored when
+            ``concurrency_limiter`` is provided.
         overwrite_chunks_per_basket: If set, override the proportional chunks per basket
         second_pass: If True, after the first search pass, entities already found in
             retrieved chunks are removed from each basket and the search is executed
             again with only the remaining entities. Results from both passes are combined.
+        rate_limiter: Optional pre-built :class:`SlidingWindowRateLimiter` to share
+            with other components (e.g. a :class:`SmartBatchingPlanner`). When
+            provided, ``requests_per_minute`` is ignored.
+        concurrency_limiter: Optional pre-built :class:`ConcurrencySemaphore` to
+            share with other components. When provided, ``max_workers`` controls
+            only the executor's worker count for basket fan-out.
 
     Returns:
         List of document dictionaries (each containing a chunks array).
@@ -1058,9 +1196,10 @@ def execute_search(
     logger.info(f"Executing search with {chunk_percentage * 100:.1f}% of chunks")
     logger.info(f"Total maximum expected chunks: {target_chunks:,}")
 
-    # Initialize rate limiter and concurrency limiter
-    rate_limiter = SlidingWindowRateLimiter(max_requests=requests_per_minute)
-    concurrency_limiter = ConcurrencySemaphore(max_concurrent=max_workers)
+    if rate_limiter is None:
+        rate_limiter = SlidingWindowRateLimiter(max_requests=requests_per_minute)
+    if concurrency_limiter is None:
+        concurrency_limiter = ConcurrencySemaphore(max_concurrent=max_workers)
 
     # Calculate proportional chunks per basket
     baskets_to_search = []