wizardflow 0.2.0__tar.gz → 0.4.0__tar.gz

{wizardflow-0.2.0 → wizardflow-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wizardflow
-Version: 0.2.0
+Version: 0.4.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=university-consultant)** —
+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
@@ -98,6 +102,8 @@ No runtime dependencies. Developing the SDK itself? See
 ## Quickstart
 
 ```python
+import uuid
+
 import wizardflow
 
 wizardflow.init(
@@ -110,10 +116,11 @@ wizardflow.init(
 
 # Every log names its message in the first argument:
 # log(message_id, node, payload_label, payload_value)
-wizardflow.log("msg-1", "router", "llm_input", prompt)    # same node, two payloads ->
-wizardflow.log("msg-1", "router", "llm_output", output)   #   folded into one step
-wizardflow.log("msg-1", "tool_node")                       # visited, no payloads
-wizardflow.end_message("msg-1")                            # -> writes the trace
+msg_id = str(uuid.uuid4())                                # one fresh id per message
+wizardflow.log(msg_id, "router", "llm_input", prompt)     # same node, two payloads ->
+wizardflow.log(msg_id, "router", "llm_output", output)    #   folded into one step
+wizardflow.log(msg_id, "tool_node")                       # visited, no payloads
+wizardflow.end_message(msg_id)                            # -> writes the trace
 ```
 
 There is **no `save()`** and no autosave: `log()` only accumulates in memory,
@@ -147,7 +154,88 @@ 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
+
+A message is **one unit of work** — one user turn, one run through the graph.
+Its id only has to be unique within the run, and it **cannot be reused** once
+`end_message` has been called on it. The simplest safe choice is a fresh UUID
+per message:
+
+```python
+import uuid
+
+msg_id = str(uuid.uuid4())
+```
+
+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'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.
+
+## One flow, or several at once
+
+`init()` installs the client it returns as the module default. With a single
+flow — the common case — **ignore the return value** and call
+`wizardflow.log(...)` / `wizardflow.end_message(...)` directly: they work from
+any module, with no handle to thread through your code.
+
+Running several agent flows side by side (say, a doctor flow and a patient
+flow) means several traces, and each needs its own instance. Keep the returned
+client per flow and log through it — and name it **`tracer`**, not `client`,
+since `client` in an agent codebase is almost always the LLM client:
+
+```python
+doctor_tracer  = wizardflow.init(file_prefix="doctor",  nodes=[...], edges=[...])
+patient_tracer = wizardflow.init(file_prefix="patient", nodes=[...], edges=[...])
+
+doctor_tracer.log(doc_msg, "diagnose", "llm_input", prompt)
+patient_tracer.log(pat_msg, "intake", "llm_input", prompt)
+```
+
+With more than one tracer, don't mix in the bare module-level calls:
+`wizardflow.log(...)` always targets the most recently initialized tracer.
+
+## Node descriptions, labels & colors
+
+Nodes can carry a short human description of what they do. In the viewer it
+stays out of the way: when a node is selected, a small info icon appears next
+to its name in the inspector — click it to read the description. Nodes without
+one show no icon, and `wizardflow md` / `wizardflow html` list the described
+nodes under the graph.
+
+```python
+wizardflow.init(
+    nodes=["router", "retriever", "generator"],
+    edges=[("router", "retriever"), ("retriever", "generator")],
+    node_descriptions={
+        "router": "Chooses the next step.",
+        "retriever": "Fetches relevant documents.",
+        "generator": "Writes the final answer.",
+    },
+)
+```
+
+Two sibling kwargs work the same way: `node_labels` maps ids to the display
+name the viewer shows instead of the raw id (especially useful with
+`init_from_langgraph`, where the extracted ids are your function names), and
+`node_colors` sets accent colors. All three are validated against the declared
+nodes: an unknown id raises a `WizardFlowError` at `init()` time so typos fail
+fast; with `silent=True` it is logged as a warning on the `wizardflow` logger
+and skipped instead. All three also work on `init_from_langgraph`, where they
+attach to the extracted node ids — `log()` always targets the **id**, never
+the label.
 
 ## LangGraph: automatic topology
 
@@ -180,8 +268,8 @@ wizardflow.init_from_langgraph(
 ```
 
 By default, a color key that does not match an extracted node id raises a
-`WizardFlowError` so typos fail fast. With `silent=True`, unknown color keys are
-ignored.
+`WizardFlowError` so typos fail fast. With `silent=True`, unknown color keys
+are skipped and logged as a warning instead.
 
 It extracts node ids (keeping `__start__` / `__end__`) and directed edges, and
 marks runtime branches with `"conditional": true` (deterministic and parallel
@@ -202,30 +290,39 @@ A non-LangGraph object raises `LangGraphExtractionError`; missing conditional
 metadata never fails extraction (the edge is just emitted plain). Call it
 **after `compile()`**, when the topology actually exists.
 
-## API (v0.2)
+## API
 
-> **Breaking change in 0.2:** traces are now JSON Lines (`.jsonl`), written by
-> appending — the old single-document `.json` format is gone from the SDK
-> (writer *and* CLI readers). The web UI at getwizardflow.com still opens old
-> `.json` traces.
-
-- `init(output_dir=, file_prefix="wizardflow", name=, description=, nodes=, edges=, meta=, silent=False, max_bytes=16_000_000, max_messages=2_000) -> Client`
+- `init(output_dir=, file_prefix="wizardflow", name=, description=, nodes=, edges=, node_labels=, node_colors=, node_descriptions=, meta=, silent=False, max_bytes=16_000_000, max_messages=2_000) -> Client`
   - `description` lands in `meta.description` (matches the schema field).
   - `nodes=` enables fast-fail: `log()` to an undeclared node raises
     `UnknownNodeError` immediately (unless silenced).
+  - `node_labels` / `node_colors` / `node_descriptions` map declared node ids
+    to a display name / CSS color / short description; an unknown id raises
+    unless silenced (then it's logged as a warning and skipped).
   - `output_dir` is optional; omitted, traces are written in cwd.
   - `file_prefix` is optional; omitted, filenames start with `wizardflow`.
   - `max_bytes` / `max_messages` cap each part file before rotation (see below).
-- `init_from_langgraph(app, output_dir=, file_prefix="wizardflow", name=, description=, meta=, node_colors=, silent=False, max_bytes=..., max_messages=...) -> Client`
+- `init_from_langgraph(app, output_dir=, file_prefix="wizardflow", name=, description=, meta=, node_labels=, node_colors=, node_descriptions=, silent=False, max_bytes=..., max_messages=...) -> Client`
   - same as `init`, but `nodes`/`edges` come from `app.get_graph()`.
-  - `node_colors` maps extracted node ids to CSS colors such as `"#A78BFA"`.
+  - `node_labels` renames extracted ids for display (they're your function
+    names); `node_colors` maps them to CSS colors such as `"#A78BFA"`;
+    `node_descriptions` to short descriptions.
 - `log(id, node, label=None, content=None)` — the first positional is the
   **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
+  new day. The old file is left as-is (**no seal**: it's a finished run, not a
+  rotated part). Open messages carry over and are written wherever they end;
+  completed message ids become reusable. `name`/`description`/`meta` replace
+  the current values when given. Returns the new trace path.
 - `Client.current_path` — the trace file currently being written.
 - `to_dict()` / `to_json()` — inspect the active part (completed messages),
   assembled into one `AgentTraceFile` object.
@@ -251,6 +348,10 @@ unparseable final line (a crash mid-append leaves a torn tail; everything
 before it is intact). Only **completed** messages are written; an in-progress
 message lives in memory until it ends.
 
+> Early SDK versions (0.1) wrote a trace as one single-document `.json` file
+> instead. Newer versions write JSONL only, but every reader — the CLI
+> subcommands and the web UI at getwizardflow.com — still opens both formats.
+
 ### How saving works
 
 `end_message` **appends one line** to the active part — O(1) no matter how
@@ -312,6 +413,20 @@ Consecutive `log()` calls to the **same** node within a message fold into a
 single step with multiple payloads (e.g. a router step carrying both
 `llm_input` and `llm_output`). A `log()` to a different node starts a new step.
 
+## What to log (conventions)
+
+Payload labels are free-form strings — the schema reserves none of them. These
+conventions just keep traces consistent and readable:
+
+- **LLM-backed nodes** — log the exact prompt as `llm_input` and the raw
+  completion as `llm_output`. When a run goes wrong, the trace then shows
+  precisely what the model saw and what it said — most of what you need to
+  debug an agent — and step folding merges the pair into one step.
+- **Everything else** — log the node's real domain data under honest labels: a
+  retriever logs its `query` and `results`, a tool node `tool_input` and
+  `tool_output`, a deterministic router its `decision`. Don't force
+  `llm_input`/`llm_output` onto nodes that never call a model.
+
 ## Examples
 
 Fuller runnable examples live in

{wizardflow-0.2.0 → wizardflow-0.4.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=university-consultant)** —
+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
@@ -51,6 +55,8 @@ No runtime dependencies. Developing the SDK itself? See
 ## Quickstart
 
 ```python
+import uuid
+
 import wizardflow
 
 wizardflow.init(
@@ -63,10 +69,11 @@ wizardflow.init(
 
 # Every log names its message in the first argument:
 # log(message_id, node, payload_label, payload_value)
-wizardflow.log("msg-1", "router", "llm_input", prompt)    # same node, two payloads ->
-wizardflow.log("msg-1", "router", "llm_output", output)   #   folded into one step
-wizardflow.log("msg-1", "tool_node")                       # visited, no payloads
-wizardflow.end_message("msg-1")                            # -> writes the trace
+msg_id = str(uuid.uuid4())                                # one fresh id per message
+wizardflow.log(msg_id, "router", "llm_input", prompt)     # same node, two payloads ->
+wizardflow.log(msg_id, "router", "llm_output", output)    #   folded into one step
+wizardflow.log(msg_id, "tool_node")                       # visited, no payloads
+wizardflow.end_message(msg_id)                            # -> writes the trace
 ```
 
 There is **no `save()`** and no autosave: `log()` only accumulates in memory,
@@ -100,7 +107,88 @@ 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
+
+A message is **one unit of work** — one user turn, one run through the graph.
+Its id only has to be unique within the run, and it **cannot be reused** once
+`end_message` has been called on it. The simplest safe choice is a fresh UUID
+per message:
+
+```python
+import uuid
+
+msg_id = str(uuid.uuid4())
+```
+
+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'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.
+
+## One flow, or several at once
+
+`init()` installs the client it returns as the module default. With a single
+flow — the common case — **ignore the return value** and call
+`wizardflow.log(...)` / `wizardflow.end_message(...)` directly: they work from
+any module, with no handle to thread through your code.
+
+Running several agent flows side by side (say, a doctor flow and a patient
+flow) means several traces, and each needs its own instance. Keep the returned
+client per flow and log through it — and name it **`tracer`**, not `client`,
+since `client` in an agent codebase is almost always the LLM client:
+
+```python
+doctor_tracer  = wizardflow.init(file_prefix="doctor",  nodes=[...], edges=[...])
+patient_tracer = wizardflow.init(file_prefix="patient", nodes=[...], edges=[...])
+
+doctor_tracer.log(doc_msg, "diagnose", "llm_input", prompt)
+patient_tracer.log(pat_msg, "intake", "llm_input", prompt)
+```
+
+With more than one tracer, don't mix in the bare module-level calls:
+`wizardflow.log(...)` always targets the most recently initialized tracer.
+
+## Node descriptions, labels & colors
+
+Nodes can carry a short human description of what they do. In the viewer it
+stays out of the way: when a node is selected, a small info icon appears next
+to its name in the inspector — click it to read the description. Nodes without
+one show no icon, and `wizardflow md` / `wizardflow html` list the described
+nodes under the graph.
+
+```python
+wizardflow.init(
+    nodes=["router", "retriever", "generator"],
+    edges=[("router", "retriever"), ("retriever", "generator")],
+    node_descriptions={
+        "router": "Chooses the next step.",
+        "retriever": "Fetches relevant documents.",
+        "generator": "Writes the final answer.",
+    },
+)
+```
+
+Two sibling kwargs work the same way: `node_labels` maps ids to the display
+name the viewer shows instead of the raw id (especially useful with
+`init_from_langgraph`, where the extracted ids are your function names), and
+`node_colors` sets accent colors. All three are validated against the declared
+nodes: an unknown id raises a `WizardFlowError` at `init()` time so typos fail
+fast; with `silent=True` it is logged as a warning on the `wizardflow` logger
+and skipped instead. All three also work on `init_from_langgraph`, where they
+attach to the extracted node ids — `log()` always targets the **id**, never
+the label.
 
 ## LangGraph: automatic topology
 
@@ -133,8 +221,8 @@ wizardflow.init_from_langgraph(
 ```
 
 By default, a color key that does not match an extracted node id raises a
-`WizardFlowError` so typos fail fast. With `silent=True`, unknown color keys are
-ignored.
+`WizardFlowError` so typos fail fast. With `silent=True`, unknown color keys
+are skipped and logged as a warning instead.
 
 It extracts node ids (keeping `__start__` / `__end__`) and directed edges, and
 marks runtime branches with `"conditional": true` (deterministic and parallel
@@ -155,30 +243,39 @@ A non-LangGraph object raises `LangGraphExtractionError`; missing conditional
 metadata never fails extraction (the edge is just emitted plain). Call it
 **after `compile()`**, when the topology actually exists.
 
-## API (v0.2)
+## API
 
-> **Breaking change in 0.2:** traces are now JSON Lines (`.jsonl`), written by
-> appending — the old single-document `.json` format is gone from the SDK
-> (writer *and* CLI readers). The web UI at getwizardflow.com still opens old
-> `.json` traces.
-
-- `init(output_dir=, file_prefix="wizardflow", name=, description=, nodes=, edges=, meta=, silent=False, max_bytes=16_000_000, max_messages=2_000) -> Client`
+- `init(output_dir=, file_prefix="wizardflow", name=, description=, nodes=, edges=, node_labels=, node_colors=, node_descriptions=, meta=, silent=False, max_bytes=16_000_000, max_messages=2_000) -> Client`
   - `description` lands in `meta.description` (matches the schema field).
   - `nodes=` enables fast-fail: `log()` to an undeclared node raises
     `UnknownNodeError` immediately (unless silenced).
+  - `node_labels` / `node_colors` / `node_descriptions` map declared node ids
+    to a display name / CSS color / short description; an unknown id raises
+    unless silenced (then it's logged as a warning and skipped).
   - `output_dir` is optional; omitted, traces are written in cwd.
   - `file_prefix` is optional; omitted, filenames start with `wizardflow`.
   - `max_bytes` / `max_messages` cap each part file before rotation (see below).
-- `init_from_langgraph(app, output_dir=, file_prefix="wizardflow", name=, description=, meta=, node_colors=, silent=False, max_bytes=..., max_messages=...) -> Client`
+- `init_from_langgraph(app, output_dir=, file_prefix="wizardflow", name=, description=, meta=, node_labels=, node_colors=, node_descriptions=, silent=False, max_bytes=..., max_messages=...) -> Client`
   - same as `init`, but `nodes`/`edges` come from `app.get_graph()`.
-  - `node_colors` maps extracted node ids to CSS colors such as `"#A78BFA"`.
+  - `node_labels` renames extracted ids for display (they're your function
+    names); `node_colors` maps them to CSS colors such as `"#A78BFA"`;
+    `node_descriptions` to short descriptions.
 - `log(id, node, label=None, content=None)` — the first positional is the
   **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
+  new day. The old file is left as-is (**no seal**: it's a finished run, not a
+  rotated part). Open messages carry over and are written wherever they end;
+  completed message ids become reusable. `name`/`description`/`meta` replace
+  the current values when given. Returns the new trace path.
 - `Client.current_path` — the trace file currently being written.
 - `to_dict()` / `to_json()` — inspect the active part (completed messages),
   assembled into one `AgentTraceFile` object.
@@ -204,6 +301,10 @@ unparseable final line (a crash mid-append leaves a torn tail; everything
 before it is intact). Only **completed** messages are written; an in-progress
 message lives in memory until it ends.
 
+> Early SDK versions (0.1) wrote a trace as one single-document `.json` file
+> instead. Newer versions write JSONL only, but every reader — the CLI
+> subcommands and the web UI at getwizardflow.com — still opens both formats.
+
 ### How saving works
 
 `end_message` **appends one line** to the active part — O(1) no matter how
@@ -265,6 +366,20 @@ Consecutive `log()` calls to the **same** node within a message fold into a
 single step with multiple payloads (e.g. a router step carrying both
 `llm_input` and `llm_output`). A `log()` to a different node starts a new step.
 
+## What to log (conventions)
+
+Payload labels are free-form strings — the schema reserves none of them. These
+conventions just keep traces consistent and readable:
+
+- **LLM-backed nodes** — log the exact prompt as `llm_input` and the raw
+  completion as `llm_output`. When a run goes wrong, the trace then shows
+  precisely what the model saw and what it said — most of what you need to
+  debug an agent — and step folding merges the pair into one step.
+- **Everything else** — log the node's real domain data under honest labels: a
+  retriever logs its `query` and `results`, a tool node `tool_input` and
+  `tool_output`, a deterministic router its `decision`. Don't force
+  `llm_input`/`llm_output` onto nodes that never call a model.
+
 ## Examples
 
 Fuller runnable examples live in

{wizardflow-0.2.0 → wizardflow-0.4.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.2.0 → wizardflow-0.4.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.`