modulearn 0.1.0__py3-none-any.whl

modulearn-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+modulearn/__init__.py,sha256=6EN58AT7BZPRsO1b_oOZUQt0jcQfa6-zxOTlgDSJ_KE,744
+modulearn/cli.py,sha256=87Nlkrh8vMLtzhFZgHw_cLy5T8x5Fxfb1R1KnoH5i2k,3292
+modulearn/compiler.py,sha256=H0_J6zvhM465IsfSJpf7b01s61rfweUu9ui3O4wtwSg,9918
+modulearn/demo.py,sha256=CAYKeJ474K2mYeCIEDeIzzNddaWKq80JCt0_5yf9_Ms,3625
+modulearn/registry.py,sha256=ZrNig7_f_KNJttPAAy_RDUOzfzKBA7Y9mrCjUZWd5ck,12279
+modulearn/server.py,sha256=2LboJ7Fa0TMwuPOruW3CXT-IwDAzHbF1Qys4DZD9mHs,7306
+modulearn/static/graph-engine.js,sha256=2S20jl-BRhbPqp-NGmeOIOHB8Ul6_L0XloBKMzzf_gY,23894
+modulearn/static/graph.html,sha256=cGi-SRTbGN2p83uHG_Rnh37xwkk3XjEDRIf3Temp1PE,9376
+modulearn/static/graph.js,sha256=pk6CoKANOvrjnKiKE_EkWtplM4rlEN91vdl49kqS0ow,42798
+modulearn-0.1.0.dist-info/METADATA,sha256=FyRzqa_1IYQUFF0go6VtaffgdBlI25UKihZTwF3_IYw,7181
+modulearn-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+modulearn-0.1.0.dist-info/entry_points.txt,sha256=M2Tgfyoyj6rZKM1yzsQr8_2K2irYMeVnp4enUNH2kRg,49
+modulearn-0.1.0.dist-info/licenses/LICENSE,sha256=D_c18RFRF53oxJo1eTGDelamr2ZMRaL-Ti4vvwmCDrI,1073
+modulearn-0.1.0.dist-info/RECORD,,

modulearn-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

modulearn-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+modulearn = modulearn.cli:main

modulearn-0.1.0.dist-info/licenses/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.