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

docs/core/crcagent/async-operations.md

@@ -0,0 +1,65 @@
+# Async Operations
+
+CRCAAgent supports asynchronous operations for concurrent causal analysis.
+
+## Overview
+
+Async operations allow non-blocking causal inference, enabling concurrent processing of multiple tasks.
+
+## Basic Usage
+
+```python
+import asyncio
+from CRCA import CRCAAgent
+
+agent = CRCAAgent(model_name="gpt-4o-mini")
+
+async def analyze():
+    result = await agent.run_async("Analyze X -> Y")
+    return result
+
+# Run async
+result = asyncio.run(analyze())
+```
+
+## Concurrent Analysis
+
+Process multiple tasks concurrently:
+
+```python
+async def analyze_multiple():
+    tasks = [
+        agent.run_async("Analyze education -> income"),
+        agent.run_async("Analyze experience -> income"),
+        agent.run_async("Analyze location -> income")
+    ]
+    
+    results = await asyncio.gather(*tasks)
+    return results
+
+results = asyncio.run(analyze_multiple())
+```
+
+## Async Batch Processing
+
+```python
+async def batch_async():
+    scenarios = [...]
+    results = await agent.batch_predict_async(
+        scenarios=scenarios,
+        target="income"
+    )
+    return results
+```
+
+## Performance Benefits
+
+Async operations improve throughput:
+
+- **Sequential**: Total time = $\sum_{i=1}^n t_i$
+- **Async**: Total time = $\max_{i=1}^n t_i$ (for I/O bound operations)
+
+## Next Steps
+
+- [Batch Prediction](batch-prediction.md) - Batch processing
+- [Optimization](optimization.md) - Optimization methods

docs/core/crcagent/automatic-extraction.md

@@ -0,0 +1,107 @@
+# Automatic Variable Extraction
+
+CRCAAgent can automatically extract variables and causal relationships from natural language tasks.
+
+## Overview
+
+The automatic extraction system uses LLM-based analysis to identify:
+- Variables of interest
+- Causal relationships between variables
+- Confounders and mediators
+- Structural equations
+
+## Mathematical Foundation
+
+Given a natural language task $T$, the extraction process identifies:
+
+1. **Variable Set**: $V = \{V_1, V_2, \ldots, V_n\}$
+2. **Causal Graph**: $G = (V, E)$ where $E$ are causal edges
+3. **Structural Equations**: $F = \{f_1, f_2, \ldots, f_n\}$
+
+For each variable $V_i$, the system extracts:
+
+$$V_i = f_i(Pa(V_i), U_i)$$
+
+Where $Pa(V_i)$ are the parents identified from the text.
+
+## Usage
+
+### Basic Extraction
+
+```python
+from CRCA import CRCAAgent
+
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    enable_automatic_extraction=True
+)
+
+task = """
+Analyze how increasing the minimum wage affects employment rates.
+Consider inflation, business costs, and consumer spending.
+"""
+
+result = agent.run(task)
+# Variables and relationships are automatically extracted
+```
+
+### View Extracted Variables
+
+```python
+# After running a task
+graph = agent.causal_graph
+variables = graph.get_variables()
+print("Extracted variables:", variables)
+```
+
+### View Causal Relationships
+
+```python
+relationships = graph.get_relationships()
+for parent, child, strength in relationships:
+    print(f"{parent} -> {child}: {strength:.2f}")
+```
+
+## Extraction Process
+
+The extraction process follows these steps:
+
+1. **Text Analysis**: Parse natural language to identify entities
+2. **Variable Identification**: Extract variable names and types
+3. **Relationship Detection**: Identify causal relationships
+4. **Graph Construction**: Build causal DAG
+5. **Strength Estimation**: Estimate relationship strengths
+
+## Example
+
+```python
+task = """
+Study the effect of education on income.
+Education affects experience, which in turn affects income.
+Geographic location also influences income.
+"""
+
+result = agent.run(task)
+
+# Extracted structure:
+# education -> experience -> income
+# location -> income
+```
+
+## Configuration
+
+Control extraction behavior:
+
+```python
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    enable_automatic_extraction=True,
+    extraction_confidence_threshold=0.5,
+    max_extracted_variables=20
+)
+```
+
+## Next Steps
+
+- [Causal Graph](causal-graph.md) - Work with extracted graphs
+- [Dual-Mode Operation](dual-mode-operation.md) - Combine with deterministic mode

docs/core/crcagent/batch-prediction.md

@@ -0,0 +1,80 @@
+# Batch Prediction
+
+CRCAAgent supports batch processing for multiple scenarios simultaneously.
+
+## Overview
+
+Batch prediction allows processing multiple causal queries in parallel, improving efficiency for large-scale analyses.
+
+## Mathematical Foundation
+
+For a batch of $n$ scenarios, we compute:
+
+$$\{E[Y_i | do(X_i=x_i)]\}_{i=1}^n$$
+
+Where each scenario $i$ has intervention $X_i=x_i$ and target $Y_i$.
+
+## Basic Usage
+
+```python
+# Batch of scenarios
+scenarios = [
+    {"education": 12, "experience": 2},
+    {"education": 16, "experience": 5},
+    {"education": 20, "experience": 10}
+]
+
+results = agent.batch_predict(
+    scenarios=scenarios,
+    target="income"
+)
+```
+
+## Vectorized Operations
+
+The agent uses vectorized operations for efficiency:
+
+$$\mathbf{Y} = f(\mathbf{X}, \mathbf{Z}, \mathbf{U})$$
+
+Where bold symbols represent vectors/matrices.
+
+## Parallel Processing
+
+Enable parallel processing:
+
+```python
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    parallel_workers=4
+)
+
+results = agent.batch_predict(scenarios, target="income")
+```
+
+## Performance
+
+Batch processing is significantly faster than sequential processing:
+
+- **Sequential**: $O(n \cdot t)$ where $t$ is time per scenario
+- **Batch**: $O(n \cdot t / p)$ where $p$ is number of workers
+
+## Example
+
+```python
+# Generate batch of counterfactuals
+interventions = [
+    {"education": "college"},
+    {"education": "masters"},
+    {"education": "phd"}
+]
+
+counterfactuals = agent.batch_generate_counterfactuals(
+    interventions=interventions,
+    outcome="income"
+)
+```
+
+## Next Steps
+
+- [Async Operations](async-operations.md) - Asynchronous batch processing
+- [Optimization](optimization.md) - Optimize batch operations

docs/core/crcagent/bayesian-inference.md

@@ -0,0 +1,60 @@
+# Bayesian Inference
+
+CRCAAgent supports Bayesian inference for causal effects with uncertainty quantification.
+
+## Overview
+
+Bayesian inference provides posterior distributions over causal effects, enabling uncertainty quantification through credible intervals.
+
+## Mathematical Foundation
+
+### Posterior Distribution
+
+Given data $D$ and prior $P(\theta)$, the posterior is:
+
+$$P(\theta | D) = \frac{P(D | \theta) P(\theta)}{P(D)}$$
+
+### Causal Effect Posterior
+
+For causal effect $\tau = E[Y | do(X=1)] - E[Y | do(X=0)]$:
+
+$$P(\tau | D) = \int P(\tau | \theta) P(\theta | D) d\theta$$
+
+### Credible Intervals
+
+A $(1-\alpha)$ credible interval $[a, b]$ satisfies:
+
+$$P(a \leq \tau \leq b | D) = 1 - \alpha$$
+
+## Usage
+
+### Bayesian Causal Inference
+
+```python
+# Compute posterior distribution
+posterior = agent.bayesian_causal_inference(
+    treatment="X",
+    outcome="Y",
+    data=dataframe
+)
+
+# Get credible interval
+ci = posterior.credible_interval(alpha=0.05)
+print(f"95% CI: [{ci.lower}, {ci.upper}]")
+```
+
+### Bootstrap Sampling
+
+```python
+# Bootstrap for uncertainty
+samples = agent.bootstrap_causal_effect(
+    treatment="X",
+    outcome="Y",
+    n_samples=1000
+)
+```
+
+## Next Steps
+
+- [Core Modules Overview](../overview.md) - Return to core modules
+- [Utils](../utils/overview.md) - Utility functions

docs/core/crcagent/causal-graph.md

@@ -0,0 +1,92 @@
+# Causal Graph Management
+
+CRCAAgent manages causal relationships through directed acyclic graphs (DAGs).
+
+## Graph Structure
+
+A causal graph $G = (V, E)$ consists of:
+- **Vertices $V$**: Variables in the system
+- **Edges $E$**: Causal relationships $(X \to Y)$
+
+The graph must be acyclic: no directed paths from a variable to itself.
+
+## Mathematical Foundation
+
+For a causal graph, each variable $V_i$ has structural equation:
+
+$$V_i = f_i(Pa(V_i), U_i)$$
+
+Where:
+- $Pa(V_i)$: Parents of $V_i$ in the graph
+- $U_i$: Exogenous variable for $V_i$
+
+## Building Graphs
+
+### Automatic Construction
+
+```python
+agent = CRCAAgent(model_name="gpt-4o-mini")
+result = agent.run("Analyze X -> Y -> Z")
+# Graph is automatically constructed
+```
+
+### Manual Construction
+
+```python
+# Add variables
+agent.add_variable("education")
+agent.add_variable("income")
+agent.add_variable("experience")
+
+# Add causal relationships
+agent.add_causal_relationship("education", "income", strength=0.6)
+agent.add_causal_relationship("education", "experience", strength=0.4)
+agent.add_causal_relationship("experience", "income", strength=0.5)
+```
+
+## Graph Operations
+
+### Get Variables
+
+```python
+variables = agent.causal_graph.get_variables()
+```
+
+### Get Relationships
+
+```python
+relationships = agent.causal_graph.get_relationships()
+for parent, child, strength in relationships:
+    print(f"{parent} -> {child}: {strength}")
+```
+
+### Check Paths
+
+```python
+# Check if path exists
+has_path = agent.causal_graph.has_path("X", "Y")
+
+# Get all paths
+paths = agent.causal_graph.get_paths("X", "Y")
+```
+
+## Causal Identification
+
+The agent can identify causal effects using do-calculus rules:
+
+$$P(Y | do(X=x)) = \sum_{z} P(Y | X=x, Z=z) P(Z=z)$$
+
+Where $Z$ is a valid adjustment set.
+
+## Graph Visualization
+
+```python
+# Export graph for visualization
+graph_data = agent.causal_graph.export()
+# Use with graph visualization libraries
+```
+
+## Next Steps
+
+- [Deterministic Simulation](deterministic-simulation.md) - Use graphs for simulation
+- [Counterfactuals](counterfactuals.md) - Generate counterfactuals from graphs

docs/core/crcagent/counterfactuals.md

@@ -0,0 +1,96 @@
+# Counterfactual Generation
+
+CRCAAgent generates counterfactual scenarios to answer "what-if" questions.
+
+## Overview
+
+Counterfactuals answer questions of the form: "What would have happened if $X$ had been $x'$ instead of $x$, given that we observed $X=x$ and $Y=y$?"
+
+## Mathematical Foundation
+
+A counterfactual query is:
+
+$$P(Y_{x'} | X=x, Y=y)$$
+
+Where:
+- $Y_{x'}$: Potential outcome under intervention $do(X=x')$
+- $X=x, Y=y$: Observed values
+
+This is computed using the three-step process:
+
+1. **Abduction**: Infer exogenous variables from observations
+2. **Action**: Set $X = x'$
+3. **Prediction**: Compute $Y$ using structural equations
+
+## Basic Usage
+
+```python
+# Generate counterfactuals
+counterfactuals = agent.generate_counterfactuals(
+    intervention={"education": "college"},
+    outcome="income",
+    observed={"education": "high_school", "income": 30000}
+)
+```
+
+## Counterfactual Types
+
+### Simple Counterfactuals
+
+Single intervention:
+
+```python
+cf = agent.generate_counterfactuals(
+    intervention={"X": x_new},
+    outcome="Y"
+)
+```
+
+### Multiple Interventions
+
+```python
+cf = agent.generate_counterfactuals(
+    intervention={"X1": x1_new, "X2": x2_new},
+    outcome="Y"
+)
+```
+
+### Conditional Counterfactuals
+
+Given observed values:
+
+```python
+cf = agent.generate_counterfactuals(
+    intervention={"X": x_new},
+    outcome="Y",
+    observed={"X": x_old, "Y": y_old}
+)
+```
+
+## Counterfactual Computation
+
+For a structural equation $Y = f(X, Z, U_Y)$:
+
+1. **Abduction**: $U_Y = f^{-1}(X=x, Z=z, Y=y)$
+2. **Action**: Set $X = x'$
+3. **Prediction**: $Y_{x'} = f(X=x', Z=z, U_Y)$
+
+## Example
+
+```python
+# What if education was college instead of high school?
+counterfactuals = agent.generate_counterfactuals(
+    intervention={"education": "college"},
+    outcome="income",
+    observed={"education": "high_school", "income": 30000}
+)
+
+for cf in counterfactuals:
+    print(f"Expected income: ${cf.expected_outcome:,.2f}")
+    print(f"Confidence: {cf.confidence:.2f}")
+```
+
+## Next Steps
+
+- [Deterministic Simulation](deterministic-simulation.md) - Understand simulation
+- [Batch Prediction](batch-prediction.md) - Process multiple scenarios

docs/core/crcagent/deterministic-simulation.md

@@ -0,0 +1,78 @@
+# Deterministic Simulation
+
+CRCAAgent performs deterministic causal simulations using structural equations.
+
+## Overview
+
+Deterministic simulation uses known or estimated structural equations to compute causal effects mathematically, without relying on LLM inference.
+
+## Mathematical Foundation
+
+Given structural equations:
+
+$$V_i = f_i(Pa(V_i), U_i)$$
+
+For $i = 1, \ldots, n$, we can simulate the system by:
+
+1. Setting exogenous variables $U_i$
+2. Computing variables in topological order
+3. Propagating values through the graph
+
+## Basic Simulation
+
+```python
+# Simulate with specific variable values
+result = agent.simulate(
+    variables={
+        "education": 16,
+        "experience": 5
+    },
+    target="income"
+)
+```
+
+## Simulation Methods
+
+### Euler Method
+
+For differential equation systems:
+
+$$V_i(t+\Delta t) = V_i(t) + f_i(Pa(V_i(t)), U_i) \cdot \Delta t$$
+
+### Runge-Kutta 4th Order
+
+More accurate for complex systems:
+
+$$k_1 = f(t, V(t))$$
+$$k_2 = f(t + \Delta t/2, V(t) + k_1 \Delta t/2)$$
+$$k_3 = f(t + \Delta t/2, V(t) + k_2 \Delta t/2)$$
+$$k_4 = f(t + \Delta t, V(t) + k_3 \Delta t)$$
+$$V(t+\Delta t) = V(t) + \frac{\Delta t}{6}(k_1 + 2k_2 + 2k_3 + k_4)$$
+
+## Configuration
+
+```python
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    simulation_method="rk4",  # or "euler"
+    simulation_steps=100,
+    simulation_dt=0.01
+)
+```
+
+## Time-Series Simulation
+
+Simulate over time:
+
+```python
+time_series = agent.simulate_time_series(
+    initial_conditions={"X": 0, "Y": 0},
+    time_steps=100,
+    dt=0.1
+)
+```
+
+## Next Steps
+
+- [Counterfactuals](counterfactuals.md) - Generate counterfactual scenarios
+- [Optimization](optimization.md) - Optimize interventions

docs/core/crcagent/dual-mode-operation.md

@@ -0,0 +1,82 @@
+# Dual-Mode Operation
+
+CRCAAgent supports two operational modes: LLM-based analysis and deterministic simulation.
+
+## Modes
+
+### LLM Mode
+
+Uses large language models for causal reasoning and analysis. Suitable for:
+- Natural language understanding
+- Complex causal reasoning
+- Variable extraction
+- Qualitative analysis
+
+### Deterministic Mode
+
+Uses mathematical simulation for precise causal inference. Suitable for:
+- Quantitative analysis
+- Numerical simulations
+- Optimization
+- Batch processing
+
+## Mathematical Foundation
+
+### LLM Mode
+
+In LLM mode, the agent uses the LLM to infer causal relationships:
+
+$$P(Y | do(X=x), Z=z) \approx LLM(T, X, Y, Z)$$
+
+Where $T$ is the task description, and the LLM approximates the causal effect.
+
+### Deterministic Mode
+
+In deterministic mode, the agent uses structural equations:
+
+$$Y = f(X, Z, U_Y)$$
+
+Where $f$ is a known or estimated function, and $U_Y$ is an exogenous variable.
+
+## Mode Selection
+
+### Automatic Mode Selection
+
+```python
+agent = CRCAAgent(
+    model_name="gpt-4o-mini",
+    auto_mode_selection=True  # Automatically choose mode
+)
+```
+
+### Manual Mode Selection
+
+```python
+# LLM mode
+result_llm = agent.run(task, mode="llm")
+
+# Deterministic mode
+result_det = agent.run(task, mode="deterministic")
+```
+
+## Hybrid Approach
+
+Combine both modes:
+
+```python
+# Use LLM for extraction
+agent.run(task, mode="llm")
+
+# Switch to deterministic for simulation
+simulation = agent.simulate(variables, mode="deterministic")
+```
+
+## Performance Considerations
+
+- **LLM Mode**: Slower but more flexible, handles complex reasoning
+- **Deterministic Mode**: Faster, precise, requires known structural equations
+
+## Next Steps
+
+- [Deterministic Simulation](deterministic-simulation.md) - Learn about simulations
+- [Causal Graph](causal-graph.md) - Understand graph operations