Metadata-Version: 2.4
Name: causality-engine
Version: 1.0.0
Summary: Official Python SDK for the Causality Engine API — causal attribution for e-commerce.
Project-URL: Homepage, https://causalityengine.ai
Project-URL: Documentation, https://developers.causalityengine.ai
Project-URL: Repository, https://github.com/causalityengine/causality-engine-python-sdk
Project-URL: Bug Tracker, https://github.com/causalityengine/causality-engine-python-sdk/issues
Project-URL: API Reference, https://developers.causalityengine.ai/api-reference
Author-email: Causality Engine <dev@causalityengine.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: analytics,attribution,causal-inference,causality,ecommerce,marketing,marketing-attribution,shopify
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: httpx<1.0.0,>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Description-Content-Type: text/markdown

# Causality Engine Python SDK

The official Python SDK for the [Causality Engine](https://causalityengine.ai) API — causal attribution for e-commerce. Replace last-click with math.

[![PyPI version](https://img.shields.io/pypi/v/causality-engine.svg)](https://pypi.org/project/causality-engine/)
[![Python 3.8+](https://img.shields.io/pypi/pyversions/causality-engine.svg)](https://pypi.org/project/causality-engine/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
pip install causality-engine
```

## Quick Start

```python
import causality

ce = causality.CausalityEngine(api_key="ce_live_sk_...")

# Run causal attribution analysis
result = ce.attribution.analyze(
    store="my-store.myshopify.com",
    date_range=["2026-01-01", "2026-01-31"],
)

for ch in result.data["channel_impact"]:
    print(f"{ch['channel']}: {ch['causal_lift']:.0%} lift, ROI {ch['roi']:.1f}x")
```

## Authentication

Get your API key at [developers.causalityengine.ai/api-keys](https://developers.causalityengine.ai/api-keys).

```python
# Option 1: Pass directly
ce = causality.CausalityEngine(api_key="ce_live_sk_...")

# Option 2: Environment variable
# export CAUSALITY_ENGINE_API_KEY="ce_live_sk_..."
ce = causality.CausalityEngine()
```

## API Coverage

| Resource | Methods | Description |
|---|---|---|
| `ce.attribution` | `analyze()`, `retrieve()`, `list()` | Causal attribution analysis |
| `ce.channels` | `performance()`, `amplification()` | Cross-channel performance |
| `ce.journeys` | `flow()`, `leakage()` | Customer journey mapping |
| `ce.campaigns` | `overview()` | Campaign-level intelligence |
| `ce.health` | `score()` | Marketing health diagnostics |
| `ce.brand` | `decompose()` | Brand awareness decomposition |
| `ce.agents` | `register()`, `me()`, `usage()` | AI agent management |
| `ce.referrals` | `list()` | Referral chain tracking |
| `ce.commissions` | `list()`, `verify()` | Commission ledger |
| `ce.billing` | `summary()`, `value_proofs()` | Billing & Delta_R tracking |
| `ce.auth` | `token()`, `rotate_key()` | OAuth & key management |

## Examples

### Channel Performance

```python
perf = ce.channels.performance(
    data_source_id="ds_abc123",
    date_range=["2026-01-01", "2026-01-31"],
)
for ch in perf.data["channels"]:
    print(f"{ch['name']}: score {ch['performance_score']}")
```

### Cross-Channel Amplification

```python
amp = ce.channels.amplification(
    data_source_id="ds_abc123",
    date_range=["2026-01-01", "2026-01-31"],
)
print(f"Strongest pair: {amp.data['strongest_pair']}")
print(f"Total synergy: {amp.data['total_synergy_score']}")
```

### Customer Journey Flow

```python
flow = ce.journeys.flow(
    data_source_id="ds_abc123",
    date_range=["2026-01-01", "2026-01-31"],
    min_conversions=10,
)
for path in flow.data["top_paths"]:
    print(f"{' → '.join(path['path'])}: {path['conversions']} conversions")
```

### Register an AI Agent

```python
agent = ce.agents.register(
    name="my-attribution-agent",
    operator_email="dev@yourcompany.com",
    capabilities=["attribution", "channel_analysis"],
)
print(f"Agent ID: {agent.data['agent_id']}")
print(f"Referral code: {agent.data['referral_code']}")
```

### Marketing Health Score

```python
health = ce.health.score(
    data_source_id="ds_abc123",
    date_range=["2026-01-01", "2026-01-31"],
)
print(f"Score: {health.data['score']}/100 (Grade: {health.data['grade']})")
print(f"Recommendation: {health.data['top_recommendation']}")
```

## Error Handling

```python
from causality_engine import (
    AuthenticationError,
    RateLimitError,
    NotFoundError,
    ValidationError,
    CausalityEngineError,
)

try:
    result = ce.attribution.analyze(
        data_source_id="ds_abc123",
        date_range=["2026-01-01", "2026-01-31"],
    )
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except NotFoundError:
    print("Resource not found")
except ValidationError as e:
    print(f"Invalid request: {e.message}")
except CausalityEngineError as e:
    print(f"API error: {e.message} (status {e.status_code})")
```

## Configuration

```python
ce = causality.CausalityEngine(
    api_key="ce_live_sk_...",
    base_url="https://api.causalityengine.ai",  # default
    timeout=30.0,       # request timeout in seconds
    max_retries=3,      # retries on 429/5xx errors
)
```

The SDK automatically retries on rate limits (429) and server errors (5xx) with exponential backoff.

## Context Manager

```python
with causality.CausalityEngine(api_key="ce_live_sk_...") as ce:
    result = ce.attribution.analyze(
        store="demo.myshopify.com",
        date_range=["2026-01-01", "2026-01-31"],
    )
# Transport is automatically closed
```

## Documentation

- [Developer Portal](https://developers.causalityengine.ai)
- [API Reference](https://developers.causalityengine.ai/api-reference)
- [Quickstart Guide](https://developers.causalityengine.ai/quickstart)
- [Agent Partner Program](https://developers.causalityengine.ai/agent-program)

## License

MIT
