econcausal 0.2.0

SDK for EconCausalAI - Causal Discovery and Economic Simulation with Bootstrap Uncertainty

EconCausalAI Python SDK

Production-ready SDK for causal discovery and economic policy simulation with bootstrap uncertainty quantification.

Features

✅ Causal Discovery - Discover cause-effect relationships from economic data ✅ Bootstrap Uncertainty - Get confidence intervals for all causal relationships ✅ Agent-Based Simulation - Simulate policy impacts with 1000+ micro agents ✅ Policy Optimization - Find optimal policies using RL ✅ 2930+ Curated Datasets - Access pre-processed economic data

Installation

pip install econcausal

Quick Start

Causal Discovery with Confidence Intervals

from econcausal import EconCausalClient
import pandas as pd

# Initialize client
client = EconCausalClient(
    base_url="http://localhost:8001/api/v1"  # Or your production URL
)

# Load your data
data = pd.read_csv("economic_data.csv")

# Discover causal relationships WITH bootstrap confidence
result = client.causal.discover(
    data=data,
    algorithm="pc_algorithm",
    use_bootstrap=True,
    n_bootstrap=50  # 50 iterations for confidence intervals
)

# Each edge has confidence metrics
for edge in result['graph']['edges']:
    print(f"{edge['source']} → {edge['target']}")
    print(f"  Confidence: {edge.get('bootstrap_frequency', 'N/A'):.2f}")
    print(f"  95% CI: {edge.get('confidence_interval', 'N/A')}")

Policy Simulation

# Simulate interest rate policy
result = client.simulation.run(
    causal_graph=result['graph'],
    policy={
        "instrument": "interest_rate",
        "value": 0.08,  # 8% rate hike
        "time_horizon": 24
    },
    n_agents=2000,
    time_steps=24,
    initial_conditions={"inflation": 0.08, "unemployment": 0.04}
)

# Results include Central Bank + Government actions
print(f"Final inflation: {result['metrics']['inflation'][-1]:.2%}")
print(f"Final unemployment: {result['metrics']['unemployment'][-1]:.2%}")
print(f"Govt debt/GDP: {result['metrics']['government_debt_to_gdp'][-1]:.1%}")

API Reference

Causal Discovery

result = client.causal.discover(
    data: pd.DataFrame | List[Dict],
    algorithm: str = "pc_algorithm",  # or "notears"
    use_bootstrap: bool = False,
    n_bootstrap: int = 50
)

Returns graph with edges containing:

• bootstrap_frequency: How often edge appears (0-1)
• confidence_interval: [lower, upper] 95% CI
• weight: Edge strength

Data Validation

validation = client.causal.validate_data(data)
# Returns: is_valid, errors, warnings, statistics

Examples

See examples/ directory:

• quickstart.ipynb - Basic workflow
• bootstrap.ipynb - Confidence intervals
• simulation.ipynb - Policy analysis

Requirements

• Python 3.8+
• pandas, numpy, requests

License

MIT License

Changelog

v0.2.0 (2025-12-20)

✨ New: Bootstrap uncertainty, data validation, enhanced agents 🐛 Improved: Error handling, timeouts

v0.1.0 (2024-12-01)

• Initial release