# Homeostat Live, for AI agents

> Homeostat Live (https://homeostat.kausalflow.com/live/) runs simulated process plants as if they were real. Every Friday at 17:00 UTC a benchmark opens: predict the lab results of the week that has just closed from its sensor data. This page tells an AI coding agent how to help someone take part.

## Start a model

In a terminal, with Python 3.10 or later (a virtual environment is best):

```bash
pip install 'homeostat-live[models]'
homeostat_live init my-model        # AGENTS.md, model.py and the plant's data
cd my-model
homeostat_live backtest model.py    # score it on the released weeks, next to the reference models
homeostat_live predictions --out p.csv   # what the reference models and the best participants predicted, next to the lab results
```

Then read `my-model/AGENTS.md`: the task, the files, the model interface, the commands, the rules and the scoring. `model.py` starts as the reference model `ref-linear`, a ridge regression on the sensor values at each sample's time. Improve it and backtest it; when it is better:

```bash
homeostat_live predict model.py     # predictions for the open benchmark, checked
homeostat_live submit <date> <plant> <file> --note "what changed"    # only when the person says so
```

## A prompt

Paste this into a coding agent (Claude Code, Codex, Cursor and the like), in an empty folder:

> I want to take part in the Homeostat Live benchmark: https://homeostat.kausalflow.com/live/agents.md. Install the tools in a virtual environment with `pip install 'homeostat-live[models]'`, run `homeostat_live init .` here and read AGENTS.md. Then improve model.py until it beats ref-linear in `homeostat_live backtest model.py --all`, one change at a time, and log what you try in NOTES.md. Don't submit anything without asking me.

## Rules

- The causal rule: a prediction for a sample may use only data up to the time the sample was taken: sensor data up to then, and the lab results of earlier, released weeks. The harness behind `backtest` and `predict` keeps it, and stops a model whose features look ahead.
- A person registers (`homeostat_live register <name>`) and decides when to submit. The token is theirs: an agent never reads, prints or copies it.
- A user's last submission before the freeze counts, and a user may submit 10 times a day. Models built with AI are welcome.

## More

- The live plants: https://homeostat.kausalflow.com/live/llms.txt, and each plant's card at /live/<plant>.md: the process, the tags, the grades, the API and the scoring.
- The package: https://pypi.org/project/homeostat-live/