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

docs/getting-started/first-agent.md

@@ -0,0 +1,164 @@
+# Creating Your First Agent
+
+This tutorial walks you through creating a complete causal reasoning agent from scratch.
+
+## Example: Education and Income Analysis
+
+Let's build an agent that analyzes the causal relationship between education and income.
+
+### Step 1: Import and Initialize
+
+```python
+from CRCA import CRCAAgent
+
+# Create the agent
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    agent_name="education-income-analyzer",
+    max_loops=5
+)
+```
+
+### Step 2: Define Your Causal Question
+
+```python
+task = """
+Analyze the causal relationship between education and income.
+
+Consider the following factors:
+- Years of education
+- Type of degree
+- Work experience
+- Industry sector
+- Geographic location
+
+Determine:
+1. The direct causal effect of education on income
+2. Mediating factors (experience, industry)
+3. Confounding variables (geographic location, family background)
+4. Counterfactual scenarios (what if education increased by 2 years?)
+"""
+```
+
+### Step 3: Run the Analysis
+
+```python
+result = agent.run(task)
+print(result)
+```
+
+The agent will automatically:
+1. Extract variables from the task
+2. Identify causal relationships
+3. Build a causal graph
+4. Perform causal inference
+5. Generate counterfactuals
+
+### Step 4: Examine the Causal Graph
+
+```python
+# Get the causal graph
+graph = agent.causal_graph
+
+# View all variables
+variables = graph.get_variables()
+print("Variables:", variables)
+
+# View causal relationships
+relationships = graph.get_relationships()
+for parent, child, strength in relationships:
+    print(f"{parent} -> {child}: {strength:.2f}")
+```
+
+### Step 5: Generate Counterfactuals
+
+```python
+# What if education increased by 2 years?
+counterfactuals = agent.generate_counterfactuals(
+    intervention={"education_years": "+2"},
+    outcome="income"
+)
+
+for cf in counterfactuals:
+    print(f"\nCounterfactual: {cf.description}")
+    print(f"Expected income change: {cf.expected_outcome}")
+```
+
+### Step 6: Run Deterministic Simulation
+
+```python
+# Simulate with specific values
+simulation = agent.simulate(
+    variables={
+        "education_years": 16,
+        "experience_years": 5,
+        "industry": "technology"
+    },
+    target="income"
+)
+
+print(f"Simulated income: ${simulation:,.2f}")
+```
+
+## Mathematical Foundation
+
+The agent uses Structural Causal Models (SCMs) to represent causal relationships. For education and income:
+
+$$Income = f(Education, Experience, Industry, Location, \epsilon)$$
+
+Where $\epsilon$ represents unobserved factors.
+
+The causal effect of education on income, controlling for confounders, is:
+
+$$E[Income | do(Education = e)] = \sum_{z} E[Income | Education = e, Z = z] P(Z = z)$$
+
+Where $Z$ represents confounders (experience, industry, location).
+
+## Complete Example
+
+```python
+from CRCA import CRCAAgent
+
+# Initialize agent
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    agent_name="education-income-analyzer"
+)
+
+# Define task
+task = """
+Analyze how increasing education from high school to college affects income,
+controlling for work experience and industry sector.
+"""
+
+# Run analysis
+result = agent.run(task)
+
+# Get causal graph
+graph = agent.causal_graph
+print("Causal Graph Variables:", graph.get_variables())
+
+# Generate counterfactuals
+counterfactuals = agent.generate_counterfactuals(
+    intervention={"education": "college"},
+    outcome="income"
+)
+
+# Run simulation
+simulation = agent.simulate(
+    variables={
+        "education": "college",
+        "experience": 3,
+        "industry": "technology"
+    },
+    target="income"
+)
+
+print(f"\nSimulated Income: ${simulation:,.2f}")
+```
+
+## Next Steps
+
+- [Core Modules](../core/crcagent/overview.md) - Learn about core functionality
+- [Examples](../examples/overview.md) - Explore more examples
+- [API Reference](../api/crca/overview.md) - Complete API documentation

docs/getting-started/installation.md

@@ -0,0 +1,144 @@
+# Installation
+
+This guide covers installing CR-CA and its dependencies.
+
+## Prerequisites
+
+- Python 3.10 or higher
+- pip package manager
+- (Optional) Git for cloning the repository
+- (Optional) Docker for containerized deployment
+
+## Quick Install
+
+### Method 1: From PyPI (Recommended)
+
+```bash
+pip install crca
+```
+
+### Method 2: From Source
+
+Clone the repository:
+
+```bash
+git clone https://github.com/IlumCI/CR-CA.git
+cd CR-CA
+```
+
+Install dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+### Method 3: Development Install
+
+For development with editable install:
+
+```bash
+git clone https://github.com/IlumCI/CR-CA.git
+cd CR-CA
+pip install -e ".[dev]"
+```
+
+## Optional Dependencies
+
+### Policy Engine
+
+```bash
+# Install policy engine dependencies
+pip install cvxpy ruptures psutil
+
+# Or install all optional dependencies
+pip install crca[policy-engine]
+```
+
+### CRCA-SD
+
+CRCA-SD dependencies are included in `requirements.txt`. Additional dependencies may be needed for specific features.
+
+### CRCA-CG
+
+```bash
+# Install TUI dependencies (optional)
+pip install rich
+
+# Or install all optional dependencies
+pip install crca[tui]
+```
+
+### CRCA-Q
+
+```bash
+# Install trading dependencies
+pip install ccxt web3
+
+# Or install all optional dependencies
+pip install crca[trading]
+```
+
+## Environment Variables
+
+Create a `.env` file in the project root with required API keys:
+
+```bash
+# Required for LLM functionality
+OPENAI_API_KEY=your_openai_api_key_here
+
+# Optional: For CRCA-Q trading
+KRAKEN_API_KEY=your_kraken_key_here
+KRAKEN_API_SECRET=your_kraken_secret_here
+
+# Optional: For alternative data sources
+TWITTER_BEARER_TOKEN=your_twitter_token_here
+ETHERSCAN_API_KEY=your_etherscan_key_here
+THEGRAPH_API_KEY=your_thegraph_key_here
+
+# Optional: For MCP servers
+MCP_SERVER_URL=http://localhost:8000
+MCP_API_KEY=your_mcp_api_key_here
+```
+
+## Verification
+
+Verify your installation:
+
+```python
+from CRCA import CRCAAgent
+
+# This should work without errors
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    agent_name="test-agent"
+)
+print("Installation successful!")
+```
+
+## Troubleshooting
+
+### Windows: cvxpy Installation Issues
+
+If you encounter issues installing `cvxpy` on Windows, you need Microsoft Visual C++ 14.0 or higher:
+
+1. Download [Microsoft Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
+2. Install the "Desktop development with C++" workload
+3. Retry: `pip install cvxpy`
+
+### Import Errors
+
+If you see import errors, ensure all dependencies are installed:
+
+```bash
+pip install -r requirements.txt
+```
+
+### API Key Issues
+
+Make sure your `.env` file is in the project root and contains valid API keys. The framework will automatically load environment variables from `.env`.
+
+## Next Steps
+
+- [Quickstart Guide](quickstart.md) - Get started with your first agent
+- [Configuration](configuration.md) - Configure your environment
+- [First Agent](first-agent.md) - Create your first causal reasoning agent

docs/getting-started/quickstart.md

@@ -0,0 +1,137 @@
+# Quickstart Guide
+
+Get started with CR-CA in minutes. This guide walks you through creating your first causal reasoning agent.
+
+## Basic Usage
+
+### 1. Import and Initialize
+
+```python
+from CRCA import CRCAAgent
+
+# Create an agent
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    agent_name="my-first-agent"
+)
+```
+
+### 2. Run a Simple Task
+
+```python
+# Ask the agent to analyze a causal relationship
+result = agent.run(
+    "What is the causal relationship between education and income?"
+)
+
+print(result)
+```
+
+### 3. Automatic Variable Extraction
+
+CR-CA automatically extracts variables and causal relationships from natural language:
+
+```python
+task = """
+Analyze how increasing the minimum wage affects employment rates.
+Consider factors like inflation, business costs, and consumer spending.
+"""
+
+result = agent.run(task)
+
+# The agent automatically:
+# 1. Extracts variables (minimum_wage, employment_rate, inflation, etc.)
+# 2. Identifies causal relationships
+# 3. Builds a causal graph
+# 4. Performs causal analysis
+```
+
+## Mathematical Foundation
+
+CR-CA uses Structural Causal Models (SCMs) to represent causal relationships. An SCM is defined as:
+
+$$(U, V, F)$$
+
+Where:
+- $U$: Exogenous (unobserved) variables
+- $V$: Endogenous (observed) variables
+- $F$: Structural equations defining causal relationships
+
+The causal effect of intervention $do(X=x)$ on outcome $Y$ is computed using:
+
+$$E[Y | do(X=x)] = \sum_{z} E[Y | X=x, Z=z] P(Z=z)$$
+
+## Working with Causal Graphs
+
+### View the Causal Graph
+
+```python
+# After running a task, access the causal graph
+graph = agent.causal_graph
+
+# Get all variables
+variables = graph.get_variables()
+print(f"Variables: {variables}")
+
+# Get causal relationships
+relationships = graph.get_relationships()
+for parent, child, strength in relationships:
+    print(f"{parent} -> {child} (strength: {strength})")
+```
+
+### Add Causal Relationships Manually
+
+```python
+# Add a causal relationship
+agent.add_causal_relationship(
+    parent="education",
+    child="income",
+    strength=0.6
+)
+
+# Add multiple relationships
+agent.add_causal_relationships([
+    ("education", "income", 0.6),
+    ("experience", "income", 0.4),
+    ("education", "experience", 0.3)
+])
+```
+
+## Counterfactual Analysis
+
+Generate "what-if" scenarios:
+
+```python
+# Generate counterfactuals
+counterfactuals = agent.generate_counterfactuals(
+    intervention={"education": "college"},
+    outcome="income"
+)
+
+for scenario in counterfactuals:
+    print(f"Scenario: {scenario.description}")
+    print(f"Expected outcome: {scenario.expected_outcome}")
+```
+
+## Deterministic Simulation
+
+Run deterministic causal simulations:
+
+```python
+# Simulate with specific variable values
+simulation_result = agent.simulate(
+    variables={
+        "education": 16,  # years
+        "experience": 5,  # years
+    },
+    target="income"
+)
+
+print(f"Simulated income: ${simulation_result:.2f}")
+```
+
+## Next Steps
+
+- [Configuration](configuration.md) - Configure advanced settings
+- [First Agent](first-agent.md) - Build a complete example
+- [Core Modules](../core/crcagent/overview.md) - Learn about core functionality

docs/index.md

@@ -0,0 +1,118 @@
+# CR-CA: Causal Reasoning and Counterfactual Analysis Framework
+
+**Version**: v1.4.0  
+**Repository**: [GitHub](https://github.com/IlumCI/CR-CA)  
+**License**: Apache-2.0
+
+CR-CA is a comprehensive framework for causal reasoning and counterfactual analysis, combining structural causal models (SCMs) with large language model (LLM) integration. The framework enables sophisticated causal inference, automatic variable extraction from natural language, deterministic causal simulation, and comprehensive counterfactual scenario generation.
+
+## Quick Start
+
+```bash
+pip install crca
+```
+
+```python
+from CRCA import CRCAAgent
+
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    agent_name="my-causal-agent"
+)
+
+result = agent.run("Analyze the causal relationship between education and income")
+```
+
+## Key Features
+
+### Core Capabilities
+
+- **Automatic Variable Extraction**: Extract variables and causal relationships from natural language tasks
+- **Dual-Mode Operation**: Switch between LLM-based analysis and deterministic simulation
+- **Structural Causal Models**: Build and manage causal directed acyclic graphs (DAGs)
+- **Deterministic Simulation**: Perform causal simulations with mathematical precision
+- **Counterfactual Generation**: Generate "what-if" scenarios for decision support
+
+### Advanced Analysis
+
+- **Batch Prediction**: Process multiple scenarios simultaneously
+- **Async Operations**: Concurrent analysis with async/await support
+- **Optimization Methods**: Gradient-based and dynamic programming optimization
+- **Time-Series Analysis**: Granger causality, VAR estimation, and temporal modeling
+- **Bayesian Inference**: Posterior distributions with credible intervals
+
+### Specialized Branches
+
+- **CRCA-Q**: Quantitative trading with causal signals and portfolio optimization
+- **CRCA-SD**: Socioeconomic dynamics with MPC solver and governance systems
+- **CRCA-CG**: Corporate governance with CorporateSwarm and ESG scoring
+- **General Agent**: Flexible general-purpose agent with personality system
+
+## Mathematical Foundation
+
+CR-CA is built on rigorous mathematical foundations:
+
+### Structural Causal Models
+
+A Structural Causal Model (SCM) is defined as a triple $(U, V, F)$ where:
+
+- $U$: Exogenous (unobserved) variables
+- $V$: Endogenous (observed) variables  
+- $F$: Structural equations defining causal relationships
+
+### Do-Calculus
+
+The causal effect of intervention $do(X=x)$ on outcome $Y$ is:
+
+$$E[Y | do(X=x)] = \sum_{z} E[Y | X=x, Z=z] P(Z=z)$$
+
+Where $Z$ represents confounders that need to be adjusted for.
+
+### Counterfactual Reasoning
+
+Counterfactual queries answer "what would have happened if" questions:
+
+$$P(Y_{x'} | X=x, Y=y)$$
+
+This represents the probability of outcome $Y$ under intervention $X=x'$, given that we observed $X=x$ and $Y=y$.
+
+## Documentation Structure
+
+- **[Getting Started](getting-started/installation.md)**: Installation and setup guides
+- **[Core Modules](core/crcagent/overview.md)**: CRCAAgent and core functionality
+- **[Branches](branches/crca-q/overview.md)**: Specialized agent implementations
+- **[Features](features/image-annotation/overview.md)**: Image annotation, policy engine, hybrid agent
+- **[Examples](examples/overview.md)**: Code examples and tutorials
+- **[Architecture](architecture/overview.md)**: System design and principles
+- **[API Reference](api/crca/overview.md)**: Complete API documentation
+
+## Installation
+
+```bash
+# From PyPI
+pip install crca
+
+# From source
+git clone https://github.com/IlumCI/CR-CA.git
+cd CR-CA
+pip install -r requirements.txt
+```
+
+## Quick Links
+
+- [Installation Guide](getting-started/installation.md)
+- [Quickstart Tutorial](getting-started/quickstart.md)
+- [API Reference](api/crca/overview.md)
+- [Examples](examples/overview.md)
+- [Contributing](contributing/overview.md)
+
+## Research & Theory
+
+CR-CA implements concepts from:
+
+- **Judea Pearl's Causal Hierarchy**: Association, intervention, and counterfactual reasoning
+- **Structural Causal Models**: Mathematical framework for causal inference
+- **Do-Calculus**: Rules for identifying causal effects from observational data
+- **Counterfactual Analysis**: Reasoning about alternative scenarios
+
+For detailed mathematical foundations, see the [Causal Reasoning](features/causal-reasoning/overview.md) section.

docs/js/mathjax.js

@@ -0,0 +1,13 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [['$', '$'], ['\\(', '\\)']],
+    displayMath: [['$$', '$$'], ['\\[', '\\]']],
+    processEscapes: true,
+    processEnvironments: true,
+    packages: {'[+]': ['ams', 'newcommand', 'configmacros']}
+  },
+  options: {
+    ignoreHtmlClass: 'tex2jax_ignore',
+    processHtmlClass: 'tex2jax_process'
+  }
+};

docs/lrm/discovery_proof_notes.md

@@ -0,0 +1,25 @@
+---
+title: Discovery Proof Notes
+---
+
+# Discovery Proof Notes (Assumptions + Correctness)
+
+## PC algorithm
+- **Assumptions**: causal sufficiency, faithfulness, correct CI test.
+- **Output**: CPDAG (equivalence class).
+- **Correctness**: asymptotic correctness under assumptions (Spirtes et al.).
+
+## FCI algorithm
+- **Assumptions**: faithfulness, correct CI test, allows latent confounding.
+- **Output**: PAG (partial ancestral graph).
+- **Correctness**: relies on ancestral graph Markov properties (Richardson & Spirtes).
+
+## GES
+- **Assumptions**: correct scoring criterion (e.g., BIC), large sample.
+- **Output**: CPDAG of highest score.
+- **Correctness**: asymptotic consistency for score-equivalent metrics.
+
+## PCMCI / PCMCI+
+- **Assumptions**: stationarity, lag sufficiency, correct CI test.
+- **Output**: lagged causal graph hypothesis.
+- **Correctness**: consistency depends on correct lag window and CI testing.

docs/lrm/finetune_full.md

@@ -0,0 +1,83 @@
+---
+title: Full Finetune (Qwen2.5-0.5B)
+---
+
+# Full Finetune (Qwen2.5-0.5B-Instruct)
+
+This guide targets finetuning the **Qwen2.5-0.5B-Instruct** model using **DeepSpeed ZeRO-3 CPU offload** and a **4k context length**. The 0.5B model is optimized for faster training with larger batch sizes and higher learning rates compared to larger models.
+
+## Requirements
+- Python deps: `transformers`, `datasets`, `accelerate`, `deepspeed`
+- GPU driver + CUDA compatible with your PyTorch build
+- Fast SSD/NVMe recommended (CPU offload is heavy on disk I/O)
+
+## 1) Build the dataset (hybrid)
+```bash
+python scripts/build_lrm_dataset.py \
+  --trace-jsonl path/to/traces.jsonl \
+  --output training_data/react_train.jsonl
+```
+
+Optional: provide a public dataset config JSON:
+```bash
+python scripts/build_lrm_dataset.py \
+  --trace-jsonl path/to/traces.jsonl \
+  --public-config configs/public_datasets.json \
+  --output training_data/react_train.jsonl
+```
+
+## 2) Run full finetune
+```bash
+python scripts/run_full_finetune.py \
+  --train-file training_data/react_train.jsonl \
+  --output-dir lrm_qwen25_0_5b_full_finetune
+```
+
+Notes:
+- Uses `training/deepspeed_zero3_0_5b.json` (optimized for 0.5B model)
+- Defaults to micro-batch 8 with gradient accumulation of 4
+- Higher learning rate (3e-4) optimized for smaller model size
+- Larger batch sizes possible due to smaller model memory footprint
+
+### Hyperparameter Comparison
+
+| Parameter | 0.5B Model (Default) | 7B Model (Reference) |
+|-----------|----------------------|----------------------|
+| per_device_batch_size | 8 | 1 |
+| gradient_accumulation_steps | 4 | 32 |
+| learning_rate | 3e-4 | 1e-5 |
+| max_seq_length | 4096 | 4096 |
+| DeepSpeed config | `deepspeed_zero3_0_5b.json` | `deepspeed_zero3_offload.json` |
+
+The 0.5B model configuration uses:
+- **Larger batch sizes**: The model is ~14x smaller, allowing for batch size 8 instead of 1
+- **Higher learning rates**: Smaller models can handle higher learning rates (3e-4 vs 1e-5)
+- **Reduced gradient accumulation**: Larger batch size means less accumulation needed
+- **Optimized DeepSpeed buckets**: Smaller bucket sizes tuned for the 0.5B model
+
+## 3) Evaluate traces
+```bash
+python scripts/run_lrm_eval.py \
+  --trace path/to/trace.jsonl \
+  --output eval_results/lrm_eval.json
+```
+
+## 4) Export to HuggingFace
+```bash
+python scripts/export_hf_lrm.py \
+  --checkpoint-dir lrm_qwen25_0_5b_full_finetune \
+  --output-dir hf_export/crca_lrm_0_5b
+```
+
+## 5) Export to Ollama (GGUF)
+```bash
+python scripts/export_ollama_gguf.py \
+  --checkpoint-dir hf_export/crca_lrm \
+  --output ollama/crca_lrm.gguf \
+  --llama-cpp-dir /path/to/llama.cpp
+```
+
+Then update `ollama/Modelfile` and run:
+```bash
+ollama create crca-lrm -f ollama/Modelfile
+```