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.
Install Quailbot from PyPI into the Python environment you want to use for direct-command work:
pip install quailbot
quailbot --helpCheck the runtime surface:
quailbot doctor
quailbot host init
quailbot host run
quailbot hub init
quailbot hub serveStart the human-first launcher:
quailbot runBare 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.jsonRun 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.jsonCalibration 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.
For source checkout work, use a clean dedicated Conda environment and install Quailbot editably into that active interpreter from the repository root:
conda create -n quailbot python=3.11 -y
conda activate quailbot
python -m pip install -U pip setuptools wheel
python -m pip install -e .
where.exe quailbotThis 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.tomldependencies or packaging metadata,- console-script entry points,
- moving, renaming, or replacing the checkout,
- package data or other install-time resources.
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.
Quailbot keeps installed runtime state out of the repository root:
| Surface | Default location |
|---|---|
| Host service | %ProgramData%\Quailbot\host\ |
| Hub bridge | %AppData%\Quailbot\hub\ |
| Local direct runs and settings | %AppData%\Quailbot\local\ |
These roots hold configs, sessions, logs, mirrors, and local settings. Normal usage should not require PowerShell launchers or repo-root session folders.
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.
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.