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

docs/lrm/math_appendix.md

@@ -0,0 +1,120 @@
+---
+title: LRM Math Appendix
+---
+
+# LRM Math Appendix (Pearl + ML/CS)
+
+## 1. Structural Causal Models (SCM)
+Let \(V=\{V_1,\dots,V_n\}\) be endogenous variables and \(U=\{U_1,\dots,U_n\}\) exogenous noise.
+An SCM is defined by structural equations:
+\[
+V_i \leftarrow f_i(\mathrm{Pa}(V_i), U_i).
+\]
+If the SCM is **Markovian**, then the joint distribution factorizes:
+\[
+P(V) = \prod_i P(V_i \mid \mathrm{Pa}(V_i)).
+\]
+
+## 2. Interventions and do-calculus
+The intervention \(do(X=x)\) replaces the structural equation for \(X\) with a constant \(x\).
+The interventional distribution is \(P(Y \mid do(X=x))\).
+The do-calculus rules (Pearl, 2009) allow transformation between interventional and observational expressions
+under graphical conditions (d-separation in manipulated graphs).
+
+## 3. Counterfactuals (Abduction–Action–Prediction)
+Given evidence \(E=e\), the counterfactual \(Y_x\) is computed by:
+1. **Abduction**: infer \(U\) from \(E=e\).
+2. **Action**: replace equations with intervention \(do(X=x)\).
+3. **Prediction**: forward-simulate \(Y\) using inferred \(U\).
+
+## 4. Identification (Pearl + Shpitser–Pearl)
+
+### 4.1 Backdoor criterion
+**Definition**: A set \(Z\) satisfies backdoor w.r.t. \((X,Y)\) if it blocks all backdoor paths from \(X\) to \(Y\) in \(G_{\bar{X}}\).
+
+**Estimand**:
+\[
+P(Y\mid do(X)) = \sum_Z P(Y\mid X,Z)P(Z).
+\]
+
+**Proof sketch**: Apply do-calculus Rule 2 on \(G_{\bar{X}}\) where \(Z\) d-separates \(X\) and \(Y\).
+
+### 4.2 Frontdoor criterion
+**Definition**: \(M\) is a frontdoor mediator if:
+1. All directed paths \(X\to Y\) go through \(M\);
+2. No backdoor path from \(X\) to \(M\);
+3. All backdoor paths from \(M\) to \(Y\) are blocked by \(X\).
+
+**Estimand**:
+\[
+P(Y\mid do(X)) = \sum_M P(M\mid X)\sum_{X'} P(Y\mid M,X')P(X').
+\]
+
+**Proof sketch**: Use Rule 3 to exchange intervention with observation for the \(M\to Y\) part and Rule 2 for the \(X\to M\) part.
+
+### 4.3 Instrumental Variables (Linear)
+Assume linear SCM:
+\[
+X = \pi Z + U_X,\quad Y = \beta X + U_Y,
+\]
+with exclusion \(Z \not\to Y\) except through \(X\), independence \(Z \perp U_Y\), and relevance \(\pi \neq 0\).
+
+Then:
+\[
+\beta_{IV} = \frac{\mathrm{Cov}(Z,Y)}{\mathrm{Cov}(Z,X)}.
+\]
+
+### 4.4 ID Algorithm (Shpitser–Pearl)
+The ID algorithm recursively identifies \(P(Y\mid do(X))\) in semi-Markovian graphs.
+Key steps:
+1. If \(Y\subseteq X\), return 1.
+2. If \(X=\emptyset\), return \(P(Y)\).
+3. Decompose into C-components and recurse.
+
+Correctness and completeness: Shpitser & Pearl (JMLR 2008).
+
+## 5. Linear-Gaussian SCM Inference
+For linear-Gaussian SCM:
+\[
+V = B^T V + U,\quad U\sim \mathcal{N}(0,\Sigma).
+\]
+Let \(A = I - B^T\). Then:
+\[
+U = AV,\quad V = A^{-1}U,\quad \Sigma_V = A^{-1}\Sigma A^{-T}.
+\]
+
+**Partial observation**: If \(V = (V_o, V_m)\) with observed \(V_o\), then
+\[
+\mathbb{E}[V_m\mid V_o] = \Sigma_{mo}\Sigma_{oo}^{-1}V_o.
+\]
+Thus:
+\[
+\mathbb{E}[U\mid V_o] = A\mathbb{E}[V\mid V_o].
+\]
+
+## 6. Discovery algorithms (assumptions)
+### PC
+Correct under causal sufficiency + faithfulness; returns CPDAG.
+
+### FCI
+Handles latent confounding; returns PAG; correctness relies on ancestral graph Markov properties.
+
+### GES
+Score-based search; consistent under correct score + large sample assumptions.
+
+### PCMCI
+Time-lagged conditional independence; requires stationarity and lag sufficiency.
+
+## 7. ReAct with critique (formal)
+Define a gating function \(g(a)\in\{\text{allow},\text{refuse}\}\) for actions.
+Define critique score:
+\[
+C_t = \sum_i w_i \phi_i(\text{missing prereqs}, \text{refusal risk}, \text{spec mismatch}).
+\]
+Policy: if \(C_t\ge \tau\), revise; else finalize.
+
+## References
+- Pearl, *Causality* (2009)
+- Shpitser & Pearl (JMLR 2008)
+- Peters, Janzing, Schölkopf (2017)
+- Runge et al. (2019) PCMCI

docs/lrm/overview.md

@@ -0,0 +1,32 @@
+---
+title: LRM Overview
+---
+
+# Large Reasoning Model (LRM)
+
+CR-CA’s LRM mode is a **ReAct + self‑critique** reasoning architecture that:
+
+- Runs **multi‑cycle Reason → Act → Observe** loops.
+- Performs **end‑of‑cycle critique** to revise plans.
+- Enforces **strict tool gating** (no numeric causal outputs unless crca_core approves).
+- Writes to structured memory **only on finalize**.
+
+## What it is
+- A **reasoning kernel** that orchestrates tools and structured memory.
+- A **training pipeline** that finetunes a small base model on ReAct traces.
+
+## Full finetune (Qwen2.5-7B-Instruct)
+- See `docs/lrm/finetune_full.md` for the 16GB GPU setup, dataset build steps, and export workflows.
+
+## What it is not
+- Not an LLM that can output causal numbers without locked specs.
+- Not a replacement for `crca_core` scientific validation.
+
+## Key modules
+- `crca_reasoning/godclass.py` (ReActGodClass)
+- `crca_reasoning/react_controller.py`
+- `crca_reasoning/critique.py`
+- `crca_reasoning/rationale.py`
+- `crca_reasoning/memory.py`
+- `crca_reasoning/tool_router.py`
+

docs/mkdocs.yml

@@ -0,0 +1,238 @@
+site_name: CR-CA Documentation
+site_description: Causal Reasoning and Counterfactual Analysis Framework
+site_author: CR-CA Contributors
+site_url: https://github.com/IlumCI/CR-CA
+
+repo_name: IlumCI/CR-CA
+repo_url: https://github.com/IlumCI/CR-CA
+edit_uri: edit/main/docs/
+
+copyright: Copyright © 2024-2026 CR-CA Contributors
+
+theme:
+  name: material
+  palette:
+    - scheme: default
+      primary: indigo
+      accent: blue
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: indigo
+      accent: blue
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  font:
+    text: Inter
+    code: Roboto Mono
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.code.annotate
+    - content.tabs.link
+    - content.code.copy
+  icon:
+    repo: fontawesome/brands/github
+
+markdown_extensions:
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.tabbed:
+      alternate_style: true
+  - admonition
+  - pymdownx.details
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - attr_list
+  - md_in_html
+  - toc:
+      permalink: true
+      toc_depth: 3
+
+plugins:
+  - search:
+      lang: en
+  - minify:
+      minify_html: true
+  - git-revision-date-localized:
+      enable_creation_date: true
+      type: date
+  - mermaid2
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [..]
+          selection:
+            docstring_style: google
+          rendering:
+            show_source: true
+            show_root_heading: true
+            show_root_toc_entry: true
+
+extra_javascript:
+  - javascripts/mathjax.js
+  - https://polyfill.io/v3/polyfill.min.js?features=es6
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+
+extra_css:
+  - css/custom.css
+  - stylesheets/extra.css
+
+nav:
+  - Home: index.md
+  - Getting Started:
+    - Installation: getting-started/installation.md
+    - Quickstart: getting-started/quickstart.md
+    - Configuration: getting-started/configuration.md
+    - First Agent: getting-started/first-agent.md
+  - Core Modules:
+    - CRCAAgent:
+      - Overview: core/crcagent/overview.md
+      - Initialization: core/crcagent/initialization.md
+      - Automatic Extraction: core/crcagent/automatic-extraction.md
+      - Dual-Mode Operation: core/crcagent/dual-mode-operation.md
+      - Causal Graph: core/crcagent/causal-graph.md
+      - Deterministic Simulation: core/crcagent/deterministic-simulation.md
+      - Counterfactuals: core/crcagent/counterfactuals.md
+      - Batch Prediction: core/crcagent/batch-prediction.md
+      - Async Operations: core/crcagent/async-operations.md
+      - Optimization: core/crcagent/optimization.md
+      - Time-Series: core/crcagent/time-series.md
+      - Bayesian Inference: core/crcagent/bayesian-inference.md
+    - Utils:
+      - Overview: core/utils/overview.md
+      - Router: core/utils/router.md
+      - Conversation: core/utils/conversation.md
+      - Graph Reasoner: core/utils/graph-reasoner.md
+      - Utilities: core/utils/utilities.md
+    - Templates:
+      - Overview: core/templates/overview.md
+      - Base Agent: core/templates/base-agent.md
+      - Feature Mixins: core/templates/feature-mixins.md
+      - Templates Guide: core/templates/templates-guide.md
+    - Schemas:
+      - Overview: core/schemas/overview.md
+      - Annotation: core/schemas/annotation.md
+      - Core Schemas: core/schemas/core-schemas.md
+      - Policy: core/schemas/policy.md
+    - Tools:
+      - Overview: core/tools/overview.md
+      - MCP Client: core/tools/mcp-client.md
+  - Branches:
+    - CRCA-Q:
+      - Overview: branches/crca-q/overview.md
+      - Philosophy: branches/crca-q/philosophy.md
+      - Architecture: branches/crca-q/architecture.md
+      - Market Data: branches/crca-q/market-data.md
+      - Alternative Data: branches/crca-q/alternative-data.md
+      - Signal Generation: branches/crca-q/signal-generation.md
+      - Causal Engine: branches/crca-q/causal-engine.md
+      - Signal Validation: branches/crca-q/signal-validation.md
+      - Portfolio Optimization: branches/crca-q/portfolio-optimization.md
+      - Risk Management: branches/crca-q/risk-management.md
+      - Execution: branches/crca-q/execution.md
+      - Backtesting: branches/crca-q/backtesting.md
+      - Setup: branches/crca-q/setup.md
+    - CRCA-SD:
+      - Overview: branches/crca-sd/overview.md
+      - Core: branches/crca-sd/core.md
+      - MPC Solver: branches/crca-sd/mpc-solver.md
+      - Governance: branches/crca-sd/governance.md
+      - Real-Time: branches/crca-sd/realtime.md
+      - TUI: branches/crca-sd/tui.md
+    - CRCA-CG:
+      - Overview: branches/crca-cg/overview.md
+      - CorporateSwarm: branches/crca-cg/corposwarm.md
+      - ESG Scoring: branches/crca-cg/esg-scoring.md
+      - Multi-Agent: branches/crca-cg/multi-agent.md
+    - General Agent:
+      - Overview: branches/general-agent/overview.md
+      - Personality: branches/general-agent/personality.md
+      - Prompt Builder: branches/general-agent/prompt-builder.md
+  - Features:
+    - Image Annotation:
+      - Overview: features/image-annotation/overview.md
+      - Quickstart: features/image-annotation/quickstart.md
+      - Engine: features/image-annotation/engine.md
+      - Features: features/image-annotation/features.md
+      - Integration: features/image-annotation/integration.md
+    - Policy Engine:
+      - Overview: features/policy-engine/overview.md
+      - Doctrine & Ledger: features/policy-engine/doctrine-ledger.md
+      - MPC & Control: features/policy-engine/mpc-control.md
+      - Monitoring & Drift Detection: features/policy-engine/monitoring.md
+    - Hybrid Agent:
+      - Overview: features/hybrid-agent/overview.md
+      - Core Components: features/hybrid-agent/core-components.md
+      - Advanced Components: features/hybrid-agent/advanced-components.md
+    - Causal Reasoning:
+      - Overview: features/causal-reasoning/overview.md
+      - Structural Models: features/causal-reasoning/structural-models.md
+      - Do-Calculus: features/causal-reasoning/do-calculus.md
+      - Counterfactuals: features/causal-reasoning/counterfactuals.md
+      - Advanced Topics: features/causal-reasoning/advanced-topics.md
+  - Examples:
+    - Overview: examples/overview.md
+    - Basic Usage: examples/basic-usage.md
+    - General Agent: examples/general-agent/general-agent-examples.md
+    - Hybrid Agent: examples/hybrid-agent/hybrid-agent-examples.md
+    - Image Annotation: examples/image-annotation/image-annotation-examples.md
+    - Trading: examples/trading/trading-examples.md
+    - Integration: examples/integration/integration-examples.md
+  - Architecture:
+    - Overview: architecture/overview.md
+    - Design Principles: architecture/design-principles.md
+    - Data Flow: architecture/data-flow.md
+    - Modular Structure: architecture/modular-structure.md
+    - Hybrid Agent:
+      - Overview: architecture/hybrid-agent/overview.md
+      - Components: architecture/hybrid-agent/components.md
+      - Consistency: architecture/hybrid-agent/consistency.md
+      - Reasoning: architecture/hybrid-agent/reasoning.md
+    - Causal Graphs: architecture/causal-graphs.md
+    - LLM Integration: architecture/llm-integration.md
+    - Policy Engine: architecture/policy-engine-arch.md
+  - API Reference:
+    - CRCAAgent:
+      - Overview: api/crca/overview.md
+      - Agent & Methods: api/crca/agent-methods.md
+      - Operations: api/crca/operations.md
+    - Utils:
+      - Overview: api/utils/overview.md
+      - Router: api/utils/router.md
+      - Conversation: api/utils/conversation.md
+      - Graph Reasoner: api/utils/graph-reasoner.md
+      - Utilities: api/utils/utilities.md
+    - Schemas:
+      - Overview: api/schemas/overview.md
+      - Annotation: api/schemas/annotation.md
+      - Core Schemas: api/schemas/core-schemas.md
+      - Policy: api/schemas/policy.md
+    - Branches:
+      - Overview: api/branches/overview.md
+      - CRCA-Q: api/branches/crca-q.md
+      - CRCA-SD: api/branches/crca-sd.md
+      - CRCA-CG: api/branches/crca-cg.md
+      - General Agent: api/branches/general-agent.md
+    - Image Annotation:
+      - Overview: api/image-annotation/overview.md
+      - Engine: api/image-annotation/engine.md
+  - Changelog: changelog/index.md
+  - Contributing: contributing/overview.md

docs/stylesheets/extra.css

@@ -0,0 +1,21 @@
+/* Additional custom styles for CR-CA documentation */
+
+/* Ensure MathJax renders properly */
+.MathJax {
+  font-size: 1.1em;
+}
+
+/* Math display blocks */
+.MathJax_Display {
+  margin: 1em 0;
+}
+
+/* Code blocks with math */
+.md-typeset code {
+  font-family: "Roboto Mono", monospace;
+}
+
+/* Ensure proper spacing for math */
+.md-typeset .arithmatex {
+  margin: 0.5em 0;
+}

docs_generated/crca_core/CounterfactualResult.md

@@ -0,0 +1,12 @@
+## `CounterfactualResult`
+
+This page is generated from the JSON schema (contract-first).
+
+| Field | Type | Notes |
+|---|---|---|
+| `result_type` | `string` | optional. |
+| `provenance` | `#/$defs/ProvenanceManifest` | required. |
+| `assumptions` | `array` | optional. |
+| `limitations` | `array` | optional. |
+| `artifacts` | `object` | optional. |
+| `counterfactual` | `object` | optional. |

docs_generated/crca_core/DiscoveryHypothesisResult.md

@@ -0,0 +1,13 @@
+## `DiscoveryHypothesisResult`
+
+This page is generated from the JSON schema (contract-first).
+
+| Field | Type | Notes |
+|---|---|---|
+| `result_type` | `string` | optional. |
+| `provenance` | `#/$defs/ProvenanceManifest` | required. |
+| `assumptions` | `array` | optional. |
+| `limitations` | `array` | optional. |
+| `artifacts` | `object` | optional. |
+| `graph_hypothesis` | `object` | optional. |
+| `stability_report` | `object` | optional. |

docs_generated/crca_core/DraftSpec.md

@@ -0,0 +1,13 @@
+## `DraftSpec`
+
+This page is generated from the JSON schema (contract-first).
+
+| Field | Type | Notes |
+|---|---|---|
+| `status` | `#/$defs/SpecStatus` | optional. |
+| `data` | `#/$defs/DataSpec` | optional. |
+| `graph` | `#/$defs/CausalGraphSpec` | optional. |
+| `roles` | `#/$defs/RoleSpec` | optional. |
+| `assumptions` | `#/$defs/AssumptionSpec` | optional. |
+| `scm` | `unknown` | optional. |
+| `draft_notes` | `unknown` | optional. |

docs_generated/crca_core/EstimateResult.md

@@ -0,0 +1,13 @@
+## `EstimateResult`
+
+This page is generated from the JSON schema (contract-first).
+
+| Field | Type | Notes |
+|---|---|---|
+| `result_type` | `string` | optional. |
+| `provenance` | `#/$defs/ProvenanceManifest` | required. |
+| `assumptions` | `array` | optional. |
+| `limitations` | `array` | optional. |
+| `artifacts` | `object` | optional. |
+| `estimate` | `object` | optional. |
+| `refutations` | `object` | optional. |

docs_generated/crca_core/IdentificationResult.md

@@ -0,0 +1,17 @@
+## `IdentificationResult`
+
+This page is generated from the JSON schema (contract-first).
+
+| Field | Type | Notes |
+|---|---|---|
+| `result_type` | `string` | optional. |
+| `provenance` | `#/$defs/ProvenanceManifest` | required. |
+| `assumptions` | `array` | optional. |
+| `limitations` | `array` | optional. |
+| `artifacts` | `object` | optional. |
+| `method` | `string` | required. |
+| `scope` | `string` | optional. |
+| `confidence` | `string` | optional. |
+| `estimand_expression` | `string` | required. |
+| `assumptions_used` | `array` | optional. |
+| `witnesses` | `object` | optional. |

docs_generated/crca_core/InterventionDesignResult.md

@@ -0,0 +1,12 @@
+## `InterventionDesignResult`
+
+This page is generated from the JSON schema (contract-first).
+
+| Field | Type | Notes |
+|---|---|---|
+| `result_type` | `string` | optional. |
+| `provenance` | `#/$defs/ProvenanceManifest` | required. |
+| `assumptions` | `array` | optional. |
+| `limitations` | `array` | optional. |
+| `artifacts` | `object` | optional. |
+| `designs` | `array` | optional. |

docs_generated/crca_core/LockedSpec.md

@@ -0,0 +1,15 @@
+## `LockedSpec`
+
+This page is generated from the JSON schema (contract-first).
+
+| Field | Type | Notes |
+|---|---|---|
+| `status` | `#/$defs/SpecStatus` | optional. |
+| `spec_hash` | `string` | required. |
+| `approvals` | `array` | optional. |
+| `locked_at_utc` | `string` | required. |
+| `data` | `#/$defs/DataSpec` | required. |
+| `graph` | `#/$defs/CausalGraphSpec` | required. |
+| `roles` | `#/$defs/RoleSpec` | required. |
+| `assumptions` | `#/$defs/AssumptionSpec` | required. |
+| `scm` | `unknown` | optional. |

docs_generated/crca_core/RefusalResult.md

@@ -0,0 +1,12 @@
+## `RefusalResult`
+
+This page is generated from the JSON schema (contract-first).
+
+| Field | Type | Notes |
+|---|---|---|
+| `result_type` | `string` | optional. |
+| `reason_codes` | `array` | optional. |
+| `message` | `string` | required. |
+| `checklist` | `array` | optional. |
+| `suggested_next_steps` | `array` | optional. |
+| `details` | `unknown` | optional. |

docs_generated/crca_core/ValidationReport.md

@@ -0,0 +1,9 @@
+## `ValidationReport`
+
+This page is generated from the JSON schema (contract-first).
+
+| Field | Type | Notes |
+|---|---|---|
+| `ok` | `boolean` | required. |
+| `errors` | `array` | optional. |
+| `warnings` | `array` | optional. |

docs_generated/crca_core/index.md

@@ -0,0 +1,13 @@
+# crca_core schema contracts (generated)
+
+These documents are generated from exported Pydantic JSON schemas.
+
+- `CounterfactualResult`: `CounterfactualResult.md`
+- `DiscoveryHypothesisResult`: `DiscoveryHypothesisResult.md`
+- `DraftSpec`: `DraftSpec.md`
+- `EstimateResult`: `EstimateResult.md`
+- `IdentificationResult`: `IdentificationResult.md`
+- `InterventionDesignResult`: `InterventionDesignResult.md`
+- `LockedSpec`: `LockedSpec.md`
+- `RefusalResult`: `RefusalResult.md`
+- `ValidationReport`: `ValidationReport.md`