claude-smart 0.2.46 → 0.2.48

package/plugin/vendor/reflexio/reflexio/server/services/playbook/components/aggregator.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import hashlib
 import logging
 import os
 import time
@@ -24,6 +23,20 @@ from reflexio.models.config_schema import (
 from reflexio.server.api_endpoints.request_context import RequestContext
 from reflexio.server.llm.litellm_client import LiteLLMClient
 from reflexio.server.services.operation_state_utils import OperationStateManager
+from reflexio.server.services.playbook.aggregation_prompt_processing import (
+    AggregationPromptProcessingContext,
+    AggregationPromptProcessor,
+)
+from reflexio.server.services.playbook.components import (
+    aggregator_clustering,
+    aggregator_prompt_formatting,
+)
+from reflexio.server.services.playbook.components.aggregator_clustering import (
+    CLUSTERING_ALGORITHM_THRESHOLD,
+)
+from reflexio.server.services.playbook.components.aggregator_postprocessing import (
+    AggregationPostProcessing,
+)
 from reflexio.server.services.playbook.playbook_service_constants import (
     PlaybookServiceConstants,
 )
@@ -33,18 +46,12 @@ from reflexio.server.services.playbook.playbook_service_utils import (
     StructuredPlaybookContent,
     ensure_playbook_content,
 )
-from reflexio.server.services.playbook.user_detail_stripping import UserDetailStripper
 from reflexio.server.services.service_utils import log_model_response
 from reflexio.server.tracing import capture_anomaly, sentry_tags
 from reflexio.server.usage_metrics import record_usage_event
 
 logger = logging.getLogger(__name__)
 
-# Threshold for switching between clustering algorithms
-# Below this, use Agglomerative (works better with small datasets)
-# Above this, use HDBSCAN (scales better, handles noise)
-CLUSTERING_ALGORITHM_THRESHOLD = 50
-
 
 class PlaybookAggregator:
     def __init__(
@@ -52,33 +59,23 @@ class PlaybookAggregator:
         llm_client: LiteLLMClient,
         request_context: RequestContext,
         agent_version: str,
-        user_detail_stripper: UserDetailStripper | None = None,
+        aggregation_prompt_processor: AggregationPromptProcessor | None = None,
     ) -> None:
         self.client = llm_client
         self.storage = request_context.storage
         self.configurator = request_context.configurator
         self.request_context = request_context
         self.agent_version = agent_version
-        self.user_detail_stripper = user_detail_stripper
-        prompt_extra_instructions = getattr(
-            user_detail_stripper, "prompt_extra_instructions", None
-        )
-        if not isinstance(prompt_extra_instructions, str):
-            prompt_extra_instructions = None
-        self.aggregation_prompt_extra_instructions = (
-            self._format_prompt_extra_instructions(prompt_extra_instructions)
-        )
+        self.aggregation_prompt_processor = aggregation_prompt_processor
+        # Cohesive pre/post-processing component (the enterprise redaction
+        # Protocol seam). Constructed from the SAME injected instance stored
+        # above — do NOT re-resolve the AGGREGATION_PROMPT_PROCESSOR ServiceKey.
+        self._postproc = AggregationPostProcessing(aggregation_prompt_processor)
 
     # ===============================
     # private methods - operation state
     # ===============================
 
-    @staticmethod
-    def _format_prompt_extra_instructions(instructions: str | None) -> str:
-        if not instructions or not instructions.strip():
-            return ""
-        return f"{instructions.strip()}\n"
-
     def _create_state_manager(self) -> OperationStateManager:
         """
         Create an OperationStateManager for the playbook aggregator.
@@ -185,403 +182,74 @@ class PlaybookAggregator:
             last_processed_id=max_id,
         )
 
-    def _format_cluster_input(self, cluster_playbooks: list[UserPlaybook]) -> str:
-        """
-        Format a cluster of playbooks for the aggregation prompt using per-item format.
-
-        Each playbook is shown as a self-contained unit with content as the
-        primary content, followed by optional structured fields as supplementary metadata.
-
-        Args:
-            cluster_playbooks: List of raw playbooks in this cluster
+    # ===============================
+    # private methods - aggregation pre/post-processing
+    # ===============================
+    # Bodies live on the AggregationPostProcessing component (self._postproc).
+    # These thin delegators are kept for OSS test call-sites that invoke them by
+    # name (test_playbook_aggregator.py). Internal callers use self._postproc.
 
-        Returns:
-            str: Formatted input for the aggregation prompt
-        """
-        blocks = []
-        for idx, fb in enumerate(cluster_playbooks, 1):
-            lines = [f"[{idx}]"]
-            if fb.content:
-                lines.append(f'Content: "{fb.content}"')
-            if fb.trigger:
-                lines.append(f'Trigger: "{fb.trigger}"')
-            if fb.rationale:
-                lines.append(f'Rationale: "{fb.rationale}"')
-            blocks.append("\n".join(lines))
-        return "\n\n".join(blocks) if blocks else "(No playbook items)"
-
-    def _strip_prompt_field(
+    def _postprocess_aggregation_output(
         self,
-        text: str | None,
-        shared_mapping: dict[str, int],
-    ) -> str | None:
-        if text is None or self.user_detail_stripper is None:
-            return text
-        return self.user_detail_stripper.strip_user_details(
-            text, shared_mapping=shared_mapping
-        ).text
-
-    def _strip_user_playbook_for_prompt(
-        self,
-        playbook: UserPlaybook,
-        shared_mapping: dict[str, int],
-    ) -> UserPlaybook:
-        if self.user_detail_stripper is None:
-            return playbook
-        return playbook.model_copy(
-            update={
-                "content": self._strip_prompt_field(playbook.content, shared_mapping)
-                or "",
-                "trigger": self._strip_prompt_field(playbook.trigger, shared_mapping),
-                "rationale": self._strip_prompt_field(
-                    playbook.rationale, shared_mapping
-                ),
-            }
-        )
+        value: object,
+        processing_context: AggregationPromptProcessingContext | None = None,
+    ) -> tuple[object, int]:
+        return self._postproc._postprocess_aggregation_output(value, processing_context)
 
-    def _sanitize_aggregation_output_text(
+    def _aggregation_prompt_extra_instructions_for_context(
         self,
-        text: str | None,
-    ) -> tuple[str | None, int]:
-        if self.user_detail_stripper is None:
-            return text, 0
-        return self.user_detail_stripper.sanitize_aggregation_output_text(text)
-
-    def _sanitize_aggregation_response(
-        self, response: PlaybookAggregationOutput
-    ) -> tuple[PlaybookAggregationOutput, int]:
-        structured = response.playbook
-        if structured is None:
-            return response, 0
-
-        updates: dict[str, str | None] = {}
-        placeholder_count = 0
-        for field_name, value in structured.model_dump().items():
-            if not isinstance(value, str):
-                continue
-            sanitized, field_count = self._sanitize_aggregation_output_text(value)
-            placeholder_count += field_count
-            if sanitized != value:
-                updates[field_name] = sanitized
-
-        if not updates:
-            return response, 0
-        return response.model_copy(
-            update={"playbook": structured.model_copy(update=updates)}
-        ), placeholder_count
-
-    def _sanitize_aggregation_log_value(self, value: object) -> tuple[object, int]:
-        if isinstance(value, str):
-            return self._sanitize_aggregation_output_text(value)
-
-        if isinstance(value, dict):
-            sanitized: dict[object, object] = {}
-            placeholder_count = 0
-            for key, item in value.items():
-                sanitized_key, key_count = self._sanitize_aggregation_log_value(key)
-                sanitized_item, item_count = self._sanitize_aggregation_log_value(item)
-                sanitized[sanitized_key] = sanitized_item
-                placeholder_count += key_count + item_count
-            return sanitized, placeholder_count
-
-        if isinstance(value, list):
-            sanitized_items: list[object] = []
-            placeholder_count = 0
-            for item in value:
-                sanitized_item, item_count = self._sanitize_aggregation_log_value(item)
-                sanitized_items.append(sanitized_item)
-                placeholder_count += item_count
-            return sanitized_items, placeholder_count
-
-        if isinstance(value, tuple):
-            sanitized_items: list[object] = []
-            placeholder_count = 0
-            for item in value:
-                sanitized_item, item_count = self._sanitize_aggregation_log_value(item)
-                sanitized_items.append(sanitized_item)
-                placeholder_count += item_count
-            return tuple(sanitized_items), placeholder_count
-
-        return value, 0
-
-    def _record_placeholder_leakage(self, placeholder_count: int) -> None:
-        if placeholder_count <= 0:
-            return
-        logger.warning(
-            "Replaced %d residual user-detail placeholders in aggregated playbook output",
-            placeholder_count,
+        processing_context: AggregationPromptProcessingContext | None,
+    ) -> str:
+        return self._postproc._aggregation_prompt_extra_instructions_for_context(
+            processing_context
         )
 
+    def _record_postprocessing_artifacts(self, artifact_count: int) -> None:
+        self._postproc._record_postprocessing_artifacts(artifact_count)
+
     @staticmethod
     def _get_direction_key(fb: UserPlaybook) -> str:
-        """
-        Extract a similarity key from a user playbook for grouping.
-
-        Returns the raw content used for token-overlap comparison. Grouping is
-        purely content-similarity based: under Option B a skill may legitimately
-        hold mixed-orientation rules (do-rules and avoid-rules for different
-        sub-aspects of one task), so whole-content polarity is NOT derived or
-        gated here. Preserving distinct do/avoid rules when similar items are
-        merged is the aggregation prompt's responsibility.
-
-        Args:
-            fb: A user playbook item
-
-        Returns:
-            str: Content used as the similarity key for grouping
-        """
-        return fb.content or ""
+        return aggregator_prompt_formatting.get_direction_key(fb)
 
     @staticmethod
     def _token_overlap(str1: str, str2: str, threshold: float = 0.6) -> bool:
-        """
-        Check if two strings have significant token overlap using asymmetric containment.
-
-        Computes the ratio of shared tokens to the smaller set, so a short string
-        contained in a longer one still counts as a match.
-
-        Args:
-            str1: First string
-            str2: Second string
-            threshold: Minimum overlap ratio
-
-        Returns:
-            bool: True if overlap ratio >= threshold
-        """
-        tokens1 = set(str1.lower().split())
-        tokens2 = set(str2.lower().split())
-        if not tokens1 or not tokens2:
-            return False
-        intersection = len(tokens1 & tokens2)
-        overlap_ratio = max(intersection / len(tokens1), intersection / len(tokens2))
-        return overlap_ratio >= threshold
+        return aggregator_prompt_formatting.token_overlap(str1, str2, threshold)
 
     @staticmethod
     def _group_playbooks_by_direction(
         cluster_playbooks: list[UserPlaybook],
         threshold: float = 0.6,
     ) -> list[list[UserPlaybook]]:
-        """
-        Group playbooks by similarity of their content.
-
-        Uses greedy single-linkage: each playbook is assigned to the first
-        existing group that has any member with sufficient token overlap.
-        Groups are returned sorted by size descending (largest first).
-
-        Grouping is purely content-similarity based and does NOT gate on a
-        derived whole-content polarity. Under Option B a skill may hold
-        mixed-orientation rules (do-rules and avoid-rules for different
-        sub-aspects), and whole-content polarity is undefined for such a skill.
-        Keeping a do-rule and an avoid-rule as distinct rules when similar items
-        are merged into one skill is the aggregation prompt's responsibility,
-        not a mechanical split here.
-
-        Args:
-            cluster_playbooks: List of raw playbooks to group
-            threshold: Token overlap threshold for grouping
-
-        Returns:
-            list[list[UserPlaybook]]: Groups sorted by size descending
-        """
-        groups: list[list[UserPlaybook]] = []
-
-        for fb in cluster_playbooks:
-            key = PlaybookAggregator._get_direction_key(fb)
-            matched = False
-            for group in groups:
-                if any(
-                    PlaybookAggregator._token_overlap(
-                        key,
-                        PlaybookAggregator._get_direction_key(group_fb),
-                        threshold,
-                    )
-                    for group_fb in group
-                ):
-                    group.append(fb)
-                    matched = True
-                    break
-            if not matched:
-                groups.append([fb])
-
-        # Sort by group size descending (largest first)
-        groups.sort(key=len, reverse=True)
-        return groups
+        return aggregator_prompt_formatting.group_playbooks_by_direction(
+            cluster_playbooks, threshold
+        )
 
     def _format_structured_cluster_input(
         self,
         cluster_playbooks: list[UserPlaybook],
         direction_overlap_threshold: float = 0.6,
     ) -> str:
-        """
-        Format a cluster of playbooks for structured aggregation prompt.
-
-        When the cluster forms a single similarity group, uses the flat-list
-        format. When distinct similarity groups are detected (multiple groups),
-        uses a grouped format so the LLM can see which items are similar and
-        preserve distinct rules (e.g. a do-rule and an avoid-rule) as separate
-        rules in the merged skill rather than collapsing them.
-
-        Args:
-            cluster_playbooks: List of raw playbooks in this cluster
-            direction_overlap_threshold: Token overlap threshold for grouping by direction
-
-        Returns:
-            str: Formatted input for the aggregation prompt
-        """
-        groups = self._group_playbooks_by_direction(
-            cluster_playbooks, threshold=direction_overlap_threshold
+        return aggregator_prompt_formatting.format_structured_cluster_input(
+            cluster_playbooks,
+            direction_overlap_threshold=direction_overlap_threshold,
         )
 
-        if len(groups) <= 1:
-            return self._format_flat(cluster_playbooks)
-        return self._format_grouped(groups)
-
-    def _format_flat(self, cluster_playbooks: list[UserPlaybook]) -> str:
-        """
-        Format playbooks as flat bullet lists (original format, used when no conflict).
-
-        Args:
-            cluster_playbooks: List of raw playbooks in this cluster
-
-        Returns:
-            str: Formatted input with separate field lists
-        """
-        triggers = []
-        rationales = []
-
-        for fb in cluster_playbooks:
-            if fb.trigger:
-                triggers.append(fb.trigger)
-            if fb.rationale:
-                rationales.append(fb.rationale)
-
-        lines: list[str] = []
-
-        if triggers:
-            lines.append("TRIGGER conditions (to be consolidated):")
-            lines.extend(f"- {trigger}" for trigger in triggers)
-        else:
-            lines.append("TRIGGER conditions: (none specified)")
-
-        if rationales:
-            lines.append("RATIONALE summaries:")
-            lines.extend(f"- {r}" for r in rationales)
-
-        self._append_freeform_observations(lines, cluster_playbooks)
-
-        return "\n".join(lines)
-
-    def _format_grouped(
-        self,
-        groups: list[list[UserPlaybook]],
-    ) -> str:
-        """
-        Format playbooks in grouped layout (used when conflicting directions are detected).
-
-        Args:
-            groups: AgentPlaybook groups sorted by size descending
-
-        Returns:
-            str: Formatted input with group headers and per-playbook fields
-        """
-        lines: list[str] = [
-            "The following playbook items are grouped by similarity. "
-            "Groups are ordered by size (largest first).",
-            "",
-        ]
-
-        for idx, group in enumerate(groups, start=1):
-            count_label = "playbook" if len(group) == 1 else "playbooks"
-            lines.append(f"Group {idx} ({len(group)} {count_label}):")
-            for fb in group:
-                parts: list[str] = []
-                if fb.trigger:
-                    parts.append(f'Trigger: "{fb.trigger}"')
-                if fb.rationale:
-                    parts.append(f'Rationale: "{fb.rationale}"')
-                if not parts and fb.content:
-                    parts.append(f'AgentPlaybook: "{fb.content}"')
-                if parts:
-                    lines.append(f"  - {parts[0]}")
-                    lines.extend(f"    {p}" for p in parts[1:])
-            lines.append("")
-
-        return "\n".join(lines)
-
-    @staticmethod
-    def _append_freeform_observations(
-        lines: list[str], cluster_playbooks: list[UserPlaybook]
-    ) -> None:
-        """Append freeform observations from cluster playbooks to output lines."""
-        freeform_observations = [
-            fb.content for fb in cluster_playbooks if not fb.trigger and fb.content
-        ]
-        if freeform_observations:
-            lines.append("Freeform observations (from freeform cluster members):")
-            lines.extend(f"- {obs}" for obs in freeform_observations)
-
     # ===============================
     # private methods - cluster change detection
     # ===============================
 
     @staticmethod
     def _compute_cluster_fingerprint(cluster_playbooks: list[UserPlaybook]) -> str:
-        """
-        Compute a fingerprint for a cluster based on its user_playbook_ids.
-        The fingerprint is deterministic and order-independent.
-
-        Args:
-            cluster_playbooks: List of raw playbooks in this cluster
-
-        Returns:
-            str: SHA-256 hash (truncated to 16 hex chars) of sorted user_playbook_ids
-        """
-        sorted_ids = sorted(fb.user_playbook_id for fb in cluster_playbooks)
-        id_str = ",".join(str(id) for id in sorted_ids)
-        return hashlib.sha256(id_str.encode()).hexdigest()[:16]
+        return aggregator_clustering.compute_cluster_fingerprint(cluster_playbooks)
 
     def _determine_cluster_changes(
         self,
         clusters: dict[int, list[UserPlaybook]],
         prev_fingerprints: dict,
     ) -> tuple[dict[int, list[UserPlaybook]], list[int]]:
-        """
-        Compare current cluster fingerprints against stored fingerprints to determine changes.
-
-        Args:
-            clusters: Current clusters (cluster_id -> list of UserPlaybook)
-            prev_fingerprints: Previous fingerprint state
-                (fingerprint_hash -> {"agent_playbook_id": int, "user_playbook_ids": list})
-
-        Returns:
-            tuple of:
-                - changed_clusters: Only clusters needing new LLM calls
-                - playbook_ids_to_archive: Old playbook_ids from changed/disappeared clusters
-        """
-        # Compute fingerprints for current clusters
-        current_fingerprints = {}
-        for cluster_id, cluster_playbooks in clusters.items():
-            fp = self._compute_cluster_fingerprint(cluster_playbooks)
-            current_fingerprints[cluster_id] = fp
-
-        current_fp_set = set(current_fingerprints.values())
-        prev_fp_set = set(prev_fingerprints.keys())
-
-        # Changed clusters: fingerprints that are new (not in previous state)
-        changed_clusters = {}
-        for cluster_id, fp in current_fingerprints.items():
-            if fp not in prev_fp_set:
-                changed_clusters[cluster_id] = clusters[cluster_id]
-
-        # Playbook IDs to archive: from fingerprints that disappeared or changed
-        playbook_ids_to_archive = []
-        for fp, fp_data in prev_fingerprints.items():
-            if fp not in current_fp_set:
-                playbook_id = fp_data.get("agent_playbook_id")
-                if playbook_id is not None:
-                    playbook_ids_to_archive.append(playbook_id)
-
-        return changed_clusters, playbook_ids_to_archive
+        return aggregator_clustering.determine_cluster_changes(
+            clusters, prev_fingerprints
+        )
 
     # ===============================
     # public methods
@@ -692,9 +360,9 @@ class PlaybookAggregator:
             self.agent_version,
         )
         logger.info(
-            "User detail stripping for aggregation: %s",
-            type(self.user_detail_stripper).__name__
-            if self.user_detail_stripper is not None
+            "Aggregation prompt processor: %s",
+            type(self.aggregation_prompt_processor).__name__
+            if self.aggregation_prompt_processor is not None
             else "disabled",
         )
 
@@ -979,6 +647,22 @@ class PlaybookAggregator:
             # Remove archived playbooks after successful aggregation. ALWAYS soft-supersede
             # (never hard-delete) so the removal is reconstructable from lineage — mirrors the
             # profile dedup always-soft path (#206).
+            archived_ids_without_overlapping_changed_cluster: set[int] = set()
+            if new_playbooks and prev_fingerprints:
+                archived_id_set = set(archived_playbook_ids)
+                for prev_fp, fp_data in prev_fingerprints.items():
+                    playbook_id = fp_data.get("agent_playbook_id")
+                    if (
+                        playbook_id in archived_id_set
+                        and prev_fp not in changed_fps_by_previous_fp
+                    ):
+                        archived_ids_without_overlapping_changed_cluster.add(
+                            playbook_id
+                        )
+            ids_to_supersede = {
+                *selective_supersede_playbook_ids,
+                *archived_ids_without_overlapping_changed_cluster,
+            }
             if not _run_id:
                 # Empty request_id makes the removal unreconstructable (lineage events are keyed
                 # on it). Fail loud and skip removal — never silently hard-delete.
@@ -996,9 +680,9 @@ class PlaybookAggregator:
                                 agent_version=self.agent_version,
                                 request_id=_run_id,
                             )
-                    elif selective_supersede_playbook_ids:
+                    elif ids_to_supersede:
                         self.storage.supersede_agent_playbooks_by_ids(  # type: ignore[reportOptionalMemberAccess]
-                            sorted(selective_supersede_playbook_ids),
+                            sorted(ids_to_supersede),
                             request_id=_run_id,
                         )
                     elif archived_playbook_ids:
@@ -1107,7 +791,9 @@ class PlaybookAggregator:
         # Mock mode: cluster by trigger
         if os.getenv("MOCK_LLM_RESPONSE", "").lower() == "true":
             logger.info("Mock mode: clustering by trigger")
-            return self._cluster_by_trigger_mock(user_playbooks, min_cluster_size)
+            return aggregator_clustering.cluster_by_trigger_mock(
+                user_playbooks, min_cluster_size
+            )
 
         # Extract embeddings from user playbooks
         import numpy as np
@@ -1162,139 +848,26 @@ class PlaybookAggregator:
 
         return clusters
 
-    def _cluster_by_trigger_mock(
-        self, user_playbooks: list[UserPlaybook], min_cluster_size: int
-    ) -> dict[int, list[UserPlaybook]]:
-        """
-        Simple mock clustering by exact trigger match.
-
-        Args:
-            user_playbooks: List of user playbooks with trigger field
-            min_cluster_size: Minimum number of playbooks per cluster
-
-        Returns:
-            dict[int, list[UserPlaybook]]: Clusters grouped by trigger
-        """
-        # Group by trigger
-        condition_groups: dict[str, list[UserPlaybook]] = {}
-        for fb in user_playbooks:
-            condition = fb.trigger or ""
-            if condition not in condition_groups:
-                condition_groups[condition] = []
-            condition_groups[condition].append(fb)
-
-        # Convert to cluster format, filtering by min_cluster_size
-        clusters: dict[int, list[UserPlaybook]] = {}
-        cluster_id = 0
-        for playbooks_group in condition_groups.values():
-            if len(playbooks_group) >= min_cluster_size:
-                clusters[cluster_id] = playbooks_group
-                cluster_id += 1
-
-        logger.info(
-            "Mock mode: created %d trigger clusters from %d playbooks",
-            len(clusters),
-            len(user_playbooks),
-        )
-        return clusters
-
     def _cluster_with_agglomerative(
         self,
         distance_matrix: np.ndarray,
-        min_cluster_size: int,  # noqa: ARG002
+        min_cluster_size: int,
         distance_threshold: float,
     ) -> np.ndarray:
-        """
-        Cluster using Agglomerative Clustering - best for small datasets.
-
-        Args:
-            distance_matrix: Precomputed cosine distance matrix
-            min_cluster_size: Minimum cluster size (used for logging only,
-                              filtering happens in get_clusters)
-            distance_threshold: Maximum cosine distance to merge clusters (1 - similarity_threshold)
-
-        Returns:
-            np.ndarray: Cluster labels for each point
-        """
-        from sklearn.cluster import AgglomerativeClustering
-
-        logger.info(
-            "Using Agglomerative Clustering for %d playbooks (< %d threshold), distance_threshold=%.2f",
-            len(distance_matrix),
-            CLUSTERING_ALGORITHM_THRESHOLD,
-            distance_threshold,
-        )
-
-        clusterer = AgglomerativeClustering(
-            n_clusters=None,  # type: ignore[reportArgumentType]
-            distance_threshold=distance_threshold,
-            metric="precomputed",
-            linkage="average",
+        return aggregator_clustering.cluster_with_agglomerative(
+            distance_matrix, min_cluster_size, distance_threshold
         )
 
-        return clusterer.fit_predict(distance_matrix)
-
     def _cluster_with_hdbscan(
         self,
         distance_matrix: np.ndarray,
         min_cluster_size: int,
         distance_threshold: float,
     ) -> np.ndarray:
-        """
-        Cluster using HDBSCAN - best for large datasets with potential noise.
-
-        Args:
-            distance_matrix: Precomputed cosine distance matrix
-            min_cluster_size: Minimum number of points to form a cluster
-            distance_threshold: Maximum cosine distance for cluster merging (1 - similarity_threshold)
-
-        Returns:
-            np.ndarray: Cluster labels for each point (-1 indicates noise)
-        """
-        import hdbscan
-
-        logger.info(
-            "Using HDBSCAN for %d playbooks (>= %d threshold), distance_threshold=%.2f",
-            len(distance_matrix),
-            CLUSTERING_ALGORITHM_THRESHOLD,
-            distance_threshold,
-        )
-
-        clusterer = hdbscan.HDBSCAN(
-            min_cluster_size=min_cluster_size,
-            min_samples=1,
-            metric="precomputed",
-            cluster_selection_epsilon=distance_threshold,
+        return aggregator_clustering.cluster_with_hdbscan(
+            distance_matrix, min_cluster_size, distance_threshold
         )
 
-        return clusterer.fit_predict(distance_matrix)
-
-    def _generate_playbooks_from_clusters(
-        self,
-        clusters: dict[int, list[UserPlaybook]],
-        existing_approved_playbooks: list[AgentPlaybook],
-        direction_overlap_threshold: float = 0.6,
-    ) -> list[AgentPlaybook]:
-        """
-        Generate playbooks from clusters, considering existing approved playbooks.
-
-        Args:
-            clusters: Dictionary mapping cluster IDs to lists of raw playbooks
-            existing_approved_playbooks: List of existing approved playbooks to avoid duplication
-            direction_overlap_threshold: Token overlap threshold for grouping by direction
-
-        Returns:
-            list[AgentPlaybook]: List of newly generated playbooks (excludes duplicates)
-        """
-        return [
-            playbook
-            for playbook, _ in self._generate_playbooks_with_source_clusters(
-                clusters,
-                existing_approved_playbooks,
-                direction_overlap_threshold=direction_overlap_threshold,
-            )
-        ]
-
     def _generate_playbooks_with_source_clusters(
         self,
         clusters: dict[int, list[UserPlaybook]],
@@ -1309,12 +882,20 @@ class PlaybookAggregator:
             else "None"
         )
         for cluster_playbooks in clusters.values():
-            shared_mapping: dict[str, int] = {}
-            if self.user_detail_stripper is None:
+            shared_state: dict[str, object] = {}
+            processing_context = AggregationPromptProcessingContext(
+                data={
+                    "agent_version": self.agent_version,
+                    "org_id": self.request_context.org_id,
+                }
+            )
+            if self.aggregation_prompt_processor is None:
                 prompt_cluster_playbooks = cluster_playbooks
             else:
                 prompt_cluster_playbooks = [
-                    self._strip_user_playbook_for_prompt(playbook, shared_mapping)
+                    self._postproc._preprocess_user_playbook_for_prompt(
+                        playbook, shared_state, processing_context
+                    )
                     for playbook in cluster_playbooks
                 ]
 
@@ -1322,6 +903,7 @@ class PlaybookAggregator:
                 prompt_cluster_playbooks,
                 approved_playbooks_str,
                 direction_overlap_threshold=direction_overlap_threshold,
+                processing_context=processing_context,
             )
             if playbook is not None:
                 new_playbooks.append((playbook, cluster_playbooks))
@@ -1371,6 +953,7 @@ class PlaybookAggregator:
         cluster_playbooks: list[UserPlaybook],
         existing_approved_playbooks_str: str,
         direction_overlap_threshold: float = 0.6,
+        processing_context: AggregationPromptProcessingContext | None = None,
     ) -> AgentPlaybook | None:
         """
         Generate a playbook from a cluster using structured JSON output.
@@ -1407,8 +990,11 @@ class PlaybookAggregator:
                     trigger=trigger,
                 )
             )
-            response, placeholder_count = self._sanitize_aggregation_response(response)
-            self._record_placeholder_leakage(placeholder_count)
+            response, artifact_count = self._postproc._postprocess_aggregation_response(
+                response,
+                processing_context,
+            )
+            self._postproc._record_postprocessing_artifacts(artifact_count)
             playbook = self._process_aggregation_response(response, cluster_playbooks)
             if playbook is None:
                 return None
@@ -1428,7 +1014,9 @@ class PlaybookAggregator:
                     {
                         "user_playbooks": raw_playbooks_str,
                         "existing_approved_playbooks": existing_approved_playbooks_str,
-                        "aggregation_prompt_extra_instructions": self.aggregation_prompt_extra_instructions,
+                        "aggregation_prompt_extra_instructions": self._postproc._aggregation_prompt_extra_instructions_for_context(
+                            processing_context
+                        ),
                     },
                 ),
             }
@@ -1442,15 +1030,21 @@ class PlaybookAggregator:
                 parse_structured_output=True,
             )
             if isinstance(response, PlaybookAggregationOutput):
-                response, placeholder_count = self._sanitize_aggregation_response(
-                    response
+                response, artifact_count = (
+                    self._postproc._postprocess_aggregation_response(
+                        response,
+                        processing_context,
+                    )
                 )
-                self._record_placeholder_leakage(placeholder_count)
+                self._postproc._record_postprocessing_artifacts(artifact_count)
             else:
-                response, placeholder_count = self._sanitize_aggregation_log_value(
-                    response
+                response, artifact_count = (
+                    self._postproc._postprocess_aggregation_output(
+                        response,
+                        processing_context,
+                    )
                 )
-                self._record_placeholder_leakage(placeholder_count)
+                self._postproc._record_postprocessing_artifacts(artifact_count)
             log_model_response(logger, "Aggregation structured response", response)
 
             if not isinstance(response, PlaybookAggregationOutput):
@@ -1462,13 +1056,16 @@ class PlaybookAggregator:
 
             return self._process_aggregation_response(response, cluster_playbooks)
         except Exception as exc:
-            sanitized_error, placeholder_count = self._sanitize_aggregation_log_value(
-                str(exc)
+            processed_error, artifact_count = (
+                self._postproc._postprocess_aggregation_output(
+                    str(exc),
+                    processing_context,
+                )
             )
-            self._record_placeholder_leakage(placeholder_count)
+            self._postproc._record_postprocessing_artifacts(artifact_count)
             logger.error(
                 "AgentPlaybook aggregation failed due to %s, returning None.",
-                sanitized_error,
+                processed_error,
             )
             return None
 
@@ -1482,7 +1079,7 @@ class PlaybookAggregator:
             response: Parsed PlaybookAggregationOutput from LLM
             cluster_playbooks: Cluster playbooks used only for non-user metadata
                 such as playbook name and agent version. Callers may pass
-                prompt-sanitized copies here, so this method must not read
+                prompt-preprocessed copies here, so this method must not read
                 user-authored fields from them.
 
         Returns:
@@ -1490,7 +1087,6 @@ class PlaybookAggregator:
         """
         if not response:
             return None
-        response, _placeholder_count = self._sanitize_aggregation_response(response)
 
         structured = response.playbook
         if structured is None: