flograph 0.1.0__tar.gz

flograph-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.idea/
+.claude/
+*.flograph.cache/
+*.egg-info/
+build/
+dist/

flograph-0.1.0/LICENSE

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

flograph-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: flograph
+Version: 0.1.0
+Summary: Visual node-based Python programming environment (KNIME-style dataflow, Blueprint-style canvas)
+Project-URL: Homepage, https://github.com/redthista/flograph
+Project-URL: Repository, https://github.com/redthista/flograph
+Project-URL: Issues, https://github.com/redthista/flograph/issues
+Author-email: redthista <dconrancpw@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dataflow,etl,gui,knime,low-code,node-editor,pandas,pyside6,qt,visual-programming
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: X11 Applications :: Qt
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.11
+Requires-Dist: jedi>=0.19
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyside6>=6.7
+Provides-Extra: dev
+Requires-Dist: pytest-qt>=4.4; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: excel
+Requires-Dist: openpyxl; extra == 'excel'
+Provides-Extra: parquet
+Requires-Dist: pyarrow; extra == 'parquet'
+Provides-Extra: plotly
+Requires-Dist: plotly; extra == 'plotly'
+Description-Content-Type: text/markdown
+
+# flograph
+
+A visual node-based Python programming environment: KNIME-style dataflow on
+an infinite Blueprint-style canvas, where every node is real, editable Python.
+
+![status](https://img.shields.io/badge/status-v0.1-blue)
+
+## Install
+
+flograph is a standard pip-installable package (hatchling build backend):
+
+```bash
+pip install .            # or: uv pip install .   /   pip install -e .
+```
+
+This puts a `flograph` command on your PATH and makes `python -m flograph`
+work. To build a distributable wheel/sdist instead:
+
+```bash
+python -m build          # or: uv build   ->   dist/flograph-*.whl
+```
+
+> The project was renamed from **flopy** to **flograph** because `flopy` is
+> already taken on PyPI (USGS MODFLOW). To migrate projects saved by the old
+> build, see [Migrating old `.flopy` projects](#migrating-old-flopy-projects).
+
+## Run it
+
+```bash
+flograph                 # console entry point (after install)
+python -m flograph                          # equivalent module entry point
+python main.py project.flograph             # open a project
+python -m flograph.engine.headless project.flograph   # run without GUI
+```
+
+## The idea
+
+- **Nodes are Python scripts.** Every node — including the shipped library —
+  is a small module: a `NODE` dict declaring typed ports, an optional
+  `PARAMS` list that auto-generates its properties form, and a
+  `run(ctx, **inputs)` function. Double-click any node to read or fork its
+  code in the built-in editor (syntax highlighting, jedi completion,
+  error markers on the failing line).
+- **KNIME semantics.** Data flows through typed ports; execution is a
+  topological walk of the dirty subgraph; every node's outputs are cached, so
+  re-runs only recompute what changed. Status LEDs: gray idle, yellow queued,
+  pulsing blue running, green done, red error.
+- **Inspect everything.** Click any node or wire to see the data on it —
+  paged table view for DataFrames (millions of rows are fine), matplotlib
+  figures with a toolbar, pretty-printed objects. Per-node stdout/logs in the
+  console dock.
+
+## Canvas
+
+| Action | Binding |
+| --- | --- |
+| Add node | `Tab` (search palette), right-click, or drag from the library |
+| Connect | drag from a port; drop on empty canvas to pick a compatible node |
+| Reroute dot | double-click a wire |
+| Comment frame | `Ctrl+G` around the selection (frames move their contents) |
+| Run all / selected / cancel | `F5` / `F6` / `Esc` |
+| Pan / zoom | middle-drag or `Space`+drag / wheel |
+| Frame view | `F` |
+| Duplicate / delete | `Ctrl+D` / `Del` |
+| Undo anything | `Ctrl+Z` — every graph mutation is on the undo stack |
+
+Projects are plain JSON (`.flograph`); caches are never saved, so a reopened
+project is fully reproducible with one `F5`.
+
+### Migrating old `.flopy` projects
+
+Projects saved by the old **flopy** build use a `.flopy` extension and embed
+`flopy.*` node type-ids, which this build no longer recognises. Convert them
+in place with the bundled one-shot migrator (stdlib-only, no install needed):
+
+```bash
+python scripts/flopy_to_flograph.py project.flopy          # -> project.flograph
+python scripts/flopy_to_flograph.py my/projects --recursive
+```
+
+It rewrites builtin `flopy.*` type-ids to `flograph.*` (leaving `user.*`
+nodes alone), renames the file and any `.flopy.cache/` side-car, and by
+default keeps the original (`--delete-original` to remove it).
+
+## Node library
+
+The shipped library covers the KNIME basics:
+
+- **IO** — read/write CSV, Excel, Parquet, JSON (incl. JSONL), SQLite
+  (query in, table out), inline Table.
+- **Transform** — Select Columns, Filter Rows, Sort, Join, Group By,
+  Expression, Concatenate, Missing Values, Duplicate Row Filter,
+  Rename Columns, Pivot, Unpivot, Row Sampling, Convert Types,
+  String Manipulation, Statistics.
+- **Viz** — Show Table, Show Plot (live on-canvas cards), Show Plotly
+  (fully interactive plotly.js chart embedded on the canvas — hover, zoom
+  and pan in place; needs `pip install plotly`, e.g. via
+  Tools > Manage Packages).
+- **Scripting / Util** — Python Script, Constant, Reroute, Note,
+  Action Button.
+
+## Packages
+
+**Tools > Manage Packages** installs, upgrades and uninstalls pip packages
+in flograph's own environment (the venv running the app). Nodes execute
+in-process, so anything installed there is immediately importable from a
+node's `run()` — no restart needed for new installs; upgrades of modules
+the app has already imported take effect on the next launch. The dialog
+uses `pip` when the interpreter has it and falls back to `uv pip` (uv-made
+venvs ship without pip); flograph's own core dependencies are protected from
+uninstall.
+
+## Writing a node
+
+```python
+"""My Node
+
+Docstring first paragraph shows in the properties panel.
+"""
+NODE = {
+    "label": "My Node",
+    "category": "Transform",
+    "inputs":  [("table", "dataframe")],
+    "outputs": [("result", "dataframe")],
+}
+PARAMS = [
+    {"name": "factor", "type": "float", "default": 1.0},
+]
+
+def run(ctx, table):
+    ctx.log(f"scaling by {ctx.params['factor']}")
+    ctx.check_cancelled()          # cooperative cancellation
+    return {"result": table * ctx.params["factor"]}
+```
+
+Port types: `any, dataframe, series, number, string, bool, object, figure`.
+`columns`-typed params render with a ▾ picker listing the columns of the
+DataFrames cached on the node's inputs (run upstream once to populate it);
+add `"multi": False` for single-column params so picking replaces instead
+of toggling a comma list.
+Rules: treat inputs as read-only (outputs are cached by reference); heavy
+imports go inside `run()`; matplotlib figures must use the OO API
+(`matplotlib.figure.Figure()`), never pyplot.
+
+Drop new `.py` files under `src/flograph/nodes/<category>/` and they appear in
+the library on next launch.
+
+## Development
+
+```bash
+uv pip install -p .venv/bin/python -e ".[dev]"
+QT_QPA_PLATFORM=offscreen .venv/bin/python -m pytest tests/
+```
+
+Architecture (src layout):
+
+- `flograph/core` — Qt-free model: graph, typed ports, script contract,
+  registry, JSON serialization. Fully unit-testable; a poison test keeps Qt
+  and pandas out of its import graph.
+- `flograph/engine` — background execution: plan builder, single-thread pool
+  worker, output cache, cancellation, per-node stdout capture, tracebacks
+  mapped to node script lines.
+- `flograph/nodes` — the standard library; each node is a script file loaded as
+  text through the same contract as user code.
+- `flograph/ui` — canvas (QGraphicsView from scratch), code editor, inspector,
+  properties, console. One rule everywhere: **QUndoCommands are the only
+  writers to the graph**; items react to graph events.
+
+## License
+
+[MIT](LICENSE) — free for commercial and private use, modification, and
+redistribution; just keep the copyright and license notice.

flograph-0.1.0/README.md

@@ -0,0 +1,172 @@
+# flograph
+
+A visual node-based Python programming environment: KNIME-style dataflow on
+an infinite Blueprint-style canvas, where every node is real, editable Python.
+
+![status](https://img.shields.io/badge/status-v0.1-blue)
+
+## Install
+
+flograph is a standard pip-installable package (hatchling build backend):
+
+```bash
+pip install .            # or: uv pip install .   /   pip install -e .
+```
+
+This puts a `flograph` command on your PATH and makes `python -m flograph`
+work. To build a distributable wheel/sdist instead:
+
+```bash
+python -m build          # or: uv build   ->   dist/flograph-*.whl
+```
+
+> The project was renamed from **flopy** to **flograph** because `flopy` is
+> already taken on PyPI (USGS MODFLOW). To migrate projects saved by the old
+> build, see [Migrating old `.flopy` projects](#migrating-old-flopy-projects).
+
+## Run it
+
+```bash
+flograph                 # console entry point (after install)
+python -m flograph                          # equivalent module entry point
+python main.py project.flograph             # open a project
+python -m flograph.engine.headless project.flograph   # run without GUI
+```
+
+## The idea
+
+- **Nodes are Python scripts.** Every node — including the shipped library —
+  is a small module: a `NODE` dict declaring typed ports, an optional
+  `PARAMS` list that auto-generates its properties form, and a
+  `run(ctx, **inputs)` function. Double-click any node to read or fork its
+  code in the built-in editor (syntax highlighting, jedi completion,
+  error markers on the failing line).
+- **KNIME semantics.** Data flows through typed ports; execution is a
+  topological walk of the dirty subgraph; every node's outputs are cached, so
+  re-runs only recompute what changed. Status LEDs: gray idle, yellow queued,
+  pulsing blue running, green done, red error.
+- **Inspect everything.** Click any node or wire to see the data on it —
+  paged table view for DataFrames (millions of rows are fine), matplotlib
+  figures with a toolbar, pretty-printed objects. Per-node stdout/logs in the
+  console dock.
+
+## Canvas
+
+| Action | Binding |
+| --- | --- |
+| Add node | `Tab` (search palette), right-click, or drag from the library |
+| Connect | drag from a port; drop on empty canvas to pick a compatible node |
+| Reroute dot | double-click a wire |
+| Comment frame | `Ctrl+G` around the selection (frames move their contents) |
+| Run all / selected / cancel | `F5` / `F6` / `Esc` |
+| Pan / zoom | middle-drag or `Space`+drag / wheel |
+| Frame view | `F` |
+| Duplicate / delete | `Ctrl+D` / `Del` |
+| Undo anything | `Ctrl+Z` — every graph mutation is on the undo stack |
+
+Projects are plain JSON (`.flograph`); caches are never saved, so a reopened
+project is fully reproducible with one `F5`.
+
+### Migrating old `.flopy` projects
+
+Projects saved by the old **flopy** build use a `.flopy` extension and embed
+`flopy.*` node type-ids, which this build no longer recognises. Convert them
+in place with the bundled one-shot migrator (stdlib-only, no install needed):
+
+```bash
+python scripts/flopy_to_flograph.py project.flopy          # -> project.flograph
+python scripts/flopy_to_flograph.py my/projects --recursive
+```
+
+It rewrites builtin `flopy.*` type-ids to `flograph.*` (leaving `user.*`
+nodes alone), renames the file and any `.flopy.cache/` side-car, and by
+default keeps the original (`--delete-original` to remove it).
+
+## Node library
+
+The shipped library covers the KNIME basics:
+
+- **IO** — read/write CSV, Excel, Parquet, JSON (incl. JSONL), SQLite
+  (query in, table out), inline Table.
+- **Transform** — Select Columns, Filter Rows, Sort, Join, Group By,
+  Expression, Concatenate, Missing Values, Duplicate Row Filter,
+  Rename Columns, Pivot, Unpivot, Row Sampling, Convert Types,
+  String Manipulation, Statistics.
+- **Viz** — Show Table, Show Plot (live on-canvas cards), Show Plotly
+  (fully interactive plotly.js chart embedded on the canvas — hover, zoom
+  and pan in place; needs `pip install plotly`, e.g. via
+  Tools > Manage Packages).
+- **Scripting / Util** — Python Script, Constant, Reroute, Note,
+  Action Button.
+
+## Packages
+
+**Tools > Manage Packages** installs, upgrades and uninstalls pip packages
+in flograph's own environment (the venv running the app). Nodes execute
+in-process, so anything installed there is immediately importable from a
+node's `run()` — no restart needed for new installs; upgrades of modules
+the app has already imported take effect on the next launch. The dialog
+uses `pip` when the interpreter has it and falls back to `uv pip` (uv-made
+venvs ship without pip); flograph's own core dependencies are protected from
+uninstall.
+
+## Writing a node
+
+```python
+"""My Node
+
+Docstring first paragraph shows in the properties panel.
+"""
+NODE = {
+    "label": "My Node",
+    "category": "Transform",
+    "inputs":  [("table", "dataframe")],
+    "outputs": [("result", "dataframe")],
+}
+PARAMS = [
+    {"name": "factor", "type": "float", "default": 1.0},
+]
+
+def run(ctx, table):
+    ctx.log(f"scaling by {ctx.params['factor']}")
+    ctx.check_cancelled()          # cooperative cancellation
+    return {"result": table * ctx.params["factor"]}
+```
+
+Port types: `any, dataframe, series, number, string, bool, object, figure`.
+`columns`-typed params render with a ▾ picker listing the columns of the
+DataFrames cached on the node's inputs (run upstream once to populate it);
+add `"multi": False` for single-column params so picking replaces instead
+of toggling a comma list.
+Rules: treat inputs as read-only (outputs are cached by reference); heavy
+imports go inside `run()`; matplotlib figures must use the OO API
+(`matplotlib.figure.Figure()`), never pyplot.
+
+Drop new `.py` files under `src/flograph/nodes/<category>/` and they appear in
+the library on next launch.
+
+## Development
+
+```bash
+uv pip install -p .venv/bin/python -e ".[dev]"
+QT_QPA_PLATFORM=offscreen .venv/bin/python -m pytest tests/
+```
+
+Architecture (src layout):
+
+- `flograph/core` — Qt-free model: graph, typed ports, script contract,
+  registry, JSON serialization. Fully unit-testable; a poison test keeps Qt
+  and pandas out of its import graph.
+- `flograph/engine` — background execution: plan builder, single-thread pool
+  worker, output cache, cancellation, per-node stdout capture, tracebacks
+  mapped to node script lines.
+- `flograph/nodes` — the standard library; each node is a script file loaded as
+  text through the same contract as user code.
+- `flograph/ui` — canvas (QGraphicsView from scratch), code editor, inspector,
+  properties, console. One rule everywhere: **QUndoCommands are the only
+  writers to the graph**; items react to graph events.
+
+## License
+
+[MIT](LICENSE) — free for commercial and private use, modification, and
+redistribution; just keep the copyright and license notice.

flograph-0.1.0/ideas.md

@@ -0,0 +1,7 @@
+1. flow variables like in knime
+2. Export py script option, that creates a output script mirroring the flow. nice to use when a flograph workflow has matured enough to move the script to its own python script thats stands alone outside of the tool.
+3. moving nodes should happen from their top bar only, make resizing better and esp important on "show *" nodes, as they often need to be resized.
+4. add node: that similar to powerbis "Cards"
+5. add node: a slicer similar to powerbis, maybe it can fit inline and automatically run the visuals that follow?
+6. a way to turn a frame into a new "mega node" that is a node that contains nodes, i can config the initial wiring and end wiring. ie i input a df and it builds the table and graph.
+7. 

flograph-0.1.0/main.py

@@ -0,0 +1,5 @@
+"""Thin launcher for the flograph visual programming environment."""
+from flograph.app import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flograph-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "flograph"
+version = "0.1.0"
+description = "Visual node-based Python programming environment (KNIME-style dataflow, Blueprint-style canvas)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "redthista", email = "dconrancpw@gmail.com" }]
+keywords = [
+    "dataflow", "visual-programming", "node-editor", "etl", "pandas",
+    "gui", "pyside6", "qt", "knime", "low-code",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: X11 Applications :: Qt",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Visualization",
+    "Topic :: Software Development :: User Interfaces",
+    "Topic :: Software Development :: Code Generators",
+]
+dependencies = [
+    "PySide6>=6.7",
+    "pandas>=2.0",
+    "matplotlib>=3.8",
+    "jedi>=0.19",
+]
+
+[project.urls]
+Homepage = "https://github.com/redthista/flograph"
+Repository = "https://github.com/redthista/flograph"
+Issues = "https://github.com/redthista/flograph/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-qt>=4.4"]
+excel = ["openpyxl"]
+parquet = ["pyarrow"]
+plotly = ["plotly"]
+
+[project.scripts]
+flograph = "flograph.app:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/flograph"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

flograph-0.1.0/scripts/flopy_to_flograph.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""Migrate legacy ``.flopy`` project files to the renamed ``.flograph`` format.
+
+The project was renamed flopy -> flograph (the name ``flopy`` is taken on PyPI
+by USGS MODFLOW). The rename is a clean break with no in-app backward
+compatibility, so this one-shot tool upgrades any projects saved by the old
+build:
+
+  * builtin node type-ids ``flopy.<sub>.<name>`` -> ``flograph.<sub>.<name>``
+    (``user.*`` and any other prefixes are left untouched);
+  * the informational ``flopy_version`` key -> ``flograph_version``;
+  * the file itself ``<name>.flopy`` -> ``<name>.flograph``;
+  * the side-car cache dir ``<name>.flopy.cache/`` -> ``<name>.flograph.cache/``.
+
+Standalone and stdlib-only on purpose: it does not import the ``flograph``
+package, so it runs against old files in any environment.
+
+Usage::
+
+    python scripts/flopy_to_flograph.py project.flopy
+    python scripts/flopy_to_flograph.py path/to/dir --recursive
+    python scripts/flopy_to_flograph.py project.flopy --delete-original
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+LEGACY_PREFIX = "flopy."
+NEW_PREFIX = "flograph."
+
+
+def convert_project_data(data: dict) -> tuple[dict, int]:
+    """Return a rewritten copy of a project dict and the number of builtin
+    node type-ids that were re-prefixed. Non-``flopy.*`` type-ids (notably
+    ``user.*``) are preserved verbatim."""
+    rewritten = 0
+    if "flopy_version" in data and "flograph_version" not in data:
+        data["flograph_version"] = data.pop("flopy_version")
+    graph = data.get("graph")
+    if isinstance(graph, dict):
+        for node in graph.get("nodes", []):
+            type_id = node.get("type")
+            if isinstance(type_id, str) and type_id.startswith(LEGACY_PREFIX):
+                node["type"] = NEW_PREFIX + type_id[len(LEGACY_PREFIX):]
+                rewritten += 1
+    return data, rewritten
+
+
+def _new_path(path: Path) -> Path:
+    # only the trailing ".flopy" suffix is swapped; the stem is preserved even
+    # if it happens to contain the substring "flopy".
+    return path.with_name(path.name[: -len(".flopy")] + ".flograph")
+
+
+def convert_file(path: Path, *, delete_original: bool = False) -> tuple[Path, int]:
+    """Convert one ``.flopy`` file, writing a sibling ``.flograph`` file and
+    renaming any ``.flopy.cache`` side-car. Returns (output_path, type_ids
+    rewritten)."""
+    data = json.loads(path.read_text())
+    data, rewritten = convert_project_data(data)
+    out_path = _new_path(path)
+    out_path.write_text(json.dumps(data, indent=2))
+
+    old_cache = path.with_name(path.name + ".cache")
+    if old_cache.is_dir():
+        new_cache = out_path.with_name(out_path.name + ".cache")
+        if not new_cache.exists():
+            old_cache.rename(new_cache)
+
+    if delete_original:
+        path.unlink()
+
+    return out_path, rewritten
+
+
+def _iter_projects(paths: list[Path], recursive: bool):
+    for p in paths:
+        if p.is_dir():
+            yield from sorted(p.rglob("*.flopy") if recursive else p.glob("*.flopy"))
+        else:
+            yield p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("paths", nargs="+", type=Path,
+                        help="`.flopy` files and/or directories to convert")
+    parser.add_argument("-r", "--recursive", action="store_true",
+                        help="recurse into directories looking for `.flopy` files")
+    parser.add_argument("--delete-original", action="store_true",
+                        help="delete each source `.flopy` after converting it")
+    args = parser.parse_args(argv)
+
+    files = 0
+    total_ids = 0
+    errors = 0
+    for project in _iter_projects(args.paths, args.recursive):
+        if project.suffix != ".flopy":
+            print(f"skip (not a .flopy file): {project}", file=sys.stderr)
+            continue
+        try:
+            out_path, rewritten = convert_file(
+                project, delete_original=args.delete_original)
+        except (OSError, json.JSONDecodeError) as exc:
+            print(f"error: {project}: {exc}", file=sys.stderr)
+            errors += 1
+            continue
+        files += 1
+        total_ids += rewritten
+        print(f"converted {project} -> {out_path} ({rewritten} type-ids rewritten)")
+
+    print(f"\n{files} file(s) converted, {total_ids} type-id(s) rewritten, "
+          f"{errors} error(s).")
+    return 1 if errors else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flograph-0.1.0/src/flograph/__main__.py

@@ -0,0 +1,5 @@
+"""Enable `python -m flograph` as an entry point (mirrors the console script)."""
+from flograph.app import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flograph-0.1.0/src/flograph/app.py

@@ -0,0 +1,43 @@
+"""Application entry point: QApplication, theme, registry, main window."""
+from __future__ import annotations
+
+import sys
+
+
+def main(argv: list[str] | None = None) -> int:
+    import matplotlib
+    matplotlib.use("QtAgg")  # before any pyplot import, GUI-safe backend
+
+    from PySide6.QtCore import Qt
+    from PySide6.QtWidgets import QApplication
+
+    from flograph.core import NodeRegistry
+    from flograph.paths import user_nodes_dir
+    from flograph.ui.mainwindow import MainWindow
+    from flograph.ui.theme import apply_theme
+
+    # must be set before the QApplication exists: the Show Plotly card embeds
+    # Qt WebEngine, which needs shared GL contexts to composite
+    QApplication.setAttribute(Qt.AA_ShareOpenGLContexts)
+    app = QApplication.instance() or QApplication(sys.argv if argv is None else argv)
+    app.setApplicationName("flograph")
+    app.setOrganizationName("flograph")
+    apply_theme(app)
+
+    registry = NodeRegistry()
+    registry.load_builtins()
+    registry.load_user_nodes(user_nodes_dir())
+
+    window = MainWindow(registry)
+    window.resize(1400, 900)
+    window.show()
+
+    args = app.arguments()[1:]
+    project = next((a for a in args if a.endswith(".flograph")), None)
+    if project:
+        window.open_path(project, confirm=False)
+    return app.exec()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())