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

crca_llm/types.py

@@ -0,0 +1,21 @@
+"""Typed outputs for crca_llm orchestrator."""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from pydantic import BaseModel, Field
+
+from crca_core.models.refusal import RefusalResult
+from crca_core.models.result import AnyResult
+from crca_llm.coauthor import DraftBundle
+
+
+class LLMRunResult(BaseModel):
+    """Container for LLM drafts + core results + refusals."""
+
+    draft_bundle: DraftBundle
+    core_results: List[AnyResult] = Field(default_factory=list)
+    refusals: List[RefusalResult] = Field(default_factory=list)
+    llm_metadata: Optional[dict] = None
+

crca_reasoning/__init__.py

@@ -0,0 +1,16 @@
+"""crca_reasoning: ReAct-style reasoning kernel with strict tool gating."""
+
+from crca_reasoning.godclass import ReActGodClass
+from crca_reasoning.react_controller import ReActController
+from crca_reasoning.types import LRMPlanResult, ReActAction
+from crca_reasoning.tool_router import ToolRouter
+from crca_reasoning.memory import StructuredMemory
+
+__all__ = [
+    "ReActGodClass",
+    "ReActController",
+    "LRMPlanResult",
+    "ReActAction",
+    "ToolRouter",
+    "StructuredMemory",
+]

crca_reasoning/critique.py

@@ -0,0 +1,54 @@
+"""End-of-cycle critique schema and rules."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+from crca_reasoning.types import ReActCycleTrace
+
+
+class CritiqueIssue(BaseModel):
+    code: str
+    message: str
+    severity: str = "warning"  # info|warning|error
+
+
+class CritiqueResult(BaseModel):
+    issues: List[CritiqueIssue] = Field(default_factory=list)
+    score: float = 0.0
+    threshold: float = 1.0
+    should_revise: bool = False
+    notes: Optional[str] = None
+
+
+def critique_cycle(trace: ReActCycleTrace) -> CritiqueResult:
+    issues: List[CritiqueIssue] = []
+    score = 0.0
+    threshold = 1.0
+    if trace.actions and not trace.observations:
+        issues.append(
+            CritiqueIssue(
+                code="NO_OBSERVATIONS",
+                message="Actions were proposed but no observations recorded.",
+                severity="error",
+            )
+        )
+        score += 1.0
+    if any(obs.refusal is not None for obs in trace.observations):
+        issues.append(
+            CritiqueIssue(
+                code="REFUSAL_OCCURRED",
+                message="At least one tool call resulted in refusal.",
+                severity="warning",
+            )
+        )
+        score += 0.5
+    should_revise = score >= threshold
+    return CritiqueResult(
+        issues=issues,
+        score=score,
+        threshold=threshold,
+        should_revise=should_revise,
+    )

crca_reasoning/godclass.py

@@ -0,0 +1,206 @@
+"""ReAct GodClass: controller + critique + memory + tool router in one."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, 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.refusal import RefusalChecklistItem, RefusalReasonCode, RefusalResult
+from crca_core.models.result import AnyResult, IdentificationResult
+from crca_reasoning.types import (
+    LRMPlanResult,
+    RationaleTrace,
+    ReActAction,
+    ReActCycleTrace,
+    ReActObservation,
+)
+
+
+ReasonerFn = Callable[["ReActGodClass"], tuple[str, List[ReActAction], str]]
+
+
+@dataclass
+class ReActGodClass:
+    """All-in-one ReAct controller with strict gating and critique."""
+
+    max_cycles: int = 3
+    memory_store: List[Dict[str, Any]] = field(default_factory=list)
+    staged_store: List[Dict[str, Any]] = field(default_factory=list)
+    last_identification: Optional[IdentificationResult] = None
+
+    # -----------------
+    # Memory operations
+    # -----------------
+    def read_memory(self) -> List[Dict[str, Any]]:
+        return list(self.memory_store)
+
+    def stage_write(self, item: Dict[str, Any]) -> None:
+        self.staged_store.append(item)
+
+    def finalize_memory(self) -> None:
+        self.memory_store.extend(self.staged_store)
+        self.staged_store = []
+
+    # -----------------
+    # Critique mechanics
+    # -----------------
+    def critique_cycle(self, trace: ReActCycleTrace) -> Dict[str, Any]:
+        issues: List[Dict[str, Any]] = []
+        score = 0.0
+        threshold = 1.0
+        if trace.actions and not trace.observations:
+            issues.append(
+                {
+                    "code": "NO_OBSERVATIONS",
+                    "message": "Actions were proposed but no observations recorded.",
+                    "severity": "error",
+                }
+            )
+            score += 1.0
+        if any(obs.refusal is not None for obs in trace.observations):
+            issues.append(
+                {
+                    "code": "REFUSAL_OCCURRED",
+                    "message": "At least one tool call resulted in refusal.",
+                    "severity": "warning",
+                }
+            )
+            score += 0.5
+        return {
+            "issues": issues,
+            "score": score,
+            "threshold": threshold,
+            "should_revise": score >= threshold,
+        }
+
+    # -----------------
+    # Tool routing
+    # -----------------
+    def call_tool(self, *, tool_name: str, payload: Dict[str, Any]) -> AnyResult | RefusalResult:
+        if tool_name in {"identify", "estimate", "counterfactual", "design_intervention"}:
+            if payload.get("locked_spec") is None:
+                return RefusalResult(
+                    message="LockedSpec required for this tool.",
+                    reason_codes=[RefusalReasonCode.SPEC_NOT_LOCKED],
+                    checklist=[
+                        RefusalChecklistItem(item="Provide LockedSpec", rationale="Tool is gated.")
+                    ],
+                    suggested_next_steps=["Lock a spec and retry."],
+                )
+
+        if tool_name == "identify":
+            res = identify_effect(
+                locked_spec=payload["locked_spec"],
+                treatment=payload.get("treatment", ""),
+                outcome=payload.get("outcome", ""),
+            )
+            if isinstance(res, IdentificationResult):
+                self.last_identification = res
+            return res
+
+        if tool_name == "estimate":
+            ident = payload.get("identification_result") or self.last_identification
+            return estimate_effect_dowhy(
+                data=payload.get("data"),
+                locked_spec=payload["locked_spec"],
+                treatment=payload.get("treatment", ""),
+                outcome=payload.get("outcome", ""),
+                identification_result=ident,
+                config=payload.get("config", EstimatorConfig()),
+            )
+
+        if tool_name == "counterfactual":
+            return simulate_counterfactual(
+                locked_spec=payload["locked_spec"],
+                factual_observation=payload.get("factual_observation", {}),
+                intervention=payload.get("intervention", {}),
+                allow_partial_observation=payload.get("allow_partial_observation", False),
+            )
+
+        if tool_name == "design_intervention":
+            return design_intervention(
+                locked_spec=payload["locked_spec"],
+                target_query=payload.get("target_query", TargetQuery()),
+                constraints=payload.get("constraints", FeasibilityConstraints()),
+            )
+
+        if tool_name == "discover_tabular":
+            return discover_tabular(
+                payload.get("data"),
+                payload.get("config", TabularDiscoveryConfig()),
+                payload.get("assumptions"),
+            )
+
+        if tool_name == "discover_timeseries":
+            return discover_timeseries_pcmci(
+                payload.get("data"),
+                payload.get("config", PCMCIConfig()),
+                payload.get("assumptions"),
+            )
+
+        return RefusalResult(
+            message=f"Unknown tool: {tool_name}",
+            reason_codes=[RefusalReasonCode.UNSUPPORTED_OPERATION],
+            checklist=[RefusalChecklistItem(item="Use a supported tool", rationale="Unknown tool name.")],
+        )
+
+    # -----------------
+    # ReAct execution
+    # -----------------
+    def run(self, reasoner: ReasonerFn) -> LRMPlanResult:
+        cycle_traces: List[ReActCycleTrace] = []
+        core_results: List[AnyResult] = []
+        refusals: List[RefusalResult] = []
+        rationale = RationaleTrace()
+
+        for _ in range(self.max_cycles):
+            reasoning, actions, rationale_step = reasoner(self)
+            cycle = ReActCycleTrace(reasoning=reasoning, actions=actions, observations=[])
+            if rationale_step:
+                rationale.steps.append(rationale_step)
+
+            for action in actions:
+                result = self.call_tool(tool_name=action.tool_name, payload=action.payload)
+                if isinstance(result, RefusalResult):
+                    obs = ReActObservation(tool_name=action.tool_name, refusal=result)
+                    refusals.append(result)
+                else:
+                    obs = ReActObservation(tool_name=action.tool_name, result=result)
+                    core_results.append(result)
+                cycle.observations.append(obs)
+
+            critique = self.critique_cycle(cycle)
+            cycle.critique = critique
+            cycle_traces.append(cycle)
+
+            if critique.get("should_revise"):
+                continue
+            break
+
+        for res in core_results:
+            try:
+                self.stage_write(res.model_dump())
+            except Exception:
+                continue
+        self.finalize_memory()
+
+        return LRMPlanResult(
+            cycle_traces=cycle_traces,
+            rationale_trace=rationale,
+            core_results=core_results,
+            refusals=refusals,
+            finalized=True,
+        )

crca_reasoning/memory.py

@@ -0,0 +1,24 @@
+"""Structured memory store for reasoning artifacts."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+
+class StructuredMemory:
+    """Write-on-finalize memory store."""
+
+    def __init__(self) -> None:
+        self._store: List[Dict[str, Any]] = []
+        self._staged: List[Dict[str, Any]] = []
+
+    def read_all(self) -> List[Dict[str, Any]]:
+        return list(self._store)
+
+    def stage_write(self, item: Dict[str, Any]) -> None:
+        self._staged.append(item)
+
+    def finalize(self) -> None:
+        self._store.extend(self._staged)
+        self._staged = []
+

crca_reasoning/rationale.py

@@ -0,0 +1,10 @@
+"""Rationale trace output (non-scientific)."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class RationaleTrace(BaseModel):
+    steps: list[str] = Field(default_factory=list)
+

crca_reasoning/react_controller.py

@@ -0,0 +1,81 @@
+"""Multi-cycle ReAct controller with strict tool gating and end-of-cycle critique."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, List, Optional
+
+from crca_core.models.refusal import RefusalResult
+from crca_core.models.result import AnyResult
+from crca_reasoning.critique import critique_cycle
+from crca_reasoning.memory import StructuredMemory
+from crca_reasoning.types import (
+    LRMPlanResult,
+    RationaleTrace,
+    ReActAction,
+    ReActCycleTrace,
+    ReActObservation,
+)
+from crca_reasoning.tool_router import ToolRouter
+
+
+ReasonerFn = Callable[[StructuredMemory], tuple[str, List[ReActAction], str]]
+
+
+@dataclass
+class ReActController:
+    max_cycles: int = 3
+    tool_router: ToolRouter = field(default_factory=ToolRouter)
+    memory: StructuredMemory = field(default_factory=StructuredMemory)
+
+    def run(self, reasoner: ReasonerFn) -> LRMPlanResult:
+        cycle_traces: List[ReActCycleTrace] = []
+        core_results: List[AnyResult] = []
+        refusals: List[RefusalResult] = []
+        rationale = RationaleTrace()
+
+        for _ in range(self.max_cycles):
+            reasoning, actions, rationale_step = reasoner(self.memory)
+            cycle = ReActCycleTrace(reasoning=reasoning, actions=actions, observations=[])
+            if rationale_step:
+                rationale.steps.append(rationale_step)
+
+            for action in actions:
+                result = self.tool_router.call_tool(
+                    tool_name=action.tool_name, payload=action.payload
+                )
+                if isinstance(result, RefusalResult):
+                    obs = ReActObservation(
+                        tool_name=action.tool_name, refusal=result
+                    )
+                    refusals.append(result)
+                else:
+                    obs = ReActObservation(
+                        tool_name=action.tool_name, result=result
+                    )
+                    core_results.append(result)
+                cycle.observations.append(obs)
+
+            critique = critique_cycle(cycle)
+            cycle.critique = critique.model_dump()
+            cycle_traces.append(cycle)
+
+            if critique.should_revise:
+                continue
+            break
+
+        # Write-on-finalize memory policy
+        for res in core_results:
+            try:
+                self.memory.stage_write(res.model_dump())
+            except Exception:
+                continue
+        self.memory.finalize()
+
+        return LRMPlanResult(
+            cycle_traces=cycle_traces,
+            rationale_trace=rationale,
+            core_results=core_results,
+            refusals=refusals,
+            finalized=True,
+        )

crca_reasoning/tool_router.py

@@ -0,0 +1,97 @@
+"""Unified tool router with strict gating."""
+
+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.refusal import RefusalChecklistItem, RefusalReasonCode, RefusalResult
+from crca_core.models.result import AnyResult, IdentificationResult
+from crca_core.models.spec import LockedSpec
+
+
+class ToolRouter:
+    """Routes tool calls with pre-Act gating."""
+
+    def __init__(self) -> None:
+        self.last_identification: Optional[IdentificationResult] = None
+
+    def call_tool(self, *, tool_name: str, payload: Dict[str, Any]) -> AnyResult | RefusalResult:
+        if tool_name in {"identify", "estimate", "counterfactual", "design_intervention"}:
+            if payload.get("locked_spec") is None:
+                return RefusalResult(
+                    message="LockedSpec required for this tool.",
+                    reason_codes=[RefusalReasonCode.SPEC_NOT_LOCKED],
+                    checklist=[
+                        RefusalChecklistItem(item="Provide LockedSpec", rationale="Tool is gated.")
+                    ],
+                    suggested_next_steps=["Lock a spec and retry."],
+                )
+
+        if tool_name == "identify":
+            res = identify_effect(
+                locked_spec=payload["locked_spec"],
+                treatment=payload.get("treatment", ""),
+                outcome=payload.get("outcome", ""),
+            )
+            if isinstance(res, IdentificationResult):
+                self.last_identification = res
+            return res
+
+        if tool_name == "estimate":
+            ident = payload.get("identification_result") or self.last_identification
+            return estimate_effect_dowhy(
+                data=payload.get("data"),
+                locked_spec=payload["locked_spec"],
+                treatment=payload.get("treatment", ""),
+                outcome=payload.get("outcome", ""),
+                identification_result=ident,
+                config=payload.get("config", EstimatorConfig()),
+            )
+
+        if tool_name == "counterfactual":
+            return simulate_counterfactual(
+                locked_spec=payload["locked_spec"],
+                factual_observation=payload.get("factual_observation", {}),
+                intervention=payload.get("intervention", {}),
+                allow_partial_observation=payload.get("allow_partial_observation", False),
+            )
+
+        if tool_name == "design_intervention":
+            return design_intervention(
+                locked_spec=payload["locked_spec"],
+                target_query=payload.get("target_query", TargetQuery()),
+                constraints=payload.get("constraints", FeasibilityConstraints()),
+            )
+
+        if tool_name == "discover_tabular":
+            return discover_tabular(
+                payload.get("data"),
+                payload.get("config", TabularDiscoveryConfig()),
+                payload.get("assumptions"),
+            )
+
+        if tool_name == "discover_timeseries":
+            return discover_timeseries_pcmci(
+                payload.get("data"),
+                payload.get("config", PCMCIConfig()),
+                payload.get("assumptions"),
+            )
+
+        return RefusalResult(
+            message=f"Unknown tool: {tool_name}",
+            reason_codes=[RefusalReasonCode.UNSUPPORTED_OPERATION],
+            checklist=[RefusalChecklistItem(item="Use a supported tool", rationale="Unknown tool name.")],
+        )

crca_reasoning/types.py

@@ -0,0 +1,40 @@
+"""Types for ReAct reasoning and outputs."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+from crca_core.models.refusal import RefusalResult
+from crca_core.models.result import AnyResult
+
+
+class ReActAction(BaseModel):
+    tool_name: str
+    payload: Dict[str, Any] = Field(default_factory=dict)
+
+
+class ReActObservation(BaseModel):
+    tool_name: str
+    result: Optional[AnyResult] = None
+    refusal: Optional[RefusalResult] = None
+
+
+class ReActCycleTrace(BaseModel):
+    reasoning: str
+    actions: List[ReActAction] = Field(default_factory=list)
+    observations: List[ReActObservation] = Field(default_factory=list)
+    critique: Optional[Dict[str, Any]] = None
+
+
+class RationaleTrace(BaseModel):
+    steps: List[str] = Field(default_factory=list)
+
+
+class LRMPlanResult(BaseModel):
+    cycle_traces: List[ReActCycleTrace] = Field(default_factory=list)
+    rationale_trace: Optional[RationaleTrace] = None
+    core_results: List[AnyResult] = Field(default_factory=list)
+    refusals: List[RefusalResult] = Field(default_factory=list)
+    finalized: bool = False

crca_sd/__init__.py

@@ -0,0 +1,15 @@
+"""Compatibility shim for tests/examples.
+
+The actual CRCA-SD implementation lives under `branches/crca_sd/` in this repo.
+This package re-exports those modules under the import path `crca_sd.*`.
+"""
+
+from crca_sd.crca_sd_core import *  # noqa: F401,F403
+from crca_sd.crca_sd_mpc import *  # noqa: F401,F403
+from crca_sd.crca_sd_governance import *  # noqa: F401,F403
+from crca_sd.crca_sd_realtime import *  # noqa: F401,F403
+# NOTE: Do NOT import `crca_sd_tui` at package import time.
+# It depends on Unix-only modules (e.g., `termios`) and breaks test collection on Windows.
+
+__all__ = []  # populated by wildcard imports above
+

crca_sd/crca_sd_core.py

@@ -0,0 +1,2 @@
+from branches.crca_sd.crca_sd_core import *  # noqa: F401,F403
+

crca_sd/crca_sd_governance.py

@@ -0,0 +1,2 @@
+from branches.crca_sd.crca_sd_governance import *  # noqa: F401,F403
+

crca_sd/crca_sd_mpc.py

@@ -0,0 +1,2 @@
+from branches.crca_sd.crca_sd_mpc import *  # noqa: F401,F403
+

crca_sd/crca_sd_realtime.py

@@ -0,0 +1,2 @@
+from branches.crca_sd.crca_sd_realtime import *  # noqa: F401,F403
+

crca_sd/crca_sd_tui.py

@@ -0,0 +1,2 @@
+from branches.crca_sd.crca_sd_tui import *  # noqa: F401,F403
+