Skip to content

Experimental controller

kd-agent uses a language model to select and run KD algorithms, inspect their results and continue searches from checkpoints. It accepts a catalog dataset or a data file and writes a Markdown report in the run workspace.

The agent example shows a short search and continuation from a saved checkpoint, with results from both segments. The sections below cover installation, input formats and run options.

Install and configure

In the activated environment from Installation, install the controller with uv:

uv pip install "sail-kd[agent]" --torch-backend=auto

Or use pip:

python -m pip install "sail-kd[agent]"

With pip on a machine with a GPU, install the PyTorch build for the driver first, as described under CUDA PyTorch.

Then configure the language-model endpoint:

kd-agent setup

Setup asks for an endpoint, base URL, model and API key. OpenAI-compatible and Anthropic endpoints are supported. The settings are saved in ~/.config/kd/agent.json and reused by run and chat. Run setup again to change the saved settings. PySR searches also require sail-kd[pysr]; install sail-kd[agent,pysr] when using both components.

Pass a data file and a request:

kd-agent run --data sample.npz \
    "Find the equation governing this data."

Here, sample.npz uses the KD NPZ layout. To try a bundled benchmark, use its catalog identifier:

kd-agent run --dataset burgers --workspace out/agent-burgers \
    "Find the equation governing this data."

The file is loaded through kd.load. A registered layout supplies the mapping; other files require the coordinate, field and left-hand-side choices described in data requirements. Pass these choices as JSON:

kd-agent run --data run.mat \
    --load-options '{"coords":{"x":"x","t":"t"},"fields":{"u":"usol"},"lhs":"u_t"}'

For a PDEBench file with several samples, select one explicitly:

kd-agent run --data 1D_Burgers_Sols_Nu0.01.hdf5 \
    --load-options '{"select":{"sample":0}}'

kd-agent chat --data sample.npz --workspace out/agent-chat

The interactive session accepts follow-up requests about the results and search choices. Supplying an existing --workspace reuses its run ledger and recorded searches. For example, ask:

Inspect the data and find an equation for u_t.

After a result, a follow-up can request another search:

Try another suitable algorithm and compare the equations it finds.

Results and run options

The command prints its workspace path. A one-shot run also prints report_path and stop_reason; open the report to read the selected equation, search history and stopping outcome. Without --workspace, the command creates a directory under kd-agent-runs/ in the current directory.

--endpoint, --base-url and --model override the saved choices for a run. --time-budget-minutes communicates a budget to the model and supplies the remaining budget to searches; it is not a timeout for the whole conversation. --recursion-limit bounds the controller's execution steps. Use kd-agent run --help or kd-agent chat --help for the command options. Help works with the base installation; running the controller requires the extra.