diff --git a/mkdocs.yml b/mkdocs.yml index a165a8a..ca20e92 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -31,6 +31,10 @@ nav: - Homepage: index.md - Quickstart: content/quickstart.md - User Guide: + - Dashboard: + - Overview: content/user_guide/dashboard/index.md + - Sessions: content/user_guide/dashboard/sessions.md + - Templates: content/user_guide/dashboard/templates.md - Logging: - Local: content/user_guide/logging/local.md - Wandb: content/user_guide/logging/wandb.md diff --git a/src/content/quickstart.md b/src/content/quickstart.md index 8600aac..96f65c8 100644 --- a/src/content/quickstart.md +++ b/src/content/quickstart.md @@ -131,6 +131,17 @@ python main.py and fenn will take care of the rest for you. +### Dashboard + +Start the local dashboard with: + +```bash +fenn dashboard +``` + +From there you can browse, filter, and rename your experiment sessions, see every template you've pulled, and launch any of them with one click — you'll be taken straight to its live session view. + + ### Training Models Use built-in trainers to handle your training loops with minimal boilerplate. diff --git a/src/content/user_guide/dashboard/index.md b/src/content/user_guide/dashboard/index.md new file mode 100644 index 0000000..5669dcf --- /dev/null +++ b/src/content/user_guide/dashboard/index.md @@ -0,0 +1,42 @@ +# The Dashboard + +The Fenn dashboard is a local web UI for browsing your experiment sessions, viewing logs, and managing the templates you've pulled - all without leaving your browser. + +## Starting the Dashboard + +```bash +fenn dashboard +``` + +By default this starts a server at `http://127.0.0.1:5000`. The dashboard only ever binds to `127.0.0.1` - it serves your local logs and is not meant to be exposed on your network. + +## Options + +| Flag | Description | +|---|---| +| `--port ` | Port to bind (default: `5000`) | +| `--log-dir [DIR ...]` | Extra directories to scan for `.fn` session files, in addition to the current directory | +| `--debug` | Run Flask in debug mode | + +Example: + +```bash +fenn dashboard --port 8080 --log-dir ./experiments ./archived-runs +``` + +## Signing In + +The first time you open the dashboard, you'll be redirected to a **Connect** page with a "Sign in with pyfenn.com" button. This opens a browser tab for a normal OAuth sign-in and consent flow, then hands control back to the dashboard. + +Once you've signed in, your session is cached locally so future launches of `fenn dashboard` skip the sign-in step and re-validate silently in the background. If your saved session is ever revoked or expires, you'll be sent back to the Connect page to sign in again. + +## Pages + +| Page | What it shows | +|---|---| +| **Overview** (`/`) | All projects with logged sessions, at a glance | +| **Project** (`/project/`) | All sessions for a single project | +| **Session** (`/session//`) | Full detail for one session - logs, metadata, status | +| **Templates** (`/templates`) | Templates you've pulled locally, with the option to launch them - see [Managing Templates](templates.md) | + +For details on filtering, renaming, and archiving sessions, see [Managing Sessions](sessions.md). diff --git a/src/content/user_guide/dashboard/sessions.md b/src/content/user_guide/dashboard/sessions.md new file mode 100644 index 0000000..717df6f --- /dev/null +++ b/src/content/user_guide/dashboard/sessions.md @@ -0,0 +1,37 @@ +# Managing Sessions + +Every run of your entrypoint is logged as a session, and the dashboard gives you tools to browse, organize, and clean up those sessions without touching the log files by hand. + +## Browsing + +The **Overview** page lists every project with logged sessions. Open a project to see its individual sessions, or open a session directly to see its full logs and metadata. + +Each session has a status: + +- `running` — currently in progress +- `completed` — finished normally +- `failed` — finished with an error +- `crashed` — stopped writing without a proper close (e.g. the process died) + +## Filtering + +From a project or the overview, sessions can be filtered by: + +- **Project** +- **Status** (`running`, `crashed`, `completed`, `failed`) +- **Date range** — sessions started after/before a given `YYYY-MM-DD HH:MM:SS` timestamp +- **Sort** — by start time, end time, duration, warning count, or exception count (ascending or descending) + +Archived sessions are hidden by default; toggle "include archived" to bring them back into the list. + +## Renaming + +Give a session a more memorable display name than its generated ID directly from the session or project view. The underlying `.fn` file and session ID are untouched - only the display name changes. + +## Archiving + +Archiving hides a session from the default view without deleting anything - useful for tidying up old or exploratory runs you want to keep around but not see day-to-day. Archived sessions can be restored at any time from the "include archived" view, which brings them back into the normal listing. + +## Deleting + +Deleting a session removes it permanently. Unlike archiving, this cannot be undone - use archiving instead if you just want a session out of the way. diff --git a/src/content/user_guide/dashboard/templates.md b/src/content/user_guide/dashboard/templates.md new file mode 100644 index 0000000..bdd0612 --- /dev/null +++ b/src/content/user_guide/dashboard/templates.md @@ -0,0 +1,23 @@ +# Managing Templates + +The **Templates** page (`/templates`) lists every template you've pulled locally with `fenn pull`, and lets you launch one directly from the browser. + +## How templates get here + +Every time you run `fenn pull