| --- |
| tags: |
| - causal-discovery |
| - time-series |
| - temporal-causal |
| - prior-fitted-network |
| license: cc-by-nc-4.0 |
| license_link: LICENSE |
| --- |
| |
| # Ceptron |
|
|
| Open foundation models, one family per folder under `models/`, served by the `ceptron` Python package (one |
| sub-package per family). |
|
|
| | family | answers | |
| |---|---| |
| | `temporal_causal` | which variables of a time series cause which, at which lag, in one forward pass (built on TCPFN) | |
|
|
| ## Use |
|
|
| Install into a virtual environment (Python 3.10 or newer). Ubuntu, Debian and Homebrew Python refuse a plain |
| `pip install` outside one: |
|
|
| ``` |
| python3 -m venv ceptron-env |
| source ceptron-env/bin/activate # Windows: ceptron-env\Scripts\activate |
| pip install "git+https://github.com/ProfitOpsAI/ceptron" pandas |
| ``` |
|
|
| On Ubuntu or Debian, if `python3 -m venv` says ensurepip is not available, run `sudo apt install python3-venv` first. |
| Or with [uv](https://docs.astral.sh/uv/), which needs no system packages: |
|
|
| ``` |
| uv venv ceptron-env |
| source ceptron-env/bin/activate |
| uv pip install "git+https://github.com/ProfitOpsAI/ceptron" pandas |
| ``` |
|
|
| Then run `python` in that environment and paste this, or save it as `quickstart.py` and run `python quickstart.py`. |
| It builds a small series with two planted causes and asks the model to find them; the first run downloads the model (about 260 MB): |
|
|
| ```python |
| import numpy as np |
| import pandas as pd |
| from ceptron.temporal_causal import CausalModel |
| |
| # A toy series with two planted causes: price drives demand 2 steps later, ads drive visits 3 steps later. |
| rng = np.random.default_rng(0) |
| T = 400 |
| x = np.zeros((T, 4)) |
| noise = rng.normal(size=(T, 4)) |
| for t in range(3, T): |
| x[t] = 0.4 * x[t - 1] + noise[t] |
| x[t, 1] += 0.9 * x[t - 2, 0] # price -> demand, lag 2 |
| x[t, 3] += 0.8 * x[t - 3, 2] # ads -> visits, lag 3 |
| df = pd.DataFrame(x, columns=["price", "demand", "ads", "visits"]) |
| |
| model = CausalModel.from_pretrained("ProfitOpsAI/ceptron", model="XS-discovery") |
| result = model.discover(df) |
| print(result) |
| ``` |
|
|
| You should see (the last digit can differ on other hardware): |
|
|
| ``` |
| Discovery: 3 edges over 4 variables (graph head logit +22.53) |
| ads -> visits lag 3 p 0.79 |
| price -> demand lag 2 p 0.76 |
| demand -> price lag 23 p 0.28 |
| ``` |
|
|
| Both planted causes come first, with the right lags. The third, much weaker link is a false alarm: XS marks as many |
| links as its probabilities add up to, and on very small graphs that count tends to be one too many, so read the |
| probabilities, not only the list. |
|
|
| On your own data, one column per variable and one row per time step (drop the timestamp column): |
|
|
| ```python |
| df = pd.read_csv("my_series.csv").drop(columns=["timestamp"]) |
| result = model.discover(df, col_types={"orders": "count"}) # declare count, binary, ordinal, bounded columns |
| print(result) |
| result.to_frame() # the marked links as a DataFrame |
| ``` |
|
|
| For an irregular clock, pass `time_gap`: the gap before each row, in steps of the regular clock. |
|
|
| ## Models |
|
|
| Each model folder holds its own card, `config.json` and `model.safetensors`. |
|
|
| | family | model | parameters | weights sha256 | |
| |---|---|---:|---| |
| | temporal_causal | [XS-discovery](models/temporal_causal/XS-discovery/README.md) | 65.5 M | `3366c5844caa4fb1...` | |
| |
| ## Sizes |
| |
| Each family comes in sizes. **XS is available now**; **S, M and L are coming soon**. XS trades accuracy for speed: |
| it is the fast first look. For higher precision, recall and F1, harder series and more of the causal questions the |
| models answer natively, use S, M and L, coming soon; each release publishes its own measured numbers, so you can pick |
| the size by the accuracy you need. |
| |
| | size | status | good for | |
| |---|---|---| |
| | XS | available: [`XS-discovery`](models/temporal_causal/XS-discovery/README.md) | a fast first causal map of a time series in seconds on a CPU or a fraction of a second on a GPU (100 columns × 400 rows: 0.8 s CPU, 0.03 s GPU): which variables drive which, and after how many steps. Strongest on process/operations and retail/demand series (AUROC 94 % and 88 % on our development set). [What XS is good for](models/temporal_causal/XS-discovery/README.md#what-xs-is-good-for) | |
| | S | coming soon | higher precision, recall and F1 than XS; harder series | |
| | M | coming soon | higher precision, recall and F1 than XS; harder series | |
| | L | coming soon | higher precision, recall and F1 than XS; harder series | |
| |
| ## License |
| |
| The model weights, configurations and cards in this repository are licensed under |
| [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/) (see `LICENSE`): anyone may use, study, modify and |
| share them for non-commercial purposes, including research, teaching and personal projects. Commercial use of the |
| models needs a separate license from ProfitOps Inc. The `ceptron` code on GitHub is |
| [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). |
| |
