labforge 0.1.0__py3-none-any.whl

labforge/ui.py

@@ -0,0 +1,167 @@
+"""
+Shared UI builders: the app's typographic and surface vocabulary.
+"""
+
+import flet as ft
+
+from .mathtext import equation_image
+
+# The app's two typographic voices: a grotesque for prose and a monospace for
+# anything that is data — parameter labels, readouts, tables, telemetry lines.
+# Both resolve by name as macOS system fonts; bundle files via page.fonts to
+# ship the same faces on Windows or in the browser.
+FONT_BODY = "Helvetica Neue"
+FONT_MONO = "Menlo"
+
+
+def image(data, width=None, height=None):
+    """
+    Display a raw base64 PNG (no data: prefix), as produced by figures/mathtext,
+    at the given logical-pixel size (None keeps the intrinsic size).
+    """
+    # Flet 0.86 Image takes base64 directly on src (there is no src_base64).
+    return ft.Image(src=data, width=width, height=height)
+
+
+def equation(latex, fontsize=18):
+    """
+    Render displayed math — content without surrounding dollar signs, e.g.
+    r"f(x)=\\lambda" — as a LaTeX image sized to the measured equation.
+    """
+    img = equation_image(latex, fontsize=fontsize)
+    return image(img["src"], width=img["width"], height=img["height"])
+
+
+def heading(text):
+    """Section heading: tracked display caps for the top of a page or section."""
+    return ft.Text(
+        text.upper(),
+        style=ft.TextStyle(size=22, weight=ft.FontWeight.W_800, letter_spacing=1.5),
+    )
+
+
+def subheading(text):
+    """Letterspaced all-caps microlabel that marks a block within a page."""
+    return ft.Text(
+        text.upper(),
+        style=ft.TextStyle(
+            size=11,
+            weight=ft.FontWeight.W_700,
+            letter_spacing=2.5,
+            color=ft.Colors.PRIMARY,
+            font_family=FONT_MONO,
+        ),
+    )
+
+
+def mono(text, size=12, color=ft.Colors.ON_SURFACE_VARIANT):
+    """Monospace telemetry text for status lines and small readouts."""
+    return ft.Text(
+        text,
+        style=ft.TextStyle(size=size, font_family=FONT_MONO, letter_spacing=0.5, color=color),
+    )
+
+
+def body(markdown):
+    """Prose as selectable GitHub-flavored Markdown."""
+    return ft.Markdown(
+        value=markdown,
+        selectable=True,
+        extension_set=ft.MarkdownExtensionSet.GITHUB_WEB,
+    )
+
+
+def action_button(label, on_click):
+    """Primary action: a squared filled button with a tracked mono-caps label."""
+    return ft.FilledButton(
+        content=ft.Text(
+            label.upper(),
+            style=ft.TextStyle(
+                size=13, weight=ft.FontWeight.W_700, letter_spacing=2, font_family=FONT_MONO
+            ),
+        ),
+        on_click=on_click,
+        style=ft.ButtonStyle(shape=ft.RoundedRectangleBorder(radius=2)),
+    )
+
+
+def card(content, padding=16):
+    """
+    Group related controls on a card surface: a lifted tone, a hairline outline
+    and near-square corners.
+    """
+    return ft.Container(
+        content=content,
+        padding=padding,
+        bgcolor=ft.Colors.SURFACE_CONTAINER_LOW,
+        border=ft.Border.all(1, ft.Colors.OUTLINE_VARIANT),
+        border_radius=2,
+    )
+
+
+def placeholder(text):
+    """Muted card standing in for a section the author registered nothing for."""
+    return card(ft.Text(text, color=ft.Colors.ON_SURFACE_VARIANT), padding=20)
+
+
+def data_table(columns, rows):
+    """
+    An ft.DataTable (same columns/rows arguments) with the house treatment —
+    tinted mono-caps heading row, hairline rules, monospace cells — so every
+    table in an app reads the same.
+    """
+    return ft.DataTable(
+        columns=columns,
+        rows=rows,
+        heading_row_color=ft.Colors.SURFACE_CONTAINER_LOW,
+        heading_row_height=44,
+        heading_text_style=ft.TextStyle(
+            size=11,
+            weight=ft.FontWeight.W_700,
+            letter_spacing=2,
+            font_family=FONT_MONO,
+            color=ft.Colors.ON_SURFACE_VARIANT,
+        ),
+        data_text_style=ft.TextStyle(size=13, font_family=FONT_MONO),
+        horizontal_lines=ft.BorderSide(1, ft.Colors.OUTLINE_VARIANT),
+        border=ft.Border.all(1, ft.Colors.OUTLINE_VARIANT),
+        border_radius=2,
+        column_spacing=32,
+    )
+
+
+def needs_run():
+    """Instrument-panel status line shown before the worker has been run."""
+    return card(
+        ft.Row(
+            spacing=12,
+            vertical_alignment=ft.CrossAxisAlignment.CENTER,
+            controls=[
+                ft.Icon(ft.Icons.SCIENCE_OUTLINED, size=18, color=ft.Colors.PRIMARY),
+                ft.Text(
+                    "NO DATA",
+                    style=ft.TextStyle(
+                        size=12,
+                        weight=ft.FontWeight.W_700,
+                        letter_spacing=2,
+                        font_family=FONT_MONO,
+                    ),
+                ),
+                mono("— set parameters on the Simulation page and press RUN"),
+            ],
+        ),
+        padding=16,
+    )
+
+
+def page_scaffold(title, controls):
+    """
+    Scrollable page body: a heading above the supplied controls, in a column
+    that fills the content pane and scrolls when tall.
+    """
+    return ft.Column(
+        expand=True,
+        scroll=ft.ScrollMode.AUTO,
+        spacing=16,
+        controls=[heading(title), *controls],
+    )

labforge-0.1.0.dist-info/METADATA

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: labforge
+Version: 0.1.0
+Summary: Wrap plain Python functions into a small scientific Flet desktop app: theory, simulation, visualization, analysis.
+Project-URL: Homepage, https://github.com/laroccod/labforge
+Project-URL: Repository, https://github.com/laroccod/labforge
+Project-URL: Issues, https://github.com/laroccod/labforge/issues
+Project-URL: Changelog, https://github.com/laroccod/labforge/blob/main/CHANGELOG.md
+Author: Daniel La Rocco
+License-Expression: MIT
+License-File: LICENSE
+Keywords: desktop-app,flet,gui,matplotlib,scientific-computing,simulation,visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+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 :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: flet==0.86.0
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: numpy>=2.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# `labforge`
+
+*By Daniel La Rocco*
+
+## **Turn plain Python scripts into a small scientific desktop app.**
+
+labforge wraps a simulation you already have — a function that produces data,
+a function that plots it, a function that summarizes it — into a polished
+four-section app following the **theory → simulation → visualization →
+analysis** workflow. Pure Python, rendered with [Flet](https://flet.dev); no
+HTML, no JavaScript, no callbacks to wire up.
+
+You provide the science and labforge supplies the app shell, the parameter controls
+generated from your function signatures, the parameter-scan engine,
+LaTeX rendering for your theory notes, and eight instrument-panel themes, four
+dark and four light.
+
+![The demo lab's Simulation and Visualization pages side by side](https://raw.githubusercontent.com/laroccod/labforge/main/assets/screenshot.png)
+
+## Quick start
+
+```python
+import matplotlib.pyplot as plt
+import numpy as np
+
+import labforge
+from labforge import Lab, Param, ScanResult
+
+lab = Lab("gausslab")
+lab.set_theory("theory.md")   # markdown file or string; $$...$$ becomes LaTeX
+
+
+def sample(mu=0.0, sigma=1.0, n=2000, seed=42):
+    """Draw n Gaussian variates; reproducible for a given seed."""
+    return np.random.default_rng(seed).normal(mu, sigma, n)
+
+
+lab.add_worker(sample, {
+    "mu": Param(default=0.0, bounds=(-5, 5), scan=True),
+    "sigma": Param(default=1.0, bounds=(0.1, 4), scan=True),
+    "n": Param(kind="int", default=2000, bounds=(10, 100_000)),
+    "seed": "int",
+})
+
+
+def histogram(data, bins=40):
+    fig, ax = plt.subplots(figsize=(7, 3.4))
+    if isinstance(data, ScanResult):   # a parameter scan: one histogram per grid point
+        for params, draws in data:
+            ax.hist(draws, bins=bins, density=True, alpha=0.5,
+                    label=", ".join(f"{k} = {params[k]:g}" for k in data.keys))
+        ax.legend()
+    else:
+        ax.hist(data, bins=bins, density=True, color=labforge.palette().data)
+    labforge.style(fig, ax)            # optional house treatment
+    return fig, ax
+
+
+lab.add_viz(histogram, "Histogram", "Density histogram of the draw.",
+            {"bins": Param(kind="int", default=40, bounds=(5, 200))})
+
+
+def moments(data):
+    if isinstance(data, ScanResult):   # one table row per grid point
+        return [{**params, "mean": float(np.mean(d)), "std": float(np.std(d))}
+                for params, d in data]
+    return {"mean": float(np.mean(data)), "std": float(np.std(data, ddof=1))}
+
+
+lab.add_analysis(moments, "Moments", "Sample moments of the draw.")
+
+lab.open()
+```
+
+That is the whole app. `lab.open()` opens a native window with four pages —
+Theory, Simulation, Visualization, Analysis — a slider for every bounded
+parameter, a Run button, and tabs for each registered visualization and
+analysis.
+
+An extended version of this example — same lab plus a fitted-density overlay
+and a Q-Q plot tab — lives at [`examples/demo_lab.py`](examples/demo_lab.py):
+
+```bash
+python examples/demo_lab.py                 # native window
+python examples/demo_lab.py --browser 8550  # serve at http://localhost:8550
+python examples/demo_lab.py --scroll        # one continuous scrolling page
+python examples/demo_lab.py --theme lavender
+```
+
+## Concepts
+
+**Worker.** One function produces the data. Each keyword argument gets a UI
+control from its `Param` spec — or from the signature default alone, if you
+spec nothing:
+
+| spec | control |
+| --- | --- |
+| `Param(default=1.0, bounds=(0, 5))` | slider with live readout |
+| `Param(kind="int", default=100, bounds=(10, 1000))` | integer slider |
+| `Param(default=1.0)` / `"scalar"` / `"int"` | validated text field |
+| `Param(..., scan=True)` / `"scalar or array"` / `"int or array"` | scannable (see below) |
+| `"N-tuple"` (e.g. `"2-tuple"`) | one field per element |
+
+Validation happens at registration: unknown spec keys, defaults outside
+bounds, or a scan spec on a non-worker function raise `ValueError` when the
+app is assembled, never mid-use.
+
+**Parameter scans.** A kwarg declared `scan=True` gets a scan toggle (bounded)
+or a comma-separated field (unbounded). Enter `0, 1, 2` and labforge calls the
+worker once per point of the cartesian grid across all scanned parameters —
+the worker itself always receives scalars. Downstream functions then receive a
+`ScanResult`: a list of `(params, result)` records with `keys`, `values()` and
+`axis(name)` helpers, distinguished with `isinstance(data, ScanResult)`.
+
+**Visualizations.** Functions `viz(data, **kwargs)` returning a matplotlib
+figure (bare or `(fig, ax)`). Each gets a tab with its own controls and a
+Render button. Figures are yours — labforge only serializes them; the house
+style (`labforge.style(fig, ax)`) is strictly opt-in.
+
+**Analyses.** Functions `analysis(data, **kwargs)` — the return shape picks
+the rendering:
+
+| return | rendered as |
+| --- | --- |
+| `dict` | two-column quantity/value table |
+| `list` of `dict`s, or a DataFrame | full table |
+| `str` | markdown |
+| Figure or `(fig, ax)` | image |
+| anything else | its `repr` |
+
+**Theory.** A markdown file or string. Displayed `$$...$$` equations render as
+crisp images — through your system LaTeX toolchain when one is installed
+(with the Euler math font), falling back to matplotlib's mathtext otherwise.
+
+## Layouts, views and themes
+
+`lab.open()` takes four independent knobs:
+
+- `view="app"` (native window, default) or `"browser"` — serve the same app
+  and open it in your web browser; with a fixed `port` the URL is stable
+  across relaunches, and every browser tab gets its own isolated session.
+- `layout="pages"` (rail navigation, default) or `"scroll"` — the whole lab
+  as one continuous scrolling page.
+- `theme` — one of eight palettes, four dark and four light. A theme sets the
+  chrome, the plot palette and the equation ink together, so figures never
+  drift from the app around them. Colour your own figures with
+  `labforge.palette().data`, `.model`, `.highlight`; list the options with
+  `labforge.themes()`:
+
+| name | mode | look |
+| --- | --- | --- |
+| `paper` | light | warm paper surfaces, graphite ink, vermilion accent (default) |
+| `mint` | light | light mint greens on white |
+| `glacier` | light | pale glacier blues, deep slate accent |
+| `lavender` | light | soft lavender neutrals, deep violet accent |
+| `retro_green` | dark | matrix mood, calmer green, legible olive card |
+| `instrument` | dark | near-black teal-tinted surfaces, one electric accent |
+| `neon_violet` | dark | violet chrome, hot-pink data |
+| `neon_gold` | dark | the violet palette with pale gold as the accent |
+
+The Theory page under each theme — the equations are real LaTeX, rendered in
+the theme's ink:
+
+| | |
+| --- | --- |
+| `paper` ![paper](https://raw.githubusercontent.com/laroccod/labforge/main/assets/theme_paper.png) | `mint` ![mint](https://raw.githubusercontent.com/laroccod/labforge/main/assets/theme_mint.png) |
+| `glacier` ![glacier](https://raw.githubusercontent.com/laroccod/labforge/main/assets/theme_glacier.png) | `lavender` ![lavender](https://raw.githubusercontent.com/laroccod/labforge/main/assets/theme_lavender.png) |
+| `retro_green` ![retro_green](https://raw.githubusercontent.com/laroccod/labforge/main/assets/theme_retro_green.png) | `instrument` ![instrument](https://raw.githubusercontent.com/laroccod/labforge/main/assets/theme_instrument.png) |
+| `neon_violet` ![neon_violet](https://raw.githubusercontent.com/laroccod/labforge/main/assets/theme_neon_violet.png) | `neon_gold` ![neon_gold](https://raw.githubusercontent.com/laroccod/labforge/main/assets/theme_neon_gold.png) |
+
+## Install
+
+Requires Python ≥ 3.10. Not yet on PyPI — install from a clone:
+
+```bash
+git clone https://github.com/laroccod/labforge.git
+cd labforge
+pip install -e .
+```
+
+Dependencies: `flet` (pinned), `numpy`, `matplotlib`. A system LaTeX
+toolchain (`latex` + `dvipng`) is optional and only affects equation
+typography.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                                        # unit + offline page-tree smoke tests
+black --check --line-length 100 src tests examples
+```
+
+The test suite builds every page and layout headlessly — no window needed —
+and asserts that equations and figures actually rendered, so most mistakes are
+caught without launching the app.
+
+## License
+
+[MIT](LICENSE)

labforge-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+labforge/__init__.py,sha256=ayUX0S7AOuaAmOo3WfRN5WSj_-EDlDagU8IbQxHw0og,671
+labforge/controls.py,sha256=1roInLtNQIuMYG1pz9qHs6AccnHpKXQViau_TFaWMsM,8947
+labforge/figures.py,sha256=eWAB5nJqRKTyJp2sRccj43FrtY96Oz9xno-HlN8G76Q,2977
+labforge/lab.py,sha256=Tdh7BTS2N46p_boeIIrv5fVW-Ob6Yqo5dn_VMamuHac,5951
+labforge/mathtext.py,sha256=PVErkvwl-S_RRTVfk90QiXo4aREc7ipvah1xJQruBy4,4972
+labforge/param.py,sha256=WT2-H5SGvunXYiK8nmFp0ar-xhGDM8jVLy26pxnvY_4,7011
+labforge/registry.py,sha256=kVKmeyPNQ12fCU5BY7mBFGOAfDHdLYBSSxSlDddBH0A,719
+labforge/scan.py,sha256=VJclxRNj5f_AGeZEtRfAOOUMIS8MrxDWrut-JRmW-K0,2213
+labforge/shell.py,sha256=KWwcKPtlgrqRNbhiXEKi4QsmAofnw-0e9u3H66qIElM,8266
+labforge/state.py,sha256=sFibg-Z6fqsGvrX41FiUU5OqVBn9tlR-BasnfWG1ytg,2741
+labforge/theme.py,sha256=itATAI9IU_evJnHLrpTDSkD9XIeza21tF2I_tz5HHjc,9535
+labforge/ui.py,sha256=zkROpZiZp6EHZBQU6dB15Ms3YTSws-h0PHLpBj8yoLw,5219
+labforge/pages/__init__.py,sha256=cHxqJmCZSDmVB_E1W0ZvagD8gnzGe39UyFIVaue4a40,204
+labforge/pages/analysis.py,sha256=Q3ILD_hY4d9bIZITDdKxlJln_tAyQXgu7yTnpTdjBg4,3097
+labforge/pages/panel.py,sha256=zhV1wylMKjZBZeF1VaM-qnkQyXRwUld7yQ74F6EhO9k,3752
+labforge/pages/scroll.py,sha256=IwJvry9ZBRE-2N9gfsWxcyFWC7hnfIrV0rKk9cXYM2Q,2011
+labforge/pages/simulation.py,sha256=pIQd8JK0QATlFIUmZ9Tt8nuwTHGh0xWOXXHR-8cyH74,2417
+labforge/pages/theory.py,sha256=dZbdMBEZnPSDnBFycSkTqxgUfbZUbDtl-pYcYx9BR9g,1373
+labforge/pages/visualization.py,sha256=vGTad6ofAVfN1F6SwD9VO4csUbfhYbJf8YwEtCLbw34,927
+labforge-0.1.0.dist-info/METADATA,sha256=HTPFcB48jO7Iqj5_f0CYeiRItRp9V5Mt8ayhhPMU9mQ,9790
+labforge-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+labforge-0.1.0.dist-info/licenses/LICENSE,sha256=jL8VIVG60zlXtgzTZRgrwChwHG8s0ZSPxYyIm84GwSY,1072
+labforge-0.1.0.dist-info/RECORD,,

labforge-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

labforge-0.1.0.dist-info/licenses/LICENSE

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