causality-engine 1.0.0__tar.gz

causality_engine-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Causality Engine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

causality_engine-1.0.0/PKG-INFO

@@ -0,0 +1,216 @@
+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

causality_engine-1.0.0/README.md

@@ -0,0 +1,181 @@
+# 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

causality_engine-1.0.0/causality/__init__.py

@@ -0,0 +1,32 @@
+"""
+Alias module so ``import causality`` works.
+
+This re-exports everything from ``causality_engine`` for convenience,
+matching the documented usage pattern::
+
+    import causality
+    ce = causality.CausalityEngine(api_key="ce_live_sk_...")
+"""
+
+from causality_engine import *  # noqa: F401, F403
+from causality_engine import (
+    CausalityEngine,
+    CausalityEngineError,
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+    ValidationError,
+    APIResponse,
+    __version__,
+)
+
+__all__ = [
+    "CausalityEngine",
+    "CausalityEngineError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NotFoundError",
+    "ValidationError",
+    "APIResponse",
+    "__version__",
+]

causality_engine-1.0.0/causality_engine/__init__.py

@@ -0,0 +1,45 @@
+"""
+Causality Engine Python SDK
+============================
+
+Official Python client for the Causality Engine API.
+Causal attribution for e-commerce — replace last-click with math.
+
+Quick start::
+
+    import causality_engine as ce
+
+    client = ce.CausalityEngine(api_key="ce_live_sk_...")
+    result = client.attribution.analyze(
+        data_source_id="ds_abc123",
+        date_range=["2026-01-01", "2026-01-31"],
+    )
+    print(result.data["channel_impact"])
+
+Or use the top-level ``causality`` alias::
+
+    import causality
+    ce = causality.CausalityEngine(api_key="ce_live_sk_...")
+
+"""
+
+__version__ = "1.0.0"
+__all__ = [
+    "CausalityEngine",
+    "CausalityEngineError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NotFoundError",
+    "ValidationError",
+    "APIResponse",
+]
+
+from causality_engine.client import CausalityEngine
+from causality_engine.exceptions import (
+    CausalityEngineError,
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+    ValidationError,
+)
+from causality_engine.models import APIResponse

causality_engine-1.0.0/causality_engine/_http.py

@@ -0,0 +1,171 @@
+"""
+Low-level HTTP transport for the Causality Engine SDK.
+
+Handles authentication, retries with exponential backoff, and
+error-to-exception mapping. Uses httpx for both sync and async.
+"""
+
+from __future__ import annotations
+
+import time
+import logging
+from typing import Any, Dict, Optional, Union
+
+import httpx
+
+from causality_engine.exceptions import (
+    CausalityEngineError,
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+    ValidationError,
+    ServerError,
+)
+from causality_engine.models import APIResponse
+
+logger = logging.getLogger("causality_engine")
+
+DEFAULT_BASE_URL = "https://api.causalityengine.ai"
+DEFAULT_TIMEOUT = 30.0
+MAX_RETRIES = 3
+RETRY_BACKOFF = 0.5  # seconds, doubles each retry
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Map HTTP error codes to typed SDK exceptions."""
+    status = response.status_code
+    request_id = response.headers.get("x-request-id")
+
+    if status < 400:
+        return
+
+    try:
+        body = response.json()
+    except Exception:
+        body = {"error": response.text}
+
+    message = body.get("error", body.get("message", f"HTTP {status}"))
+    if isinstance(message, dict):
+        message = message.get("message", str(message))
+
+    kwargs = dict(
+        message=str(message),
+        status_code=status,
+        body=body,
+        request_id=request_id,
+    )
+
+    if status == 401:
+        raise AuthenticationError(**kwargs)
+    elif status == 404:
+        raise NotFoundError(**kwargs)
+    elif status == 422:
+        raise ValidationError(**kwargs)
+    elif status == 429:
+        retry_after = response.headers.get("retry-after")
+        raise RateLimitError(
+            retry_after=float(retry_after) if retry_after else None,
+            **kwargs,
+        )
+    elif status >= 500:
+        raise ServerError(**kwargs)
+    else:
+        raise CausalityEngineError(**kwargs)
+
+
+class Transport:
+    """Synchronous HTTP transport with retry logic."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = MAX_RETRIES,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": "causality-engine-python/1.0.0",
+                "Accept": "application/json",
+            },
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> APIResponse:
+        """Execute an HTTP request with automatic retries on 429/5xx."""
+        last_exc: Optional[Exception] = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self._client.request(
+                    method,
+                    path,
+                    json=json,
+                    params=_clean_params(params),
+                )
+                _raise_for_status(response)
+
+                data = response.json() if response.content else {}
+                return APIResponse(
+                    data=data,
+                    status_code=response.status_code,
+                    request_id=response.headers.get("x-request-id"),
+                    headers=dict(response.headers),
+                )
+
+            except (RateLimitError, ServerError) as exc:
+                last_exc = exc
+                if attempt < self.max_retries:
+                    wait = getattr(exc, "retry_after", None)
+                    if wait is None:
+                        wait = RETRY_BACKOFF * (2 ** attempt)
+                    logger.warning(
+                        "Retrying %s %s (attempt %d/%d, wait %.1fs): %s",
+                        method, path, attempt + 1, self.max_retries, wait, exc,
+                    )
+                    time.sleep(wait)
+                else:
+                    raise
+
+            except httpx.TransportError as exc:
+                last_exc = exc
+                if attempt < self.max_retries:
+                    wait = RETRY_BACKOFF * (2 ** attempt)
+                    logger.warning(
+                        "Transport error on %s %s (attempt %d/%d): %s",
+                        method, path, attempt + 1, self.max_retries, exc,
+                    )
+                    time.sleep(wait)
+                else:
+                    raise CausalityEngineError(
+                        message=f"Transport error after {self.max_retries} retries: {exc}",
+                    ) from exc
+
+        # Should not reach here, but just in case
+        raise CausalityEngineError(
+            message=f"Request failed after {self.max_retries} retries",
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+
+def _clean_params(params: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    """Remove None values from query parameters."""
+    if params is None:
+        return None
+    return {k: v for k, v in params.items() if v is not None}