modulearn 0.1.0__tar.gz

modulearn-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.whl
+.venv/
+venv/
+env/
+runs/
+.DS_Store
+.idea/
+.vscode/

modulearn-0.1.0/LICENSE

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

modulearn-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: modulearn
+Version: 0.1.0
+Summary: A visual, Unreal-Blueprints-style node-graph editor for building and launching ML training runs.
+Project-URL: Homepage, https://github.com/IsaiahKoamalu/modulearn
+Project-URL: Source, https://github.com/IsaiahKoamalu/modulearn
+Author: Isaiah Broderson
+License: MIT
+License-File: LICENSE
+Keywords: fastapi,machine-learning,node-graph,training,visual-programming
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.110
+Requires-Dist: pydantic>=2.0
+Requires-Dist: uvicorn>=0.29
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ModuLearn
+
+A visual, [Unreal-Blueprints](https://dev.epicgames.com/documentation/en-us/unreal-engine/blueprints-visual-scripting-in-unreal-engine)-style
+node-graph editor for building and launching machine-learning training runs.
+Drop **Dataset → Model → Train** nodes on a canvas, wire **hyperparameters**,
+**loss** and **feature transforms** into them, hit ▶ Train, and watch the learning
+curve live on the graph. No forms, no drift between the UI and the code it runs.
+
+> **ModuLearn** is a working name — you assemble training runs from modular nodes and
+> learn from the live curve. Rename the package/repo freely; nothing depends on the name.
+
+<!-- A screenshot or GIF of the editor goes well here. -->
+
+## Why
+
+Most training UIs are flat forms that slowly rot out of sync with the code behind
+them. ModuLearn inverts that: your Python is the single source of truth. You *declare*
+what you can train once, in a `Registry`, and the entire editor — palette, typed
+wiring rules, live validation, launch — is generated from it. Wire something the
+backend can't accept and it simply won't connect.
+
+## Install
+
+```bash
+pip install -e .          # fastapi + uvicorn + pydantic
+modulearn demo            # serve the bundled editor at http://localhost:8000
+```
+
+`modulearn demo` is a complete, **dependency-free** editor (its "trainer" is a toy
+loss curve) so you can click around immediately. Once you've built your own app,
+serve it the same way:
+
+```bash
+modulearn run myproject.py        # serves the `app` you built with create_app
+modulearn run myproject.py:editor # ...or a differently-named app / factory
+modulearn --help
+```
+
+Swap `on_train` for your real training loop and nothing else changes. (The
+equivalent source file lives at [`examples/quickstart.py`](examples/quickstart.py)
+if you'd rather run it directly with `python`.)
+
+## The whole integration is two things
+
+```python
+from modulearn import Registry, Param, create_app
+
+reg = Registry()
+
+reg.add_dataset("iris", title="Iris", kind="tabular",
+                features=[...], targets=["species"])
+reg.add_model("mlp", title="MLP", requires_kind="tabular",
+              params=[Param("hidden", "hidden layers", "int_list", [64, 32])])
+reg.add_hyperparameter("lr", label="learning rate", default=1e-3, min=1e-6, max=1)
+reg.add_loss([Param("loss", "kind", "enum", "mse", choices=["mse", "cross_entropy"])])
+
+def on_train(compiled, reporter):
+    # compiled.dataset, .model, .model_params, .hyperparameters, .loss_params, .transforms
+    reporter.state(epochs=100)
+    for e in range(100):
+        reporter.metric(epoch=e, train=..., val=...)   # drives the live chart
+        reporter.state(epoch=e, best_val=...)
+    reporter.state(phase="done", test_score=...)
+
+app = create_app(reg, on_train, title="My Project")
+```
+
+1. **A `Registry`** — declare datasets, models, hyperparameters, a loss, and
+   optional feature transforms. Each hyperparameter you add automatically grows a
+   matching, type-checked input on the Train sink.
+2. **`on_train(compiled, reporter)`** — your training loop. `compiled` is a
+   fully-validated [`CompiledGraph`](modulearn/compiler.py); `reporter` publishes
+   progress the editor polls (see the state contract below).
+
+## How it fits together
+
+```
+ registry.py   ── you declare nodes ──►  catalog (GET /api/nodes)
+      │                                        │
+      ▼                                        ▼
+ compiler.py   ◄── canvas JSON ────────  static/ (custom canvas engine)
+      │  type-checks every wire, runs semantic checks
+      ▼
+ CompiledGraph ──►  your on_train(compiled, reporter)  ──►  runs/<id>/{state,metrics}.json
+                                                                   │
+                                                    editor polls ◄─┘  (live panel + chart)
+```
+
+- **Typed ports.** Links carry a family (`dataset`, `model`, `loss`, `run`) or a
+  field-specific scalar subtype (`scalar/lr`), so a learning-rate value fits the
+  `lr` input and *never* `epochs` — enforced both client-side and in the compiler.
+- **All-or-nothing compile.** `compile_graph` collects every structural, type and
+  semantic error and raises them together, so the UI flags all bad wires at once.
+- **Composable transforms.** Chain `Dataset → Transform → … → Model`; the compiler
+  walks the chain into `compiled.transforms`. Mark a transform `live=False` to show
+  it in the palette but have the compiler refuse it until your backend is ready.
+- **Stateless live window.** Training runs in a background thread and persists to
+  `runs/<id>/`. Closing the browser never stops a run; reopening shows true state.
+
+## The state contract
+
+Your `on_train` reports through `reporter`, and the editor reads these keys:
+
+| call | keys the UI understands |
+|------|-------------------------|
+| `reporter.state(**kw)` | `phase` (`running`/`done`/`error`), `epoch`, `epochs`, `best_val`, `test_score`, `error` |
+| `reporter.metric(**row)` | `epoch`, `train`, `val` → the live learning curve |
+
+Anything else you write is stored and returned by the API, just not charted.
+
+## Editor niceties
+
+- Searchable palette with collapsible category dropdowns; `⌘K` / `/` to focus,
+  Enter to drop the first match.
+- Wires colored by type, with flowing pulses that speed up on the edges feeding a
+  running Train node; ports glow while you drag a compatible connection.
+- Canvas persists to `localStorage`; reload/fork any past run's blueprint.
+- All motion respects `prefers-reduced-motion`.
+
+## Layout
+
+```
+modulearn/
+  registry.py    the declarative surface your app fills in
+  compiler.py    graph JSON -> validated CompiledGraph (pure, unit-testable)
+  server.py      create_app(): FastAPI factory + background job runner
+  cli.py         the `modulearn` command (demo / run)
+  demo.py        the app `modulearn demo` serves
+  static/        graph.html, graph.js (app), graph-engine.js (canvas engine)
+examples/
+  quickstart.py  a complete, dependency-free editor
+```
+
+## License
+
+MIT (see [LICENSE](LICENSE)). The canvas node-graph engine
+(`static/graph-engine.js`) is our own, built from scratch — no third-party
+graph library.

modulearn-0.1.0/PUBLISHING.md

@@ -0,0 +1,103 @@
+# Publishing `modulearn`
+
+The exact steps to cut a release. The package builds to the distribution name
+**`modulearn`** (so `pip install modulearn`), with the CLI entry point `modulearn`.
+
+Replace `<USER>` with the GitHub account you're publishing under.
+
+## 0. One-time setup
+
+```bash
+pip install -e ".[dev]"     # pytest + build + twine
+```
+
+## 1. Sanity checks
+
+```bash
+python tests/test_smoke.py          # or: pytest -q
+python -m build                     # writes dist/modulearn-<ver>-*.whl and .tar.gz
+twine check dist/*                  # validates the rendered PyPI metadata
+```
+
+Confirm the wheel bundles the static assets (the editor is dead without them):
+
+```bash
+python -c "import zipfile,glob; print('\n'.join(zipfile.ZipFile(sorted(glob.glob('dist/*.whl'))[-1]).namelist()))" | grep static
+# expect: modulearn/static/graph.html, graph.js, graph-engine.js
+```
+
+## 2. Push the source to GitHub (a different account than you're logged into)
+
+This repo isn't wired to a remote yet. Create an **empty** repo named `modulearn`
+under `<USER>` on github.com (no README/license — this repo already has them), then:
+
+```bash
+git init
+git add .
+git commit -m "modulearn 0.1.0"
+git branch -M main
+```
+
+Pick one auth path for the other account:
+
+**A. gh CLI, if that account is already added to `gh`:**
+```bash
+gh auth switch --user <USER>        # or: gh auth login
+gh repo view <USER>/modulearn >/dev/null 2>&1 || gh repo create <USER>/modulearn --public --source=. --remote=origin
+git push -u origin main
+```
+
+**B. Plain git over SSH (no gh):** add that account's SSH key to your agent, then:
+```bash
+git remote add origin git@github.com:<USER>/modulearn.git
+git push -u origin main
+```
+
+**C. Plain git over HTTPS:** push and, when prompted, authenticate as `<USER>`
+(use a Personal Access Token as the password, not your login password):
+```bash
+git remote add origin https://github.com/<USER>/modulearn.git
+git push -u origin main
+```
+
+> The `Homepage`/`Source` URLs in `pyproject.toml` must point at
+> `github.com/<USER>/modulearn` so the PyPI page's links resolve.
+
+## 3. TestPyPI dry run (always do this first)
+
+A given filename can never be re-uploaded, so rehearse on TestPyPI. Get a token at
+https://test.pypi.org/manage/account/token/.
+
+```bash
+twine upload --repository testpypi dist/*
+# install it fresh to prove it works end-to-end:
+python -m venv /tmp/ml-test && /tmp/ml-test/bin/pip install \
+  --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ modulearn
+/tmp/ml-test/bin/modulearn demo      # open http://localhost:8000
+```
+
+Eyeball the rendered page at https://test.pypi.org/project/modulearn/.
+
+## 4. Publish to PyPI
+
+Token from https://pypi.org/manage/account/token/.
+
+```bash
+twine upload dist/*
+```
+
+Then verify:
+
+```bash
+pip install modulearn
+modulearn demo
+```
+
+## Cutting later releases
+
+1. Bump `version` in `pyproject.toml` **and** `__version__` in `modulearn/__init__.py`.
+2. `rm -rf dist && python -m build`
+3. `twine check dist/*`
+4. `git commit -am "modulearn <ver>" && git tag v<ver> && git push --tags`
+5. `twine upload dist/*`

modulearn-0.1.0/README.md

@@ -0,0 +1,138 @@
+# ModuLearn
+
+A visual, [Unreal-Blueprints](https://dev.epicgames.com/documentation/en-us/unreal-engine/blueprints-visual-scripting-in-unreal-engine)-style
+node-graph editor for building and launching machine-learning training runs.
+Drop **Dataset → Model → Train** nodes on a canvas, wire **hyperparameters**,
+**loss** and **feature transforms** into them, hit ▶ Train, and watch the learning
+curve live on the graph. No forms, no drift between the UI and the code it runs.
+
+> **ModuLearn** is a working name — you assemble training runs from modular nodes and
+> learn from the live curve. Rename the package/repo freely; nothing depends on the name.
+
+<!-- A screenshot or GIF of the editor goes well here. -->
+
+## Why
+
+Most training UIs are flat forms that slowly rot out of sync with the code behind
+them. ModuLearn inverts that: your Python is the single source of truth. You *declare*
+what you can train once, in a `Registry`, and the entire editor — palette, typed
+wiring rules, live validation, launch — is generated from it. Wire something the
+backend can't accept and it simply won't connect.
+
+## Install
+
+```bash
+pip install -e .          # fastapi + uvicorn + pydantic
+modulearn demo            # serve the bundled editor at http://localhost:8000
+```
+
+`modulearn demo` is a complete, **dependency-free** editor (its "trainer" is a toy
+loss curve) so you can click around immediately. Once you've built your own app,
+serve it the same way:
+
+```bash
+modulearn run myproject.py        # serves the `app` you built with create_app
+modulearn run myproject.py:editor # ...or a differently-named app / factory
+modulearn --help
+```
+
+Swap `on_train` for your real training loop and nothing else changes. (The
+equivalent source file lives at [`examples/quickstart.py`](examples/quickstart.py)
+if you'd rather run it directly with `python`.)
+
+## The whole integration is two things
+
+```python
+from modulearn import Registry, Param, create_app
+
+reg = Registry()
+
+reg.add_dataset("iris", title="Iris", kind="tabular",
+                features=[...], targets=["species"])
+reg.add_model("mlp", title="MLP", requires_kind="tabular",
+              params=[Param("hidden", "hidden layers", "int_list", [64, 32])])
+reg.add_hyperparameter("lr", label="learning rate", default=1e-3, min=1e-6, max=1)
+reg.add_loss([Param("loss", "kind", "enum", "mse", choices=["mse", "cross_entropy"])])
+
+def on_train(compiled, reporter):
+    # compiled.dataset, .model, .model_params, .hyperparameters, .loss_params, .transforms
+    reporter.state(epochs=100)
+    for e in range(100):
+        reporter.metric(epoch=e, train=..., val=...)   # drives the live chart
+        reporter.state(epoch=e, best_val=...)
+    reporter.state(phase="done", test_score=...)
+
+app = create_app(reg, on_train, title="My Project")
+```
+
+1. **A `Registry`** — declare datasets, models, hyperparameters, a loss, and
+   optional feature transforms. Each hyperparameter you add automatically grows a
+   matching, type-checked input on the Train sink.
+2. **`on_train(compiled, reporter)`** — your training loop. `compiled` is a
+   fully-validated [`CompiledGraph`](modulearn/compiler.py); `reporter` publishes
+   progress the editor polls (see the state contract below).
+
+## How it fits together
+
+```
+ registry.py   ── you declare nodes ──►  catalog (GET /api/nodes)
+      │                                        │
+      ▼                                        ▼
+ compiler.py   ◄── canvas JSON ────────  static/ (custom canvas engine)
+      │  type-checks every wire, runs semantic checks
+      ▼
+ CompiledGraph ──►  your on_train(compiled, reporter)  ──►  runs/<id>/{state,metrics}.json
+                                                                   │
+                                                    editor polls ◄─┘  (live panel + chart)
+```
+
+- **Typed ports.** Links carry a family (`dataset`, `model`, `loss`, `run`) or a
+  field-specific scalar subtype (`scalar/lr`), so a learning-rate value fits the
+  `lr` input and *never* `epochs` — enforced both client-side and in the compiler.
+- **All-or-nothing compile.** `compile_graph` collects every structural, type and
+  semantic error and raises them together, so the UI flags all bad wires at once.
+- **Composable transforms.** Chain `Dataset → Transform → … → Model`; the compiler
+  walks the chain into `compiled.transforms`. Mark a transform `live=False` to show
+  it in the palette but have the compiler refuse it until your backend is ready.
+- **Stateless live window.** Training runs in a background thread and persists to
+  `runs/<id>/`. Closing the browser never stops a run; reopening shows true state.
+
+## The state contract
+
+Your `on_train` reports through `reporter`, and the editor reads these keys:
+
+| call | keys the UI understands |
+|------|-------------------------|
+| `reporter.state(**kw)` | `phase` (`running`/`done`/`error`), `epoch`, `epochs`, `best_val`, `test_score`, `error` |
+| `reporter.metric(**row)` | `epoch`, `train`, `val` → the live learning curve |
+
+Anything else you write is stored and returned by the API, just not charted.
+
+## Editor niceties
+
+- Searchable palette with collapsible category dropdowns; `⌘K` / `/` to focus,
+  Enter to drop the first match.
+- Wires colored by type, with flowing pulses that speed up on the edges feeding a
+  running Train node; ports glow while you drag a compatible connection.
+- Canvas persists to `localStorage`; reload/fork any past run's blueprint.
+- All motion respects `prefers-reduced-motion`.
+
+## Layout
+
+```
+modulearn/
+  registry.py    the declarative surface your app fills in
+  compiler.py    graph JSON -> validated CompiledGraph (pure, unit-testable)
+  server.py      create_app(): FastAPI factory + background job runner
+  cli.py         the `modulearn` command (demo / run)
+  demo.py        the app `modulearn demo` serves
+  static/        graph.html, graph.js (app), graph-engine.js (canvas engine)
+examples/
+  quickstart.py  a complete, dependency-free editor
+```
+
+## License
+
+MIT (see [LICENSE](LICENSE)). The canvas node-graph engine
+(`static/graph-engine.js`) is our own, built from scratch — no third-party
+graph library.