Metadata-Version: 2.4
Name: quailbot
Version: 0.1.1
Summary: Workspace-defined automation for quantum instrument action-outcome loops
Author-email: BB84 <hustphysicscheng@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/BB-84C/QUAIL-Bot
Project-URL: Repository, https://github.com/BB-84C/QUAIL-Bot
Project-URL: Issues, https://github.com/BB-84C/QUAIL-Bot/issues
Keywords: automation,instrumentation,cli,tui,agent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: Microsoft :: Windows
Classifier: Environment :: Console
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anyio
Requires-Dist: mss
Requires-Dist: pyautogui
Requires-Dist: pillow
Requires-Dist: pynput
Requires-Dist: openai==2.24.0
Requires-Dist: fastapi
Requires-Dist: uvicorn
Requires-Dist: httpx
Requires-Dist: pyyaml
Requires-Dist: anthropic
Requires-Dist: google-genai
Requires-Dist: textual
Requires-Dist: mcp
Requires-Dist: rich
Dynamic: license-file

# Quailbot

![Quailbot header](https://raw.githubusercontent.com/BB-84C/QUAIL-Bot/main/assets/quailbot-header.png)

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:

```powershell
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:

```powershell
quailbot doctor
quailbot host init
quailbot host run
quailbot hub init
quailbot hub serve
```

Start the human-first launcher:

```powershell
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:

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

Run a local headless task against a workspace:

```powershell
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:

```powershell
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

```text
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:

| 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.

## 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.
