# Sessions

> saving a report on where a session ended up, and recalling one later

Conversations meander. A saved session is **not** a transcript of that — it is a
short report on where things landed, written so a future session (yours or a
colleague's) can pick the thread back up.

Variables are not saved. Artifacts are, by name, because a name is all you need:
`FeatureSet("logd_value_f1")` reconstitutes the thing itself.

## Saving

When the user asks to save the session, call `save_session` with a short name and
the report. Show them the report first if the session was long — it is your read
of what mattered, and they may want something different in it.

```
name:   logd-cleanup
report: the markdown below
```

What earns its place:

- **Goal** — what the user was actually trying to do.
- **Artifacts** — the names touched or created (FeatureSets, models, endpoints,
  contests, DFStore keys).
- **Findings** — what you concluded, with the numbers that back it.
- **Decisions** — what was chosen, and why the alternative lost.
- **Open threads** — what was left undone, and any dead end worth not repeating.

The report is capped at 6000 characters, which is generous when you **name
artifacts instead of restating them**. `logd_value_f1` is thirteen characters and
re-derivable; its column list is not. If a report won't fit, it is carrying data
rather than conclusions — park the data in a `DFStore` frame and name the key.

Write in past tense, plainly, for a reader who was not there. "Chemprop beat XGB
by 0.04 RMSE on the analog set, so we kept chemprop" — not "we tried some models."

## Recalling

```
read_session("logd-cleanup")           # your own
read_session("briford/logd-cleanup")   # someone else's -- reports are shared
```

Recall gives you the report and nothing else — **no variables, no artifacts in
hand**. Pick up what you need by name before working with it, and say plainly what
you are re-fetching rather than implying it was already there.

A report is a record of what was true when it was written. If it names a model or
a metric, check the artifact still exists and still says that before repeating it
to the user.

To see what is available, most recent first:

```python
recent_sessions()                  # yours -- [session, saved, when], for showing a person
recent_sessions(all_users=True)    # everyone's
show_session("eromm/caco2-er-class-xgb")   # rendered markdown; no arg = most recent
```

`recent_sessions` and `show_session` are REPL commands, so the user can run them
too — point them at `show_session` rather than reading a report back to them.
`list_sessions()` (import from `workbench.utils.bosco_utils`) is the same rows with
a real timestamp column, for comparing or filtering in code.

Empty is a real answer: no sessions have been saved yet. Say so rather than
reporting it as a lookup failure.
