rootcause-sdk 1.0.0__tar.gz

rootcause_sdk-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.env
+.venv/
+
+*.rctwin
+examples/*-executed.ipynb

rootcause_sdk-1.0.0/.gitlab-ci.yml

@@ -0,0 +1,65 @@
+stages:
+  - generate
+  - build
+  - publish
+
+variables:
+  PYTHON_IMAGE: python:3.12-slim
+
+generate:
+  stage: generate
+  image: $PYTHON_IMAGE
+  script:
+    - pip install openapi-python-client
+    - openapi-python-client generate --path $OPENAPI_SPEC_URL --output-path /tmp/gen --overwrite
+    - cp -r /tmp/gen/root_cause_public_api_client/* generated/
+  artifacts:
+    paths:
+      - generated/
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "trigger"
+    - if: $CI_PIPELINE_SOURCE == "web"
+
+build:
+  stage: build
+  image: $PYTHON_IMAGE
+  script:
+    # On a tag, the tag is the single source of truth for the version.
+    - |
+      if [ -n "$CI_COMMIT_TAG" ]; then
+        echo "Pinning version to tag $CI_COMMIT_TAG"
+        sed -i -E "s/^version = \".*\"/version = \"$CI_COMMIT_TAG\"/" pyproject.toml
+        grep -E '^version = ' pyproject.toml
+      fi
+    - pip install build twine
+    - python -m build
+    - twine check --strict dist/*
+    - ls -l dist/
+  artifacts:
+    paths:
+      - dist/
+    expire_in: 30 days
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^[0-9]+\.[0-9]+\.[0-9]+([ab]|rc)?[0-9]*$/
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+
+publish:
+  stage: publish
+  image: $PYTHON_IMAGE
+  needs:
+    - job: build
+      artifacts: true
+  environment:
+    name: pypi
+    url: https://pypi.org/project/rootcause-sdk/
+  variables:
+    TWINE_USERNAME: __token__
+    TWINE_PASSWORD: $PYPI_API_TOKEN
+    TWINE_REPOSITORY_URL: https://upload.pypi.org/legacy/
+  script:
+    - pip install twine
+    - twine check --strict dist/*
+    - twine upload --non-interactive --disable-progress-bar dist/*
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^[0-9]+\.[0-9]+\.[0-9]+([ab]|rc)?[0-9]*$/
+      when: manual

rootcause_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.5
+Name: rootcause-sdk
+Version: 1.0.0
+Summary: Official Python SDK for the RootCause causal AI platform
+Project-URL: Homepage, https://rootcause.ai
+Project-URL: Repository, https://gitlab.com/perceptura/sdks/rootcause-python
+Project-URL: Documentation, https://docs.rootcause.ai
+Author-email: RootCause <engineering@rootcause.ai>
+License: MIT
+Keywords: api-client,causal-inference,digital-twin,jupyter,rootcause,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pyarrow>=14.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: graph
+Requires-Dist: networkx>=3.0; extra == 'graph'
+Provides-Extra: jupyter
+Requires-Dist: anywidget>=0.9; extra == 'jupyter'
+Description-Content-Type: text/markdown
+
+# rootcause-sdk
+
+[RootCause](https://rootcause.ai) is a causal AI platform: bring your data, discover causal structure, train digital twins, and ask what-if questions. This is the official Python SDK. Full docs: [docs.rootcause.ai](https://docs.rootcause.ai).
+
+## Installation
+
+```bash
+pip install rootcause-sdk
+```
+
+## Quick start
+
+```python
+import rootcause as rc
+import pandas as pd
+
+rc.login()                                   # ROOTCAUSE_API_KEY, or browser login
+
+df = pd.read_csv("lalonde.csv")
+
+graph = rc.discover(df, target="re78")       # causal discovery on a DataFrame
+graph.pin("treat", "re78")                   # domain knowledge
+twin = graph.train()
+
+ate = twin.intervene({"treat": rc.set(1)}, where={"re75": ("<", 5000)})
+ate.summary
+```
+
+Nothing above mentions a workspace: direct mode keeps platform ceremony out of sight and reuses uploads by content hash.
+
+## Platform mode
+
+The same classes work against everything your team builds in the RootCause UI:
+
+```python
+ws = rc.workspace("Calix Forecasting")
+
+ws.sources["shipments"].to_frame()           # tab-completes live names
+ws.upload(df, name="shipments-v2")
+
+twin = ws.twin("C8 Temporal")                # trained by a colleague — just there
+fc = twin.forecast(horizon=24)
+fc.to_frame()                                # tidy long format, straight to pandas
+
+twin.ask("what happens to bookings if we cut trade shows entirely?")
+```
+
+## The power-user primitive
+
+Every simulation family is a wrapper over conditional sampling. The SDK exposes it raw:
+
+```python
+draws = twin.sample(n=10_000, do={"price": rc.pct(+10)}, where={"region": "FL"}, seed=42)
+draws.to_frame()                             # one row per joint posterior draw
+```
+
+Interventions: `rc.set(value)`, `rc.pct(+15)`, `rc.add(-5)`, `rc.prob("yes", 0.8)`, `rc.adjust_prob("yes", +10)`, `rc.members(include=[...], size=4)`. Bare values mean `rc.set`. Conditions: `{"region": "EMEA"}` or `{"re75": ("<", 5000)}`.
+
+## Ontology queries
+
+```python
+onto = ws.ontology
+onto.concepts
+
+result = onto.query(
+    select=["customer", "revenue"],
+    where=[("region", "==", "US")],
+    group_by=["customer"],
+    order_by="-revenue",
+    aggregate={"revenue": "sum"},
+)
+result.to_frame()
+
+onto.ask("average revenue per customer in Florida last quarter")
+```
+
+## Portable twins
+
+```python
+twin.save("c8.rctwin")                       # export zip with trained model params
+twin2 = rc.load_twin("c8.rctwin")            # later, anywhere, same auth
+```
+
+## Authentication
+
+`rc.login()` resolves credentials in order: explicit `api_key="pk_…"` → `ROOTCAUSE_API_KEY` / `ROOTCAUSE_BASE_URL` env vars → cached OAuth token in `~/.rootcause/` → interactive browser login (PKCE; remote kernels get a paste-the-code fallback). Create API keys under **Organisation → API** on your platform.
+
+## Releasing
+
+Publishing to PyPI is driven entirely by git tags. The tag is the version — `pyproject.toml`
+is patched in CI at build time, so don't bother bumping it by hand.
+
+1. Push a tag matching `MAJOR.MINOR.PATCH` (pre-releases like `1.2.0rc1` also work):
+
+   ```bash
+   git tag 0.2.0 && git push origin 0.2.0
+   ```
+
+2. The `build` job builds the sdist + wheel and runs `twine check --strict`.
+3. Trigger the `publish` job (manual) to release to PyPI.
+
+### Required CI variable
+
+Set as a **masked** and **protected** project-level variable in GitLab
+(Settings → CI/CD → Variables):
+
+| Variable         | Purpose                                             |
+| ---------------- | --------------------------------------------------- |
+| `PYPI_API_TOKEN` | PyPI API token (`pypi-...`), scoped to this project |
+
+It is passed to twine as the password with username `__token__`; nothing is
+hardcoded in the pipeline.
+
+## License
+
+MIT

rootcause_sdk-1.0.0/README.md

@@ -0,0 +1,116 @@
+# rootcause-sdk
+
+[RootCause](https://rootcause.ai) is a causal AI platform: bring your data, discover causal structure, train digital twins, and ask what-if questions. This is the official Python SDK. Full docs: [docs.rootcause.ai](https://docs.rootcause.ai).
+
+## Installation
+
+```bash
+pip install rootcause-sdk
+```
+
+## Quick start
+
+```python
+import rootcause as rc
+import pandas as pd
+
+rc.login()                                   # ROOTCAUSE_API_KEY, or browser login
+
+df = pd.read_csv("lalonde.csv")
+
+graph = rc.discover(df, target="re78")       # causal discovery on a DataFrame
+graph.pin("treat", "re78")                   # domain knowledge
+twin = graph.train()
+
+ate = twin.intervene({"treat": rc.set(1)}, where={"re75": ("<", 5000)})
+ate.summary
+```
+
+Nothing above mentions a workspace: direct mode keeps platform ceremony out of sight and reuses uploads by content hash.
+
+## Platform mode
+
+The same classes work against everything your team builds in the RootCause UI:
+
+```python
+ws = rc.workspace("Calix Forecasting")
+
+ws.sources["shipments"].to_frame()           # tab-completes live names
+ws.upload(df, name="shipments-v2")
+
+twin = ws.twin("C8 Temporal")                # trained by a colleague — just there
+fc = twin.forecast(horizon=24)
+fc.to_frame()                                # tidy long format, straight to pandas
+
+twin.ask("what happens to bookings if we cut trade shows entirely?")
+```
+
+## The power-user primitive
+
+Every simulation family is a wrapper over conditional sampling. The SDK exposes it raw:
+
+```python
+draws = twin.sample(n=10_000, do={"price": rc.pct(+10)}, where={"region": "FL"}, seed=42)
+draws.to_frame()                             # one row per joint posterior draw
+```
+
+Interventions: `rc.set(value)`, `rc.pct(+15)`, `rc.add(-5)`, `rc.prob("yes", 0.8)`, `rc.adjust_prob("yes", +10)`, `rc.members(include=[...], size=4)`. Bare values mean `rc.set`. Conditions: `{"region": "EMEA"}` or `{"re75": ("<", 5000)}`.
+
+## Ontology queries
+
+```python
+onto = ws.ontology
+onto.concepts
+
+result = onto.query(
+    select=["customer", "revenue"],
+    where=[("region", "==", "US")],
+    group_by=["customer"],
+    order_by="-revenue",
+    aggregate={"revenue": "sum"},
+)
+result.to_frame()
+
+onto.ask("average revenue per customer in Florida last quarter")
+```
+
+## Portable twins
+
+```python
+twin.save("c8.rctwin")                       # export zip with trained model params
+twin2 = rc.load_twin("c8.rctwin")            # later, anywhere, same auth
+```
+
+## Authentication
+
+`rc.login()` resolves credentials in order: explicit `api_key="pk_…"` → `ROOTCAUSE_API_KEY` / `ROOTCAUSE_BASE_URL` env vars → cached OAuth token in `~/.rootcause/` → interactive browser login (PKCE; remote kernels get a paste-the-code fallback). Create API keys under **Organisation → API** on your platform.
+
+## Releasing
+
+Publishing to PyPI is driven entirely by git tags. The tag is the version — `pyproject.toml`
+is patched in CI at build time, so don't bother bumping it by hand.
+
+1. Push a tag matching `MAJOR.MINOR.PATCH` (pre-releases like `1.2.0rc1` also work):
+
+   ```bash
+   git tag 0.2.0 && git push origin 0.2.0
+   ```
+
+2. The `build` job builds the sdist + wheel and runs `twine check --strict`.
+3. Trigger the `publish` job (manual) to release to PyPI.
+
+### Required CI variable
+
+Set as a **masked** and **protected** project-level variable in GitLab
+(Settings → CI/CD → Variables):
+
+| Variable         | Purpose                                             |
+| ---------------- | --------------------------------------------------- |
+| `PYPI_API_TOKEN` | PyPI API token (`pypi-...`), scoped to this project |
+
+It is passed to twine as the password with username `__token__`; nothing is
+hardcoded in the pipeline.
+
+## License
+
+MIT

rootcause_sdk-1.0.0/examples/.ipynb_checkpoints/temporal-panel-checkpoint.ipynb

@@ -0,0 +1,296 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Temporal and panel twins\n",
+    "\n",
+    "Time series and multi-environment (panel) data get their own twin kinds with their own machinery:\n",
+    "lagged dependencies, latent influence detection, per-environment models, forecasts with\n",
+    "attribution, and interventions that are scheduled in time. This notebook runs all of it live.\n",
+    "\n",
+    "| Kind | Kwargs | What it models |\n",
+    "| --- | --- | --- |\n",
+    "| `temporal` | `time=` | one time series with lagged causal structure |\n",
+    "| `multi-environment-static` | `entity=` | the same system observed across environments |\n",
+    "| `multi-environment-temporal` | `time=` + `entity=` | a panel: many environments, each a time series |"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "import numpy as np\n",
+    "import pandas as pd\n",
+    "\n",
+    "import rootcause as rc\n",
+    "\n",
+    "rc.login(base_url=os.environ.get(\"ROOTCAUSE_BASE_URL\", \"https://platform.rootcause.ai\"))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## A panel: three stores, thirty months\n",
+    "\n",
+    "Ground truth: price suppresses demand, demand carries momentum (a lag), seasonality moves both,\n",
+    "and each store runs at its own scale. Long format: one row per store per month."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rng = np.random.default_rng(11)\n",
+    "months = pd.date_range(\"2024-01-01\", periods=30, freq=\"MS\")\n",
+    "stores = {\"london\": 1.0, \"paris\": 0.8, \"berlin\": 1.25}\n",
+    "rows = []\n",
+    "for store, scale in stores.items():\n",
+    "    demand_prev = 100.0 * scale\n",
+    "    for i, month in enumerate(months):\n",
+    "        season = 12 * np.sin(2 * np.pi * (i % 12) / 12)\n",
+    "        price = 20 + 2 * np.sin(2 * np.pi * (i % 12) / 12 + 1) + rng.normal(0, 0.5)\n",
+    "        demand = 0.55 * demand_prev + 60 * scale - 2.4 * price + season + rng.normal(0, 4)\n",
+    "        revenue = price * demand * 0.1 + rng.normal(0, 3)\n",
+    "        rows.append({\"month\": month.strftime(\"%Y-%m-%d\"), \"store\": store,\n",
+    "                     \"price\": round(price, 2), \"demand\": round(demand, 1), \"revenue\": round(revenue, 1)})\n",
+    "        demand_prev = demand\n",
+    "panel = pd.DataFrame(rows)\n",
+    "panel.head()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Discovery finds more than edges\n",
+    "\n",
+    "`time=` and `entity=` make this a panel-temporal twin. Note the graph: alongside the causal\n",
+    "edges, discovery surfaced a **latent influence**, a hidden common cause it detected in the data\n",
+    "but could not name, and it attributes the store-level differences to the environment itself."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "graph = rc.discover(panel, time=\"month\", entity=\"store\", force=True)\n",
+    "graph.edges"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "twin = graph.train()\n",
+    "twin"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Per-environment sampling\n",
+    "\n",
+    "Panel twins hold one model per environment. Sampling narrows with `environments=` and the\n",
+    "returned frame carries an `environment` column; seeds derive stable per-environment children,\n",
+    "so comparisons are deterministic."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "draws = twin.sample(n=500, environments=[\"london\", \"berlin\"], seed=3)\n",
+    "draws.to_frame().groupby(\"environment\").mean(numeric_only=True).round(1)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Forecasts carry their reasoning\n",
+    "\n",
+    "Each forecast step comes with bounds and an attribution: how much of the prediction is trend,\n",
+    "season, and each causal parent (with lags). `aggregate=\"sum\"` adds a combined series across\n",
+    "environments; `origin_timestamp` anchors backtests."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fc = twin.forecast(horizon=6, targets=[\"revenue\"], aggregate=\"sum\")\n",
+    "fc.to_frame()[[\"environment\", \"timestamp\", \"prediction\", \"lowerBound\", \"upperBound\"]].head(8).round(1)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fc.to_frame().loc[0, \"attribution\"]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Interventions scheduled in time\n",
+    "\n",
+    "`rc.at` wraps any intervention value with when it applies: `persistent=True` from the first\n",
+    "step onwards, `duration_steps=` for a limited window, `timestamp=` for a specific start.\n",
+    "Here: a permanent 10 percent price cut, in London only."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "result = twin.intervene(\n",
+    "    {\"price\": rc.at(rc.pct(-10), persistent=True)},\n",
+    "    outcomes=[\"revenue\"],\n",
+    "    environments=[\"london\"],\n",
+    ")\n",
+    "result"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Monthly refresh: assimilate instead of retrain\n",
+    "\n",
+    "When next month's rows arrive, the model doesn't need rebuilding — extend the twin's\n",
+    "source and fold the new rows into the fitted model with `update()`. It finishes with a\n",
+    "status, never an error: `committed` (rows folded in), `up_to_date` (nothing new), or\n",
+    "`retrain_required` (the model can't take these rows incrementally — call `twin.retrain()`).\n",
+    "\n",
+    "Static and temporal twins assimilate out of the box. Panel twins need the v2 panel\n",
+    "engine (an opt-in in the twin builder); on anything else `update()` simply reports\n",
+    "`retrain_required`, and `twin.update_eligibility` tells you in advance. London's series\n",
+    "as its own temporal twin:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "london = panel[panel[\"store\"] == \"london\"][[\"month\", \"price\", \"demand\", \"revenue\"]].reset_index(drop=True)\n",
+    "monthly = rc.discover(london, time=\"month\", force=True).train()\n",
+    "monthly"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Two months pass. Extend the source with the new rows and update — the transcript is\n",
+    "the whole loop:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "source = monthly.source\n",
+    "current = source.to_frame()\n",
+    "last_month = pd.to_datetime(current[\"month\"]).max()\n",
+    "demand_prev = current.sort_values(\"month\")[\"demand\"].iloc[-1]\n",
+    "\n",
+    "rows = []\n",
+    "for month in pd.date_range(last_month + pd.offsets.MonthBegin(1), periods=2, freq=\"MS\"):\n",
+    "    j = (month.year - 2024) * 12 + (month.month - 1)\n",
+    "    season = 12 * np.sin(2 * np.pi * (j % 12) / 12)\n",
+    "    price = 20 + 2 * np.sin(2 * np.pi * (j % 12) / 12 + 1) + rng.normal(0, 0.5)\n",
+    "    demand = 0.55 * demand_prev + 60 - 2.4 * price + season + rng.normal(0, 4)\n",
+    "    rows.append({\"month\": month.strftime(\"%Y-%m-%d\"),\n",
+    "                 \"price\": round(price, 2), \"demand\": round(demand, 1),\n",
+    "                 \"revenue\": round(price * demand * 0.1 + rng.normal(0, 3), 1)})\n",
+    "    demand_prev = demand\n",
+    "\n",
+    "source.extend(pd.DataFrame(rows))\n",
+    "result = monthly.update()\n",
+    "result"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Running it again with nothing new in the source is how a scheduled job stays honest —\n",
+    "the second call is a cheap no-op:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "monthly.update()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The refreshed model forecasts onwards from the assimilated months:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "fc = monthly.forecast(horizon=3, targets=[\"revenue\"])\n",
+    "fc.to_frame()[[\"timestamp\", \"prediction\", \"lowerBound\", \"upperBound\"]].round(1)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The same scheduling works on plain temporal twins, and everything else from the\n",
+    "[quickstart](quickstart.ipynb) applies unchanged: `save`, `load_twin`, `console`, and the\n",
+    "ontology all understand temporal and panel twins."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}