Metadata-Version: 2.4
Name: tcpfn
Version: 2.1.0
Summary: Temporal Causal Prior-Data Fitted Networks — zero-shot causal discovery and effect estimation for time series
Author-email: "ProfitOps Inc." <hello@profitops.ai>
License: Proprietary
Project-URL: Homepage, https://profitops.ai
Project-URL: Documentation, https://huggingface.co/ProfitOpsAI/tcpfn
Keywords: causal-inference,time-series,foundation-model,causal-discovery,treatment-effect
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0
Requires-Dist: numpy>=1.24
Requires-Dist: scikit-learn>=1.3
Requires-Dist: faiss-cpu>=1.7
Requires-Dist: huggingface-hub>=0.19
Requires-Dist: pandas>=2.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# TCPFN

**Temporal Causal Prior-Data Fitted Networks** -- zero-shot causal discovery and effect estimation for time series.

A foundation model that discovers causal relationships in multivariate time series data without per-dataset training. One pretrained model handles industrial processes, biological networks, environmental systems, and more.

## Installation

```bash
pip install tcpfn
```

## Setup (one-time)

TCPFN model weights are hosted on HuggingFace (private repo). To access:

1. **Request access** at [huggingface.co/ProfitOpsAI/tcpfn](https://huggingface.co/ProfitOpsAI/tcpfn)
2. **Create a token** at [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) (Read access)
3. **Set the token:**
```bash
export HF_TOKEN=hf_your_token_here

# Or add to your shell profile:
echo 'export HF_TOKEN=hf_your_token_here' >> ~/.bashrc
```

The model (~259 MB) downloads automatically on first use and is cached at `~/.cache/tcpfn/`.

## Quick Start

```python
from tcpfn import discover

# Discover causal structure (auto-downloads model on first use)
edges = discover("sensor_data.csv")
for e in edges[:10]:
    print(f"  {e['cause']} -> {e['effect']}  strength={e['strength']:.3f}")
```

## Causal Discovery

```python
from tcpfn import TemporalCausalDiscovery
import numpy as np

data = np.load("sensors.npy")  # shape: (timesteps, variables)

disc = TemporalCausalDiscovery(device="cuda:0")  # or "cpu", "mps"
adj = disc.discover(data)  # (V, V) adjacency matrix

edges = disc.get_edges(data, threshold=0.1,
    variable_names=["temp", "pressure", "flow", "quality"])
```

## Effect Estimation

```python
from tcpfn import TemporalCATEEstimator

est = TemporalCATEEstimator(device="cuda:0")
est.fit(X_train, treatment, Y_pre, Y_post)

# Treatment effect trajectory
cate = est.estimate_cate(X_test, Y_pre_test)  # (N, T_post)

# With confidence intervals
result = est.estimate_cate_ci(X_test, Y_pre_test, alpha=0.05)
```

## Full Analysis (CLI)

```bash
# Causal discovery
tcpfn discover sensor_data.csv -o graph.json

# Root cause analysis
tcpfn explain sensor_data.csv \
    --target "temperature" --event-time "2025-11-15 14:15" \
    -o rca.json
```

## Key Features

- **Zero-shot**: no training needed per dataset
- **Temporal**: handles delayed, decaying, oscillating causal effects
- **Judgment signals**: detects null effects, confounding, regime type
- **Anti-hallucination**: NullF1 0.94 -- model knows when NOT to predict
- **14 benchmarks**: tested on industrial, biological, environmental, dynamical systems

## Benchmark Results (v2.1)

| Dataset | AUROC | Domain |
|---|---|---|
| Tennessee Eastman (52 vars) | 0.904 | Industrial |
| Causal Rivers | 0.955 | Environmental |
| SWaT (51 vars) | 0.859 | Cyber-physical |
| Sachs (11 proteins) | 0.725 | Biological |

## Model Details

- Architecture: 12-layer transformer, 8 heads, 512 dim, 21.6M params
- Training: 200K steps on synthetic causal data (30M units)
- Hosted on HuggingFace: `ProfitOpsAI/tcpfn`
- Auto-downloaded on first use (~259 MB)

## License

Copyright 2026 ProfitOps Inc. All rights reserved. Proprietary.

Contact: hello@profitops.ai
