Gently 0.22: web-first operator surface, self-managed auth, and observable permissioned autonomy

README.md

@@ -2,7 +2,7 @@
 
 Agentic harness for microscopy.
 
-**Status**: v0.11.0 — actively developed at Shroff Lab, Janelia.
+**Status**: 0.22.0.dev0 — actively developed at Shroff Lab, Janelia.
 
 ![Safety Architecture](docs/images/safety_architecture.png)
 
@@ -67,47 +67,156 @@ Currently, the sample abstraction is the `Embryo` object for *C. elegans* work.
 
 ### Prerequisites
 
-- Python 3.11+
-- [Node.js](https://nodejs.org/) 18+ (for the Ink TUI)
-- An `ANTHROPIC_API_KEY` environment variable
+- Python 3.10+
+- An `ANTHROPIC_API_KEY` — either exported in your shell
+  (`export ANTHROPIC_API_KEY=your-key`) or placed in a `.env` file in the
+  project root (`ANTHROPIC_API_KEY=your-key`), which is loaded automatically
+  on launch and is gitignored. *(Not required if you launch with `--no-api`
+  to browse the UI only — see Launch below.)*
+- *(Optional)* `GENTLY_STORAGE_PATH` — where sessions and data live (default `D:/Gently3`)
+
+Gently is **web-first**: the agent is driven from an in-page chat in your
+browser. There is no TUI to build (Node.js is only needed for the paper
+diagrams, not the app).
 
 ### Setup
 
+This project uses [uv](https://docs.astral.sh/uv/) for environment and
+dependency management. If you don't have it yet, install it following the
+[uv installation guide](https://docs.astral.sh/uv/getting-started/installation/)
+(e.g. `curl -LsSf https://astral.sh/uv/install.sh | sh` on macOS/Linux).
+
+Gently depends on **`gently-perception`** (the VLM perception harness, repo
+`pskeshu/gently-perception`), which is not published to PyPI. Clone it as a
+**sibling** of `gently` so the path source in `pyproject.toml` can find it:
+
 ```bash
-# Clone and install Python dependencies
+# Clone both repos side by side
 git clone https://github.com/pskeshu/gently.git
+git clone https://github.com/pskeshu/gently-perception.git
+
+# Layout:
+#   <parent>/
+#     gently/             <- you run commands from here
+#     gently-perception/  <- resolved via [tool.uv.sources]
+```
+
+From the project root run:
+
+```bash
 cd gently
-pip install -r requirements.txt
+uv sync
+```
+
+This creates a `.venv` in the project directory and installs the runtime + dev
+dependencies pinned in `uv.lock` (see `pyproject.toml` for the spec), including
+`gently-perception` as an editable install from the sibling clone. Activate it
+with `source .venv/bin/activate`, or just prefix commands with `uv run` (e.g.
+`uv run python ...`) to use it without activating.
 
-# Build the TUI (one-time, rebuild after TUI code changes)
-cd gently/tui
-npm install
-npm run build
-cd ../..
+#### Optional extras
+
+```bash
+# Device-layer accessories (microscope computer): BLE/serial/MQTT transports
+uv sync --extra device
+
+# GPU acceleration for SAM detection — install the CUDA build of PyTorch
+# (skip on CPU-only machines; the default torch from uv sync works there)
+uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
+```
+
+#### Running tests
+
+```bash
+uv run pytest
 ```
 
 ### Launch
 
+> The commands below use `uv run` so they work without activating the env. If you've activated it first (`source .venv/bin/activate`), the `uv run` prefix isn't necessary.
+
+To verify the install, you can start gently without an API key or hardware. The
+web UI boots and is browsable, though the agent itself (chat, perception, plan
+mode) stays disabled until you add a key:
+
+```bash
+uv run python launch_gently.py --offline --no-api
+```
+
+For the full launch:
+
 ```bash
-# 1. Start the device layer (hardware control + SAM detection)
-python start_device_layer.py
+# 1. Device layer (hardware control + SAM detection) — separate process, own terminal
+uv run python start_device_layer.py
+
+# 2. Agent + web UI (starts the in-process server and opens your browser)
+uv run python launch_gently.py
+
+# Run without hardware (development / review)
+uv run python launch_gently.py --offline
 
-# 2. Launch the agent
-python launch_gently.py
+# UI-only — boot the web UI with no API key (chat/perception disabled)
+uv run python launch_gently.py --no-api
 
-# Or launch without hardware (for development / review)
-python launch_gently.py --offline
+# Don't auto-open a browser — open the printed URL yourself
+uv run python launch_gently.py --no-browser
 
 # Resume a previous session
-python launch_gently.py --resume            # interactive picker
-python launch_gently.py --resume latest     # most recent session
-python launch_gently.py --resume <id>       # specific session
+uv run python launch_gently.py --resume            # interactive picker
+uv run python launch_gently.py --resume latest     # most recent session
+uv run python launch_gently.py --resume <id>       # specific session
 
 # Verbose / debug logging
-python launch_gently.py -v                  # INFO level
-python launch_gently.py --debug             # DEBUG level
+uv run python launch_gently.py -v                  # INFO level
+uv run python launch_gently.py --debug             # DEBUG level
+```
+
+The launcher prints a banner with the URL (default `http://localhost:8080`),
+device status, storage path, and log location. Open that URL in any browser on
+the LAN.
+
+### First sign-in (accounts)
+
+**Viewing is open** — the dashboard loads read-only for anyone, no login.
+Signing in *elevates* you to control (driving hardware, taking the
+single-operator lock); it isn't a gate on the page.
+
+On the **first run**, Gently creates one `admin` account and prints a one-time
+random password in the startup banner:
+
+```
+First-run admin account created — sign in at the URL above:
+    username: admin
+    password: <random>
 ```
 
+- **Save it now** — the password is printed to the console once and never
+  written to the log (only a PBKDF2 hash is stored).
+- After signing in, add accounts (roles `viewer` / `operator` / `admin`) via the
+  admin-only `POST /api/auth/users`.
+- **Lost it?** There's no reset command yet — delete
+  `<GENTLY_STORAGE_PATH>/auth/users.yaml` and restart to bootstrap a fresh
+  `admin` (this clears all accounts).
+- **Just trying it locally?** `GENTLY_NO_AUTH=1` disables accounts entirely
+  (legacy mode: localhost gets control, remote callers need `X-Gently-Token`).
+
+Accounts live under `<GENTLY_STORAGE_PATH>/auth/` (`users.yaml` + `secret.key`),
+outside the repo.
+
+## Make your first plan
+
+You don't need a microscope to try the core loop — **plan mode is pure agent reasoning and works under `--offline`**. The path from launch to an inspectable plan:
+
+1. **Open the agent chat.** Click **Agent** in the header (or press `Ctrl`/`Cmd`+`J`). New here? The **Home** tab's *Start an experiment* button runs a short setup wizard (also available anytime via `/wizard` — it sets the organism, the campaign, and what you're trying to learn).
+2. **Enter plan mode** — type `/plan` in the chat. The agent switches from *operator* to *scientific collaborator*: it won't touch hardware, it helps you design an experiment.
+3. **Describe what you want, in plain language.** For example:
+   > *"Follow GFP-tagged embryos from bean stage through elongation, imaging every 10 minutes, with a no-laser control — three embryos per condition."*
+
+   The agent drafts a **campaign**: a sequence of typed **plan items** — imaging 📷, bench 🧪, genetics 🧬, analysis 📊, decision points 🚦 — each with concrete specs (strain, interval, laser power, Z-slices, target window, success criteria). Keep replying to refine it; `/plan status` shows progress and `/plan exit` returns to run mode.
+4. **Inspect it in the plan viewer.** Open the **Plans** tab. Your campaign appears as a card — click it to open the **plan document**. Each item shows its status (○ planned · ◑ in progress · ● done) and specs; click one to see full details in the inspector. Switch layouts (document / board / graph / timeline) from the view controls, and browse plan **versions** as it evolves. (Typing `/campaign` in chat lists campaigns too.)
+
+That's the loop: **talk → plan → inspect.** With hardware connected (drop `--offline` and start the device layer), the same campaign drives acquisition — and perception events can wake the agent to adjust it as the embryos develop.
+
 ## Guides
 
 | Guide | Audience | What you'll learn |
@@ -125,7 +234,7 @@ Four layers with strict downward-only dependencies. The **harness** (reusable ag
 gently/
 ├── core/                  # Layer 1: Foundation — zero domain knowledge
 │   ├── event_bus.py       #   Async pub/sub messaging
-│   ├── store.py           #   GentlyStore (SQLite + files)
+│   ├── file_store.py      #   FileStore (file-based: YAML / JSONL / TIF)
 │   ├── imaging.py         #   Projection, normalization, encoding
 │   └── coordinates.py     #   Pixel/stage transforms
 │
@@ -220,4 +329,6 @@ These papers provide theoretical background for gently's approach:
 
 ## License
 
-See [LICENSE](LICENSE) file.
+Copyright © 2026 Howard Hughes Medical Institute.
+
+Gently is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later) — see the [LICENSE](LICENSE) file.

config/config.yml

@@ -1,4 +1,13 @@
 organism: "celegans"
 hardware: "dispim"
 mmconfig: "MMConfig_tracking_screening.cfg"
-mmdirectory: "C:/Program Files/Micro-Manager-1.4"
+mmdirectory: "C:/Program Files/Micro-Manager-1.4"
+
+# SwitchBot Bot — physical button-pusher mounted on the diSPIM room light
+# switch. Talks BLE direct (no SwitchBot Hub / cloud). Plans address it by
+# name, e.g. `bps.mv(room_light, 'on')`. Remove this block to skip
+# registration; the device layer is tolerant of either state.
+switchbot:
+  name: room_light
+  address: "EC:6F:04:06:5B:23"
+  timeout: 20.0