From 0309aef0093585db2a462eb6c39c565562805497 Mon Sep 17 00:00:00 2001 From: Tianhao-Gu Date: Tue, 18 Aug 2026 15:33:08 -0500 Subject: [PATCH] Add the KIND*AI user guide --- README.md | 1 + user_guides/kind_guide.md | 65 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+) create mode 100644 user_guides/kind_guide.md diff --git a/README.md b/README.md index e2267ab..17ee11f 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ Step-by-step guides for working with the BERDL platform. Guides live under [`use | Guide | Description | |-------|-------------| | [Accessing BERDL JupyterHub](./user_guides/user_guide.md) | Getting started: logging in, linking ORCID, roles, and launching a notebook. | +| [KIND*AI](./user_guides/kind_guide.md) | The natural-language front door: AI co-scientist sessions and data portal apps, auto-started for KIND-role holders. | | [Requesting Tenant Access](./user_guides/requesting-tenant-access.md) | How to request access to tenant groups via the JupyterLab extension. | | [Tenant SQL Warehouse](./user_guides/tenant_sql_warehouse_guide.md) | Configuring your Spark session to write to a personal or shared tenant SQL warehouse. | | [Trino SQL Queries](./user_guides/trino_guide.md) | Interactive read-only SQL over your data lake tables with Trino. | diff --git a/user_guides/kind_guide.md b/user_guides/kind_guide.md new file mode 100644 index 0000000..8fbebb9 --- /dev/null +++ b/user_guides/kind_guide.md @@ -0,0 +1,65 @@ +# KIND*AI on the BERDL Lakehouse — User Guide + +KIND*AI is the graphical, natural-language front door to the lakehouse: ask a +research question and watch an AI co-scientist (a KOROS/Claude Code session) +work it — plan, decisions, and results surfaced in a web UI — plus one-click +data portal apps (Lakehouse Explorer, Diaspora, ENIGMA Strata, Function +Junction, Fungal Jungle, GenePool, genKnown, Plant Terra). No terminal, no +installation: it's built into the notebook image and starts automatically. + +## Who gets it + +Users holding a KIND role in KBase Auth2 — **`KBASE_STAFF`** or +**`BERDL_KIND_USER`**. Everyone else keeps the plain JupyterLab experience, +unchanged. + +## Getting in + +1. Go to **https://hub.berdl.kbase.us** and log in. +2. Your server starts (KIND boots with it and pre-warms the app portals). +3. You land on the KIND UI: `https://hub.berdl.kbase.us/user//proxy/8770/`. + +If you land on JupyterLab instead despite holding the role: **log out of the +hub, log back in, then stop + start your server** (Hub Control Panel) — in +that order; the role is stamped into your hub session at login. Only the hub +session needs it — your KBase login is untouched, so logging back in is one +click. + +**JupyterLab hasn't gone anywhere:** use the Jupyter button in KIND's top +bar, or go to `https://hub.berdl.kbase.us/user//lab` directly — explicit +`/lab` URLs always take you to Lab. + +## One-time setup: an LLM credential + +Driving sessions requires a credential **BERDL does not provide**. Either: + +- run `claude` in a hub terminal and log in with a Claude Pro/Max account, or +- put a CBORG key in `~/.env`: + `CBORG_API_KEY=...` (and `CBORG_BASE_URL=https://api.cborg.lbl.gov/v1`). + +KIND's **⚙ doctor** panel tells you exactly what's missing. + +## Where your work lives + +Everything survives pod restarts and idle culls: research arcs under +`~/koros/runs`, KIND session state under `~/.local/share/king/runs`, both on +your persistent home. Stopping your server kills an *in-flight* agent turn, +but recorded arc state is resumable. + +## Troubleshooting + +| Symptom | Fix | +|---|---| +| I land on JupyterLab though I have the role | Log out of the hub → log in (one click — your KBase login persists) → stop + start your server (Hub Control Panel), **in that order** | +| Error page right after my server starts | KIND is still booting (~15 s) — reload | +| KIND looks old / no Jupyter button in the top bar | An earlier manual KING install is shadowing the built-in one. In a hub terminal run: `for f in ~/.local/bin/king* ~/.local/bin/kind*; do if [ -L "$f" ] && [[ $(readlink "$f") == $HOME/king/* ]]; then rm -v "$f"; fi; done` then stop + start your server once more. Your `~/king` checkout and all research state stay untouched. (Skip this if you're actively developing KING — it's your build, on purpose.) | +| "KBase token expired" banner though I just logged in | Stop + start your server; if it persists, log out/in first | +| An app tile won't load | Give it ~45 s (cold start), then relaunch from the switchboard | + + +## For KING developers + +Manual development is unchanged: `serve.sh` from your own checkout still +works, and the built-in autostart defers to any server you're already +running. Note the flip side — leftover `~/.local/bin/king*` symlinks from an +old install shadow the built-in KIND (see the troubleshooting row above).