fletchr-studio 0.1.0__tar.gz

fletchr_studio-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+.venv
+__pycache__
+.hypothesis
+.pytest_cache
+.ipynb_checkpoints
+*.ipynb
+_version.py
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Frontend (fletchr-studio canvas)
+node_modules/
+fletchr-studio/src/fletchr_studio/static/
+
+# Generated studio demo (fletchr-studio/examples/make_demo.py)
+studio-demo/
+
+# Coverage
+.coverage
+htmlcov/
+coverage.xml
+
+# Lint / type-check caches
+.ruff_cache/
+.mypy_cache/

fletchr_studio-0.1.0/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to `fletchr-studio` are documented here.
+
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+this project follows [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-07-27
+
+Initial release: a visual flowgraph editor for fletchr pipelines —
+sources → transformers → sinks on a canvas, compiled to plain Python.
+
+### Added
+
+- **Canvas editor** (React Flow) served by a local FastAPI host
+  (`fletchr-studio` CLI): drag blocks from a palette grouped by
+  category (frame/mux/packet/clock/dataframe lanes, color-coded type
+  chips and port handles), connect typed ports with live
+  reject-on-connect, configure params in an inspector with
+  type-resolved widgets (`Literal` → dropdowns, `bool | None` →
+  tri-state, mappings → key/value row editors, paths → file browser).
+  Undo/redo, copy/paste, Ctrl+S, auto-layout with crossing reduction,
+  nameable nodes, recent files, resizable inspector.
+- **Palette from the live registries** — every registered transformer
+  (plugin-contributed ones included, via the normal entry-point
+  discovery), file source/sink blocks with per-extension format
+  options introspected from reader/writer signatures, and merge
+  blocks wrapping `stack` / `merge`.
+- **Codegen artifact** — graphs compile to a runnable script
+  depending only on the fletchr packages: linear runs become `|`
+  pipelines, imports group by each block's defining module (plugin
+  blocks import from their own package), source/sink paths lift into
+  `main()` kwargs and an argparse CLI (`python flow.py --capture
+  other.bits`), and sink paths support `{stem}`/`{name}` tokens
+  derived from a single upstream `read_file`. The graph document
+  embeds as `__fletchr_graph__` with a drift-detecting hash;
+  reopening is byte-identical.
+- **Runs with observability** — sampled preview runs (sinks skipped,
+  sources sliced) and full runs execute in a background thread with
+  live per-node status, cooperative cancellation at node boundaries,
+  per-node capture of stdout/stderr/warnings/logging shown in the
+  inspector, previews of completed nodes mid-run, and a toggle to
+  disable result caching (intermediates freed eagerly) for large
+  runs.
+- **Previews** — schema, row/null counts, and paginated table windows
+  for any cached node (containers, polars, pandas), as JSON or Arrow
+  IPC; internal underscore-prefixed columns hidden.
+- **Sessions API** — graph CRUD with live validation, run control,
+  previews, generate/save/open (drift flagged), and a file-browser
+  endpoint, all under `/api`; `Branding` lets a downstream
+  meta-package present the studio under its own name and favicon.
+- **Validation** — structural (cycles, ports, params), subclass-aware
+  port types mirroring `Pipeline`'s rules, and extension-aware I/O
+  checks (missing required format options like `.bits`
+  `start_time`, unregistered extensions) surfaced live as node
+  badges.
+- **Demo generator** — `python fletchr-studio/examples/make_demo.py`
+  writes a factory serial-bus scenario (packet lane, `PacketSelect`
+  lane change, measurand decoding) with data, an openable flow, and a
+  self-verifying run.
+- **Packaging guard** — `hatch-jupyter-builder` ensures dists always
+  contain the canvas bundle: prebuilt bundles need no Node, missing
+  bundles are npm-built when Node is present, and a headless dist
+  fails the build instead of shipping silently.
+
+## Links
+
+- [Source](https://github.com/fletchr-labs/fletchr/tree/main/fletchr-studio)
+- [PyPI](https://pypi.org/project/fletchr-studio/)
+- [Design record](https://github.com/fletchr-labs/fletchr/blob/main/docs/design/studio.md)

fletchr_studio-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Olsten
+
+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.

fletchr_studio-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: fletchr-studio
+Version: 0.1.0
+Summary: Flowgraph engine for the fletchr studio GUI: graph model, palette introspection, validation, and Python code generation.
+Project-URL: Homepage, https://github.com/fletchr-labs/fletchr
+Project-URL: Repository, https://github.com/fletchr-labs/fletchr
+Project-URL: Issues, https://github.com/fletchr-labs/fletchr/issues
+Project-URL: Changelog, https://github.com/fletchr-labs/fletchr/blob/main/fletchr-studio/CHANGELOG.md
+Author-email: Jonathan Olsten <jolsten@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: arrow,codegen,flowgraph,gui,pipeline,pyarrow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+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 :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: attrs>=22.1.0
+Requires-Dist: fastapi>=0.110
+Requires-Dist: fletchr-core>=0.1.0
+Requires-Dist: uvicorn>=0.29
+Description-Content-Type: text/markdown
+
+# fletchr-studio
+
+The flowgraph engine behind the fletchr studio GUI: a graph document
+model for source → transformer → sink flowgraphs, a block palette built
+by introspecting the live fletchr registries, graph validation, and
+Python code generation with round-trip reopen.
+
+The package also ships the studio itself: a FastAPI host
+(`fletchr_studio.server`) serving a React Flow canvas UI, with
+sessions, sampled/full graph runs, and per-node table previews. See
+[`docs/design/studio.md`](../docs/design/studio.md) at the workspace
+root for the design record and phased plan.
+
+## Running the GUI
+
+```bash
+fletchr-studio            # serves http://127.0.0.1:8410
+```
+
+Drag blocks from the palette, connect them (incompatible ports are
+rejected), configure params in the inspector, then **Preview Run** —
+sources are sampled and sinks are skipped, so a preview never
+overwrites real outputs. Click any node to see its table preview.
+**Full Run** executes everything, sinks included. **Generate** shows
+the emitted script; **Save** writes it; **Open** reopens a generated
+`.py` (hand edits are flagged as drift).
+
+## Rebranding for meta-packages
+
+A downstream protocol wrapper can present the studio as its own tool.
+Ship a console script that launches it with a `Branding`:
+
+```python
+# acme_decoder/studio.py
+import acme_decoder.plugins  # noqa: F401 - registers blocks via entry points
+from fletchr_studio import Branding
+from fletchr_studio.server import main
+
+
+def cli() -> None:
+    main(branding=Branding(name="ACME Decoder Studio", favicon="path/to/icon.svg"))
+```
+
+```toml
+[project.scripts]
+acme-studio = "acme_decoder.studio:cli"
+```
+
+The name flows into the browser tab, the top bar, and the FastAPI
+title; the favicon replaces the default. Generated scripts still
+record `fletchr-studio <version>` as their generator — that's
+provenance, not presentation. The wrapper's transformers, readers,
+and writers appear in the palette automatically via the normal
+entry-point plugin discovery.
+
+The canvas bundle builds into `src/fletchr_studio/static/` and ships
+in both the wheel and the sdist. Packaging is guarded by
+`hatch-jupyter-builder`: building a dist with the bundle already
+present needs no Node (`skip-if-exists`); with the bundle missing it
+runs `npm install` + `npm run build` itself; and with neither bundle
+nor Node the build **fails** rather than producing a headless dist
+(`ensured-targets`). Editable installs only warn, so Python-only
+contributors without Node get a working headless dev server. Escape
+hatch for deliberate headless builds: `SKIP_JUPYTER_BUILDER=1`.
+
+To rebuild the bundle by hand you need Node 18+:
+
+```bash
+cd frontend
+npm install
+npm run build     # type-checks and outputs to ../src/fletchr_studio/static
+npm run dev       # dev server with /api proxied to a running fletchr-studio
+```
+
+## What it does
+
+```python
+from fletchr_studio import GraphDoc, generate_code, load_graph
+
+doc = GraphDoc()
+doc.add_node("capture", "source", "read_file", path="capture.arrow")
+doc.add_node("sel", "transform", "Subframe", columns="1-32")
+doc.add_node("inv", "transform", "Invert")
+doc.add_node("out", "sink", "write_file", path="frames.parquet")
+doc.add_edge("capture", "sel")
+doc.add_edge("sel", "inv")
+doc.add_edge("inv", "out")
+
+code = generate_code(doc)
+```
+
+`generate_code` validates the graph (unknown blocks, port type
+mismatches, cycles, missing params — reusing the same subclass-aware
+compatibility rules `Pipeline` enforces) and emits a plain Python
+script depending only on the fletchr packages:
+
+```python
+"""Flowgraph generated by fletchr-studio 0.1.0."""
+
+import argparse
+
+from fletchr_core import read_file, write_file
+from fletchr_core.transform import Invert, Subframe
+
+
+def main(capture_path='capture.arrow', out_path='frames.parquet'):
+    capture = read_file(capture_path)
+    inv = (Subframe(columns='1-32') | Invert())(capture)
+    write_file(out_path, inv)
+
+
+def _cli():
+    parser = argparse.ArgumentParser(description="Flowgraph generated by fletchr-studio.")
+    parser.add_argument("--capture", dest="capture_path", default='capture.arrow', help="source 'capture' path")
+    parser.add_argument("--out", dest="out_path", default='frames.parquet', help="sink 'out' path")
+    main(**vars(parser.parse_args()))
+
+
+if __name__ == "__main__":
+    _cli()
+
+
+__fletchr_graph__ = {...}
+```
+
+Source and sink paths are lifted into `main()`'s signature and an
+argparse CLI, so the artifact is parameterizable without editing:
+`python flow.py --capture other.bits`, or import it and call
+`main(capture_path=...)` from a loop.
+
+The embedded `__fletchr_graph__` literal is the graph document —
+`load_graph("flow.py")` reopens it, and a stored SHA-256 of the code
+section detects hand edits (drift) without parsing arbitrary Python.
+Linear chains compile to `|` pipelines; fan-out becomes named
+intermediates; merge blocks (`stack`, `merge`) compile to plain calls.
+
+The palette (`build_palette()`) discovers every registered transformer
+— including plugin-contributed ones — plus file source/sink blocks and
+the merge blocks, with parameter schemas introspected from attrs fields
+or `__init__` signatures and port types from `apply` annotations.

fletchr_studio-0.1.0/README.md

@@ -0,0 +1,140 @@
+# fletchr-studio
+
+The flowgraph engine behind the fletchr studio GUI: a graph document
+model for source → transformer → sink flowgraphs, a block palette built
+by introspecting the live fletchr registries, graph validation, and
+Python code generation with round-trip reopen.
+
+The package also ships the studio itself: a FastAPI host
+(`fletchr_studio.server`) serving a React Flow canvas UI, with
+sessions, sampled/full graph runs, and per-node table previews. See
+[`docs/design/studio.md`](../docs/design/studio.md) at the workspace
+root for the design record and phased plan.
+
+## Running the GUI
+
+```bash
+fletchr-studio            # serves http://127.0.0.1:8410
+```
+
+Drag blocks from the palette, connect them (incompatible ports are
+rejected), configure params in the inspector, then **Preview Run** —
+sources are sampled and sinks are skipped, so a preview never
+overwrites real outputs. Click any node to see its table preview.
+**Full Run** executes everything, sinks included. **Generate** shows
+the emitted script; **Save** writes it; **Open** reopens a generated
+`.py` (hand edits are flagged as drift).
+
+## Rebranding for meta-packages
+
+A downstream protocol wrapper can present the studio as its own tool.
+Ship a console script that launches it with a `Branding`:
+
+```python
+# acme_decoder/studio.py
+import acme_decoder.plugins  # noqa: F401 - registers blocks via entry points
+from fletchr_studio import Branding
+from fletchr_studio.server import main
+
+
+def cli() -> None:
+    main(branding=Branding(name="ACME Decoder Studio", favicon="path/to/icon.svg"))
+```
+
+```toml
+[project.scripts]
+acme-studio = "acme_decoder.studio:cli"
+```
+
+The name flows into the browser tab, the top bar, and the FastAPI
+title; the favicon replaces the default. Generated scripts still
+record `fletchr-studio <version>` as their generator — that's
+provenance, not presentation. The wrapper's transformers, readers,
+and writers appear in the palette automatically via the normal
+entry-point plugin discovery.
+
+The canvas bundle builds into `src/fletchr_studio/static/` and ships
+in both the wheel and the sdist. Packaging is guarded by
+`hatch-jupyter-builder`: building a dist with the bundle already
+present needs no Node (`skip-if-exists`); with the bundle missing it
+runs `npm install` + `npm run build` itself; and with neither bundle
+nor Node the build **fails** rather than producing a headless dist
+(`ensured-targets`). Editable installs only warn, so Python-only
+contributors without Node get a working headless dev server. Escape
+hatch for deliberate headless builds: `SKIP_JUPYTER_BUILDER=1`.
+
+To rebuild the bundle by hand you need Node 18+:
+
+```bash
+cd frontend
+npm install
+npm run build     # type-checks and outputs to ../src/fletchr_studio/static
+npm run dev       # dev server with /api proxied to a running fletchr-studio
+```
+
+## What it does
+
+```python
+from fletchr_studio import GraphDoc, generate_code, load_graph
+
+doc = GraphDoc()
+doc.add_node("capture", "source", "read_file", path="capture.arrow")
+doc.add_node("sel", "transform", "Subframe", columns="1-32")
+doc.add_node("inv", "transform", "Invert")
+doc.add_node("out", "sink", "write_file", path="frames.parquet")
+doc.add_edge("capture", "sel")
+doc.add_edge("sel", "inv")
+doc.add_edge("inv", "out")
+
+code = generate_code(doc)
+```
+
+`generate_code` validates the graph (unknown blocks, port type
+mismatches, cycles, missing params — reusing the same subclass-aware
+compatibility rules `Pipeline` enforces) and emits a plain Python
+script depending only on the fletchr packages:
+
+```python
+"""Flowgraph generated by fletchr-studio 0.1.0."""
+
+import argparse
+
+from fletchr_core import read_file, write_file
+from fletchr_core.transform import Invert, Subframe
+
+
+def main(capture_path='capture.arrow', out_path='frames.parquet'):
+    capture = read_file(capture_path)
+    inv = (Subframe(columns='1-32') | Invert())(capture)
+    write_file(out_path, inv)
+
+
+def _cli():
+    parser = argparse.ArgumentParser(description="Flowgraph generated by fletchr-studio.")
+    parser.add_argument("--capture", dest="capture_path", default='capture.arrow', help="source 'capture' path")
+    parser.add_argument("--out", dest="out_path", default='frames.parquet', help="sink 'out' path")
+    main(**vars(parser.parse_args()))
+
+
+if __name__ == "__main__":
+    _cli()
+
+
+__fletchr_graph__ = {...}
+```
+
+Source and sink paths are lifted into `main()`'s signature and an
+argparse CLI, so the artifact is parameterizable without editing:
+`python flow.py --capture other.bits`, or import it and call
+`main(capture_path=...)` from a loop.
+
+The embedded `__fletchr_graph__` literal is the graph document —
+`load_graph("flow.py")` reopens it, and a stored SHA-256 of the code
+section detects hand edits (drift) without parsing arbitrary Python.
+Linear chains compile to `|` pipelines; fan-out becomes named
+intermediates; merge blocks (`stack`, `merge`) compile to plain calls.
+
+The palette (`build_palette()`) discovers every registered transformer
+— including plugin-contributed ones — plus file source/sink blocks and
+the merge blocks, with parameter schemas introspected from attrs fields
+or `__init__` signatures and port types from `apply` annotations.

fletchr_studio-0.1.0/examples/make_demo.py

@@ -0,0 +1,156 @@
+"""Generate a self-contained studio demo: test data + an openable flowgraph.
+
+The scenario is a factory-floor serial bus log: machines share a bus
+and emit variable-length status messages, captured to a CSV in the
+delimited packets layout (`time, ctime, pid, pdl, w1..wN`, ragged
+rows). Machine IDs: 1 = stamping press, 2 = conveyor, 3 = spot welder.
+
+Message payloads (8-bit words):
+
+    press (pid=1, 4 words)    cycle_hi, cycle_lo, motor_temp, vibration
+    conveyor (pid=2, 4 words) cycle_hi, cycle_lo, motor_temp, vibration
+    welder (pid=3, 6 words)   cycle_hi, cycle_lo, motor_temp, vibration,
+                              current_hi, current_lo
+
+The generated flow exercises the packet lane end to end:
+
+    bus_log (.csv, packets mode) ─┬→ welder (PacketFilter pid=3) → welder_log.csv
+                                  └→ press (PacketSelect pid=1) → decode → press_health.parquet
+
+`PacketSelect` stacks the fixed-length press messages into a
+FrameArray (packet → frame lane change), and `MeasurandGroup` decodes
+cycle count (16-bit across two words), motor temperature, and
+vibration into the dataframe lane.
+
+Usage:
+
+    uv run python fletchr-studio/examples/make_demo.py [out_dir]
+
+then `cd <out_dir>` and run `fletchr-studio` — File > Open >
+demo_flow.py. Paths in the flow are relative, so the server must be
+started from the demo directory.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+import numpy as np
+
+from fletchr_studio import (
+    KIND_SINK,
+    KIND_SOURCE,
+    KIND_TRANSFORM,
+    GraphDoc,
+    generate_code,
+    run_graph,
+)
+
+N_MESSAGES = 400
+MACHINES = {1: "press", 2: "conveyor", 3: "welder"}
+
+
+def make_bus_log(rng: np.random.Generator) -> str:
+    start = np.datetime64("2025-03-10T09:00:00", "ns")
+    cycles = dict.fromkeys(MACHINES, 0)
+    rows = ["time,ctime,pid,pdl,w1,w2,w3,w4,w5,w6"]
+    clock = start
+    for _ in range(N_MESSAGES):
+        clock = clock + np.timedelta64(int(rng.integers(80, 400)), "ms")
+        pid = int(rng.choice([1, 1, 2, 2, 3]))  # welder chattier than nothing, rarer than the rest
+        cycles[pid] += int(rng.integers(1, 4))
+        cycle = cycles[pid] % 65536
+        motor_temp = int(np.clip(rng.normal(70 + 12 * pid, 6), 0, 255))
+        vibration = int(np.clip(rng.normal(28, 9), 0, 255))
+        words = [cycle >> 8, cycle & 0xFF, motor_temp, vibration]
+        if pid == 3:  # welder appends weld current, 16-bit
+            current = int(np.clip(rng.normal(11_500, 900), 0, 65_535))
+            words += [current >> 8, current & 0xFF]
+        stamp = str(clock)
+        cells = [stamp, stamp, str(pid), str(len(words)), *map(str, words)]
+        rows.append(",".join(cells))
+    return "\n".join(rows) + "\n"
+
+
+def make_flow() -> GraphDoc:
+    doc = GraphDoc()
+    doc.add_node(
+        "bus_log",
+        KIND_SOURCE,
+        "read_file",
+        path="bus_log.csv",
+        mode="packets",
+        bits=8,
+    )
+    doc.add_node("welder", KIND_TRANSFORM, "PacketFilter", pid=3)
+    doc.add_node("press", KIND_TRANSFORM, "PacketSelect", pid=1, apdl=4)
+    doc.add_node(
+        "decode",
+        KIND_TRANSFORM,
+        "MeasurandGroup",
+        measurands={
+            "cycle_count": "[1+2];u",
+            "motor_temp": "[3];u",
+            "vibration": "[4];u",
+        },
+    )
+    doc.add_node("welder_out", KIND_SINK, "write_file", path="welder_log.csv", header=True)
+    doc.add_node("health_out", KIND_SINK, "write_file", path="press_health.parquet")
+    doc.add_edge("bus_log", "welder")
+    doc.add_edge("welder", "welder_out")
+    doc.add_edge("bus_log", "press")
+    doc.add_edge("press", "decode")
+    doc.add_edge("decode", "health_out")
+    doc.layout.update(
+        {
+            "bus_log": [40, 160],
+            "welder": [300, 60],
+            "welder_out": [560, 60],
+            "press": [300, 260],
+            "decode": [560, 260],
+            "health_out": [820, 260],
+        }
+    )
+    return doc
+
+
+def main() -> None:
+    out_dir = Path(sys.argv[1] if len(sys.argv) > 1 else "studio-demo").resolve()
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    rng = np.random.default_rng(1972)
+    with open(out_dir / "bus_log.csv", "w", encoding="utf-8", newline="") as data_file:
+        data_file.write(make_bus_log(rng))
+
+    doc = make_flow()
+    with open(out_dir / "demo_flow.py", "w", encoding="utf-8", newline="") as flow_file:
+        flow_file.write(generate_code(doc))
+
+    # Self-verify: run the flow (full mode, so the sinks write) from
+    # the demo directory, since the flow uses relative paths.
+    previous_cwd = os.getcwd()
+    os.chdir(out_dir)
+    try:
+        result = run_graph(doc, mode="full")
+    finally:
+        os.chdir(previous_cwd)
+
+    print(f"demo written to {out_dir}")
+    for node_id, node in result.nodes.items():
+        rows = f"  {node.rows} rows" if node.rows is not None else ""
+        print(f"  {node_id:12} {node.status}{rows}")
+        for line in node.logs:
+            print(f"               | {line}")
+    if not result.ok:
+        raise SystemExit("demo flow did not run cleanly")
+    print()
+    print("Open it in the studio:")
+    print(f"  cd {out_dir}")
+    print("  fletchr-studio")
+    print("  -> File > Open... > demo_flow.py, then hit the play button.")
+
+
+if __name__ == "__main__":
+    main()

fletchr_studio-0.1.0/frontend/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <title>fletchr studio</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>