econcausal 0.2.0
SDK for EconCausalAI - Causal Discovery and Economic Simulation with Bootstrap Uncertainty
Requires Python: >=3.8
Keywords: causal-inference, economics, agent-based-modeling, policy-analysis, simulation

# EconCausalAI Python SDK

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

[![PyPI version](https://badge.fury.io/py/econcausal.svg)](https://badge.fury.io/py/econcausal)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

## 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

```bash
pip install econcausal
```

## Quick Start

### Causal Discovery with Confidence Intervals

```python
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

```python
# 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

```python
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

```python
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