wizardflow 0.3.0__tar.gz → 0.5.0__tar.gz

{wizardflow-0.3.0 → wizardflow-0.5.0}/CONTRIBUTING.md

@@ -50,3 +50,22 @@ That script runs the shared Next frontend with
 `NEXT_PUBLIC_WIZARDFLOW_TARGET=local`, copies the static export into
 `src/wizardflow/_ui/`, and removes hosted-only legal route artifacts (`Impressum`
 / `Datenschutz`). The SDK UI keeps the GitHub project link.
+
+## Checking live traces by hand
+
+The viewer follows a trace file while it is still being written: it polls with
+`If-None-Match`, extends the timeline without losing your place, and stops when
+the part rotates away. None of that is covered by an automated test, so there is
+a generator to watch it with:
+
+```bash
+cd sdk/python
+python scripts/live_trace_demo.py
+```
+
+It records a synthetic run with the ordinary SDK calls, writing into the
+monorepo's `web/public/` (so the trace is same-origin for `npm run dev` in
+`web/`) and printing the viewer URL. It rotates after 18 messages, so the sealed
+part, the part navigation, and the live pulse dot can all be seen in a couple of
+minutes. Like `build_ui.py`, it needs the full monorepo checkout and is never
+packaged.

{wizardflow-0.3.0 → wizardflow-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wizardflow
-Version: 0.3.0
+Version: 0.5.0
 Summary: Python SDK for recording agent flows into the WizardFlow / AgentTrace file format.
 Project-URL: Homepage, https://getwizardflow.com
 Project-URL: Documentation, https://getwizardflow.com
@@ -57,6 +57,10 @@ runtime dependencies**, no daemon, no setup.
 
 ![WizardFlow replaying an agent run](https://raw.githubusercontent.com/lkleonk/wizardflow/main/sdk/python/assets/demo.gif)
 
+▶ **[Watch this exact run live](https://getwizardflow.com/?example=doctor-consultation)** —
+the flow from the GIF, replaying in your browser right now. No install, and
+nothing is uploaded.
+
 The file it produces is JSON Lines with a small, documented schema: line 1 is a
 `header` record carrying the `graph { nodes, edges }`, then one `message`
 record per line (`steps[] → payloads[] { label, value }`). Every line is plain
@@ -150,7 +154,11 @@ wizardflow.end_message("msg-2")          # writes msg-2
 
 Pass the **string `id`**, never a handle object — safe to hand to a callback or
 across threads. A message is created on first reference and finalized by
-`end_message`; `end_message(id, title="...")` optionally gives it a human title.
+`end_message`; `end_message(id, title="...")` optionally gives it a human title,
+and `end_message(id, meta={...})` attaches flat metadata about the message as a
+whole (outcome, latency, user id, …) — the viewer shows it on the message's
+timeline chip. Keep meta values short scalars; large structured data belongs in
+`log()` payloads.
 
 ### Choosing message ids
 
@@ -169,8 +177,9 @@ Do **not** use a session id, user id, or thread id as the message id. Those
 identify a *conversation*, and a conversation contains many messages — after
 the first `end_message(session_id)`, every further `log(session_id, ...)` in
 that session raises, because that "message" has already ended. If you want the
-session visible in the trace, put it in `init(meta=...)` or in the message
-title (`end_message(msg_id, title=...)`) — never in the id. Ids are opaque:
+session visible in the trace, put it in `init(meta=...)` or in the message's
+meta (`end_message(msg_id, meta={"session": session_id})`) — never in the id.
+Ids are opaque:
 the viewer only displays and groups by them, so encoding meaning into them
 buys nothing. Hardcoded ids like `"msg-1"` are fine for demo scripts; `uuid4`
 is the right default for real applications.
@@ -302,9 +311,11 @@ metadata never fails extraction (the edge is just emitted plain). Call it
   **message id**, the second is the node. With `label`/`content` it records a
   payload; bare `log(id, "node")` records a visit with no payloads. The message
   is created on first reference; this only accumulates in memory.
-- `end_message(id, title=None)` — finalize a message and append it to the
-  trace; returns the current trace path. The **only** call that touches disk.
-  Optional `title` sets the message's human title. Idempotent.
+- `end_message(id, title=None, meta=None)` — finalize a message and append it
+  to the trace; returns the current trace path. The **only** call that touches
+  disk. Optional `title` sets the message's human title; optional `meta` (a
+  flat dict of short scalars) attaches message-level metadata shown on the
+  message's chip in the viewer. Idempotent.
 - `reinit(name=None, description=None, meta=None)` — start a **new trace
   file** (fresh timestamped name), keeping the graph and output configuration.
   Use it at natural boundaries of a long-lived process — a new user session, a
@@ -440,6 +451,11 @@ wizardflow html run.jsonl
 wizardflow json run.jsonl
 # --path is equivalent everywhere:
 wizardflow ui --path run.jsonl
+# --latest: treat the path as a directory (default: the current directory) and
+# open its most recently modified *.jsonl / *.json file — handy right after a
+# run, or to attach to the trace an agent is writing right now:
+wizardflow ui --latest
+wizardflow ui --latest traces/
 ```
 
 The SDK only ever **writes** JSONL, but these commands **read** either framing —
@@ -449,16 +465,22 @@ they stay at parity with the web viewer, which also accepts both.
 ### `wizardflow ui` — local viewer
 
 ```bash
-wizardflow ui run.jsonl [--host 127.0.0.1] [--port 0] [--no-open]
+wizardflow ui run.jsonl [--latest] [--host 127.0.0.1] [--port 0] [--no-open]
 ```
 
 Binds a stdlib HTTP server, serves the static WizardFlow UI bundled in the SDK
-package, and opens the selected trace in your browser (the JSONL is assembled
-server-side and served to the UI as one JSON document, re-read on refresh — so
-you can watch a still-running trace grow).
+package, and opens the selected trace in your browser. The JSONL is assembled
+server-side and served to the UI as one JSON document, re-read on every fetch —
+and the UI **follows a still-running trace live**: it polls the file (cheap
+ETag revalidation; an unchanged file is a single `stat()` on the server) and
+extends the view in place without resetting your selection, playback position,
+or arranged node layout. A pulse dot in the header shows the watch is active;
+messages that arrive while you're inspecting an older one appear as a
+"+N new" chip in the timeline.
 
 | flag | default | meaning |
 | --- | --- | --- |
+| `--latest` | off | treat the path as a directory (default: cwd) and open its most recently modified `*.jsonl` / `*.json` |
 | `--host` | `127.0.0.1` | interface to bind |
 | `--port` | `0` | port to bind; `0` asks the OS for a free port |
 | `--no-open` | off | print the local URL instead of launching a browser |

{wizardflow-0.3.0 → wizardflow-0.5.0}/README.md

@@ -10,6 +10,10 @@ runtime dependencies**, no daemon, no setup.
 
 ![WizardFlow replaying an agent run](https://raw.githubusercontent.com/lkleonk/wizardflow/main/sdk/python/assets/demo.gif)
 
+▶ **[Watch this exact run live](https://getwizardflow.com/?example=doctor-consultation)** —
+the flow from the GIF, replaying in your browser right now. No install, and
+nothing is uploaded.
+
 The file it produces is JSON Lines with a small, documented schema: line 1 is a
 `header` record carrying the `graph { nodes, edges }`, then one `message`
 record per line (`steps[] → payloads[] { label, value }`). Every line is plain
@@ -103,7 +107,11 @@ wizardflow.end_message("msg-2")          # writes msg-2
 
 Pass the **string `id`**, never a handle object — safe to hand to a callback or
 across threads. A message is created on first reference and finalized by
-`end_message`; `end_message(id, title="...")` optionally gives it a human title.
+`end_message`; `end_message(id, title="...")` optionally gives it a human title,
+and `end_message(id, meta={...})` attaches flat metadata about the message as a
+whole (outcome, latency, user id, …) — the viewer shows it on the message's
+timeline chip. Keep meta values short scalars; large structured data belongs in
+`log()` payloads.
 
 ### Choosing message ids
 
@@ -122,8 +130,9 @@ Do **not** use a session id, user id, or thread id as the message id. Those
 identify a *conversation*, and a conversation contains many messages — after
 the first `end_message(session_id)`, every further `log(session_id, ...)` in
 that session raises, because that "message" has already ended. If you want the
-session visible in the trace, put it in `init(meta=...)` or in the message
-title (`end_message(msg_id, title=...)`) — never in the id. Ids are opaque:
+session visible in the trace, put it in `init(meta=...)` or in the message's
+meta (`end_message(msg_id, meta={"session": session_id})`) — never in the id.
+Ids are opaque:
 the viewer only displays and groups by them, so encoding meaning into them
 buys nothing. Hardcoded ids like `"msg-1"` are fine for demo scripts; `uuid4`
 is the right default for real applications.
@@ -255,9 +264,11 @@ metadata never fails extraction (the edge is just emitted plain). Call it
   **message id**, the second is the node. With `label`/`content` it records a
   payload; bare `log(id, "node")` records a visit with no payloads. The message
   is created on first reference; this only accumulates in memory.
-- `end_message(id, title=None)` — finalize a message and append it to the
-  trace; returns the current trace path. The **only** call that touches disk.
-  Optional `title` sets the message's human title. Idempotent.
+- `end_message(id, title=None, meta=None)` — finalize a message and append it
+  to the trace; returns the current trace path. The **only** call that touches
+  disk. Optional `title` sets the message's human title; optional `meta` (a
+  flat dict of short scalars) attaches message-level metadata shown on the
+  message's chip in the viewer. Idempotent.
 - `reinit(name=None, description=None, meta=None)` — start a **new trace
   file** (fresh timestamped name), keeping the graph and output configuration.
   Use it at natural boundaries of a long-lived process — a new user session, a
@@ -393,6 +404,11 @@ wizardflow html run.jsonl
 wizardflow json run.jsonl
 # --path is equivalent everywhere:
 wizardflow ui --path run.jsonl
+# --latest: treat the path as a directory (default: the current directory) and
+# open its most recently modified *.jsonl / *.json file — handy right after a
+# run, or to attach to the trace an agent is writing right now:
+wizardflow ui --latest
+wizardflow ui --latest traces/
 ```
 
 The SDK only ever **writes** JSONL, but these commands **read** either framing —
@@ -402,16 +418,22 @@ they stay at parity with the web viewer, which also accepts both.
 ### `wizardflow ui` — local viewer
 
 ```bash
-wizardflow ui run.jsonl [--host 127.0.0.1] [--port 0] [--no-open]
+wizardflow ui run.jsonl [--latest] [--host 127.0.0.1] [--port 0] [--no-open]
 ```
 
 Binds a stdlib HTTP server, serves the static WizardFlow UI bundled in the SDK
-package, and opens the selected trace in your browser (the JSONL is assembled
-server-side and served to the UI as one JSON document, re-read on refresh — so
-you can watch a still-running trace grow).
+package, and opens the selected trace in your browser. The JSONL is assembled
+server-side and served to the UI as one JSON document, re-read on every fetch —
+and the UI **follows a still-running trace live**: it polls the file (cheap
+ETag revalidation; an unchanged file is a single `stat()` on the server) and
+extends the view in place without resetting your selection, playback position,
+or arranged node layout. A pulse dot in the header shows the watch is active;
+messages that arrive while you're inspecting an older one appear as a
+"+N new" chip in the timeline.
 
 | flag | default | meaning |
 | --- | --- | --- |
+| `--latest` | off | treat the path as a directory (default: cwd) and open its most recently modified `*.jsonl` / `*.json` |
 | `--host` | `127.0.0.1` | interface to bind |
 | `--port` | `0` | port to bind; `0` asks the OS for a free port |
 | `--no-open` | off | print the local URL instead of launching a browser |

{wizardflow-0.3.0 → wizardflow-0.5.0}/examples/multibranch.html

@@ -18,6 +18,10 @@ blockquote {
   color: #8a8a8a; font-style: italic;
 }
 table.meta { border-collapse: collapse; font-size: .85rem; margin-bottom: 2rem; }
+section.nodes { margin: -1rem 0 2rem; }
+section.nodes h2 { font-size: 1.05rem; margin: 0 0 .2rem; }
+section.nodes ul { margin: 0; padding-left: 1.2rem; font-size: .9rem; }
+section.nodes li { margin: .15rem 0; }
 table.meta th, table.meta td {
   border: 1px solid #8884; padding: .25rem .6rem; text-align: left;
 }
@@ -27,6 +31,7 @@ section.message {
   padding: .25rem 1rem 1rem; margin-bottom: 1.5rem;
 }
 section.message > h2 { font-size: 1.15rem; margin: .8rem 0 .4rem; }
+section.message > p.msg-meta { font-size: .85rem; color: #8a8a8a; margin: -.2rem 0 .6rem; }
 section.step { padding: .9rem 0; }
 section.step:first-of-type { padding-top: .2rem; }
 /* Divider between consecutive nodes in a message. */
@@ -57,48 +62,60 @@ pre code { background: none; padding: 0; }
 <table class="meta">
 <tr><th>version</th><td>0.2</td></tr>
 </table>
+<section class="nodes">
+<h2>Nodes</h2>
+<ul>
+<li><span class="label">router</span> — Classifies the request and picks a branch: planner or retriever.</li>
+<li><span class="label">planner</span> — Decomposes a tool-using request into concrete tool calls.</li>
+<li><span class="label">retriever</span> — Fetches the most relevant documents for the query.</li>
+<li><span class="label">tool_node</span> — Runs the planned tool calls against external APIs.</li>
+<li><span class="label">generator</span> — Writes the answer from the tool result or retrieved docs.</li>
+</ul>
+</section>
 <section class="message">
 <h2>Weather in Berlin</h2>
+<p class="msg-meta"><span class="label">branch</span>: planner · <span class="label">outcome</span>: answered · <span class="label">latency_ms</span>: 10210</p>
 <section class="step">
-<h3>user_input <span class="time">· 21:39:58</span></h3>
+<h3>user_input <span class="time">· 13:14:05</span></h3>
 <p class="scalar"><span class="label">Input</span> <code>What&#x27;s the weather in Berlin?</code></p>
 </section>
 <section class="step">
-<h3>router <span class="time">· 21:39:58</span></h3>
+<h3>router <span class="time">· 13:14:05</span></h3>
 <p class="scalar"><span class="label">llm_input</span> <code>Pick a route for the request...</code></p>
 <p class="scalar"><span class="label">llm_output</span> <code>{&quot;route&quot;: &quot;planner&quot;, &quot;confidence&quot;: 0.92}</code></p>
 </section>
 <section class="step">
-<h3>planner <span class="time">· 21:39:58</span></h3>
+<h3>planner <span class="time">· 13:14:05</span></h3>
 <p class="scalar"><span class="label">llm_input</span> <code>Decompose into tool calls...</code></p>
 <p class="scalar"><span class="label">llm_output</span> <code>{&quot;plan&quot;: [&quot;weather_api(city=&#x27;Berlin&#x27;)&quot;]}</code></p>
 </section>
 <section class="step">
-<h3>tool_node <span class="time">· 21:39:58</span></h3>
+<h3>tool_node <span class="time">· 13:14:05</span></h3>
 </section>
 <section class="step">
-<h3>generator <span class="time">· 21:39:58</span></h3>
+<h3>generator <span class="time">· 13:14:05</span></h3>
 <p class="scalar"><span class="label">llm_input</span> <code>Answer using the tool result...</code></p>
 <p class="scalar"><span class="label">llm_output</span> <code>It&#x27;s 19C and partly cloudy in Berlin.</code></p>
 </section>
 <section class="step">
-<h3>final_response <span class="time">· 21:39:58</span></h3>
+<h3>final_response <span class="time">· 13:14:05</span></h3>
 <p class="scalar"><span class="label">Output</span> <code>It&#x27;s 19C and partly cloudy in Berlin.</code></p>
 </section>
 </section>
 <section class="message">
 <h2>Summarize research paper</h2>
+<p class="msg-meta"><span class="label">branch</span>: retriever · <span class="label">outcome</span>: answered · <span class="label">docs_used</span>: 2 · <span class="label">latency_ms</span>: 7130</p>
 <section class="step">
-<h3>user_input <span class="time">· 21:39:58</span></h3>
+<h3>user_input <span class="time">· 13:14:05</span></h3>
 <p class="scalar"><span class="label">Input</span> <code>Summarize the attached research paper.</code></p>
 </section>
 <section class="step">
-<h3>router <span class="time">· 21:39:58</span></h3>
+<h3>router <span class="time">· 13:14:05</span></h3>
 <p class="scalar"><span class="label">llm_input</span> <code>Pick a route for the request...</code></p>
 <p class="scalar"><span class="label">llm_output</span> <code>{&quot;route&quot;: &quot;retriever&quot;, &quot;confidence&quot;: 0.88}</code></p>
 </section>
 <section class="step">
-<h3>retriever <span class="time">· 21:39:58</span></h3>
+<h3>retriever <span class="time">· 13:14:05</span></h3>
 <div class="payload"><span class="label">Input</span><pre><code>{
   &quot;topK&quot;: 4,
   &quot;namespace&quot;: &quot;papers&quot;
@@ -115,12 +132,12 @@ pre code { background: none; padding: 0; }
 ]</code></pre></div>
 </section>
 <section class="step">
-<h3>generator <span class="time">· 21:39:58</span></h3>
+<h3>generator <span class="time">· 13:14:05</span></h3>
 <p class="scalar"><span class="label">llm_input</span> <code>Summarize the retrieved documents...</code></p>
 <p class="scalar"><span class="label">llm_output</span> <code>The paper proposes a sparse attention variant with near-linear cost.</code></p>
 </section>
 <section class="step">
-<h3>final_response <span class="time">· 21:39:58</span></h3>
+<h3>final_response <span class="time">· 13:14:05</span></h3>
 <p class="scalar"><span class="label">Output</span> <code>The paper proposes a sparse attention variant with near-linear cost.</code></p>
 </section>
 </section>

{wizardflow-0.3.0 → wizardflow-0.5.0}/examples/multibranch.md

@@ -26,49 +26,59 @@ flowchart TD
     n5 --> n6
 ```
 
+- **router** — Classifies the request and picks a branch: planner or retriever.
+- **planner** — Decomposes a tool-using request into concrete tool calls.
+- **retriever** — Fetches the most relevant documents for the query.
+- **tool_node** — Runs the planned tool calls against external APIs.
+- **generator** — Writes the answer from the tool result or retrieved docs.
+
 ## Weather in Berlin
 
-### user_input · 21:39:58
+**branch**: planner · **outcome**: answered · **latency_ms**: 10210
+
+### user_input · 13:14:05
 
 **Input**: `What's the weather in Berlin?`
 
-### router · 21:39:58
+### router · 13:14:05
 
 **llm_input**: `Pick a route for the request...`
 
 **llm_output**: `{"route": "planner", "confidence": 0.92}`
 
-### planner · 21:39:58
+### planner · 13:14:05
 
 **llm_input**: `Decompose into tool calls...`
 
 **llm_output**: `{"plan": ["weather_api(city='Berlin')"]}`
 
-### tool_node · 21:39:58
+### tool_node · 13:14:05
 
-### generator · 21:39:58
+### generator · 13:14:05
 
 **llm_input**: `Answer using the tool result...`
 
 **llm_output**: `It's 19C and partly cloudy in Berlin.`
 
-### final_response · 21:39:58
+### final_response · 13:14:05
 
 **Output**: `It's 19C and partly cloudy in Berlin.`
 
 ## Summarize research paper
 
-### user_input · 21:39:58
+**branch**: retriever · **outcome**: answered · **docs_used**: 2 · **latency_ms**: 7130
+
+### user_input · 13:14:05
 
 **Input**: `Summarize the attached research paper.`
 
-### router · 21:39:58
+### router · 13:14:05
 
 **llm_input**: `Pick a route for the request...`
 
 **llm_output**: `{"route": "retriever", "confidence": 0.88}`
 
-### retriever · 21:39:58
+### retriever · 13:14:05
 
 **Input**
 
@@ -94,12 +104,12 @@ flowchart TD
 ]
 ```
 
-### generator · 21:39:58
+### generator · 13:14:05
 
 **llm_input**: `Summarize the retrieved documents...`
 
 **llm_output**: `The paper proposes a sparse attention variant with near-linear cost.`
 
-### final_response · 21:39:58
+### final_response · 13:14:05
 
 **Output**: `The paper proposes a sparse attention variant with near-linear cost.`

{wizardflow-0.3.0 → wizardflow-0.5.0}/examples/multibranch.py

@@ -43,6 +43,16 @@ wiz = wizardflow.init(
         ("retriever", "generator"),  # branches rejoin
         ("generator", "final_response"),
     ],
+    # Optional one-line description per node (keyed by id), shown behind an
+    # info icon in the viewer when the node is selected. Plumbing nodes
+    # (user_input, final_response) are intentionally left out.
+    node_descriptions={
+        "router": "Classifies the request and picks a branch: planner or retriever.",
+        "planner": "Decomposes a tool-using request into concrete tool calls.",
+        "retriever": "Fetches the most relevant documents for the query.",
+        "tool_node": "Runs the planned tool calls against external APIs.",
+        "generator": "Writes the answer from the tool result or retrieved docs.",
+    },
 )
 
 # msg-1 — takes the planner / tool branch.
@@ -55,7 +65,14 @@ wizardflow.log("msg-1", "tool_node")  # ran the tool, logged no payload
 wizardflow.log("msg-1", "generator", "llm_input", "Answer using the tool result...")
 wizardflow.log("msg-1", "generator", "llm_output", "It's 19C and partly cloudy in Berlin.")
 wizardflow.log("msg-1", "final_response", "Output", "It's 19C and partly cloudy in Berlin.")
-wizardflow.end_message("msg-1", title="Weather in Berlin")
+# Optional meta: flat facts about the message as a whole (short scalars only),
+# shown on the message's chip in the viewer. Here it records which branch ran
+# and how the run turned out.
+wizardflow.end_message(
+    "msg-1",
+    title="Weather in Berlin",
+    meta={"branch": "planner", "outcome": "answered", "latency_ms": 10210},
+)
 
 # msg-2 — takes the retriever branch (skips planner/tool entirely).
 wizardflow.log("msg-2", "user_input", "Input", "Summarize the attached research paper.")
@@ -71,6 +88,10 @@ wizardflow.log("msg-2", "generator", "llm_output",
                "The paper proposes a sparse attention variant with near-linear cost.")
 wizardflow.log("msg-2", "final_response", "Output",
                "The paper proposes a sparse attention variant with near-linear cost.")
-wizardflow.end_message("msg-2", title="Summarize research paper")
+wizardflow.end_message(
+    "msg-2",
+    title="Summarize research paper",
+    meta={"branch": "retriever", "outcome": "answered", "docs_used": 2, "latency_ms": 7130},
+)
 
 print(f"wrote {wiz.current_path}")

{wizardflow-0.3.0 → wizardflow-0.5.0}/examples/quickstart.html

@@ -18,6 +18,10 @@ blockquote {
   color: #8a8a8a; font-style: italic;
 }
 table.meta { border-collapse: collapse; font-size: .85rem; margin-bottom: 2rem; }
+section.nodes { margin: -1rem 0 2rem; }
+section.nodes h2 { font-size: 1.05rem; margin: 0 0 .2rem; }
+section.nodes ul { margin: 0; padding-left: 1.2rem; font-size: .9rem; }
+section.nodes li { margin: .15rem 0; }
 table.meta th, table.meta td {
   border: 1px solid #8884; padding: .25rem .6rem; text-align: left;
 }
@@ -27,6 +31,7 @@ section.message {
   padding: .25rem 1rem 1rem; margin-bottom: 1.5rem;
 }
 section.message > h2 { font-size: 1.15rem; margin: .8rem 0 .4rem; }
+section.message > p.msg-meta { font-size: .85rem; color: #8a8a8a; margin: -.2rem 0 .6rem; }
 section.step { padding: .9rem 0; }
 section.step:first-of-type { padding-top: .2rem; }
 /* Divider between consecutive nodes in a message. */
@@ -57,33 +62,42 @@ pre code { background: none; padding: 0; }
 <table class="meta">
 <tr><th>version</th><td>0.2</td></tr>
 </table>
+<section class="nodes">
+<h2>Nodes</h2>
+<ul>
+<li><span class="label">router</span> — Classifies the request and picks the next node.</li>
+<li><span class="label">planner</span> — Decomposes the request into concrete tool calls.</li>
+<li><span class="label">tool_node</span> — Runs the planned tool calls against external APIs.</li>
+</ul>
+</section>
 <section class="message">
 <h2>msg-1</h2>
 <section class="step">
-<h3>user_input <span class="time">· 21:39:58</span></h3>
+<h3>user_input <span class="time">· 13:13:58</span></h3>
 <p class="scalar"><span class="label">Input</span> <code>What&#x27;s the weather in Berlin?</code></p>
 </section>
 <section class="step">
-<h3>router <span class="time">· 21:39:58</span></h3>
+<h3>router <span class="time">· 13:13:58</span></h3>
 <p class="scalar"><span class="label">llm_input</span> <code>Route this request...</code></p>
 <p class="scalar"><span class="label">llm_output</span> <code>{&quot;route&quot;: &quot;planner&quot;}</code></p>
 </section>
 <section class="step">
-<h3>tool_node <span class="time">· 21:39:58</span></h3>
+<h3>tool_node <span class="time">· 13:13:58</span></h3>
 </section>
 <section class="step">
-<h3>final_response <span class="time">· 21:39:58</span></h3>
+<h3>final_response <span class="time">· 13:13:58</span></h3>
 <p class="scalar"><span class="label">Output</span> <code>It&#x27;s 19C and partly cloudy in Berlin.</code></p>
 </section>
 </section>
 <section class="message">
 <h2>Summarize the paper</h2>
+<p class="msg-meta"><span class="label">outcome</span>: answered · <span class="label">latency_ms</span>: 320</p>
 <section class="step">
-<h3>user_input <span class="time">· 21:39:58</span></h3>
+<h3>user_input <span class="time">· 13:13:58</span></h3>
 <p class="scalar"><span class="label">Input</span> <code>Summarize the paper.</code></p>
 </section>
 <section class="step">
-<h3>router <span class="time">· 21:39:58</span></h3>
+<h3>router <span class="time">· 13:13:58</span></h3>
 <p class="scalar"><span class="label">llm_output</span> <code>{&quot;route&quot;: &quot;planner&quot;}</code></p>
 </section>
 </section>

{wizardflow-0.3.0 → wizardflow-0.5.0}/examples/quickstart.md

@@ -21,30 +21,36 @@ flowchart TD
     n3 --> n4
 ```
 
+- **router** — Classifies the request and picks the next node.
+- **planner** — Decomposes the request into concrete tool calls.
+- **tool_node** — Runs the planned tool calls against external APIs.
+
 ## msg-1
 
-### user_input · 21:39:58
+### user_input · 13:13:58
 
 **Input**: `What's the weather in Berlin?`
 
-### router · 21:39:58
+### router · 13:13:58
 
 **llm_input**: `Route this request...`
 
 **llm_output**: `{"route": "planner"}`
 
-### tool_node · 21:39:58
+### tool_node · 13:13:58
 
-### final_response · 21:39:58
+### final_response · 13:13:58
 
 **Output**: `It's 19C and partly cloudy in Berlin.`
 
 ## Summarize the paper
 
-### user_input · 21:39:58
+**outcome**: answered · **latency_ms**: 320
+
+### user_input · 13:13:58
 
 **Input**: `Summarize the paper.`
 
-### router · 21:39:58
+### router · 13:13:58
 
 **llm_output**: `{"route": "planner"}`

{wizardflow-0.3.0 → wizardflow-0.5.0}/examples/quickstart.py

@@ -26,6 +26,15 @@ wiz = wizardflow.init(
         ("planner", "tool_node"),
         ("tool_node", "final_response"),
     ],
+    # Optional: a one-line description per node, keyed by node id. It shows
+    # behind an info icon in the viewer when the node is selected. Plumbing
+    # nodes (user_input, final_response) are left out on purpose — not every
+    # node needs one.
+    node_descriptions={
+        "router": "Classifies the request and picks the next node.",
+        "planner": "Decomposes the request into concrete tool calls.",
+        "tool_node": "Runs the planned tool calls against external APIs.",
+    },
 )
 
 # Message 1 — each log names its message ("msg-1") in the first argument.
@@ -36,10 +45,16 @@ wizardflow.log("msg-1", "tool_node")  # visited, no payloads
 wizardflow.log("msg-1", "final_response", "Output", "It's 19C and partly cloudy in Berlin.")
 wizardflow.end_message("msg-1")  # <- writes the file; msg-1 is now persisted
 
-# Message 2 — same shape; an optional title gives the message a human title.
+# Message 2 — same shape; an optional title gives the message a human title,
+# and optional meta attaches flat facts about the message as a whole (shown on
+# the message's chip in the viewer). Keep meta values short scalars.
 wizardflow.log("msg-2", "user_input", "Input", "Summarize the paper.")
 wizardflow.log("msg-2", "router", "llm_output", '{"route": "planner"}')
-wizardflow.end_message("msg-2", title="Summarize the paper")
+wizardflow.end_message(
+    "msg-2",
+    title="Summarize the paper",
+    meta={"outcome": "answered", "latency_ms": 320},
+)
 # -> the part file now contains msg-1 and msg-2
 
 print(f"wrote {wiz.current_path}")

{wizardflow-0.3.0 → wizardflow-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wizardflow"
-version = "0.3.0"
+version = "0.5.0"
 description = "Python SDK for recording agent flows into the WizardFlow / AgentTrace file format."
 readme = "README.md"
 requires-python = ">=3.9"