crca 1.4.0__py3-none-any.whl → 1.5.0__py3-none-any.whl

crca_core/core/api.py

@@ -0,0 +1,120 @@
+"""Public API functions for the H1 `crca_core`.
+
+These functions provide the stable, refusal-first entry points that other
+layers (including LLM tooling) should call.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from crca_core.core.estimate import EstimatorConfig, estimate_effect_dowhy
+from crca_core.identify import identify_effect
+from crca_core.core.intervention_design import (
+    FeasibilityConstraints,
+    TargetQuery,
+    design_intervention,
+)
+from crca_core.models.provenance import ProvenanceManifest
+from crca_core.models.refusal import RefusalChecklistItem, RefusalReasonCode, RefusalResult
+from crca_core.models.result import CounterfactualResult
+from crca_core.scm import LinearGaussianSCM
+from crca_core.models.spec import DraftSpec, LockedSpec
+from crca_core.timeseries.pcmci import PCMCIConfig, discover_timeseries_pcmci
+from crca_core.discovery.tabular import TabularDiscoveryConfig, discover_tabular
+from utils.canonical import stable_hash
+
+
+def simulate_counterfactual(
+    *,
+    locked_spec: LockedSpec,
+    factual_observation: Dict[str, float],
+    intervention: Dict[str, float],
+    allow_partial_observation: bool = False,
+) -> CounterfactualResult | RefusalResult:
+    """Simulate a counterfactual under an explicit SCM (required).
+
+    Refuses if `locked_spec.scm` is missing.
+    """
+
+    if locked_spec.scm is None:
+        return RefusalResult(
+            message="Counterfactuals require an explicit SCMSpec (structural equations + noise model).",
+            reason_codes=[RefusalReasonCode.NO_SCM_FOR_COUNTERFACTUAL],
+            checklist=[
+                RefusalChecklistItem(
+                    item="Provide SCMSpec",
+                    rationale="A DAG alone does not define counterfactual semantics; SCM is required.",
+                )
+            ],
+            suggested_next_steps=[
+                "Attach a SCMSpec (e.g., linear_gaussian) to the spec, then re-lock and retry."
+            ],
+        )
+
+    scm = LinearGaussianSCM.from_spec(locked_spec.scm)
+    try:
+        u = scm.abduce_noise(factual_observation, allow_partial=allow_partial_observation)
+    except ValueError as exc:
+        return RefusalResult(
+            message=str(exc),
+            reason_codes=[RefusalReasonCode.INPUT_INVALID],
+            checklist=[
+                RefusalChecklistItem(
+                    item="Provide complete factual observation",
+                    rationale="Counterfactuals require abduction for all endogenous variables in v1.0 unless partial mode is enabled.",
+                )
+            ],
+            suggested_next_steps=[
+                "Provide all endogenous variables or set allow_partial_observation=True (partial mode)."
+            ],
+        )
+    cf = scm.predict(u, interventions=intervention)
+
+    prov = ProvenanceManifest.minimal(
+        spec_hash=stable_hash(
+            {
+                "spec_hash": locked_spec.spec_hash,
+                "module": "simulate_counterfactual",
+                "intervention": intervention,
+                "factual_keys": sorted(list(factual_observation.keys())),
+            }
+        )
+    )
+
+    return CounterfactualResult(
+        provenance=prov,
+        assumptions=[
+            "SCM structure and parameters are correct (strong assumption).",
+            "Factual observation includes all endogenous variables for abduction in v1.0 unless partial mode is enabled.",
+        ],
+        limitations=[
+            "v0.1 counterfactuals require a fully observed system (no missing variables).",
+            "Only linear-Gaussian SCMs are supported in v0.1.",
+        ],
+        counterfactual={"factual": dict(factual_observation), "do": dict(intervention), "result": cf},
+    )
+
+
+__all__ = [
+    # Core lifecycle
+    "DraftSpec",
+    "LockedSpec",
+    # Identification
+    "identify_effect",
+    # Discovery
+    "TabularDiscoveryConfig",
+    "discover_tabular",
+    "PCMCIConfig",
+    "discover_timeseries_pcmci",
+    # Design
+    "TargetQuery",
+    "FeasibilityConstraints",
+    "design_intervention",
+    # Counterfactuals
+    "simulate_counterfactual",
+    # Estimation
+    "EstimatorConfig",
+    "estimate_effect_dowhy",
+]
+

crca_core/core/estimate.py

@@ -0,0 +1,208 @@
+"""Identification → estimation → refutation wrapper (DoWhy).
+
+This is supporting infrastructure for causal R&D. It is gated behind:
+- LockedSpec
+- explicit treatment/outcome
+- DoWhy identification success
+
+Refuters do not prove causality; they are diagnostics and must be surfaced.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+from crca_core.models.provenance import ProvenanceManifest
+from crca_core.models.refusal import RefusalChecklistItem, RefusalReasonCode, RefusalResult
+from crca_core.models.result import EstimateResult, IdentificationResult
+from crca_core.models.spec import LockedSpec
+from utils.canonical import stable_hash
+
+
+class EstimatorConfig(BaseModel):
+    method_name: str = Field(default="backdoor.linear_regression")
+    test_significance: bool = True
+    confidence_intervals: bool = True
+    refuters: List[str] = Field(
+        default_factory=lambda: ["placebo_treatment_refuter", "random_common_cause", "subset_refuter"]
+    )
+
+
+def _ensure_networkx_compat() -> None:
+    """Patch NetworkX API differences required by DoWhy.
+
+    DoWhy versions in the wild have referenced `networkx.algorithms.d_separated`,
+    while NetworkX >=3.6 provides `networkx.algorithms.d_separation.is_d_separator`.
+    """
+    try:
+        import networkx as nx  # type: ignore
+        import networkx.algorithms.d_separation as ds  # type: ignore
+
+        if not hasattr(nx.algorithms, "d_separated") and hasattr(ds, "is_d_separator"):
+            setattr(nx.algorithms, "d_separated", ds.is_d_separator)
+    except Exception:
+        # If networkx isn't available, DoWhy will fail later anyway.
+        return
+
+
+def _graph_to_dot(spec: LockedSpec) -> str:
+    # Minimal DOT string compatible with DoWhy's graph parser.
+    edges = spec.graph.edges
+    lines = ["digraph {"]
+    for n in spec.graph.nodes:
+        lines.append(f'  "{n.name}";')
+    for e in edges:
+        lines.append(f'  "{e.source}" -> "{e.target}";')
+    lines.append("}")
+    return "\n".join(lines)
+
+
+def estimate_effect_dowhy(
+    *,
+    data: Any,
+    locked_spec: LockedSpec,
+    treatment: str,
+    outcome: str,
+    identification_result: IdentificationResult | None = None,
+    config: Optional[EstimatorConfig] = None,
+) -> EstimateResult | RefusalResult:
+    """Run DoWhy identify→estimate→refute and return a structured result."""
+
+    cfg = config or EstimatorConfig()
+
+    # Basic gating
+    if not treatment or not outcome:
+        return RefusalResult(
+            message="Treatment and outcome must be provided.",
+            reason_codes=[RefusalReasonCode.INPUT_INVALID],
+            checklist=[
+                RefusalChecklistItem(item="Provide treatment", rationale="Required to define the estimand."),
+                RefusalChecklistItem(item="Provide outcome", rationale="Required to define the estimand."),
+            ],
+            suggested_next_steps=["Pass treatment='X', outcome='Y'."],
+        )
+
+    if identification_result is None:
+        return RefusalResult(
+            message="Estimation requires an IdentificationResult.",
+            reason_codes=[RefusalReasonCode.INPUT_INVALID],
+            checklist=[
+                RefusalChecklistItem(
+                    item="Run identify_effect() first",
+                    rationale="Estimation is gated behind validated identifiability.",
+                )
+            ],
+            suggested_next_steps=["Call identify_effect() and pass its result here."],
+        )
+
+    if identification_result.method == "not_identifiable":
+        return RefusalResult(
+            message="Cannot estimate: identification failed.",
+            reason_codes=[RefusalReasonCode.NOT_IDENTIFIABLE],
+            checklist=[
+                RefusalChecklistItem(
+                    item="Revise causal model or collect additional data/interventions",
+                    rationale="Identification result indicates non-identifiability.",
+                )
+            ],
+            suggested_next_steps=["Use design_intervention() to propose identifying experiments."],
+        )
+
+    dot = _graph_to_dot(locked_spec)
+    prov = ProvenanceManifest.minimal(
+        spec_hash=stable_hash(
+            {
+                "spec_hash": locked_spec.spec_hash,
+                "treatment": treatment,
+                "outcome": outcome,
+                "method": cfg.model_dump(),
+                "graph": dot,
+                "module": "dowhy_pipeline",
+            }
+        ),
+        algorithm_config=cfg.model_dump(),
+    )
+
+    try:
+        import pandas as pd  # type: ignore
+
+        if not isinstance(data, pd.DataFrame):
+            return RefusalResult(
+                message="DoWhy estimation requires a pandas DataFrame.",
+                reason_codes=[RefusalReasonCode.INPUT_INVALID],
+                checklist=[RefusalChecklistItem(item="Provide pandas DataFrame", rationale="DoWhy expects tabular data.")],
+                suggested_next_steps=["Convert your data to pandas.DataFrame and retry."],
+            )
+    except Exception as e:  # pragma: no cover
+        return RefusalResult(
+            message=f"pandas is required for estimation: {e}",
+            reason_codes=[RefusalReasonCode.UNSUPPORTED_OPERATION],
+            checklist=[RefusalChecklistItem(item="Install pandas", rationale="Required dependency for tabular estimation.")],
+            suggested_next_steps=["pip install pandas"],
+        )
+
+    try:
+        _ensure_networkx_compat()
+        from dowhy import CausalModel  # type: ignore
+    except Exception as e:
+        return RefusalResult(
+            message=f"DoWhy not available: {e}",
+            reason_codes=[RefusalReasonCode.UNSUPPORTED_OPERATION],
+            checklist=[RefusalChecklistItem(item="Install dowhy", rationale="Required for this estimation pipeline.")],
+            suggested_next_steps=["pip install dowhy"],
+        )
+
+    model = CausalModel(data=data, treatment=treatment, outcome=outcome, graph=dot)
+    identified_estimand = model.identify_effect()
+
+    # If identification fails, DoWhy usually still returns an object; we gate on its string.
+    if identified_estimand is None:
+        return RefusalResult(
+            message="Causal effect not identifiable under the provided graph/assumptions.",
+            reason_codes=[RefusalReasonCode.NOT_IDENTIFIABLE],
+            checklist=[
+                RefusalChecklistItem(
+                    item="Revise the causal model or collect additional data/interventions",
+                    rationale="Effect identification failed.",
+                )
+            ],
+            suggested_next_steps=["Use design_intervention() to propose identifying experiments."],
+        )
+
+    estimate = model.estimate_effect(
+        identified_estimand,
+        method_name=cfg.method_name,
+        test_significance=cfg.test_significance,
+        confidence_intervals=cfg.confidence_intervals,
+    )
+
+    refutations: Dict[str, Any] = {}
+    for refuter in cfg.refuters:
+        try:
+            ref = model.refute_estimate(identified_estimand, estimate, method_name=refuter)
+            refutations[refuter] = str(ref)
+        except Exception as e:
+            refutations[refuter] = {"error": str(e)}
+
+    return EstimateResult(
+        provenance=prov,
+        assumptions=[
+            "Causal graph is correctly specified (strong assumption).",
+            "Estimator assumptions depend on the chosen method (see DoWhy).",
+        ],
+        limitations=[
+            "Refutation tests are diagnostics; passing does not prove causality.",
+            "Estimation quality depends on overlap/positivity and measurement quality.",
+        ],
+        estimate={
+            "value": float(getattr(estimate, "value", float("nan"))),
+            "method_name": cfg.method_name,
+            "estimand": str(identified_estimand),
+            "raw_estimate": str(estimate),
+        },
+        refutations=refutations,
+        artifacts={"identification_result": identification_result.model_dump()},
+    )
+

crca_core/core/godclass.py

@@ -0,0 +1,72 @@
+"""CausalCore GodClass: consolidated core API facade."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from crca_core.core.api import (
+    EstimatorConfig,
+    FeasibilityConstraints,
+    PCMCIConfig,
+    TabularDiscoveryConfig,
+    TargetQuery,
+    design_intervention,
+    discover_tabular,
+    discover_timeseries_pcmci,
+    identify_effect,
+    estimate_effect_dowhy,
+    simulate_counterfactual,
+)
+from crca_core.models.result import AnyResult, IdentificationResult
+from crca_core.models.spec import LockedSpec
+
+
+class CausalCoreGod:
+    """Single class exposing all core causal operations."""
+
+    def __init__(self) -> None:
+        self.last_identification: Optional[IdentificationResult] = None
+
+    def identify(self, *, locked_spec: LockedSpec, treatment: str, outcome: str) -> AnyResult:
+        res = identify_effect(locked_spec=locked_spec, treatment=treatment, outcome=outcome)
+        if isinstance(res, IdentificationResult):
+            self.last_identification = res
+        return res
+
+    def estimate(self, *, data: Any, locked_spec: LockedSpec, treatment: str, outcome: str) -> AnyResult:
+        return estimate_effect_dowhy(
+            data=data,
+            locked_spec=locked_spec,
+            treatment=treatment,
+            outcome=outcome,
+            identification_result=self.last_identification,
+            config=EstimatorConfig(),
+        )
+
+    def counterfactual(
+        self,
+        *,
+        locked_spec: LockedSpec,
+        factual_observation: Dict[str, float],
+        intervention: Dict[str, float],
+        allow_partial_observation: bool = False,
+    ) -> AnyResult:
+        return simulate_counterfactual(
+            locked_spec=locked_spec,
+            factual_observation=factual_observation,
+            intervention=intervention,
+            allow_partial_observation=allow_partial_observation,
+        )
+
+    def design_intervention(self, *, locked_spec: LockedSpec, target_query: TargetQuery) -> AnyResult:
+        return design_intervention(
+            locked_spec=locked_spec,
+            target_query=target_query,
+            constraints=FeasibilityConstraints(),
+        )
+
+    def discover_tabular(self, *, data: Any) -> AnyResult:
+        return discover_tabular(data, TabularDiscoveryConfig())
+
+    def discover_timeseries(self, *, data: Any) -> AnyResult:
+        return discover_timeseries_pcmci(data, PCMCIConfig())

crca_core/core/intervention_design.py

@@ -0,0 +1,174 @@
+"""Intervention/experiment design (v0.1: graphical, non-probabilistic).
+
+This module is intentionally conservative:
+- It does not invent numeric information gain.
+- It produces structured candidate designs with explicit prerequisites and rationale.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+from crca_core.models.provenance import ProvenanceManifest
+from crca_core.models.result import InterventionDesignResult
+from utils.canonical import stable_hash
+
+
+class TargetQuery(BaseModel):
+    query_type: Literal["identify_effect", "reduce_uncertainty_edge"] = "identify_effect"
+    treatment: Optional[str] = None
+    outcome: Optional[str] = None
+    edge_source: Optional[str] = None
+    edge_target: Optional[str] = None
+
+
+class FeasibilityConstraints(BaseModel):
+    manipulable_variables: List[str] = Field(default_factory=list)
+    observable_variables: List[str] = Field(default_factory=list)
+    costs: Dict[str, Any] = Field(default_factory=dict)
+    ethics_notes: Optional[str] = None
+
+
+class DesignCandidate(BaseModel):
+    design_type: str
+    mechanism: str
+    prerequisites: List[str] = Field(default_factory=list)
+    feasibility_inputs_needed: List[str] = Field(default_factory=list)
+    notes: Optional[str] = None
+
+
+def _parents_of(graph_edges, node: str) -> List[str]:
+    res: List[str] = []
+    for e in graph_edges:
+        if e.target == node:
+            res.append(e.source)
+    return res
+
+
+def design_intervention(
+    *,
+    locked_spec: Any,
+    target_query: TargetQuery,
+    constraints: Optional[FeasibilityConstraints] = None,
+) -> InterventionDesignResult:
+    """Propose interventions/measurements to support identifiability or hypothesis discrimination.
+
+    v0.1 is graphical and deliberately non-numeric. It does not claim identifiability;
+    it produces designs and checklists that *could* help under explicit assumptions.
+    """
+
+    constraints = constraints or FeasibilityConstraints()
+
+    # Provenance: we hash only the spec hash + query + constraints (no raw data).
+    spec_hash = getattr(locked_spec, "spec_hash", "unknown")
+    prov = ProvenanceManifest.minimal(
+        spec_hash=stable_hash(
+            {
+                "spec_hash": spec_hash,
+                "target_query": target_query.model_dump(),
+                "constraints": constraints.model_dump(),
+                "module": "intervention_design_v0.1",
+            }
+        )
+    )
+
+    designs: List[Dict[str, Any]] = []
+
+    if target_query.query_type == "identify_effect":
+        X = target_query.treatment
+        Y = target_query.outcome
+        if not X or not Y:
+            return InterventionDesignResult(
+                provenance=prov,
+                assumptions=[],
+                limitations=["Missing treatment/outcome in target_query."],
+                designs=[],
+            )
+
+        # 1) Randomize treatment if feasible
+        if X in constraints.manipulable_variables:
+            designs.append(
+                DesignCandidate(
+                    design_type="randomize_treatment",
+                    mechanism=f"Randomize {X} to break backdoor confounding when estimating effect on {Y}.",
+                    prerequisites=[
+                        "Well-defined intervention on treatment (consistency/SUTVA).",
+                        "No interference between units (SUTVA).",
+                        "Feasible randomization protocol and compliance monitoring.",
+                    ],
+                    feasibility_inputs_needed=["sample_size", "randomization_unit", "ethical_constraints"],
+                ).model_dump()
+            )
+
+        # 2) Measure candidate confounders (parents of treatment in the current draft DAG)
+        parents_x = _parents_of(locked_spec.graph.edges, X)
+        if parents_x:
+            designs.append(
+                DesignCandidate(
+                    design_type="measure_confounder_candidates",
+                    mechanism=(
+                        f"Measure candidate confounders {parents_x} because they are modeled as direct causes of {X}; "
+                        f"conditioning/adjusting may help estimate effect of {X} on {Y} under exchangeability."
+                    ),
+                    prerequisites=[
+                        "Candidate confounders are measured without severe error or are modeled as proxies.",
+                        "Exchangeability holds conditional on measured covariates (assumption).",
+                        "Positivity/overlap holds in the collected data.",
+                    ],
+                    feasibility_inputs_needed=["measurement_instrument_quality", "data_collection_costs"],
+                    notes="This does not guarantee identifiability; it is a measurement suggestion grounded in the current graph hypothesis.",
+                ).model_dump()
+            )
+
+        # 3) Instrument design if user provided candidate instruments
+        if getattr(locked_spec.roles, "instruments", []):
+            Zs = list(getattr(locked_spec.roles, "instruments", []))
+            designs.append(
+                DesignCandidate(
+                    design_type="instrument_design",
+                    mechanism=f"Collect/create instrument(s) {Zs} to identify effect of {X} on {Y} under IV assumptions.",
+                    prerequisites=[
+                        "Relevance: Z affects X.",
+                        "Exclusion: Z affects Y only through X.",
+                        "Independence: Z is independent of unmeasured causes of Y.",
+                    ],
+                    feasibility_inputs_needed=["instrument_source", "exclusion_justification"],
+                ).model_dump()
+            )
+
+    elif target_query.query_type == "reduce_uncertainty_edge":
+        s = target_query.edge_source
+        t = target_query.edge_target
+        if not s or not t:
+            return InterventionDesignResult(
+                provenance=prov,
+                assumptions=[],
+                limitations=["Missing edge_source/edge_target in target_query."],
+                designs=[],
+            )
+
+        if s in constraints.manipulable_variables:
+            designs.append(
+                DesignCandidate(
+                    design_type="perturb_source",
+                    mechanism=f"Intervene on {s} (do({s}=...)) and observe downstream changes in {t} to test the edge hypothesis {s}→{t}.",
+                    prerequisites=[
+                        "Well-defined intervention on source variable.",
+                        "No simultaneous changes to other upstream causes (or they are measured/controlled).",
+                    ],
+                    feasibility_inputs_needed=["intervention_range", "measurement_frequency", "time_horizon"],
+                ).model_dump()
+            )
+
+    return InterventionDesignResult(
+        provenance=prov,
+        assumptions=[],
+        limitations=[
+            "v0.1 design is graphical and non-probabilistic; it does not compute numeric information gain.",
+            "Suggestions depend on the correctness of the locked causal graph/spec assumptions.",
+        ],
+        designs=designs,
+    )
+

crca_core/core/lifecycle.py

@@ -0,0 +1,48 @@
+"""Spec lifecycle: DraftSpec → LockedSpec.
+
+The LockedSpec is a scientific boundary: only LockedSpec may be used for numeric
+causal outputs. This module enforces that boundary.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import List
+
+from crca_core.models.spec import DraftSpec, LockedSpec
+from utils.canonical import stable_hash
+
+
+def lock_spec(draft: DraftSpec, approvals: List[str]) -> LockedSpec:
+    """Lock a draft spec by hashing its canonical content and recording approvals.
+
+    Args:
+        draft: The draft specification (possibly LLM-generated).
+        approvals: Human (or explicit programmatic) approvals. Must be non-empty.
+
+    Returns:
+        LockedSpec
+
+    Raises:
+        ValueError: If approvals are empty.
+    """
+
+    if not approvals:
+        raise ValueError("approvals must be non-empty to lock a spec")
+
+    # Canonicalize via stable_hash over model_dump
+    draft_payload = draft.model_dump()
+    spec_hash = stable_hash(draft_payload)
+    locked_at = datetime.now(timezone.utc).isoformat()
+
+    return LockedSpec(
+        spec_hash=spec_hash,
+        approvals=list(approvals),
+        locked_at_utc=locked_at,
+        data=draft.data,
+        graph=draft.graph,
+        roles=draft.roles,
+        assumptions=draft.assumptions,
+        scm=draft.scm,
+    )
+

crca_core/discovery/__init__.py

@@ -0,0 +1,9 @@
+"""Causal discovery (hypothesis generation) modules.
+
+Discovery outputs are hypotheses under explicit assumptions; they are not truth.
+"""
+
+from crca_core.discovery.tabular import TabularDiscoveryConfig, discover_tabular
+
+__all__ = ["TabularDiscoveryConfig", "discover_tabular"]
+