counterfact 0.1.0__tar.gz

counterfact-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Rudraneel Das
+
+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.

counterfact-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: counterfact
+Version: 0.1.0
+Summary: Did your change really work? Causal effect of a price change, campaign or policy on any time series.
+Project-URL: Homepage, https://counterfact-site.vercel.app
+Project-URL: Open model, https://huggingface.co/Rudraneel93/counterfact-v2
+Author: Rudraneel Das
+License-Expression: MIT
+License-File: LICENSE
+Keywords: causal impact,causal inference,counterfactual,marketing measurement,pricing,time series
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.3; extra == 'pandas'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.5; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# counterfact
+
+**Did your change really work?** Measure the real effect of a price change, campaign, launch or policy on any time series. You get an honest likely range, and a plain "can't tell yet" when the data can't support a claim.
+
+```bash
+pip install counterfact            # add [pandas] and [plot] for DataFrames and charts
+```
+
+```python
+import pandas as pd
+from counterfact import Client
+
+cf = Client(api_key="YOUR_KEY")    # or set COUNTERFACT_API_KEY
+df = pd.read_csv("weekly_sales.csv")
+r = cf.analyze(df, metric="sales", change_at="2025-10-06", time_col="week",
+               comparisons=["sales_other_region", "category_sales"])
+print(r)
+# sales, change at 2025-10-06: WORKED
+#   effect per period: +40.9 (+9.5%)   likely range: +18.6 to +63.2
+#   checks: fake change dates flagged 0 of 3, verdict stable when dropping a comparison 3 of 3
+print(r.explanation)   # plain-language summary
+r.plot()               # needs matplotlib
+```
+
+## What you get back
+- `verdict`: "worked", "hurt" or "can't tell yet"
+- `effect` per period, `effect_percent`, `likely_range` (holds about 9 times in 10), `total_effect`
+- `quick_before_after`: the naive comparison, for contrast
+- `robustness`: fake-change-date checks and leave-one-comparison-out checks
+- `counterfactual`: what would most likely have happened without the change, period by period
+
+## Keys
+- **Counterfact Pro** (₹1,999/month) includes 2,000 API calls: [counterfact-site.vercel.app/#pricing](https://counterfact-site.vercel.app/#pricing). Your Pro access code is your API key. `cf.usage()` shows calls left.
+- **RapidAPI:** `Client(rapidapi_key="...")`, billed through RapidAPI.
+
+## How it works
+Counterfact is a transformer pretrained on millions of synthetic worlds where the true cause and effect is known, and calibrated on 1,200 real Indian and US data windows. An open research version is on Hugging Face: [Rudraneel93/counterfact-v2](https://huggingface.co/Rudraneel93/counterfact-v2).
+
+## Licence
+This client is MIT licensed. Use of the API is subject to the Counterfact terms.

counterfact-0.1.0/README.md

@@ -0,0 +1,40 @@
+# counterfact
+
+**Did your change really work?** Measure the real effect of a price change, campaign, launch or policy on any time series. You get an honest likely range, and a plain "can't tell yet" when the data can't support a claim.
+
+```bash
+pip install counterfact            # add [pandas] and [plot] for DataFrames and charts
+```
+
+```python
+import pandas as pd
+from counterfact import Client
+
+cf = Client(api_key="YOUR_KEY")    # or set COUNTERFACT_API_KEY
+df = pd.read_csv("weekly_sales.csv")
+r = cf.analyze(df, metric="sales", change_at="2025-10-06", time_col="week",
+               comparisons=["sales_other_region", "category_sales"])
+print(r)
+# sales, change at 2025-10-06: WORKED
+#   effect per period: +40.9 (+9.5%)   likely range: +18.6 to +63.2
+#   checks: fake change dates flagged 0 of 3, verdict stable when dropping a comparison 3 of 3
+print(r.explanation)   # plain-language summary
+r.plot()               # needs matplotlib
+```
+
+## What you get back
+- `verdict`: "worked", "hurt" or "can't tell yet"
+- `effect` per period, `effect_percent`, `likely_range` (holds about 9 times in 10), `total_effect`
+- `quick_before_after`: the naive comparison, for contrast
+- `robustness`: fake-change-date checks and leave-one-comparison-out checks
+- `counterfactual`: what would most likely have happened without the change, period by period
+
+## Keys
+- **Counterfact Pro** (₹1,999/month) includes 2,000 API calls: [counterfact-site.vercel.app/#pricing](https://counterfact-site.vercel.app/#pricing). Your Pro access code is your API key. `cf.usage()` shows calls left.
+- **RapidAPI:** `Client(rapidapi_key="...")`, billed through RapidAPI.
+
+## How it works
+Counterfact is a transformer pretrained on millions of synthetic worlds where the true cause and effect is known, and calibrated on 1,200 real Indian and US data windows. An open research version is on Hugging Face: [Rudraneel93/counterfact-v2](https://huggingface.co/Rudraneel93/counterfact-v2).
+
+## Licence
+This client is MIT licensed. Use of the API is subject to the Counterfact terms.

counterfact-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "counterfact"
+version = "0.1.0"
+description = "Did your change really work? Causal effect of a price change, campaign or policy on any time series."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Rudraneel Das" }]
+keywords = ["causal inference", "time series", "causal impact", "counterfactual", "marketing measurement", "pricing"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = []
+
+[project.optional-dependencies]
+pandas = ["pandas>=1.3"]
+plot = ["matplotlib>=3.5"]
+
+[project.urls]
+Homepage = "https://counterfact-site.vercel.app"
+"Open model" = "https://huggingface.co/Rudraneel93/counterfact-v2"

counterfact-0.1.0/src/counterfact/__init__.py

@@ -0,0 +1,11 @@
+"""Counterfact: did your change really work?
+
+    from counterfact import Client
+    cf = Client()                       # reads COUNTERFACT_API_KEY
+    r = cf.analyze(df, metric="sales", change_at="2025-10-06", time_col="week")
+    print(r)                            # verdict, effect, likely range, checks
+"""
+from .client import Client, CounterfactError, Result
+
+__all__ = ["Client", "Result", "CounterfactError"]
+__version__ = "0.1.0"

counterfact-0.1.0/src/counterfact/client.py

@@ -0,0 +1,146 @@
+"""Thin client for the Counterfact API (standard library only; pandas and matplotlib optional)."""
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any
+
+DEFAULT_URL = "https://mastyf-support--counterfact-api-api.us-east.modal.run"
+RAPIDAPI_HOST = "counterfact.p.rapidapi.com"
+
+
+class CounterfactError(Exception):
+    """Raised when the API refuses a request (bad input, missing or used-up key, ...)."""
+
+    def __init__(self, status: int, message: str):
+        super().__init__(f"[{status}] {message}")
+        self.status, self.message = status, message
+
+
+@dataclass
+class Result:
+    """The answer for one change. Effects are per period, in the metric's own units."""
+    metric: str
+    change_at: str
+    verdict: str                       # "worked" | "hurt" | "can't tell yet"
+    effect: float                      # per period
+    effect_percent: float | None
+    likely_range: tuple[float, float]  # holds about 9 times in 10
+    total_effect: float
+    chance_positive: float
+    quick_before_after: dict
+    robustness: dict
+    comparisons_used: list[str]
+    explanation: str
+    counterfactual: dict
+    raw: dict = field(repr=False, default_factory=dict)
+
+    @classmethod
+    def from_api(cls, d: dict) -> "Result":
+        s = d["summary"]
+        return cls(metric=s["metric"], change_at=s["change_at"], verdict=s["verdict"],
+                   effect=s["effect_per_period"], effect_percent=s["effect_percent"],
+                   likely_range=tuple(s["likely_range_per_period"]), total_effect=s["total_effect_over_period"],
+                   chance_positive=s["chance_effect_is_positive"], quick_before_after=s["quick_before_after"],
+                   robustness=s["robustness"], comparisons_used=s["comparisons_used"],
+                   explanation=d.get("explanation", ""), counterfactual=d.get("counterfactual", {}), raw=d)
+
+    def __str__(self) -> str:
+        pct = f" ({self.effect_percent:+.1f}%)" if self.effect_percent is not None else ""
+        lo, hi = self.likely_range
+        return (f"{self.metric}, change at {self.change_at}: {self.verdict.upper()}\n"
+                f"  effect per period: {self.effect:+,.3g}{pct}   likely range: {lo:+,.3g} to {hi:+,.3g}\n"
+                f"  checks: fake change dates flagged {self.robustness.get('fake_dates_flagged')}, "
+                f"verdict stable when dropping a comparison {self.robustness.get('verdict_stable_when_dropping')}")
+
+    def to_dict(self) -> dict:
+        return self.raw
+
+    def plot(self, ax=None):
+        """Plot what happened vs what would have happened anyway (needs matplotlib)."""
+        import matplotlib.pyplot as plt
+        cf = self.counterfactual
+        ax = ax or plt.subplots(figsize=(9, 4))[1]
+        x = list(range(len(cf["observed"])))
+        ax.plot(x, cf["observed"], color="#0891b2", lw=2, label="What happened")
+        ax.plot(x, cf["median"], "--", color="#7c5cff", lw=2, label="What would have happened anyway")
+        ax.fill_between(x, cf["lo90"], cf["hi90"], color="#7c5cff", alpha=0.18, label="Likely range")
+        step = max(1, len(x) // 8)
+        ax.set_xticks(x[::step], [str(v) for v in cf["index"][::step]], rotation=30, fontsize=8)
+        ax.set_title(f"{self.metric} after the change at {self.change_at}: {self.verdict}")
+        ax.legend(fontsize=8)
+        return ax
+
+
+class Client:
+    """Counterfact API client.
+
+    Client(api_key=...)            a Counterfact Pro key (or set COUNTERFACT_API_KEY)
+    Client(rapidapi_key=...)       a RapidAPI key (or set RAPIDAPI_KEY), billed through RapidAPI
+    """
+
+    def __init__(self, api_key: str | None = None, rapidapi_key: str | None = None,
+                 base_url: str | None = None, timeout: float = 120.0):
+        self.api_key = api_key or os.environ.get("COUNTERFACT_API_KEY")
+        self.rapidapi_key = rapidapi_key or os.environ.get("RAPIDAPI_KEY")
+        if self.rapidapi_key and not base_url:
+            base_url = f"https://{RAPIDAPI_HOST}"
+        self.base_url = (base_url or os.environ.get("COUNTERFACT_URL") or DEFAULT_URL).rstrip("/")
+        self.timeout = timeout
+        if not (self.api_key or self.rapidapi_key):
+            raise CounterfactError(401, "No key. Pass api_key=... (Counterfact Pro) or rapidapi_key=..., "
+                                        "or set COUNTERFACT_API_KEY. Get a key at https://counterfact-site.vercel.app/#pricing")
+
+    def _headers(self) -> dict:
+        h = {"content-type": "application/json", "user-agent": "counterfact-python/0.1.0"}
+        if self.rapidapi_key:
+            h.update({"x-rapidapi-key": self.rapidapi_key, "x-rapidapi-host": RAPIDAPI_HOST})
+        else:
+            h["x-api-key"] = self.api_key
+        return h
+
+    def _call(self, method: str, path: str, body: Any = None) -> dict:
+        data = None if body is None else json.dumps(body).encode()
+        req = urllib.request.Request(self.base_url + path, data=data, method=method, headers=self._headers())
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                return json.loads(r.read())
+        except urllib.error.HTTPError as e:
+            try:
+                msg = json.loads(e.read()).get("detail", e.reason)
+            except Exception:
+                msg = str(e.reason)
+            raise CounterfactError(e.code, str(msg)) from None
+
+    def analyze(self, data, metric: str, change_at, comparisons: list[str] | None = None,
+                time_col: str | None = None, changed_column: str = "") -> Result:
+        """Measure the effect of a change on `metric`.
+
+        data:        a pandas DataFrame (rows in time order) or a dict {name: list of numbers}
+        change_at:   first period after the change: a value from `time_col`, or a 1-based row number
+        comparisons: columns the change could NOT have affected (default: every other numeric column)
+        time_col:    optional column with dates or period labels
+        """
+        index = None
+        if hasattr(data, "to_dict") and hasattr(data, "columns"):        # pandas DataFrame
+            df = data
+            if time_col:
+                index = [str(v) for v in df[time_col].tolist()]
+            series = {str(c): [float(v) for v in df[c].tolist()] for c in df.columns
+                      if c != time_col and str(df[c].dtype)[:3] in ("int", "flo", "uin")}
+        else:
+            series = {str(k): [float(v) for v in vals] for k, vals in dict(data).items() if k != time_col}
+            if time_col and time_col in dict(data):
+                index = [str(v) for v in dict(data)[time_col]]
+        if metric not in series:
+            raise CounterfactError(400, f"No numeric column named {metric!r}. Available: {', '.join(series)}")
+        body = {"series": series, "metric": metric, "change_at": str(change_at),
+                "comparisons": comparisons, "changed_column": changed_column, "index": index}
+        return Result.from_api(self._call("POST", "/v2/analyze", body))
+
+    def usage(self) -> dict:
+        """Plan, expiry and API calls left on a Counterfact Pro key."""
+        return self._call("GET", "/v2/usage")

counterfact-0.1.0/tests/test_client.py

@@ -0,0 +1,45 @@
+import json, threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+import pytest
+
+from counterfact import Client, CounterfactError
+
+SUMMARY = {"metric": "sales", "change_at": "W81", "verdict": "worked", "effect_per_period": 40.9, "effect_percent": 9.5,
+           "likely_range_per_period": [18.6, 63.2], "total_effect_over_period": 982.0, "chance_effect_is_positive": 0.99,
+           "quick_before_after": {"difference": 52.1}, "comparisons_used": ["b"],
+           "robustness": {"fake_dates_flagged": "0 of 3", "verdict_stable_when_dropping": "n/a"}}
+
+
+class H(BaseHTTPRequestHandler):
+    def log_message(self, *a): pass
+    def do_POST(self):
+        body = json.loads(self.rfile.read(int(self.headers["content-length"])))
+        if self.headers.get("x-api-key") != "good":
+            self.send_response(403); self.end_headers(); self.wfile.write(b'{"detail":"That access code isn\'t valid."}'); return
+        assert body["metric"] == "sales" and body["index"][0] == "W1" and "week" not in body["series"]
+        self.send_response(200); self.end_headers()
+        self.wfile.write(json.dumps({"summary": SUMMARY, "explanation": "It worked.", "counterfactual": {}}).encode())
+
+
+@pytest.fixture
+def server():
+    s = HTTPServer(("127.0.0.1", 0), H)
+    threading.Thread(target=s.serve_forever, daemon=True).start()
+    yield f"http://127.0.0.1:{s.server_port}"
+    s.shutdown()
+
+
+def test_analyze_dict_and_errors(server):
+    data = {"week": [f"W{i}" for i in range(1, 21)], "sales": list(range(20)), "b": list(range(20))}
+    r = Client(api_key="good", base_url=server).analyze(data, metric="sales", change_at="W15", time_col="week")
+    assert r.verdict == "worked" and r.likely_range == (18.6, 63.2) and "WORKED" in str(r)
+    with pytest.raises(CounterfactError) as e:
+        Client(api_key="bad", base_url=server).analyze(data, metric="sales", change_at="W15", time_col="week")
+    assert e.value.status == 403 and "isn't valid" in e.value.message
+
+
+def test_requires_key(monkeypatch):
+    monkeypatch.delenv("COUNTERFACT_API_KEY", raising=False); monkeypatch.delenv("RAPIDAPI_KEY", raising=False)
+    with pytest.raises(CounterfactError):
+        Client()