flowtask 5.12.7__tar.gz → 5.12.9__tar.gz

{flowtask-5.12.7 → flowtask-5.12.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowtask
-Version: 5.12.7
+Version: 5.12.9
 Summary: Framework for Task orchestration
 Author-email: Jesus Lara <jesuslarag@gmail.com>
 License: Apache-2.0
@@ -45,7 +45,7 @@ Requires-Dist: aioimaplib==1.1.0
 Requires-Dist: adal==1.2.7
 Requires-Dist: xlrd>=2.0.2
 Requires-Dist: xmltodict<1.0.0,>=0.14.2
-Requires-Dist: zeep[async]==4.3.2
+Requires-Dist: zeep[async]>=4.3.3
 Requires-Dist: nltk>=3.9.3
 Requires-Dist: jdcal==1.4.1
 Requires-Dist: html5lib==1.1
@@ -119,12 +119,16 @@ Requires-Dist: microsoft-kiota-authentication-azure==1.9.6
 Requires-Dist: msgraph-sdk==1.22.0
 Requires-Dist: zendriver>=0.15.2
 Requires-Dist: pyarrow>=14.0
+Requires-Dist: scipy>=1.13
+Requires-Dist: scikit-learn>=1.5
 Provides-Extra: docker
 Requires-Dist: aiodocker>=0.21.0; extra == "docker"
 Provides-Extra: k8s
 Requires-Dist: kr8s>=0.16.0; extra == "k8s"
 Provides-Extra: git
 Requires-Dist: gitpython>=3.1.50; extra == "git"
+Provides-Extra: scoring
+Requires-Dist: h3>=4.0; extra == "scoring"
 Provides-Extra: ai
 Requires-Dist: ai-parrot[agents,graphindex,images,llms,retrieval]>=0.20.4; extra == "ai"
 Requires-Dist: ai-parrot-loaders[audio,document,ebook,ml,pdf,scraping,video,web,youtube]>=0.1.0; extra == "ai"

{flowtask-5.12.7 → flowtask-5.12.9}/flowtask/components/CallAnalysis.py

@@ -1,5 +1,6 @@
 from collections.abc import Callable
 import asyncio
+import re
 import pandas as pd
 import orjson
 from ..exceptions import DataNotFound, ComponentError
@@ -711,11 +712,18 @@ class CallAnalysis(ParrotBot, FlowComponent):
                     formatted_question = self.format_question(call_identifier, transcripts, row)
                     result = await self._bot.invoke(question=formatted_question)
 
-                    # Try to parse JSON output before returning
-                    try:
-                        parsed_output = orjson.loads(result.output) if isinstance(result.output, str) else result.output
-                    except Exception:
-                        parsed_output = result.output  # fallback: keep as string if parsing fails
+                    # Try to parse JSON output before returning. Some models wrap
+                    # the JSON in markdown code fences (```json ... ```) — strip
+                    # those first. If parsing still fails, raise so the retry
+                    # loop below re-invokes the LLM instead of persisting the
+                    # raw/malformed text as if it were the analysis.
+                    if isinstance(result.output, str):
+                        cleaned = re.sub(
+                            r'^```(?:json)?\s*|\s*```\s*$', '', result.output.strip()
+                        )
+                        parsed_output = orjson.loads(cleaned)
+                    else:
+                        parsed_output = result.output
 
                     # Success - return the parsed result
                     self._logger.debug(f"✓ Successfully analyzed {call_identifier}")
@@ -1043,7 +1051,15 @@ class CallAnalysis(ParrotBot, FlowComponent):
                     try:
                         return json.loads(cleaned)
                     except (json.JSONDecodeError, ValueError):
-                        return cleaned
+                        # Not valid JSON even after stripping fences (truncated
+                        # output, leaked reasoning text, etc). Storing the raw
+                        # string would corrupt the jsonb column downstream, so
+                        # drop it instead of persisting garbage.
+                        self._logger.warning(
+                            f"Discarding non-JSON {self.output_column} value "
+                            f"(unparseable after cleanup): {cleaned[:120]!r}"
+                        )
+                        return None
                 return x
             result_df[self.output_column] = result_df[self.output_column].apply(clean_json_formatting)
 

{flowtask-5.12.7 → flowtask-5.12.9}/flowtask/components/PodcastMaker.py

@@ -62,8 +62,10 @@ class PodcastMaker(AgentBase, FlowComponent):
 
     Wraps ``BasicAgent.speech_report()`` as a FlowTask component.  For each
     row in the input DataFrame the agent generates a conversational script and
-    synthesises it to audio.  The TTS model is always determined by the agent
-    internally — the ``llm:`` block controls only the script-generation LLM.
+    synthesises it to audio.  Note the ``llm:`` block configures the agent's
+    general conversation model — it does **not** reach ``speech_report()``.
+    Use ``script_model``/``tts_model`` to override the script/TTS models used
+    for generation (both default to Gemini 2.5 inside ``BasicAgent`` otherwise).
 
     Failed episodes (common with Google TTS rate limits) are not discarded.
     They remain in the output DataFrame with ``podcast_path=None``,
@@ -95,8 +97,20 @@ class PodcastMaker(AgentBase, FlowComponent):
             → ``costco_canada.wav``).  Useful for making files human-readable.
             When combined with ``as_bytes``, the rename happens first so
             ``podcast_path`` reflects the new name.
-        llm (dict): LLM config for script generation — ``llm``, ``model``,
-            ``temperature``.  Does **not** affect the TTS model.
+        output_directory (str, optional): Directory path where generated audio
+            files are written.  When omitted, ``BasicAgent`` defaults to
+            ``STATIC_DIR/{agent_id}/podcasts``.  Also reused internally as
+            ``destination`` (AgentBase's required startup workspace) unless
+            ``destination`` is set explicitly — one path covers both.
+        script_model (str, optional): Gemini model for script generation
+            (passed to ``speech_report(script_model=...)``).  Defaults to
+            ``BasicAgent``'s own default (``gemini-2.5-flash``) when omitted.
+        tts_model (str, optional): Gemini model for audio synthesis (passed to
+            ``speech_report(tts_model=...)``).  Defaults to ``BasicAgent``'s
+            own default (``gemini-2.5-flash-preview-tts``) when omitted.
+        llm (dict): LLM config for the agent's general conversation model
+            (``llm``, ``model``, ``temperature``).  Does **not** affect
+            ``speech_report()`` — use ``script_model``/``tts_model`` for that.
 
     Example YAML::
 
@@ -140,10 +154,26 @@ class PodcastMaker(AgentBase, FlowComponent):
         self.title_column: Optional[str] = kwargs.get("title_column")
         self.output_column: str = kwargs.get("output_column", "podcast_result")
         self.podcast_instructions: str = kwargs.get("podcast_instructions", "for_podcast.txt")
+        # Optional overrides for the underlying Gemini models (BasicAgent
+        # defaults to gemini-2.5-flash for the script and gemini-2.5-flash-
+        # preview-tts for the audio if these are left unset).
+        self.script_model: Optional[str] = kwargs.get("script_model")
+        self.tts_model: Optional[str] = kwargs.get("tts_model")
         self.max_lines: int = int(kwargs.get("max_lines", 20))
         self.num_speakers: int = int(kwargs.get("num_speakers", 2))
         self.as_bytes: bool = bool(kwargs.get("as_bytes", False))
         self.filename_column: Optional[str] = kwargs.get("filename_column")
+        # Optional override for where generated audio files are written.
+        # Defaults (inside BasicAgent) to STATIC_DIR/{agent_id}/podcasts.
+        # Stored as str (not Path): FlowComponent re-applies raw kwargs after
+        # super().__init__(), which would otherwise clobber a Path back to str.
+        self.output_directory: Optional[str] = kwargs.get("output_directory")
+        # AgentBase.start() requires self.destination to exist (used as the
+        # tools base_dir — irrelevant here since _define_tools() is a no-op).
+        # Reuse output_directory for it so only one path needs to be declared
+        # in YAML; an explicit `destination` kwarg still wins if provided.
+        if self.output_directory and "destination" not in kwargs:
+            self.destination = self.output_directory
         # Optional speaker override from YAML
         self._speakers_cfg: Optional[Dict[str, Any]] = kwargs.get("speakers")
         # Parse llm config dict — AgentBase expects llm to be a provider string,
@@ -223,17 +253,23 @@ class PodcastMaker(AgentBase, FlowComponent):
         # AgentBase.start() creates and configures self._agent
         await super().start(**kwargs)
 
-        # Resolve the prompt file using PodcastMaker's own agent_id so it
-        # looks in AGENTS_DIR/podcast_maker/prompts/ instead of the internal
-        # agent's agent_id directory (which defaults to "agent").
-        prompt_path = AGENTS_DIR / self.agent_id / "prompts" / self.podcast_instructions
+        # Resolve the prompt file, preferring the task/program repo (same
+        # convention as ParrotBot: {program}/prompts/{file}, e.g. PositiveBot)
+        # over the shared AGENTS_DIR/podcast_maker/prompts/ location. `self.directory`
+        # is set by AgentBase.start() above (defaults to the taskstore's program path).
+        task_prompt_path = self.directory / "prompts" / self.podcast_instructions
+        if task_prompt_path.exists():
+            prompt_path = task_prompt_path
+        else:
+            prompt_path = AGENTS_DIR / self.agent_id / "prompts" / self.podcast_instructions
         try:
             self._resolved_podcast_instructions: str = prompt_path.read_text(encoding="utf-8")
             self.logger.debug("PodcastMaker: loaded prompt from %s", prompt_path)
         except FileNotFoundError:
             self.logger.warning(
-                "PodcastMaker: prompt file not found at %s — passing filename to agent",
-                prompt_path,
+                "PodcastMaker: prompt file not found in task repo (%s) or AGENTS_DIR (%s) "
+                "— passing filename to agent",
+                task_prompt_path, prompt_path,
             )
             self._resolved_podcast_instructions = self.podcast_instructions
 
@@ -290,6 +326,9 @@ class PodcastMaker(AgentBase, FlowComponent):
                         max_lines=self.max_lines,
                         num_speakers=self.num_speakers,
                         podcast_instructions=self._resolved_podcast_instructions,
+                        output_directory=Path(self.output_directory) if self.output_directory else None,
+                        script_model=self.script_model,
+                        tts_model=self.tts_model,
                     )
                     podcast_path = str(result.get("podcast_path")) if result.get("podcast_path") else None
                     script_path = str(result.get("script_path")) if result.get("script_path") else None

flowtask-5.12.9/flowtask/components/SweetSpotScore/__init__.py

@@ -0,0 +1,14 @@
+"""
+SweetSpotScore.
+
+DAG component for spatial and/or column-value suitability (site-selection)
+scoring: DataFrame(s) in, enriched DataFrame out (``sweetspot_score``,
+``sweetspot_rank``, ``sweetspot_filtered``, and optional per-criterion
+breakdown columns). Wraps ``flowtask.interfaces.scoring.SweetSpotScorer``
+and/or ``ScoringEngine``. No LLM, no agent dependency — the scoring policy
+comes from inline YAML component config or an external policy file
+(FEAT-190, FEAT-191).
+"""
+from .component import SweetSpotScore
+
+__all__ = ["SweetSpotScore"]

flowtask-5.12.9/flowtask/components/SweetSpotScore/component.py

@@ -0,0 +1,444 @@
+"""SweetSpotScore FlowComponent (FEAT-190, spec Module 8 / FEAT-191).
+
+DAG node: DataFrame(s) in -> enriched DataFrame out. Wraps ``ScoringEngine``
+(column-value criteria) and/or ``SweetSpotScorer`` (spatial criteria) for
+pipeline use. No LLM, no agent, no dataset-manager dependency — the scoring
+policy is provided via inline YAML component config or an external
+YAML/JSON ``policy_file`` (FEAT-191, kept simple for v1, per spec Key
+Constraints).
+
+Example YAML (spatial, FEAT-190):
+
+```yaml
+SweetSpotScore:
+  depends:
+    - QueryToPandas_pois
+    - QueryToPandas_census
+  candidates:
+    source: 0              # index into depends list
+    lat_col: latitude
+    lon_col: longitude
+    id_col: store_id
+  layers:
+    - name: hotels
+      source: 1
+      lat_col: lat
+      lon_col: lng
+      attribute_cols: [rooms]
+  policy:
+    profile: pizza_midmarket
+    criteria:
+      - name: hotels
+        dataset: hotels
+        feature_type: gravity
+        params: {k: 5, attribute: rooms, kernel: gaussian, bandwidth_m: 2000}
+        value_fn: {kind: sigmoid, center: 500, steepness: 0.005}
+        weight: 0.4
+    aggregation: weighted_mean
+```
+
+Example YAML (column-value shorthand, FEAT-191). ``policy_file`` and
+``policy`` are mutually exclusive — if both are set, ``policy_file`` takes
+precedence and ``policy`` is ignored (a warning is logged). Use ONE of the
+two forms below:
+
+```yaml
+# Form A: external policy file
+SweetSpotScore:
+  policy_file: scoring/store_ranking.yaml
+  include_breakdown: true
+```
+
+```yaml
+# Form B: inline policy block
+SweetSpotScore:
+  include_breakdown: true
+  policy:
+    profile: store_ranking
+    criteria:
+      - column: revenue
+        weight: 0.5
+      - column: rent
+        weight: 0.2
+        direction: lower_better
+```
+"""
+from collections.abc import Callable
+import asyncio
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+from navconfig import BASE_DIR
+from pydantic import ValidationError
+
+from ...interfaces.flow import FlowComponent
+from ...exceptions import ComponentError
+from ...interfaces.scoring import (
+    CandidateGrid,
+    Criterion,
+    HardFilter,
+    POILayer,
+    ScoreResult,
+    ScoringPolicy,
+)
+
+
+class SweetSpotScore(FlowComponent):
+    """DAG node: DataFrame(s) in, enriched DataFrame out.
+
+    Supports three scoring modes, resolved automatically from the
+    normalized policy at ``start()`` time (spec K4):
+
+    - **Column-value-only**: every criterion/filter reads a DataFrame
+      column directly (``ScoringEngine.score()`` called directly, no
+      scipy/h3 import).
+    - **Spatial-only**: existing FEAT-190 path, unchanged
+      (``SweetSpotScorer.score()``).
+    - **Mixed**: a unified feature matrix is assembled from both sources,
+      then ``ScoringEngine.score()`` is called directly.
+    """
+
+    _version = "1.0.0"
+
+    def __init__(
+        self,
+        loop: asyncio.AbstractEventLoop = None,
+        job: Callable = None,
+        stat: Callable = None,
+        **kwargs,
+    ):
+        # Scoring config, extracted from YAML component arguments.
+        self._policy_config: dict = kwargs.pop("policy", {})
+        self._policy_file: Optional[str] = kwargs.pop("policy_file", None)
+        self._candidates_config: dict = kwargs.pop("candidates", {})
+        self._layers_config: list = kwargs.pop("layers", [])
+        self._include_breakdown: bool = kwargs.pop("include_breakdown", False)
+        self._scorer = None
+        self._df: list = []
+        # Populated in start(): the frozen, normalized ScoringPolicy plus
+        # the criterion/filter-index -> column-name maps used by run() to
+        # decide the column-value vs. spatial code path (spec Module 3/5).
+        self._policy: Optional[ScoringPolicy] = None
+        self._column_criteria: dict[int, str] = {}
+        self._column_filters: dict[int, str] = {}
+        super(SweetSpotScore, self).__init__(loop=loop, job=job, stat=stat, **kwargs)
+
+    async def start(self, **kwargs):
+        if self.previous:
+            if isinstance(self.input, list):
+                self._df = self.input  # multiple predecessor DataFrames
+            else:
+                self._df = [self.input]  # single predecessor DataFrame
+        else:
+            raise ComponentError(
+                "SweetSpotScore requires input DataFrames", status=404
+            )
+
+        from .layers import load_policy_file, normalize_policy
+
+        try:
+            if self._policy_file:
+                if self._policy_config:
+                    self._logger.warning(
+                        "SweetSpotScore: both 'policy_file' and 'policy' were "
+                        "provided; 'policy_file' takes precedence and the "
+                        "inline 'policy' block will be ignored."
+                    )
+                raw_policy = load_policy_file(self._policy_file, BASE_DIR)
+            elif self._policy_config:
+                raw_policy = self._policy_config
+            else:
+                raise ComponentError(
+                    "SweetSpotScore requires either 'policy' (inline) or "
+                    "'policy_file' (external YAML/JSON) configuration."
+                )
+            normalized = normalize_policy(raw_policy)
+        except FileNotFoundError as exc:
+            raise ComponentError(
+                f"SweetSpotScore: policy_file not found: {exc}"
+            ) from exc
+        except ValueError as exc:
+            raise ComponentError(
+                f"SweetSpotScore: policy configuration error: {exc}"
+            ) from exc
+
+        # Separate column-value criteria/filters from spatial ones, and
+        # strip the `_column` (and any other `_`-prefixed) metadata before
+        # constructing the frozen ScoringPolicy. Column-value entries get a
+        # placeholder `feature_type` (the engine never dispatches on it —
+        # see spec K2/OQ2) so they validate against the spatial-only
+        # `Criterion.feature_type`/`HardFilter.feature_type` Literal.
+        column_criteria: dict[int, str] = {}
+        clean_criteria = []
+        for idx, criterion in enumerate(normalized.get("criteria", [])):
+            column = criterion.get("_column")
+            clean = {k: v for k, v in criterion.items() if not k.startswith("_")}
+            if column is not None:
+                column_criteria[idx] = column
+                clean.setdefault("dataset", "__column__")
+                clean["feature_type"] = "count_within_radius"
+                clean.setdefault("params", {})
+            clean_criteria.append(clean)
+
+        column_filters: dict[int, str] = {}
+        clean_filters = []
+        for idx, hard_filter in enumerate(normalized.get("filters", [])):
+            column = hard_filter.get("_column")
+            clean = {k: v for k, v in hard_filter.items() if not k.startswith("_")}
+            if column is not None:
+                column_filters[idx] = column
+                clean.setdefault("dataset", "__column__")
+                clean["feature_type"] = "count_within_radius"
+                clean.setdefault("params", {})
+            clean_filters.append(clean)
+
+        try:
+            self._policy = ScoringPolicy(
+                **{**normalized, "criteria": clean_criteria, "filters": clean_filters}
+            )
+        except ValidationError as exc:
+            raise ComponentError(
+                f"SweetSpotScore: invalid policy configuration: {exc}"
+            ) from exc
+
+        self._column_criteria = column_criteria
+        self._column_filters = column_filters
+
+        # Only spin up the spatial scorer facade (``SweetSpotScorer``) when
+        # ``run()`` will actually take the all-spatial branch and call
+        # ``self._scorer.score(...)`` directly — column-only policies must
+        # NOT trigger a scipy/h3 import anywhere in their code path (spec
+        # K3), and mixed policies use ``extractor_registry`` directly
+        # (``_extract_spatial_feature``) instead of the scorer facade, so
+        # constructing it there would be wasted work.
+        is_all_spatial = not column_criteria and not column_filters and (
+            self._policy.criteria or self._policy.filters
+        )
+        if is_all_spatial:
+            # Lazy import: avoid pulling scipy/sklearn at component
+            # registration time — only needed once the component actually
+            # runs a spatial criterion.
+            from flowtask.interfaces.scoring import SweetSpotScorer
+
+            self._scorer = SweetSpotScorer()
+
+        await super(SweetSpotScore, self).start(**kwargs)
+        return True
+
+    def _fill_column_features(
+        self, matrix: np.ndarray, df: pd.DataFrame, mapping: dict[int, str]
+    ) -> None:
+        """Fill the given columns of ``matrix`` from ``df`` column values, in place.
+
+        Args:
+            matrix: Pre-allocated ``(N, C)`` feature/filter matrix.
+            df: The primary input DataFrame.
+            mapping: ``{column_index: column_name}`` for the column-value
+                criteria/filters to fill.
+
+        Raises:
+            ComponentError: if a referenced column is missing or non-numeric.
+        """
+        for idx, column in mapping.items():
+            if column not in df.columns:
+                raise ComponentError(
+                    f"SweetSpotScore: column {column!r} not found in input "
+                    f"DataFrame. Available columns: {list(df.columns)}"
+                )
+            series = df[column]
+            if not pd.api.types.is_numeric_dtype(series):
+                raise ComponentError(
+                    f"SweetSpotScore: column {column!r} is not numeric "
+                    f"(dtype={series.dtype})."
+                )
+            values = series.to_numpy(dtype=float)
+            nan_mask = np.isnan(values)
+            if nan_mask.any():
+                self._logger.warning(
+                    "SweetSpotScore: column %r has %d NaN value(s), "
+                    "replaced with 0.0",
+                    column,
+                    int(nan_mask.sum()),
+                )
+                values = np.nan_to_num(values, nan=0.0)
+            matrix[:, idx] = values
+
+    async def _extract_spatial_feature(
+        self,
+        candidates: CandidateGrid,
+        layers: dict[str, POILayer],
+        spec: Criterion | HardFilter,
+    ) -> np.ndarray:
+        """Compute one spatial criterion/filter's raw feature column.
+
+        Mirrors ``SweetSpotScorer``'s internal extraction step, but uses the
+        public ``extractor_registry`` directly (spec Module 3 Implementation
+        Notes) so a single spatial column can be computed for the "mixed"
+        code path without going through a full ``SweetSpotScorer.score()``
+        call.
+
+        Args:
+            candidates: The candidate grid.
+            layers: ``{dataset_name: POILayer}`` mapping.
+            spec: A ``Criterion`` or ``HardFilter``.
+
+        Returns:
+            A numpy array of shape ``(N,)`` with raw feature values.
+        """
+        from flowtask.interfaces.scoring import extractor_registry
+
+        # Ensure concrete extractors are registered (idempotent, cheap
+        # after the first call).
+        import flowtask.interfaces.scoring.extractors  # noqa: F401
+
+        try:
+            poi_layer = layers[spec.dataset]
+        except KeyError as exc:
+            raise ValueError(
+                f"No POILayer found for dataset {spec.dataset!r}. "
+                f"Available datasets: {sorted(layers.keys())}"
+            ) from exc
+        extractor_cls = extractor_registry.get(spec.feature_type)
+        extractor = extractor_cls()
+        return await extractor.compute(candidates, poi_layer, spec.params)
+
+    async def run(self):
+        from .layers import build_candidate_grid, build_poi_layers
+
+        df = self._df[0]
+        n_criteria = len(self._policy.criteria)
+        n_filters = len(self._policy.filters)
+        has_spatial_criteria = len(self._column_criteria) < n_criteria
+        has_spatial_filters = len(self._column_filters) < n_filters
+
+        # The framework-agnostic scoring package (models/service/extractors)
+        # deliberately raises plain built-in exceptions (ValueError, KeyError,
+        # pydantic's ValidationError) — it has no dependency on flowtask's
+        # DAG runtime (spec G2). This is the boundary where those errors get
+        # translated into a DAG-friendly ComponentError with a message that
+        # names this component, instead of an opaque KeyError/IndexError
+        # surfacing several frames deep from a misconfigured YAML (e.g. a
+        # `dataset` name with no matching `layers` entry, or an out-of-range
+        # `source` index). ComponentErrors raised directly below (e.g. from
+        # `_fill_column_features`) are intentionally NOT in this tuple, so
+        # they propagate unwrapped instead of being double-wrapped.
+        try:
+            if not has_spatial_criteria and not has_spatial_filters:
+                # Column-value-only path (spec K3/K4): no CandidateGrid/
+                # POILayer, no scipy/h3 import anywhere in this branch.
+                feature_matrix = np.zeros((len(df), n_criteria))
+                self._fill_column_features(feature_matrix, df, self._column_criteria)
+                filter_matrix = None
+                if n_filters:
+                    filter_matrix = np.zeros((len(df), n_filters))
+                    self._fill_column_features(filter_matrix, df, self._column_filters)
+
+                from flowtask.interfaces.scoring import ScoringEngine
+
+                result = ScoringEngine().score(
+                    feature_matrix, self._policy, filter_matrix=filter_matrix
+                )
+            elif not self._column_criteria and not self._column_filters:
+                # All-spatial — existing FEAT-190 path, unchanged (AC7).
+                candidates = build_candidate_grid(self._df, self._candidates_config)
+                layers = build_poi_layers(self._df, self._layers_config)
+                result = await self._scorer.score(candidates, layers, self._policy)
+            else:
+                # Mixed — unify column-value + spatial columns into one
+                # feature matrix, in policy.criteria/policy.filters order.
+                candidates = build_candidate_grid(self._df, self._candidates_config)
+                layers = build_poi_layers(self._df, self._layers_config)
+
+                feature_matrix = np.zeros((len(df), n_criteria))
+                self._fill_column_features(feature_matrix, df, self._column_criteria)
+                for idx, criterion in enumerate(self._policy.criteria):
+                    if idx not in self._column_criteria:
+                        feature_matrix[:, idx] = await self._extract_spatial_feature(
+                            candidates, layers, criterion
+                        )
+
+                filter_matrix = None
+                if n_filters:
+                    filter_matrix = np.zeros((len(df), n_filters))
+                    self._fill_column_features(filter_matrix, df, self._column_filters)
+                    for idx, hard_filter in enumerate(self._policy.filters):
+                        if idx not in self._column_filters:
+                            filter_matrix[:, idx] = await self._extract_spatial_feature(
+                                candidates, layers, hard_filter
+                            )
+
+                from flowtask.interfaces.scoring import ScoringEngine
+
+                result = ScoringEngine().score(
+                    feature_matrix, self._policy, filter_matrix=filter_matrix
+                )
+        except (KeyError, IndexError, ValueError, ValidationError) as exc:
+            raise ComponentError(
+                f"SweetSpotScore: configuration or scoring error: {exc}"
+            ) from exc
+
+        self._result = self._enrich_dataframe(df, result)
+        self.add_metric("NUM_ROWS", self._result.shape[0])
+        self.add_metric("NUM_COLUMNS", self._result.shape[1])
+        return self._result
+
+    def _enrich_dataframe(self, df: pd.DataFrame, result: ScoreResult) -> pd.DataFrame:
+        """Merge a ``ScoreResult`` into a copy of the original DataFrame.
+
+        Adds ``sweetspot_score`` (float, 0-100), ``sweetspot_rank`` (int,
+        1-based, descending — ties share the same rank via
+        ``method="min"``), and ``sweetspot_filtered`` (bool). When
+        ``include_breakdown`` is enabled, also adds
+        ``sweetspot_{criterion_name}_utility``/``_contribution`` columns
+        per criterion (spec Module 4).
+
+        Args:
+            df: The primary input DataFrame (never mutated — a copy is
+                returned).
+            result: The ``ScoreResult`` produced by scoring.
+
+        Returns:
+            A new, enriched DataFrame.
+        """
+        enriched = df.copy()
+
+        base_columns = ("sweetspot_score", "sweetspot_rank", "sweetspot_filtered")
+        for col in base_columns:
+            if col in enriched.columns:
+                self._logger.warning(
+                    "SweetSpotScore: column %r already exists in the input "
+                    "DataFrame, overwriting.",
+                    col,
+                )
+
+        enriched["sweetspot_score"] = result.scores
+        enriched["sweetspot_rank"] = (
+            enriched["sweetspot_score"]
+            .rank(ascending=False, method="min")
+            .astype(int)
+        )
+        enriched["sweetspot_filtered"] = result.filtered_out
+
+        if self._include_breakdown:
+            for criterion in self._policy.criteria:
+                name = criterion.name
+                for suffix, field in (
+                    ("utility", "utility"),
+                    ("contribution", "contribution"),
+                ):
+                    col_name = f"sweetspot_{name}_{suffix}"
+                    if col_name in enriched.columns:
+                        self._logger.warning(
+                            "SweetSpotScore: column %r already exists in "
+                            "the input DataFrame, overwriting.",
+                            col_name,
+                        )
+                    enriched[col_name] = [
+                        row[name][field] for row in result.breakdown
+                    ]
+
+        return enriched
+
+    async def close(self):
+        pass