qwen-sci 0.2.2__py3-none-any.whl

src/agents/idea_agent/utils/mcts/component_novelty.py

@@ -0,0 +1,342 @@
+"""Component novelty scoring utilities backed by embedding similarity."""
+
+from __future__ import annotations
+
+import math
+from collections import Counter, defaultdict
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
+from sentence_transformers import SentenceTransformer
+
+from src.agents.idea_agent.agent.prompts.component_novelty_evaluation import (
+    COMPONENT_NOVELTY_EVALUATION_PROMPT,
+)
+from src.agents.idea_agent.utils.core.json_utils import pretty_json
+from src.agents.idea_agent.utils.core.response_parsing import parse_json_response
+from src.agents.idea_agent.utils.papers.paper_graph_vector_store import (
+    PaperGraphComponentVectorStore,
+)
+
+
+def _clamp_novelty_score(value: Any) -> float:
+    score = float(value)
+    if math.isnan(score) or math.isinf(score):
+        raise ValueError(f"Invalid novelty score: {value!r}")
+    return max(0.0, min(5.0, score))
+
+
+def _clip_text(value: Any, limit: int = 6000) -> str:
+    text = "" if value is None else str(value).strip()
+    if limit <= 0 or len(text) <= limit:
+        return text
+    return text[: max(1, limit - 3)] + "..."
+
+
+from src.agents.idea_agent.utils.mcts.scientific_rubric import PROFILE_NOVELTY_AXES
+
+
+class ComponentNoveltyScorer:
+    """Retrieve nearby paper-graph nodes from component explanations and ask an LLM for novelty."""
+
+    def __init__(
+        self,
+        model_name_or_path: str = "all-MiniLM-L6-v2",
+        *,
+        index_dir: Optional[str] = None,
+        retrieval_top_k: int = 50,
+        evidence_node_top_k: int = 5,
+        evaluation_model: str = "gpt-5.2",
+        evaluation_temperature: float = 0.001,
+        evaluation_max_tokens: int = 2048,
+        chat_fn: Optional[Callable[..., str]] = None,
+        logger: Optional[Any] = None,
+        log_sink: Optional[Callable[[str, str], None]] = None,
+        vector_store: Optional[PaperGraphComponentVectorStore] = None,
+    ) -> None:
+        self.model_name_or_path = model_name_or_path
+        self.index_dir = index_dir
+        self.retrieval_top_k = max(1, int(retrieval_top_k))
+        self.evidence_node_top_k = max(1, int(evidence_node_top_k))
+        self.evaluation_model = evaluation_model
+        self.evaluation_temperature = float(evaluation_temperature)
+        self.evaluation_max_tokens = max(256, int(evaluation_max_tokens))
+        self.chat_fn = chat_fn
+        self.logger = logger
+        self.log_sink = log_sink
+
+        self._model: Optional[Any] = None
+        self._vector_store: Optional[PaperGraphComponentVectorStore] = vector_store
+        self._disabled_error: Optional[str] = None
+        self.last_novelty_axes: Dict[str, float] = {}
+
+    def _log(self, level: str, message: str, *args: Any) -> None:
+        rendered = message % args if args else message
+        if self.logger is not None:
+            log_method = getattr(self.logger, level, None)
+            if callable(log_method):
+                log_method(rendered)
+        if self.log_sink is not None:
+            try:
+                self.log_sink(level, rendered)
+            except Exception:
+                pass
+
+    def _resolve_model_source(self) -> str:
+        candidate = Path(str(self.model_name_or_path)).expanduser()
+        if candidate.exists():
+            return str(candidate.resolve())
+        local_path = Path(__file__).resolve().parents[5] / "models" / str(self.model_name_or_path)
+        return str(local_path) if local_path.exists() else str(self.model_name_or_path)
+
+    def _get_model(self) -> Any:
+        if self._model is not None:
+            return self._model
+        if self._vector_store is not None:
+            self._model = self._vector_store.get_model()
+            return self._model
+        self._model = SentenceTransformer(self._resolve_model_source())
+        return self._model
+
+    def _get_vector_store(self) -> PaperGraphComponentVectorStore:
+        if self._vector_store is None:
+            self._vector_store = PaperGraphComponentVectorStore(
+                model_name_or_path=self.model_name_or_path,
+                index_dir=self.index_dir,
+                model=self._model,
+            )
+        if self._vector_store.size <= 0:
+            self._vector_store.load(allow_stale_graph=True)
+        return self._vector_store
+
+    def _extract_components(
+        self,
+        state: Any,
+    ) -> Tuple[List[Dict[str, str]], Dict[str, Any]]:
+        if hasattr(state, "component_inventory") and callable(state.component_inventory):
+            components_with_explanations = state.component_inventory()
+            payload = state.to_payload() if hasattr(state, "to_payload") and callable(state.to_payload) else {}
+            return components_with_explanations, payload
+
+        if isinstance(state, dict):
+            components = state.get("components_with_explanations")
+            if isinstance(components, list):
+                return components, dict(state)
+
+        if isinstance(state, list):
+            return state, {}
+
+        raise ValueError("Unsupported state payload for component novelty scoring")
+
+    def _prepare_component_queries(
+        self,
+        components_with_explanations: Sequence[Dict[str, str]],
+        idea_payload: Optional[Dict[str, Any]] = None,
+    ) -> List[Dict[str, str]]:
+        queries: List[Dict[str, str]] = []
+        for item in components_with_explanations:
+            if not isinstance(item, dict):
+                continue
+            component = str(item.get("component", "")).strip()
+            explanation = str(item.get("explanation", "")).strip()
+            query_text = explanation
+            if not query_text:
+                continue
+            queries.append(
+                {
+                    "component": component or f"component_{len(queries)}",
+                    "explanation": explanation,
+                    "query_text": query_text,
+                }
+            )
+        idea_payload = idea_payload if isinstance(idea_payload, dict) else {}
+        for label, value in (
+            ("central_hypothesis", idea_payload.get("core_contribution")),
+            ("mechanism_or_relation", idea_payload.get("method")),
+        ):
+            text = str(value or "").strip()
+            if text:
+                queries.append(
+                    {
+                        "component": label,
+                        "explanation": text,
+                        "query_text": text,
+                    }
+                )
+        return queries
+
+    def _embed_queries(self, query_payloads: Sequence[Dict[str, str]]) -> Any:
+        model = self._get_model()
+        return model.encode(
+            [item["query_text"] for item in query_payloads],
+            convert_to_numpy=True,
+            normalize_embeddings=True,
+            show_progress_bar=False,
+        )
+
+    def _collect_evidence_nodes(
+        self,
+        store: PaperGraphComponentVectorStore,
+        query_payloads: Sequence[Dict[str, str]],
+        component_hits: Sequence[Sequence[Dict[str, Any]]],
+    ) -> List[Dict[str, Any]]:
+        node_counts: Counter[str] = Counter()
+        node_best_scores: Dict[str, float] = {}
+        node_support: Dict[str, List[Dict[str, Any]]] = defaultdict(list)
+
+        for query_index, hits in enumerate(component_hits):
+            query_info = query_payloads[query_index] if query_index < len(query_payloads) else {}
+            for hit in hits:
+                node_id = str(hit.get("node_id") or "")
+                if not node_id:
+                    continue
+                score = float(hit.get("score") or 0.0)
+                node_counts[node_id] += 1
+                prev = node_best_scores.get(node_id)
+                if prev is None or score > prev:
+                    node_best_scores[node_id] = score
+                if len(node_support[node_id]) < 3:
+                    node_support[node_id].append(
+                        {
+                            "query_component": query_info.get("component", ""),
+                            "query_text": _clip_text(query_info.get("query_text", "")),
+                            "matched_component": hit.get("component_name"),
+                            "score": score,
+                        }
+                    )
+
+        if not node_counts:
+            return []
+
+        ranked_node_ids = sorted(
+            node_counts.keys(),
+            key=lambda node_id: (
+                -node_counts[node_id],
+                -node_best_scores.get(node_id, 0.0),
+                str(store.get_core_node(node_id).get("paper_title") or node_id).lower(),
+            ),
+        )
+
+        evidence_nodes: List[Dict[str, Any]] = []
+        for node_id in ranked_node_ids[: self.evidence_node_top_k]:
+            core_node = store.get_core_node(node_id)
+            evidence_nodes.append(
+                {
+                    "node_id": node_id,
+                    "label": core_node.get("full_name") or core_node.get("label") or node_id,
+                    "paper_title": core_node.get("paper_title") or "",
+                    "match_count": int(node_counts[node_id]),
+                    "best_score": float(node_best_scores.get(node_id, 0.0)),
+                    "summary": _clip_text(core_node.get("summary") or ""),
+                    "insight": _clip_text(core_node.get("insight") or ""),
+                    "support": node_support.get(node_id, []),
+                }
+            )
+        return evidence_nodes
+
+    def _evaluate_with_llm(
+        self,
+        *,
+        topic: str,
+        idea_payload: Dict[str, Any],
+        components_with_explanations: Sequence[Dict[str, str]],
+        evidence_nodes: Sequence[Dict[str, Any]],
+    ) -> float:
+        if self.chat_fn is None:
+            raise RuntimeError("chat_fn is unavailable for component novelty scoring")
+
+        self.last_novelty_axes = {}
+        intervention = idea_payload.get("scientific_intervention")
+        intervention = intervention if isinstance(intervention, dict) else {}
+        profile_id = str(intervention.get("profile_id") or "generic_scientific").strip().lower()
+        novelty_axes = PROFILE_NOVELTY_AXES.get(profile_id, PROFILE_NOVELTY_AXES["generic_scientific"])
+        prompt = COMPONENT_NOVELTY_EVALUATION_PROMPT.format(
+            topic=topic or "Unknown topic",
+            profile_id=profile_id,
+            novelty_axes=", ".join(novelty_axes),
+            idea_state=pretty_json(idea_payload),
+            components_with_explanations=pretty_json(list(components_with_explanations)),
+            retrieval_top_k=self.retrieval_top_k,
+            retrieved_nodes=pretty_json(list(evidence_nodes)),
+        )
+        response = self.chat_fn(
+            prompt,
+            model=self.evaluation_model,
+            temperature=self.evaluation_temperature,
+            max_output_tokens=self.evaluation_max_tokens,
+            stage="component_novelty_evaluation",
+        )
+        payload = parse_json_response(response)
+        if isinstance(payload, list):
+            payload = payload[0] if payload else {}
+        if not isinstance(payload, dict):
+            payload = {}
+        raw_axes = payload.get("novelty_axes") if isinstance(payload, dict) else None
+        if isinstance(raw_axes, dict):
+            self.last_novelty_axes = {
+                str(key): _clamp_novelty_score(value)
+                for key, value in raw_axes.items()
+                if str(key).strip() in novelty_axes
+            }
+        score = payload.get("rubric_score")
+        if score is None:
+            score = payload.get("scientific_novelty")
+        if score is None:
+            score = payload.get("perceived_novelty", payload.get("novelty"))
+        if score is None and isinstance(payload.get("novelty_axes"), dict):
+            axis_scores = []
+            for axis_name in novelty_axes:
+                axis = payload["novelty_axes"].get(axis_name)
+                if axis is None:
+                    continue
+                try:
+                    axis_scores.append(_clamp_novelty_score(axis))
+                except (TypeError, ValueError):
+                    continue
+            if axis_scores:
+                score = sum(axis_scores) / len(axis_scores)
+        if score is None:
+            raise ValueError(f"Novelty evaluator missing rubric_score: {payload}")
+        return _clamp_novelty_score(score)
+
+    def score(self, state: Any, topic: str = "") -> float:
+        if self._disabled_error:
+            raise RuntimeError(self._disabled_error)
+
+        components_with_explanations, idea_payload = self._extract_components(state)
+        query_payloads = self._prepare_component_queries(
+            components_with_explanations,
+            idea_payload,
+        )
+        if not query_payloads:
+            raise ValueError("No component explanations were provided for novelty scoring")
+
+        try:
+            embeddings = self._embed_queries(query_payloads)
+            store = self._get_vector_store()
+        except Exception as exc:
+            self._disabled_error = str(exc)
+            raise
+
+        component_hits = store.search_component_hits_by_vectors(
+            query_embeddings=embeddings,
+            top_k=self.retrieval_top_k,
+        )
+        evidence_nodes = self._collect_evidence_nodes(store, query_payloads, component_hits)
+        if not evidence_nodes:
+            raise ValueError("Component novelty retrieval returned no evidence nodes")
+
+        self._log(
+            "info",
+            "[ComponentNovelty] Retrieved top evidence nodes: %s",
+            ", ".join(
+                f"{item['label']}#{item['match_count']}"
+                for item in evidence_nodes
+            ),
+        )
+
+        return self._evaluate_with_llm(
+            topic=topic,
+            idea_payload=idea_payload,
+            components_with_explanations=query_payloads,
+            evidence_nodes=evidence_nodes,
+        )

src/agents/idea_agent/utils/mcts/defect_registry.py

@@ -0,0 +1,302 @@
+"""Canonical defect registry shared by MCTS evaluation and skill selection."""
+
+from __future__ import annotations
+
+from typing import Dict, Optional, Set
+
+
+DEFECT_REGISTRY: Dict[str, str] = {
+    # mechanism-first innovation
+    "stagnant_novelty": (
+        "The idea lacks a genuinely new mechanism; contributions feel incremental "
+        "or re-package known techniques without a clear novel insight."
+    ),
+    "unclear_mechanism": (
+        "The core mechanism is vaguely described or under-specified, making it "
+        "hard to reproduce, reason about, or evaluate the contribution."
+    ),
+    "validation_gap": (
+        "The validation plan is missing key ablations, stress tests, or fair "
+        "comparisons needed to support the claims."
+    ),
+    # domain-neutral scientific reasoning and evidence defects
+    "unsupported_causal_link": (
+        "The proposal claims a causal or mechanistic link that is not supported "
+        "by the stated intervention, observation, proof, or evidence."
+    ),
+    "unresolved_alternative_explanation": (
+        "A competing explanation remains plausible and the proposed evidence does "
+        "not distinguish it from the preferred mechanism."
+    ),
+    "missing_comparator": (
+        "No adequate control, counterfactual, reference case, or competing condition "
+        "is specified for interpreting the claimed effect."
+    ),
+    "measurement_construct_mismatch": (
+        "The observable, assay, endpoint, or characterization does not validly "
+        "represent the construct or mechanism being claimed."
+    ),
+    "missing_boundary_condition": (
+        "The proposal does not state the regime, population, scale, assumptions, "
+        "or operating conditions where the claim holds or fails."
+    ),
+    "nonidentifiable_mechanism": (
+        "The proposed mechanism cannot be distinguished from plausible alternatives "
+        "with the stated data, experiment, observation, or proof."
+    ),
+    "confounding_or_selection_bias": (
+        "Confounding, selection, sampling, or allocation bias can explain the "
+        "observed relation and is not adequately controlled."
+    ),
+    "invalid_generalization": (
+        "The conclusion is extended beyond the supported object, sample, regime, "
+        "scale, domain, or formal validity conditions."
+    ),
+    "claim_overreach": (
+        "The wording claims more causal, universal, predictive, or mechanistic "
+        "strength than the evidence and validation can justify."
+    ),
+    "insufficient_reproducibility": (
+        "The intervention, measurement, derivation, protocol, or conditions are "
+        "not specified well enough for an independent reproduction."
+    ),
+    "missing_assumption": (
+        "A formal or scientific assumption required for the stated relation is "
+        "implicit, incomplete, or inconsistent."
+    ),
+    "missing_counterexample": (
+        "The proposal lacks a counterexample, limiting case, or failure probe that "
+        "could expose the boundary of the claim."
+    ),
+    "proof_gap": (
+        "A required proof, derivation, construction, or verification step is "
+        "missing or does not establish the stated conclusion."
+    ),
+    # alternative-path-contrast
+    "brittle_single_path": (
+        "The method assumes one dominant operating regime and lacks a structured "
+        "fallback or contrastive treatment for rare regimes, failures, or recovery."
+    ),
+    "rare_regime_failure": (
+        "Behavior under boundary conditions, overload, adversarial inputs, or "
+        "other rare regimes is weak or unexamined."
+    ),
+    "weak_fallback_behavior": (
+        "Fallback, recovery, or degraded-mode behavior is missing, underspecified, "
+        "or ineffective when the primary path breaks down."
+    ),
+    # modular architecture
+    "feature_dumping": (
+        "Multiple components or features are added simultaneously without "
+        "individual justification, making ablation or attribution impossible."
+    ),
+    "monolithic_design": (
+        "Core responsibilities are trapped inside a single tightly coupled block, "
+        "resisting modular analysis, replacement, or incremental improvement."
+    ),
+    "harder_to_ablate": (
+        "Design choices make it difficult to isolate the effect of any single "
+        "component through controlled ablation studies."
+    ),
+    # coordination across scales or layers
+    "scale_mismatch": (
+        "The solution operates at one scale, layer, or tier while the problem "
+        "requires coordination across multiple scales or granularities."
+    ),
+    "coordination_failure": (
+        "Multiple subsystems, branches, or layers fail to maintain a coherent "
+        "decision rule, causing conflicts, redundancy, or information loss."
+    ),
+    "latency_bottleneck": (
+        "A component, synchronization point, or coordination rule introduces "
+        "unacceptable latency or throughput collapse."
+    ),
+    # hierarchical decomposition
+    "responsibility_entanglement": (
+        "Planning, control, execution, or analysis responsibilities are tangled "
+        "together instead of being separated into explicit layers or roles."
+    ),
+    # feedback and adaptation
+    "silent_failure": (
+        "The system produces wrong or degraded outputs without exposing enough "
+        "signal for downstream detection or correction."
+    ),
+    "drift": (
+        "Performance degrades over time or across regimes as workloads, data, or "
+        "operating conditions shift away from the design assumptions."
+    ),
+    "open_loop_fragility": (
+        "The system acts in an open-loop manner and cannot adapt when outcomes, "
+        "errors, or environment conditions change."
+    ),
+    # theory-guided reformulation
+    "theory_gap": (
+        "The approach lacks grounding in a transferable principle, invariant, or "
+        "formal lens that could justify the mechanism design."
+    ),
+    "weak_generalization": (
+        "Evidence that the approach transfers across domains, workloads, "
+        "distributions, or operating regimes is insufficient or absent."
+    ),
+    # speculative execution
+    "over_conservative_execution": (
+        "The system pays full serialization, synchronization, or safety cost on "
+        "every path because it lacks a principled optimistic fast path."
+    ),
+    "rollback_blindspot": (
+        "The design lacks explicit detection, rollback, or repair when optimistic "
+        "actions misfire or speculative assumptions are violated."
+    ),
+    # default fallback used when no context-specific defect is identified
+    "unexplored_gap": (
+        "No specific defect has been identified yet; the idea space is still "
+        "being explored and requires targeted analysis."
+    ),
+}
+
+
+DEFECT_PROFILE_PRIORITIES: Dict[str, tuple[str, ...]] = {
+    "computational_algorithmic": (
+        "feature_dumping",
+        "latency_bottleneck",
+        "weak_fallback_behavior",
+        "monolithic_design",
+        "stagnant_novelty",
+    ),
+    "physical_materials_chemical": (
+        "measurement_construct_mismatch",
+        "unsupported_causal_link",
+        "missing_boundary_condition",
+        "insufficient_reproducibility",
+    ),
+    "life_molecular_mechanistic": (
+        "unsupported_causal_link",
+        "missing_comparator",
+        "measurement_construct_mismatch",
+        "missing_boundary_condition",
+        "confounding_or_selection_bias",
+    ),
+    "clinical_health": (
+        "missing_comparator",
+        "confounding_or_selection_bias",
+        "invalid_generalization",
+        "claim_overreach",
+        "measurement_construct_mismatch",
+        "missing_boundary_condition",
+    ),
+    "earth_environment_agro": (
+        "unsupported_causal_link",
+        "missing_boundary_condition",
+        "measurement_construct_mismatch",
+        "invalid_generalization",
+    ),
+    "energy_engineering_systems": (
+        "unsupported_causal_link",
+        "missing_boundary_condition",
+        "insufficient_reproducibility",
+        "invalid_generalization",
+    ),
+    "formal_theoretical": (
+        "missing_assumption",
+        "proof_gap",
+        "missing_counterexample",
+        "nonidentifiable_mechanism",
+        "invalid_generalization",
+    ),
+    "generic_scientific": (
+        "unsupported_causal_link",
+        "unresolved_alternative_explanation",
+        "missing_comparator",
+        "missing_boundary_condition",
+        "claim_overreach",
+    ),
+}
+
+
+# Profile-native defects are mapped onto the existing skill vocabulary so
+# legacy skill files remain readable while profile-aware selection can still
+# reward the right intervention family.
+PROFILE_DEFECT_SKILL_MATCHES: Dict[str, Dict[str, tuple[str, ...]]] = {
+    "computational_algorithmic": {},
+    "physical_materials_chemical": {
+        "measurement_construct_mismatch": ("mechanism-commit-innovation", "feedback-closed-loop"),
+        "unsupported_causal_link": ("mechanism-commit-innovation", "alternative-path-contrast"),
+        "missing_boundary_condition": ("alternative-path-contrast", "feedback-closed-loop"),
+        "insufficient_reproducibility": ("mechanism-commit-innovation", "feedback-closed-loop"),
+    },
+    "life_molecular_mechanistic": {
+        "unsupported_causal_link": ("mechanism-commit-innovation", "alternative-path-contrast"),
+        "missing_comparator": ("alternative-path-contrast",),
+        "measurement_construct_mismatch": ("mechanism-commit-innovation", "feedback-closed-loop"),
+        "missing_boundary_condition": ("alternative-path-contrast", "feedback-closed-loop"),
+        "confounding_or_selection_bias": ("alternative-path-contrast",),
+    },
+    "clinical_health": {
+        "missing_comparator": ("alternative-path-contrast",),
+        "confounding_or_selection_bias": ("alternative-path-contrast",),
+        "invalid_generalization": ("alternative-path-contrast", "theory-transfer-injection"),
+        "claim_overreach": ("alternative-path-contrast",),
+        "measurement_construct_mismatch": ("mechanism-commit-innovation", "feedback-closed-loop"),
+        "missing_boundary_condition": ("alternative-path-contrast", "feedback-closed-loop"),
+    },
+    "earth_environment_agro": {
+        "unsupported_causal_link": ("mechanism-commit-innovation", "alternative-path-contrast"),
+        "missing_boundary_condition": ("alternative-path-contrast", "feedback-closed-loop"),
+        "measurement_construct_mismatch": ("mechanism-commit-innovation", "feedback-closed-loop"),
+        "invalid_generalization": ("alternative-path-contrast", "theory-transfer-injection"),
+    },
+    "energy_engineering_systems": {
+        "unsupported_causal_link": ("mechanism-commit-innovation", "alternative-path-contrast"),
+        "missing_boundary_condition": ("alternative-path-contrast", "feedback-closed-loop"),
+        "insufficient_reproducibility": ("mechanism-commit-innovation", "feedback-closed-loop"),
+        "invalid_generalization": ("alternative-path-contrast", "theory-transfer-injection"),
+    },
+    "formal_theoretical": {
+        "missing_assumption": ("mechanism-commit-innovation", "theory-transfer-injection"),
+        "proof_gap": ("theory-transfer-injection",),
+        "missing_counterexample": ("alternative-path-contrast",),
+        "nonidentifiable_mechanism": ("alternative-path-contrast", "theory-transfer-injection"),
+        "invalid_generalization": ("alternative-path-contrast", "theory-transfer-injection"),
+    },
+    "generic_scientific": {
+        "unsupported_causal_link": ("mechanism-commit-innovation", "alternative-path-contrast"),
+        "unresolved_alternative_explanation": ("alternative-path-contrast", "theory-transfer-injection"),
+        "missing_comparator": ("alternative-path-contrast",),
+        "missing_boundary_condition": ("alternative-path-contrast", "feedback-closed-loop"),
+        "claim_overreach": ("alternative-path-contrast",),
+    },
+}
+
+
+def profile_skill_defect_tags(profile_id: Optional[str], skill_name: str) -> Set[str]:
+    """Return profile-native defects that a legacy skill can remediate."""
+
+    profile_key = str(profile_id or "generic_scientific").strip().lower()
+    profile_matches = PROFILE_DEFECT_SKILL_MATCHES.get(profile_key, {})
+    priority_tags = set(DEFECT_PROFILE_PRIORITIES.get(profile_key, ()))
+    if priority_tags:
+        profile_matches = {
+            defect: skill_names
+            for defect, skill_names in profile_matches.items()
+            if defect in priority_tags
+        }
+    skill_key = str(skill_name or "").strip()
+    return {
+        defect
+        for defect, skill_names in profile_matches.items()
+        if skill_key in skill_names
+    }
+
+
+def format_defect_registry(profile_id: Optional[str] = None) -> str:
+    """Return a prompt-friendly listing of canonical defect tags."""
+    profile_key = str(profile_id or "").strip()
+    priority_tags = set(DEFECT_PROFILE_PRIORITIES.get(profile_key, ()))
+    header = "Canonical defect tag registry (use ONLY these tags in detected_defects):"
+    if profile_key:
+        header += f"\nProfile priority: {profile_key}"
+    lines = [header]
+    for tag, desc in DEFECT_REGISTRY.items():
+        priority = " [profile-priority]" if tag in priority_tags else ""
+        lines.append(f"  - {tag}{priority}: {desc}")
+    return "\n".join(lines)