wizardflow 0.6.7__tar.gz → 0.7.0__tar.gz

{wizardflow-0.6.7 → wizardflow-0.7.0}/.gitignore

@@ -5,6 +5,7 @@ __pycache__/
 build/
 dist/
 .pytest_cache/
+.test-tmp/
 .venv/
 venv/
 # uv resolves this in CI (uv run / uv build); a zero-dependency library doesn't

wizardflow-0.7.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.5
+Name: wizardflow
+Version: 0.7.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
+Author: Leon Koch
+License: MIT License
+        
+        Copyright (c) 2026 Leon Koch
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agents,langgraph,llm,observability,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# WizardFlow Python SDK
+
+**A lightweight recorder for Python agents.** WizardFlow turns an agent run
+into a portable WizardFlow JSONL file that you can replay as an interactive
+graph, inspect with ordinary tools, or attach to a bug report.
+
+Drop the file into [getwizardflow.com](https://getwizardflow.com) and it is
+processed entirely in the browser—nothing is uploaded. You can also replay it
+locally with `wizardflow ui`.
+
+![WizardFlow replaying an agent run](https://raw.githubusercontent.com/lkleonk/wizardflow/main/sdk/python/assets/demo.gif)
+
+â–¶ **[Watch this run replay](https://getwizardflow.com/?example=doctor-consultation)**
+
+## Why WizardFlow?
+
+- **The trace is a file.** Commit, diff, grep, archive, or share it without an
+  observability account.
+- **Replay it anywhere.** Use the bundled local viewer or the fully client-side
+  hosted viewer.
+- **Zero runtime dependencies.** The base SDK is pure Python and requires no
+  daemon or framework.
+- **Explicit by design.** Your code chooses which node executions and values
+  enter the trace.
+- **OpenTelemetry is optional.** The same node executions can also be projected
+  to OTLP-compatible observability backends.
+
+## Install
+
+```bash
+pip install wizardflow
+```
+
+## Quickstart
+
+```python
+import uuid
+
+import wizardflow
+
+trace = wizardflow.init(
+    output_dir="traces",
+    file_prefix="run",
+    nodes=["generator"],
+)
+
+message_id = str(uuid.uuid4())
+input_value = ...
+
+with trace.node(message_id, "generator") as node:
+    node.log_input(input_value)
+    output_value = ...
+    node.log_output(output_value)
+
+trace_path = trace.end_message(message_id)
+print(trace_path)
+```
+
+`trace.node(...)` records the node's execution interval. `log_input()` and
+`log_output()` preserve their JSON-compatible values in the trace, and
+`end_message()` appends the completed message to JSONL. There is no separate
+`save()` call.
+
+Drop `trace_path` into [getwizardflow.com](https://getwizardflow.com), or open
+it locally:
+
+```bash
+wizardflow ui traces/run__<timestamp>.jsonl
+```
+
+The module-level style remains available for applications that use one default
+trace:
+
+```python
+wizardflow.init(nodes=["generator"])
+
+with wizardflow.node("msg-1", "generator") as node:
+    node.log_input(input_value)
+    node.log_output(output_value)
+
+wizardflow.end_message("msg-1")
+```
+
+## Optional OpenTelemetry export
+
+Install the optional OTel packages directly:
+
+```bash
+pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
+```
+
+Then enable OTLP trace export while retaining JSONL as the portable source of
+truth:
+
+```python
+trace = wizardflow.init(
+    nodes=["generator"],
+    name="my-agent",
+    otel=True,
+    otel_endpoint="http://localhost:4318/v1/traces",
+    otel_trace_scope="message",
+)
+
+with trace.node("msg-1", "generator", kind="llm") as node:
+    node.log_input(input_value)
+    node.log_output(output_value)
+
+trace.end_message("msg-1")
+trace.close_otel()
+```
+
+Generic logs can optionally choose an exact application-owned span attribute
+without changing their JSONL/UI label:
+
+```python
+node.log("quality", 0.92, otel_attribute="app.response.quality")
+```
+
+Content export is privacy-conscious and disabled by default. See the
+[OpenTelemetry guide](https://github.com/lkleonk/wizardflow/blob/main/sdk/python/docs/opentelemetry.md)
+for provider ownership, GenAI mappings, content controls, graph events, and
+independent JSONL/OTel lifecycles. Existing artifacts can be exported later:
+
+```bash
+wizardflow otel export run.jsonl --endpoint http://localhost:4318/v1/traces
+```
+
+## LangGraph topology
+
+WizardFlow can read nodes and edges from a compiled LangGraph application
+without importing LangGraph itself:
+
+```python
+trace = wizardflow.init_from_langgraph(
+    compiled_app,
+    output_dir="traces",
+    file_prefix="run",
+)
+```
+
+Runtime recording then uses the same `trace.node(...)` API. Extraction is
+duck-typed through `app.get_graph()`.
+
+## Documentation
+
+- **[Recording agent runs](https://github.com/lkleonk/wizardflow/blob/main/sdk/python/docs/recording.md)**
+  — messages, node scopes, semantic records, generic logs, kinds, output
+  selection, multiple clients, and reinitialization.
+- **[OpenTelemetry export](https://github.com/lkleonk/wizardflow/blob/main/sdk/python/docs/opentelemetry.md)**
+  — OTLP setup, provider ownership, GenAI mappings, privacy controls, graph
+  events, offline JSONL export, and cleanup.
+- **[WizardFlow JSONL format](https://github.com/lkleonk/wizardflow/blob/main/sdk/python/docs/jsonl-file-format.md)**
+  — record shapes, semantic fields, compatibility, and rotation.
+- **[CLI and local viewer](https://github.com/lkleonk/wizardflow/blob/main/sdk/python/docs/cli.md)**
+  — live local replay and Markdown, HTML, and JSON export.
+
+## CLI at a glance
+
+```bash
+wizardflow ui run.jsonl              # interactive local replay
+wizardflow ui --latest traces/       # newest trace in a directory
+wizardflow md run.jsonl -o run.md    # Markdown export
+wizardflow html run.jsonl -o run.html
+wizardflow json run.jsonl -o run.json
+```
+
+All commands read both WizardFlow JSONL and the single-document JSON form. See
+the [CLI guide](https://github.com/lkleonk/wizardflow/blob/main/sdk/python/docs/cli.md)
+for flags, live-trace behavior, and rotated-part navigation.
+
+## Examples
+
+Runnable examples live in
+[`examples/`](https://github.com/lkleonk/wizardflow/tree/main/sdk/python/examples):
+
+- `quickstart.py` records a small linear flow.
+- `multibranch.py` records two messages that take different graph branches.
+
+## Development
+
+See
+[CONTRIBUTING.md](https://github.com/lkleonk/wizardflow/blob/main/sdk/python/CONTRIBUTING.md)
+for local tests and maintainer workflows.

wizardflow-0.7.0/README.md

@@ -0,0 +1,183 @@
+# WizardFlow Python SDK
+
+**A lightweight recorder for Python agents.** WizardFlow turns an agent run
+into a portable WizardFlow JSONL file that you can replay as an interactive
+graph, inspect with ordinary tools, or attach to a bug report.
+
+Drop the file into [getwizardflow.com](https://getwizardflow.com) and it is
+processed entirely in the browser—nothing is uploaded. You can also replay it
+locally with `wizardflow ui`.
+
+![WizardFlow replaying an agent run](https://raw.githubusercontent.com/lkleonk/wizardflow/main/sdk/python/assets/demo.gif)
+
+â–¶ **[Watch this run replay](https://getwizardflow.com/?example=doctor-consultation)**
+
+## Why WizardFlow?
+
+- **The trace is a file.** Commit, diff, grep, archive, or share it without an
+  observability account.
+- **Replay it anywhere.** Use the bundled local viewer or the fully client-side
+  hosted viewer.
+- **Zero runtime dependencies.** The base SDK is pure Python and requires no
+  daemon or framework.
+- **Explicit by design.** Your code chooses which node executions and values
+  enter the trace.
+- **OpenTelemetry is optional.** The same node executions can also be projected
+  to OTLP-compatible observability backends.
+
+## Install
+
+```bash
+pip install wizardflow
+```
+
+## Quickstart
+
+```python
+import uuid
+
+import wizardflow
+
+trace = wizardflow.init(
+    output_dir="traces",
+    file_prefix="run",
+    nodes=["generator"],
+)
+
+message_id = str(uuid.uuid4())
+input_value = ...
+
+with trace.node(message_id, "generator") as node:
+    node.log_input(input_value)
+    output_value = ...
+    node.log_output(output_value)
+
+trace_path = trace.end_message(message_id)
+print(trace_path)
+```
+
+`trace.node(...)` records the node's execution interval. `log_input()` and
+`log_output()` preserve their JSON-compatible values in the trace, and
+`end_message()` appends the completed message to JSONL. There is no separate
+`save()` call.
+
+Drop `trace_path` into [getwizardflow.com](https://getwizardflow.com), or open
+it locally:
+
+```bash
+wizardflow ui traces/run__<timestamp>.jsonl
+```
+
+The module-level style remains available for applications that use one default
+trace:
+
+```python
+wizardflow.init(nodes=["generator"])
+
+with wizardflow.node("msg-1", "generator") as node:
+    node.log_input(input_value)
+    node.log_output(output_value)
+
+wizardflow.end_message("msg-1")
+```
+
+## Optional OpenTelemetry export
+
+Install the optional OTel packages directly:
+
+```bash
+pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
+```
+
+Then enable OTLP trace export while retaining JSONL as the portable source of
+truth:
+
+```python
+trace = wizardflow.init(
+    nodes=["generator"],
+    name="my-agent",
+    otel=True,
+    otel_endpoint="http://localhost:4318/v1/traces",
+    otel_trace_scope="message",
+)
+
+with trace.node("msg-1", "generator", kind="llm") as node:
+    node.log_input(input_value)
+    node.log_output(output_value)
+
+trace.end_message("msg-1")
+trace.close_otel()
+```
+
+Generic logs can optionally choose an exact application-owned span attribute
+without changing their JSONL/UI label:
+
+```python
+node.log("quality", 0.92, otel_attribute="app.response.quality")
+```
+
+Content export is privacy-conscious and disabled by default. See the
+[OpenTelemetry guide](https://github.com/lkleonk/wizardflow/blob/main/sdk/python/docs/opentelemetry.md)
+for provider ownership, GenAI mappings, content controls, graph events, and
+independent JSONL/OTel lifecycles. Existing artifacts can be exported later:
+
+```bash
+wizardflow otel export run.jsonl --endpoint http://localhost:4318/v1/traces
+```
+
+## LangGraph topology
+
+WizardFlow can read nodes and edges from a compiled LangGraph application
+without importing LangGraph itself:
+
+```python
+trace = wizardflow.init_from_langgraph(
+    compiled_app,
+    output_dir="traces",
+    file_prefix="run",
+)
+```
+
+Runtime recording then uses the same `trace.node(...)` API. Extraction is
+duck-typed through `app.get_graph()`.
+
+## Documentation
+
+- **[Recording agent runs](https://github.com/lkleonk/wizardflow/blob/main/sdk/python/docs/recording.md)**
+  — messages, node scopes, semantic records, generic logs, kinds, output
+  selection, multiple clients, and reinitialization.
+- **[OpenTelemetry export](https://github.com/lkleonk/wizardflow/blob/main/sdk/python/docs/opentelemetry.md)**
+  — OTLP setup, provider ownership, GenAI mappings, privacy controls, graph
+  events, offline JSONL export, and cleanup.
+- **[WizardFlow JSONL format](https://github.com/lkleonk/wizardflow/blob/main/sdk/python/docs/jsonl-file-format.md)**
+  — record shapes, semantic fields, compatibility, and rotation.
+- **[CLI and local viewer](https://github.com/lkleonk/wizardflow/blob/main/sdk/python/docs/cli.md)**
+  — live local replay and Markdown, HTML, and JSON export.
+
+## CLI at a glance
+
+```bash
+wizardflow ui run.jsonl              # interactive local replay
+wizardflow ui --latest traces/       # newest trace in a directory
+wizardflow md run.jsonl -o run.md    # Markdown export
+wizardflow html run.jsonl -o run.html
+wizardflow json run.jsonl -o run.json
+```
+
+All commands read both WizardFlow JSONL and the single-document JSON form. See
+the [CLI guide](https://github.com/lkleonk/wizardflow/blob/main/sdk/python/docs/cli.md)
+for flags, live-trace behavior, and rotated-part navigation.
+
+## Examples
+
+Runnable examples live in
+[`examples/`](https://github.com/lkleonk/wizardflow/tree/main/sdk/python/examples):
+
+- `quickstart.py` records a small linear flow.
+- `multibranch.py` records two messages that take different graph branches.
+
+## Development
+
+See
+[CONTRIBUTING.md](https://github.com/lkleonk/wizardflow/blob/main/sdk/python/CONTRIBUTING.md)
+for local tests and maintainer workflows.

wizardflow-0.7.0/docs/cli.md

@@ -0,0 +1,118 @@
+# CLI and local viewer
+
+The `wizardflow` command reads both WizardFlow JSONL parts and the legacy
+single-document JSON representation.
+
+## Selecting a trace
+
+Every subcommand accepts a trace as a positional argument or through `--path`:
+
+```bash
+wizardflow ui run.jsonl
+wizardflow ui --path run.jsonl
+```
+
+Use `--latest` to select the most recently modified `.jsonl` or `.json` file in
+a directory:
+
+```bash
+wizardflow ui --latest
+wizardflow ui --latest traces/
+```
+
+## Local interactive viewer
+
+```bash
+wizardflow ui run.jsonl [--host 127.0.0.1] [--port 0] [--no-open]
+```
+
+This starts a standard-library HTTP server and serves the static WizardFlow UI
+bundled in the package.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `--latest` | off | Treat the path as a directory and choose its newest trace |
+| `--host` | `127.0.0.1` | Interface to bind |
+| `--port` | `0` | Port to bind; zero asks the OS for a free port |
+| `--no-open` | off | Print the URL instead of opening a browser |
+
+The viewer follows a growing active part using ETag revalidation. Polling pauses
+while the tab is hidden and stops when the part gains `nextPart`, because a
+sealed part no longer grows. Part navigation loads neighboring files rather
+than stitching the entire rotation chain into one timeline.
+
+## Markdown export
+
+```bash
+wizardflow md run.jsonl
+wizardflow md run.jsonl -o run.md
+wizardflow md run.jsonl --no-mermaid
+```
+
+Markdown output includes metadata, an optional Mermaid graph, messages, steps,
+and payloads.
+
+| Option | Meaning |
+| --- | --- |
+| `-o`, `--output` | Write to a file instead of stdout |
+| `--mermaid` | Include the graph diagram; enabled by default |
+| `--no-mermaid` | Omit the graph diagram |
+
+## HTML export
+
+```bash
+wizardflow html run.jsonl
+wizardflow html run.jsonl -o run.html
+```
+
+This produces one self-contained document with inline CSS, no JavaScript, and
+no external assets. It renders messages and payloads; use Markdown when a graph
+diagram is required.
+
+## Assemble JSONL into JSON
+
+```bash
+wizardflow json run.jsonl
+wizardflow json run.jsonl -o run.json
+```
+
+This assembles the selected part's header and message records into one
+pretty-printed WizardFlow trace. A seal's `nextPart` is folded into metadata. It
+does not combine an entire rotation chain.
+
+## Export JSONL to OpenTelemetry
+
+```bash
+wizardflow otel export run.jsonl --endpoint http://localhost:4318/v1/traces
+wizardflow otel export run.jsonl --trace-scope message
+```
+
+This projects an existing artifact through OTLP/HTTP using the same semantic
+mapping as live export. It creates fresh OTel trace IDs and never modifies the
+source file. By default it discovers and exports the complete rotated
+part-chain and creates one `wizardflow.run` trace; `--trace-scope message`
+creates one `wizardflow.message` trace per message.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `--endpoint` | OTel environment | OTLP/HTTP traces endpoint |
+| `--trace-scope` | `recording` | `recording` or `message` trace boundaries |
+| `--include-content` | off | Export bounded input, output, and structured log content |
+| `--content-max-bytes` | `16_384` | Maximum bytes for each exported content value |
+| `--export-graph` | off | Add the WizardFlow graph event to each root |
+| `--graph-max-bytes` | `65_536` | Maximum full graph-event content size |
+| `--current-part-only` | off | Export only the named rotation part |
+
+When `--endpoint` is omitted, the command reads
+`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, then `OTEL_EXPORTER_OTLP_ENDPOINT`.
+See [opentelemetry.md](opentelemetry.md) for installation, privacy, and mapping
+details.
+
+## Live traces and rotated parts
+
+`end_message()` appends one durable line, so `wizardflow ui` can show messages
+while the process is still recording. When the active part rotates, its seal
+points to the next filename. The local server resolves only plain sibling part
+names from the trace directory; UI assets always take precedence.
+
+See [jsonl-file-format.md](jsonl-file-format.md) for the record and rotation schema.