Metadata-Version: 2.4
Name: predictnow-cai
Version: 0.1.0
Summary: Python client for PredictNow Corrective AI — regime-gated exposure overlays on a trading strategy's returns.
Author-email: PredictNow <support@predictnow.ai>
License: Proprietary
Project-URL: Homepage, https://predictnow.ai
Project-URL: Documentation, https://portal.predictnow.ai/#/docs
Project-URL: Repository, https://github.com/ruchir-lab/CAI-API
Keywords: quant,trading,machine-learning,corrective-ai,regime,backtest,quantconnect
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Office/Business :: Financial :: Investment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Provides-Extra: pandas
Requires-Dist: pandas>=1.5; extra == "pandas"

# predictnow-cai — Python client

Run PredictNow **Corrective AI (CAI)** on a strategy's return series from Python — the same thing the
web portal does, programmatically. CAI learns the regimes where a strategy's edge is real and returns
a **point-in-time exposure series** you can apply in a backtest or live (walk-forward, no lookahead).
The model runs server-side; this client only sends returns and reads results.

## Install

```bash
pip install predictnow-cai          # core client
pip install "predictnow-cai[pandas]" # + pandas convenience (DataFrame in, Series out)
```

## Quickstart

```python
from predictnow import Client
import pandas as pd

# 1. authenticate with an API key (generate one on the portal's "API keys" page).
#    A key is revocable and safe to store as a secret — the right thing for a LEAN
#    algorithm or a scheduled job. (Notebooks can use cai.login(email, password) instead.)
cai = Client("https://portal.predictnow.ai", api_key="pn_...")

# 2. create a project
project = cai.create_project("My Momentum Book", asset_class="US equity")

# 3. run CAI on a return series (DataFrame with Date + return columns, a CSV path, or bytes)
returns = pd.read_csv("daily_returns.csv")      # columns: Date, return
run = cai.run(project["id"], returns=returns, version="v1", recipe="auto", wait=True,
              on_progress=lambda stage, pct: print(f"{pct:>3}%  {stage}"))

# 4. read the result
print(run.verdict)                 # 'valid' or 'null' (honest — no fabricated lift)
print(run.metrics)                 # {'original': {...}, 'cai': {...}}  Sharpe/return/vol/drawdown
res = run.result                   # full dict: profile, recipe, attribution, curves, signal

# 5. get the execution signal — point-in-time exposure per date
exposure = run.exposure()          # pandas Series (date -> exposure in [0,1]) if pandas installed
# apply in your own execution loop: position = intended_position * exposure.loc[today]
```

## Recipes (per-strategy tuning)

`recipe="auto"` classifies the strategy and picks a feature set. You can also select a specific
recipe/rule for a tuned version (e.g. the Estee wins):

```python
print(cai.recipes())               # {'auto', 'trend', 'mean_reversion', ..., 'own_momentum', 'usdinr_regime'}

# v1 = generic, v2 = tuned rule
cai.run(pid, returns=r, version="v1", recipe="auto")
cai.run(pid, returns=r, version="v2", recipe="own_momentum")   # e.g. for a mean-reverting L/S book
```

## API surface

| Method | Does |
|---|---|
| `Client(base_url, token=None)` | create a client |
| `.signup(email, pw)` / `.login(email, pw)` | authenticate (stores the token) |
| `.create_project(name, asset_class=None)` | create a project |
| `.projects()` / `.delete_project(id)` | list / delete projects |
| `.recipes()` | available recipes/rules |
| `.run(project_id, returns, version, recipe, horizon=0, wait=True, on_progress=None)` | upload returns → run CAI → `CaiRun` |
| `.result(run_id)` / `.exposure(run_id)` | full result / exposure series |
| `.get_run(run_id)` / `.delete_run(run_id)` | run status / delete |

`CaiRun`: `.status`, `.wait()`, `.result`, `.metrics`, `.verdict`, `.exposure()`.

## Input & output format
- **Input:** a `date` column (any parseable format) + a `return` column of **decimal periodic
  returns** (e.g. `0.0125` = +1.25%), one row per period. Price/NAV series and percentage-scale
  inputs are auto-detected and converted — every assumption is reported in `result["input_notes"]`.
- **Output:** `run.exposure()` gives the point-in-time exposure (ISO dates, values in `[0, 1]`, no
  gaps); `run.result` carries metrics, verdict, attribution, and those input notes.

## Notes
- Every call is scoped to your account — you only ever see your own projects and runs.
- `returns` accepts a pandas `DataFrame`/`Series`, a CSV file path, or raw CSV bytes/str. Without
  pandas, pass a CSV path/bytes and `.exposure()` returns a list of `(date, exposure)` tuples.
- Daily-cadence, regime-dependent strategies are the sweet spot; intraday/HFT is out of scope for the
  daily feature set (the API will tell you).
