Quailbot

QUAIL stands for Quantum Uncertain Action-Outcome Instrument Loop.

Quailbot is a workspace-defined automation system for long-running action-outcome loops over external CLI surfaces and optional GUI fallback targets.

Quickstart

For direct-command work, use a clean dedicated Conda environment and install Quailbot into that active interpreter:

conda create -n quailbot python=3.11 -y
conda activate quailbot
python -m pip install -U pip setuptools wheel
python -m pip install -e D:\path\to\quailbot
where.exe quailbot

From the repository root, python -m pip install -e . is equivalent.

This is the recommended local toolized mode for source checkouts: it installs the quailbot command into the active Python environment instead of requiring a repo-local virtual environment launcher. where.exe quailbot verifies that Windows resolves the command from the environment you just activated.

On Windows, do not assume py -3.11 will work unless py -0p shows a registered Python 3.11 runtime. If the Windows launcher points at the wrong interpreter, keep using the environment's python -m pip ... command instead.

Editable installs pick up normal Python source edits on the next run.

Re-run python -m pip install -e . after changes to:

• pyproject.toml dependencies or packaging metadata,
• console-script entry points,
• moving, renaming, or replacing the checkout,
• package data or other install-time resources.

Check the runtime surface:

quailbot doctor
quailbot host init
quailbot host run
quailbot hub init
quailbot hub serve

Start the human-first launcher:

quailbot run

Bare quailbot run is the human-first launcher path. The launcher can reopen the last workspace, use the local starter workspace, accept another workspace path, or open calibration first.

Open a specific workspace interactively:

quailbot run --workspace D:\path\to\workspace.json

Run a local headless task against a workspace:

quailbot run --workspace D:\path\to\workspace.json --task "Set the requested values, verify the readbacks, and collect the requested scan."

Headless --task runs require an explicit --workspace <path>.

Open the workspace calibration UI:

quailbot calibrate --workspace D:\path\to\workspace.json

Calibration remains where workspace definition and refinement happen.

If no workspace is supplied, quailbot calibrate creates a writable starter copy under %AppData%\Quailbot\local\workspace.json and opens that file.

Command surface

quailbot host init|run|start|stop|status|logs
quailbot hub init|serve|status
quailbot run
quailbot run --workspace <path>
quailbot run --workspace <path> --task "..."
quailbot monitor --job <job_id>
quailbot calibrate [--workspace <path>] [--check]
quailbot doctor [host|hub|workspace --path <path>]

The headless run --task path prints the produced session artifact path on stdout so it can be inspected after the run. The interactive path keeps the local Textual operator UI available without requiring the host or hub services.

Runtime data locations

Quailbot keeps installed runtime state out of the repository root:

These roots hold configs, sessions, logs, mirrors, and local settings. Normal usage should not require PowerShell launchers or repo-root session folders.

Workspaces

The workspace remains the automation contract. It defines:

• external CLI parameters and actions Quailbot may use,
• optional GUI anchors and regions for fallback operations,
• linked observables used for post-action readback,
• provider and run settings used by local or hosted execution.

Calibration is the only place where external CLI capabilities are imported into a workspace. Runtime commands execute the already-approved capabilities from the workspace rather than inventing a new CLI contract.

Diagnostics

Use quailbot doctor for a read-only status report. It prints structured JSON checks for host, hub, local runtime paths, and workspace validity when a path is supplied.