causality-engine 1.0.0

Official Python SDK for the Causality Engine API — causal attribution for e-commerce.

Causality Engine Python SDK

The official Python SDK for the Causality Engine API — causal attribution for e-commerce. Replace last-click with math.

Installation

pip install causality-engine

Quick Start

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.

# 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

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

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

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

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

Marketing Health Score

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

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

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

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
• API Reference
• Quickstart Guide
• Agent Partner Program

License

MIT