auto_cate
Race multiple meta-learners to estimate heterogeneous treatment effects and return a validated, scored leaderboard with the winning model.
Instructions
Race several meta-learners and return a scored leaderboard + winner. Validation: validated evidence tier (known-truth, reference, external-parity, or Monte Carlo artifact). Assumptions: Unconfoundedness given the covariates; Overlap / positivity across the covariate space; Nuisance functions are estimated consistently; cross-fitting controls overfitting bias. Pre-conditions: Covariates, a treatment indicator, and an outcome for each unit; Enough data to fit flexible nuisance models with sample-splitting / cross-fitting. Failure modes: CATE estimates are unstable or extrapolate beyond the covariate support -> Restrict to the overlap region, increase data, or use a doubly-robust learner (DR-/R-learner). Alternatives: sp.dml, sp.causal_forest, sp.tmle. Typical minimum N: 500.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| y | Yes | Outcome column name. | |
| alpha | No | Significance level for both learner confidence intervals and the BLP-beta1 acceptance region used by the selection rule. | |
| score | No | Currently only ``'r_loss'`` is implemented. Reserved for future expansion. | r_loss |
| treat | Yes | Binary treatment column name (values in {0, 1}). | |
| detail | No | Payload depth: 'minimal' (~150 tokens) for sub-step calls where only the point estimate is needed; 'standard' (~1K tokens) for diagnostics + coefficient table; 'agent' (~2K tokens, default) adds violations / next_steps / suggested_functions so the LLM can plan its next call without another round-trip. | agent |
| n_folds | No | Number of folds used for both the shared nuisance cross-fit and each learner's honest CATE prediction. | |
| learners | No | Short codes of the meta-learners to race. Duplicates are ignored. | |
| as_handle | No | If true, cache the fitted result on the server and return result_id + result_uri alongside the JSON payload so a subsequent tools/call can chain without re-running. | |
| data_path | Yes | Absolute path or URL to a data file. Supported: .csv / .tsv / .txt (delimited), .parquet / .pq, .feather / .arrow, .xlsx / .xls, .dta (Stata), .json / .jsonl. Schemes: file://, s3://, gs://, https://. | |
| result_id | No | Optional handle to a previously-fitted result (returned by an earlier call when as_handle=true). Tools that operate on a fitted object accept this in place of re-supplying data_path + columns. | |
| cate_model | No | Override the default gradient-boosting models used for nuisance and final CATE fitting. | |
| covariates | Yes | Effect-modifier columns used as features for every nuisance and CATE model. | |
| n_bootstrap | No | Bootstrap iterations for ATE standard error on non-DR learners (passed through to ``metalearner``). | |
| data_columns | No | Optional column projection. Parquet/Feather/Stata loaders honour this for fast partial reads. | |
| random_state | No | Seed for all K-fold splits. | |
| data_sample_n | No | Optional uniform random subsample size (seed=0, deterministic) — useful on huge panels. | |
| outcome_model | No | Override the default gradient-boosting models used for nuisance and final CATE fitting. | |
| propensity_model | No | Override the default gradient-boosting models used for nuisance and final CATE fitting. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||