Metadata-Version: 2.4
Name: econcausal
Version: 0.2.0
Summary: SDK for EconCausalAI - Causal Discovery and Economic Simulation with Bootstrap Uncertainty
Author-email: Karthik <karthik@econcausal.ai>
Project-URL: Homepage, https://github.com/econcausal/econcausal-sdk
Keywords: causal-inference,economics,agent-based-modeling,policy-analysis,simulation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: pandas>=1.5.0
Requires-Dist: numpy>=1.24.0

# 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
