Theoretical Enrichment & Tenability Evaluation¶

class TheoreticalEnrichmentRunner(PhaseRunner[Phase4ArtifactsView]):
    """Executes Theoretical Enrichment & Tenability Evaluation post-processing.

    Parameters
    ----------
    config : TheoreticalEnrichmentConfig | None, optional
        Configuration block for Theoretical Enrichment, by default None.
    schema : SchemaConfig | None, optional
        Decoupled schema configuration, by default None.
    graph_store : ProjectionGraph | None, optional
        Graph backend to project enriched parameters and scores into, by default None.
    registry : TheoryRegistry | None, optional
        Registry of formal Theory-Element definitions, by default None.
    projector : TheoryProjector | None, optional
        Domain projection engine (Phi_spec), by default None.
    solver : TenabilitySolver | None, optional
        Tenability optimization solver, by default None.
    inducer : TheoryInducer | None, optional
        Dynamic Theory-Element induction engine, by default None.
    llm : Any | None, optional
        Underlying LLM facade for induction and projection, by default None.
    """

    name = "Theoretical Enrichment & Tenability Evaluation"
    phase_key = "theoretical_enrichment"
    input_view = Phase4ArtifactsView

    def __init__(
        self,
        config: TheoreticalEnrichmentConfig | None = None,
        schema: SchemaConfig | None = None,
        graph_store: ProjectionGraph | None = None,
        registry: TheoryRegistry | None = None,
        projector: TheoryProjector | None = None,
        solver: TenabilitySolver | None = None,
        inducer: TheoryInducer | None = None,
        llm: Any | None = None,
    ) -> None:
        self.config = config or TheoreticalEnrichmentConfig()
        self.schema = schema or SchemaConfig()
        self.graph_store = graph_store
        self.registry = registry or TheoryRegistry()
        self.llm: StructuredLLM | None = ensure_structured_llm(llm) if llm is not None else None

        if inducer is not None:
            self.inducer: TheoryInducer | None = inducer
        elif self.llm is not None and self.config.induce_theories:
            self.inducer = LLMTheoryInducer(
                llm=self.llm,
                prompts=self.config.induction_prompts,
                strategy=self.config.decoding_strategy,
            )
        else:
            self.inducer = None

        if projector is not None:
            self.projector = projector
        elif self.llm is not None:
            self.projector = LLMTheoryProjector(
                llm=self.llm,
                prompts=self.config.projection_prompts,
                strategy=self.config.decoding_strategy,
            )
        else:
            self.projector = CompositeTheoryProjector()

        self.solver = solver or TenabilitySolver(
            anomaly_threshold=self.config.tenability_threshold,
            weight_local=self.config.weight_local,
            weight_edge=self.config.weight_edge,
        )

    @property
    def event_emitter(self) -> EventEmitter:
        """Centralized event emitter."""
        return get_event_emitter()

    async def run(
        self, input: Phase4ArtifactsView, context: ArtifactExecutionContext
    ) -> ArtifactCollection:
        """Run the Theoretical Enrichment and Tenability Evaluation post-processor.

        Parameters
        ----------
        input : Phase4ArtifactsView
            Typed slice of upstream Phase 4/5 theory atoms and relations.
        context : ArtifactExecutionContext
            Execution run context and manifest tracking.

        Returns
        -------
        ArtifactCollection
            Collection of emitted TheoreticalEnrichmentArtifact envelopes.
        """
        logger.info(
            "Theoretical Enrichment: Beginning evaluation on %d atoms and %d relations",
            len(input.theory_atoms),
            len(input.theory_relations),
        )

        if not self.config.enabled:
            logger.info("Theoretical Enrichment is disabled in config. Skipping.")
            return ArtifactCollection([])

        # -------------------------------------------------------------
        # Stage 0: Dynamic Theory-Element Induction (Macro Scope)
        # -------------------------------------------------------------
        if not self.registry.all_theories() and self.config.induce_theories and self.inducer:
            logger.info("Theoretical Enrichment: Registry is unseeded. Running LLM Theory-Element induction...")
            induced = await self.inducer.induce_theories(
                atoms=input.theory_atoms,
                relations=input.theory_relations,
                schema=self.schema,
                max_theories=self.config.max_theories,
            )
            for theory in induced:
                self.registry.register(theory)
            logger.info(
                "Theoretical Enrichment: Successfully induced and registered %d theories: %s",
                len(induced),
                [t.theory_id for t in induced],
            )

        # -------------------------------------------------------------
        # Step 1: Cluster Mapping (Application Identification)
        # -------------------------------------------------------------
        clusters = self._identify_empirical_clusters(
            input.theory_atoms, input.theory_relations
        )
        logger.info(
            "Theoretical Enrichment: Identified %d empirical clusters (Intended Applications I)",
            len(clusters),
        )

        # Map each cluster to claiming theories
        for cluster in clusters:
            claimants = self.registry.match_claimants(cluster)
            if not claimants:
                # Default to all registered theories for evaluation
                claimants = [t.theory_id for t in self.registry.all_theories()]
            cluster.claimant_theory_ids = claimants

            self.event_emitter.emit(
                TheoreticalClusterIdentified(
                    run_id=context.run_id,
                    phase=self.name,
                    cluster_id=cluster.cluster_id,
                    observation_count=len(cluster.observations),
                    claimant_theories=claimants,
                )
            )

        # -------------------------------------------------------------
        # Step 2: Domain-Specific Projections (Phi_spec)
        # Step 3: Local Tenability Calculation (TS_local)
        # Step 4: Global and Intertheoretical Consistency (GL)
        # -------------------------------------------------------------
        enrichment_artifacts: list[ArtifactEnvelope[TheoreticalEnrichmentArtifact]] = []
        cluster_theory_params: dict[tuple[str, str], dict[str, Any]] = {}
        atoms_to_update: list[TheoryAtom] = []
        relations_to_update: list[dict[str, Any]] = []

        atom_by_id = {a.id: a for a in input.theory_atoms}

        for cluster in clusters:
            for theory_id in cluster.claimant_theory_ids:
                theory = self.registry.get(theory_id)
                if not theory:
                    continue

                # Step 2: Project cluster through the theory-specific lens (Phi_spec)
                if hasattr(self.projector, "aproject"):
                    projected_params = await self.projector.aproject(cluster, theory)
                else:
                    projected_params = self.projector.project(cluster, theory)
                cluster_theory_params[(cluster.cluster_id, theory_id)] = projected_params

                self.event_emitter.emit(
                    TheoreticalParametersProjected(
                        run_id=context.run_id,
                        phase=self.name,
                        cluster_id=cluster.cluster_id,
                        theory_id=theory_id,
                        parameters=projected_params,
                    )
                )

                # Step 3: Local Tenability Calculation (TS_local)
                ts_local, delta_star, local_anomalies = self.solver.solve_local_tenability(
                    projected_params, theory
                )

                for anom in local_anomalies:
                    self.event_emitter.emit(
                        TenabilityAnomalyDetected(
                            run_id=context.run_id,
                            phase=self.name,
                            element_id=cluster.cluster_id,
                            theory_id=theory_id,
                            score=ts_local,
                            reason=anom,
                        )
                    )

                # Step 4: Edge Tenability Calculation (TS_edge) across cluster relations
                edge_scores: dict[str, float] = {}
                edge_anomalies: list[str] = []

                for rel in cluster.relations:
                    rel_key = f"{rel.source_id}->{rel.relation_type}->{rel.target_id}"

                    # Look up counterpart params (either target node's cluster or sibling theory)
                    target_params = self._find_target_parameters(
                        rel.target_id, clusters, cluster_theory_params, theory_id
                    )

                    ts_edge, delta_c, anoms = self.solver.solve_edge_tenability(
                        source_params=projected_params,
                        target_params=target_params,
                        relation=rel,
                    )
                    edge_scores[rel_key] = ts_edge
                    edge_anomalies.extend(anoms)

                    for anom in anoms:
                        self.event_emitter.emit(
                            TenabilityAnomalyDetected(
                                run_id=context.run_id,
                                phase=self.name,
                                element_id=rel_key,
                                theory_id=theory_id,
                                score=ts_edge,
                                reason=anom,
                            )
                        )

                    # Stage relation for graph update
                    rel_copy = rel.model_copy()
                    rel_copy.tenability = ts_edge
                    relations_to_update.append(
                        {
                            "from_id": rel.source_id,
                            "relation_type": rel.relation_type,
                            "to_id": rel.target_id,
                            "properties": {
                                "confidence": rel.confidence,
                                "scope": rel.scope,
                                "tenability": ts_edge,
                                "weight": rel.weight,
                            },
                        }
                    )

                tenability_res = self.solver.evaluate_theory_tenability(
                    local_score=ts_local,
                    edge_scores=edge_scores,
                    delta_star=delta_star,
                    local_anomalies=local_anomalies,
                    edge_anomalies=edge_anomalies,
                )

                self.event_emitter.emit(
                    TenabilityEvaluationCompleted(
                        run_id=context.run_id,
                        phase=self.name,
                        theory_id=theory_id,
                        local_score=ts_local,
                        aggregated_score=tenability_res.aggregated_score,
                        is_tenable=tenability_res.is_tenable,
                        tightest_blur=delta_star,
                    )
                )

                # Attach parameters and scores to TheoreticalHypothesis nodes in the cluster
                for obs in cluster.observations:
                    if self.schema.component_partitions.get(obs.component_type) == "A":
                        obs_updated = obs.model_copy()
                        obs_updated.parameters.update(projected_params)
                        obs_updated.tenability = tenability_res
                        atoms_to_update.append(obs_updated)

                enrichment_payload = TheoreticalEnrichmentArtifact(
                    enrichment_id=f"enrichment-{uuid4()}",
                    cluster_id=cluster.cluster_id,
                    theory_id=theory_id,
                    projected_parameters=projected_params,
                    local_tenability=ts_local,
                    edge_tenabilities=edge_scores,
                    aggregated_tenability=tenability_res.aggregated_score,
                    admissible_blur_delta=delta_star,
                    is_tenable=tenability_res.is_tenable,
                    anomalies=tenability_res.anomalies,
                )

                envelope = ArtifactEnvelope[TheoreticalEnrichmentArtifact](
                    artifact_id=enrichment_payload.enrichment_id,
                    kind=ArtifactKind.THEORETICAL_ENRICHMENT,
                    run_id=context.run_id,
                    phase_name=self.name,
                    method="theoretical_enrichment",
                    payload=enrichment_payload,
                    provenance=ArtifactProvenance(
                        source_chunk_id=cluster.observations[0].source_chunk_id
                        if cluster.observations
                        else None
                    ),
                )
                enrichment_artifacts.append(envelope)

        # -------------------------------------------------------------
        # Step 5: Graph Persistence
        # -------------------------------------------------------------
        if self.graph_store:
            from itertools import batched

            if atoms_to_update:
                for batch in batched(atoms_to_update, 500):
                    await self.graph_store.upsert_argument_components(list(batch))

            if relations_to_update:
                for batch in batched(relations_to_update, 500):
                    await self.graph_store.upsert_relations(list(batch))

            logger.info(
                "Theoretical Enrichment: Projected %d enriched TheoryAtoms and %d relations to graph store",
                len(atoms_to_update),
                len(relations_to_update),
            )

        return ArtifactCollection(enrichment_artifacts)

    def _identify_empirical_clusters(
        self, atoms: list[TheoryAtom], relations: list[TheoryRelation]
    ) -> list[EmpiricalCluster]:
        """Group ObservationUnit nodes into empirical clusters (Intended Applications).

        Parameters
        ----------
        atoms : list[TheoryAtom]
            Input theory atoms.
        relations : list[TheoryRelation]
            Input theory relations.

        Returns
        -------
        list[EmpiricalCluster]
            List of empirical clusters.
        """
        # Group observation units by chunk id as base empirical partitions
        clusters_by_chunk: dict[str, list[TheoryAtom]] = {}
        for atom in atoms:
            clusters_by_chunk.setdefault(atom.source_chunk_id, []).append(atom)

        rel_by_chunk: dict[str, list[TheoryRelation]] = {}
        atom_chunk_map = {a.id: a.source_chunk_id for a in atoms}
        for rel in relations:
            chunk_s = atom_chunk_map.get(rel.source_id)
            if chunk_s:
                rel_by_chunk.setdefault(chunk_s, []).append(rel)

        clusters: list[EmpiricalCluster] = []
        for chunk_id, cluster_atoms in clusters_by_chunk.items():
            cluster_id = f"cluster-{chunk_id}"
            cluster_rels = rel_by_chunk.get(chunk_id, [])
            clusters.append(
                EmpiricalCluster(
                    cluster_id=cluster_id,
                    observations=cluster_atoms,
                    claimant_theory_ids=[],
                    relations=cluster_rels,
                )
            )

        return clusters

    def _find_target_parameters(
        self,
        target_id: str,
        clusters: list[EmpiricalCluster],
        cluster_theory_params: dict[tuple[str, str], dict[str, Any]],
        current_theory_id: str,
    ) -> dict[str, Any]:
        """Find parameters postulated at a target node or its associated theories."""
        # Find which cluster target_id belongs to
        for cluster in clusters:
            for obs in cluster.observations:
                if obs.id == target_id:
                    # Check if current theory or an overlapping theory has projected parameters
                    for (c_id, t_id), params in cluster_theory_params.items():
                        if c_id == cluster.cluster_id:
                            return params

        # Fallback to current parameters if self-referential or not yet resolved
        return {}

class LLMTheoryInducer:
    """LLM-backed inducer for discovering Theory-Elements from epistemic graphs.

    Parameters
    ----------
    llm : Any
        Underlying LLM facade or StructuredLLM instance.
    prompts : StructuredPromptBundle | str | None, optional
        Custom prompt bundle or template string, by default None.
    strategy : Any, optional
        Decoding strategy for structured prediction, by default "direct_constrained".
    """

    def __init__(
        self,
        llm: Any,
        prompts: StructuredPromptBundle | str | None = None,
        strategy: Any = "direct_constrained",
    ) -> None:
        self.llm: StructuredLLM = ensure_structured_llm(llm)
        self.prompts = prompts or THEORY_INDUCTION_DIRECT_PROMPT
        self.strategy = strategy

    async def induce_theories(
        self,
        atoms: list[TheoryAtom],
        relations: list[TheoryRelation],
        schema: SchemaConfig | None = None,
        max_theories: int = 5,
    ) -> list[TheoryElementDefinition]:
        """Induce Theory-Elements using structured LLM prediction.

        Parameters
        ----------
        atoms : list[TheoryAtom]
            Input graph nodes across partitions A and B.
        relations : list[TheoryRelation]
            Structural relations connecting atoms.
        schema : SchemaConfig | None, optional
            Graph schema defining component partitions, by default None.
        max_theories : int, optional
            Upper bound on induced theories, by default 5.

        Returns
        -------
        list[TheoryElementDefinition]
            List of induced formal Theory-Element specifications.
        """
        graph_schema = schema or DEFAULT_SCHEMA

        # Partition atoms into Theoretical (A) and Empirical (B)
        hypotheses: list[TheoryAtom] = []
        observations: list[TheoryAtom] = []

        for atom in atoms:
            part = graph_schema.component_partitions.get(atom.component_type, "")
            if part == "A" or "hypothesis" in atom.component_type.lower() or "claim" in atom.component_type.lower():
                hypotheses.append(atom)
            else:
                observations.append(atom)

        if not hypotheses:
            logger.info("LLMTheoryInducer: No TheoreticalHypothesis nodes found to induce theories from.")
            return []

        # Format prompt context
        hyp_lines = [f"- [{h.id}] {h.text}" for h in hypotheses[:30]]
        hyp_str = "\n".join(hyp_lines) if hyp_lines else "None identified."

        obs_lines = []
        for o in observations[:30]:
            dims = [f"{m.dimension}={m.value}" for m in o.measurements]
            dim_str = f" (measurements: {', '.join(dims)})" if dims else ""
            obs_lines.append(f"- [{o.id}] {o.text}{dim_str}")
        obs_str = "\n".join(obs_lines) if obs_lines else "None identified."

        rel_lines = [
            f"- {r.source_id} -[{r.relation_type}]-> {r.target_id} (conf={r.confidence})"
            for r in relations[:40]
        ]
        rel_str = "\n".join(rel_lines) if rel_lines else "None identified."

        logger.info(
            "LLMTheoryInducer: Prompting LLM on %d hypotheses and %d observations...",
            len(hypotheses),
            len(observations),
        )

        try:
            raw_output: TheoryInductionOutput = await self.llm.predict_structured(
                TheoryInductionOutput,
                self.prompts,
                strategy=self.strategy,
                theoretical_hypotheses=hyp_str,
                empirical_observations=obs_str,
                structural_relations=rel_str,
                max_theories=max_theories,
            )
        except Exception as err:
            logger.error("LLMTheoryInducer failed structured induction: %s", err)
            return []

        definitions: list[TheoryElementDefinition] = []
        for item in raw_output.theories:
            laws = [
                TheoryLaw(
                    law_id=law.law_id,
                    description=law.description,
                    formula_expression=law.formula_expression,
                    involved_parameters=law.involved_parameters,
                )
                for law in item.laws
            ]
            theory_def = TheoryElementDefinition(
                theory_id=item.theory_id,
                name=item.name,
                required_dimensions=item.required_dimensions,
                parameter_names=item.parameter_names,
                laws=laws,
                max_admissible_blur=item.max_admissible_blur,
                claimant_hypothesis_ids=item.claimant_hypothesis_ids,
            )
            definitions.append(theory_def)

        logger.info(
            "LLMTheoryInducer: Successfully induced %d Theory-Elements: %s",
            len(definitions),
            [d.theory_id for d in definitions],
        )
        return definitions

class LLMTheoryProjector(TheoryProjector):
    """LLM-backed projector estimating empirical dimensions and theoretical parameters.

    Prompts the LLM to project an empirical cluster through the specific formal lens
    of a Theory-Element, extracting observed dimension values and postulating
    candidate latent parameter values (M_p).

    Parameters
    ----------
    llm : Any
        Underlying LLM facade or StructuredLLM instance.
    prompts : StructuredPromptBundle | str | None, optional
        Custom prompt bundle or template string, by default None.
    strategy : Any, optional
        Decoding strategy for structured prediction, by default "direct_constrained".
    """

    def __init__(
        self,
        llm: Any,
        prompts: StructuredPromptBundle | str | None = None,
        strategy: Any = "direct_constrained",
    ) -> None:
        self.llm: StructuredLLM = ensure_structured_llm(llm)
        self.prompts = prompts or CLUSTER_PROJECTION_DIRECT_PROMPT
        self.strategy = strategy
        self._fallback = GenericTheoryProjector()

    async def aproject(
        self, cluster: EmpiricalCluster, theory: TheoryElementDefinition
    ) -> dict[str, Any]:
        """Asynchronously project empirical cluster into theoretical parameters via LLM.

        Parameters
        ----------
        cluster : EmpiricalCluster
            Target empirical cluster.
        theory : TheoryElementDefinition
            Theory-element definition specifying M_pp and M_p.

        Returns
        -------
        dict[str, Any]
            Dictionary of parameter name to postulated value.
        """
        # Fast path: check if cluster has exact structured measurements matching all parameters
        fast = self._try_measurement_fast_path(cluster, theory)
        if fast and len(fast) == len(theory.parameter_names):
            return fast

        obs_lines = []
        for o in cluster.observations:
            dims = [f"{m.dimension}={m.value} {m.unit}" for m in o.measurements]
            dim_str = f" [measurements: {', '.join(dims)}]" if dims else ""
            obs_lines.append(f"- [{o.id}] ({o.component_type}) {o.text}{dim_str}")
        obs_str = "\n".join(obs_lines) if obs_lines else "No observations."

        laws_str = "; ".join([f"{law.law_id}: {law.description}" for law in theory.laws]) or "None"

        try:
            raw: ClusterProjectionOutput = await self.llm.predict_structured(
                ClusterProjectionOutput,
                self.prompts,
                strategy=self.strategy,
                theory_name=theory.name,
                required_dimensions=", ".join(theory.required_dimensions) or "None specified",
                parameter_names=", ".join(theory.parameter_names) or "None specified",
                theory_laws=laws_str,
                cluster_observations=obs_str,
            )
            result = dict(raw.projected_parameters)
            for p in theory.parameter_names:
                if p not in result:
                    result[p] = 0.5
            return result
        except Exception as err:
            logger.warning("LLMTheoryProjector failed structured projection: %s. Using fallback.", err)
            return self._fallback.project(cluster, theory)

    def project(
        self, cluster: EmpiricalCluster, theory: TheoryElementDefinition
    ) -> dict[str, Any]:
        """Synchronous projection wrapper using fast-path or fallback."""
        fast = self._try_measurement_fast_path(cluster, theory)
        if fast:
            return fast
        return self._fallback.project(cluster, theory)

    def _try_measurement_fast_path(
        self, cluster: EmpiricalCluster, theory: TheoryElementDefinition
    ) -> dict[str, Any]:
        """Extract parameters if structured measurements directly match."""
        params: dict[str, Any] = {}
        for i, param in enumerate(theory.parameter_names):
            p_clean = param.lower().replace("_", "")
            tokens = [t for t in re.findall(r"[a-z]+", param.lower()) if len(t) > 3]
            vals: list[float] = []
            for obs in cluster.observations:
                for m in obs.measurements:
                    m_clean = m.dimension.lower().replace("_", "")
                    if m_clean in p_clean or p_clean in m_clean or any(t in m_clean for t in tokens):
                        if isinstance(m.value, (int, float)):
                            vals.append(float(m.value))
                    elif i < len(theory.required_dimensions):
                        req_dim = theory.required_dimensions[i].lower().replace("_", "")
                        if req_dim in m_clean or m_clean in req_dim:
                            if isinstance(m.value, (int, float)):
                                vals.append(float(m.value))
            if vals:
                params[param] = round(sum(vals) / len(vals), 3)
        return params

class SafeFormulaEvaluator:
    """Safe AST-based evaluator for induced mathematical constraint laws.

    Evaluates symbolic arithmetic and functional constraints without using Python's
    eval() function, preventing code injection and syntax crashes.
    """

    _ALLOWED_CALLS = {
        "abs": abs,
        "min": min,
        "max": max,
        "sqrt": lambda x: math.sqrt(max(0.0, float(x))),
    }

    @classmethod
    def evaluate(cls, expression: str, parameters: dict[str, Any]) -> float:
        """Evaluate a constraint expression and return deviation >= 0.0.

        Parameters
        ----------
        expression : str
            Symbolic formula (e.g. 'abs(dopamine - amygdala) * 0.5').
        parameters : dict[str, Any]
            Dictionary of parameter names to numeric values.

        Returns
        -------
        float
            Computed deviation (0.0 represents exact satisfaction).
        """
        if not expression or not expression.strip():
            return 0.0

        try:
            tree = ast.parse(expression.strip(), mode="eval")
            param_lower = {k.lower(): float(v) for k, v in parameters.items() if isinstance(v, (int, float))}
            val = cls._eval_node(tree.body, param_lower, parameters)
            return abs(float(val))
        except Exception as err:
            logger.warning("SafeFormulaEvaluator failed on '%s': %s", expression, err)
            return 1.0

    @classmethod
    def _eval_node(cls, node: ast.AST, param_lower: dict[str, float], raw_params: dict[str, Any]) -> float:
        if isinstance(node, ast.Constant):
            if isinstance(node.value, (int, float)):
                return float(node.value)
            raise ValueError(f"Unsupported constant type: {type(node.value)}")

        if isinstance(node, ast.Name):
            name = node.id
            if name in raw_params and isinstance(raw_params[name], (int, float)):
                return float(raw_params[name])
            if name.lower() in param_lower:
                return param_lower[name.lower()]
            return 0.0

        if isinstance(node, ast.UnaryOp):
            operand = cls._eval_node(node.operand, param_lower, raw_params)
            if isinstance(node.op, ast.UAdd):
                return +operand
            if isinstance(node.op, ast.USub):
                return -operand
            raise ValueError(f"Unsupported unary operator: {type(node.op)}")

        if isinstance(node, ast.BinOp):
            left = cls._eval_node(node.left, param_lower, raw_params)
            right = cls._eval_node(node.right, param_lower, raw_params)
            if isinstance(node.op, ast.Add):
                return left + right
            if isinstance(node.op, ast.Sub):
                return left - right
            if isinstance(node.op, ast.Mult):
                return left * right
            if isinstance(node.op, ast.Div):
                return left / right if right != 0.0 else 1.0
            if isinstance(node.op, ast.Pow):
                return left ** right
            raise ValueError(f"Unsupported binary operator: {type(node.op)}")

        if isinstance(node, ast.Call):
            func_name = getattr(node.func, "id", None)
            if func_name in cls._ALLOWED_CALLS:
                args = [cls._eval_node(arg, param_lower, raw_params) for arg in node.args]
                return float(cls._ALLOWED_CALLS[func_name](*args))
            raise ValueError(f"Unsupported function call: {func_name}")

        if isinstance(node, ast.Compare):
            left = cls._eval_node(node.left, param_lower, raw_params)
            if len(node.comparators) == 1 and len(node.ops) == 1:
                right = cls._eval_node(node.comparators[0], param_lower, raw_params)
                op = node.ops[0]
                if isinstance(op, ast.Eq):
                    return abs(left - right)
                if isinstance(op, (ast.Lt, ast.LtE)):
                    return max(0.0, left - right)
                if isinstance(op, (ast.Gt, ast.GtE)):
                    return max(0.0, right - left)
            raise ValueError("Unsupported comparison expression")

        raise ValueError(f"Unsupported AST node: {type(node)}")

class TheoryRegistry:
    """Registry holding active Theory-Element definitions.

    Parameters
    ----------
    seed_theories : list[TheoryElementDefinition] | None, optional
        Initial list of theory elements to populate the registry with.
    """

    def __init__(
        self, seed_theories: list[TheoryElementDefinition] | None = None
    ) -> None:
        self._theories: dict[str, TheoryElementDefinition] = {}
        if seed_theories:
            for theory in seed_theories:
                self.register(theory)

    def register(self, theory: TheoryElementDefinition) -> None:
        """Register a new Theory-Element definition.

        Parameters
        ----------
        theory : TheoryElementDefinition
            Theory-element specification to register.
        """
        self._theories[theory.theory_id] = theory

    def register_induced_theories(
        self, induced: list[InducedTheoryElement]
    ) -> list[TheoryElementDefinition]:
        """Convert and register dynamically induced Theory-Elements.

        Parameters
        ----------
        induced : list[InducedTheoryElement]
            List of induced theory elements from LLM induction.

        Returns
        -------
        list[TheoryElementDefinition]
            The instantiated and registered TheoryElementDefinition objects.
        """
        registered: list[TheoryElementDefinition] = []
        for item in induced:
            laws = [
                TheoryLaw(
                    law_id=law.law_id,
                    description=law.description,
                    formula_expression=law.formula_expression,
                    involved_parameters=law.involved_parameters,
                )
                for law in item.laws
            ]
            theory_def = TheoryElementDefinition(
                theory_id=item.theory_id,
                name=item.name,
                required_dimensions=item.required_dimensions,
                parameter_names=item.parameter_names,
                laws=laws,
                max_admissible_blur=item.max_admissible_blur,
                claimant_hypothesis_ids=item.claimant_hypothesis_ids,
            )
            self.register(theory_def)
            registered.append(theory_def)
        return registered

    def get(self, theory_id: str) -> TheoryElementDefinition | None:
        """Retrieve a registered Theory-Element by id.

        Parameters
        ----------
        theory_id : str
            Identifier of the theory.

        Returns
        -------
        TheoryElementDefinition | None
            The registered theory definition, or None if not found.
        """
        return self._theories.get(theory_id)

    def all_theories(self) -> list[TheoryElementDefinition]:
        """Return all registered theory definitions.

        Returns
        -------
        list[TheoryElementDefinition]
            List of registered theory definitions.
        """
        return list(self._theories.values())

    def match_claimants(self, cluster: EmpiricalCluster) -> list[str]:
        """Identify which registered theories claim an empirical cluster.

        A theory claims a cluster if:
        1. Any of the theory's required dimensions are present in the cluster measurements, OR
        2. Any observation unit text mentions the theory keywords or concepts, OR
        3. Any cluster node is registered as a claimant hypothesis ID for the theory.

        Parameters
        ----------
        cluster : EmpiricalCluster
            Target empirical cluster.

        Returns
        -------
        list[str]
            List of matching theory_id strings.
        """
        claimants: list[str] = []
        cluster_dims = cluster.available_dimensions
        cluster_texts = " ".join(obs.text.lower() for obs in cluster.observations)
        cluster_node_ids = {obs.id for obs in cluster.observations}

        for tid, theory in self._theories.items():
            req_set = {d.lower() for d in theory.required_dimensions}
            if req_set and not req_set.isdisjoint(cluster_dims):
                claimants.append(tid)
                continue
            if tid in cluster_texts or theory.name.lower() in cluster_texts:
                claimants.append(tid)
                continue
            if set(theory.claimant_hypothesis_ids).intersection(cluster_node_ids):
                claimants.append(tid)
                continue

        return claimants