labforge 0.1.0__py3-none-any.whl

labforge/pages/analysis.py

@@ -0,0 +1,99 @@
+"""
+Analysis page: one tab per registered analysis, with a dispatched result pane.
+"""
+
+import flet as ft
+
+from .. import ui
+from ..figures import figure_to_base64, is_figure, unpack_figure
+from . import panel
+
+EMPTY = "No analyses registered — add one with Lab.add_analysis."
+
+
+def section_controls(entry, state, page):
+    """
+    One analysis's description, kwarg controls, Compute action and result pane,
+    as a list of controls. Shared by the tabbed page and the scroll layout.
+    """
+    pane = ft.Container()
+
+    def show(value):
+        # Swap only the content: the mounted Container stays, so the tab survives.
+        pane.content = render_result(value)
+
+    return panel.section_controls(
+        entry, state, state.analysis_values[entry.title], page, "Compute", pane, show
+    )
+
+
+def build(state, page):
+    """Build the tabbed analysis page."""
+    return panel.build("Analysis", state.lab.analyses, state, page, section_controls, EMPTY)
+
+
+def render_result(value):
+    """
+    Dispatch an analysis return to a display control.
+
+    What an analysis may return is deliberately loose: the author writes plain
+    Python and the shape of the return picks the treatment.
+
+    Parameters
+    ----------
+    value: object
+        dict, list of dicts, DataFrame-like, str, Figure or (fig, ax), or
+        anything with a repr as the fallback.
+
+    Returns
+    -------
+    A Flet control rendering the value.
+    """
+    if isinstance(value, dict):
+        return two_column_table(value)
+    if isinstance(value, list) and value and all(isinstance(row, dict) for row in value):
+        return records_table(value)
+    if hasattr(value, "columns") and hasattr(value, "itertuples"):  # DataFrame, duck-typed
+        return records_table(
+            [dict(zip(value.columns, row)) for row in value.itertuples(index=False)]
+        )
+    if isinstance(value, str):
+        return ui.body(value)
+    if is_figure(value):
+        return ui.image(figure_to_base64(unpack_figure(value)))
+    return ui.body(f"`{value!r}`")
+
+
+def format_cell(value):
+    """Compact display form of one table cell."""
+    return f"{value:.4g}" if isinstance(value, float) else str(value)
+
+
+def two_column_table(mapping):
+    """A {quantity: value} dict as a two-column table."""
+    return ui.data_table(
+        columns=[
+            ft.DataColumn(ft.Text("QUANTITY")),
+            ft.DataColumn(ft.Text("VALUE"), numeric=True),
+        ],
+        rows=[
+            ft.DataRow(
+                cells=[ft.DataCell(ft.Text(str(key))), ft.DataCell(ft.Text(format_cell(value)))]
+            )
+            for key, value in mapping.items()
+        ],
+    )
+
+
+def records_table(records):
+    """A list of homogeneous dicts as a table, columns taken from the first record."""
+    columns = list(records[0])
+    return ui.data_table(
+        columns=[ft.DataColumn(ft.Text(str(name).upper())) for name in columns],
+        rows=[
+            ft.DataRow(
+                cells=[ft.DataCell(ft.Text(format_cell(record.get(name)))) for name in columns]
+            )
+            for record in records
+        ],
+    )

labforge/pages/panel.py

@@ -0,0 +1,109 @@
+"""
+Shared machinery for the visualization and analysis pages, which differ only in
+what they put on screen.
+"""
+
+import flet as ft
+
+from .. import ui
+from ..controls import build_control
+
+
+def section_controls(entry, state, values, page, action, output, show):
+    """
+    Build one registered entry as a stackable list: the optional description,
+    the controls card, and output.
+
+    The output control is persistent: show() mutates it in place rather than
+    replacing it, so the open tab survives a re-render. The first paint runs
+    from the stored kwargs, so returning to a page shows finished output rather
+    than a blank pane.
+
+    Parameters
+    ----------
+    values: dict
+        The entry's persisted {kwarg: value}; controls read and commit to it.
+    action: str
+        Action button label ("Render", "Compute").
+    output: Control
+        The persistent pane show() writes into.
+    show: callable
+        show(result) -> None, writing the entry function's return into output.
+    """
+    bindings = {
+        name: build_control(name, param, values, page) for name, param in entry.params.items()
+    }
+    status = ui.mono("")
+
+    def refresh():
+        kwargs = {name: binding.read() for name, binding in bindings.items()}
+        try:
+            show(entry.func(state.data, **kwargs))
+            status.value = ""
+        except Exception as err:  # surface the author's failure, keep the app alive
+            status.value = f"{entry.title} raised {type(err).__name__}: {err}"
+
+    def on_action(e):
+        refresh()
+        page.update()
+
+    refresh()  # first paint, from the kwargs the last visit left behind
+    controls_card = ui.card(
+        ft.Column(
+            spacing=12,
+            controls=[
+                *[binding.row for binding in bindings.values()],
+                ui.action_button(action, on_action),
+                status,
+            ],
+        )
+    )
+    header = [ui.body(entry.desc)] if entry.desc else []
+    return [*header, controls_card, output]
+
+
+def build(title, entries, state, page, section, empty):
+    """
+    Build a tabbed page — one tab per registered entry, behind the run gate —
+    or the placeholder / run-gate scaffold when there is nothing to show.
+
+    Parameters
+    ----------
+    section: callable
+        section(entry, state, page) -> list of controls for one entry.
+    empty: str
+        Placeholder text shown when nothing is registered.
+    """
+    if not entries:
+        return ui.page_scaffold(title, [ui.placeholder(empty)])
+    if not state.has_data():
+        return ui.page_scaffold(title, [ui.needs_run()])
+
+    # Flet 0.86 Tabs is a controller wrapping a separate TabBar and TabBarView,
+    # whose control count must equal length.
+    tabs = ft.Tabs(
+        length=len(entries),
+        expand=True,
+        content=ft.Column(
+            expand=True,
+            controls=[
+                ft.TabBar(tabs=[ft.Tab(label=entry.title) for entry in entries]),
+                ft.TabBarView(
+                    expand=True,
+                    # Each tab body scrolls itself; see the column note below.
+                    controls=[
+                        ft.Column(
+                            expand=True,
+                            scroll=ft.ScrollMode.AUTO,
+                            spacing=12,
+                            controls=section(entry, state, page),
+                        )
+                        for entry in entries
+                    ],
+                ),
+            ],
+        ),
+    )
+    # Deliberately not a scrolling column: an expanding TabBarView needs bounded
+    # ancestor heights, so each tab body scrolls on its own instead.
+    return ft.Column(expand=True, spacing=16, controls=[ui.heading(title), tabs])

labforge/pages/scroll.py

@@ -0,0 +1,61 @@
+"""
+Scroll layout: the whole lab as one continuous page, refreshed in place by Run.
+"""
+
+import flet as ft
+
+from .. import ui
+from . import analysis, simulation, theory, visualization
+
+
+def divider():
+    """Hairline rule between sections."""
+    return ft.Divider(height=1, color=ft.Colors.OUTLINE_VARIANT)
+
+
+def results_content(state, page):
+    """The visualization and analysis sections, or the run gate before data."""
+    if not state.has_data():
+        return ft.Column(spacing=16, controls=[ui.heading("Results"), ui.needs_run()])
+
+    # Both kinds stack the same way; only the section builder differs.
+    sections = [(entry, visualization.section_controls) for entry in state.lab.vizzes]
+    sections += [(entry, analysis.section_controls) for entry in state.lab.analyses]
+    controls = []
+    for entry, section in sections:
+        controls += [ui.heading(entry.title), *section(entry, state, page), divider()]
+    if controls:
+        controls.pop()  # no rule after the last section
+    return ft.Column(spacing=16, controls=controls)
+
+
+def build(state, page):
+    """
+    Build the single-page layout for the whole lab.
+
+    With no navigation there is no rebuild-on-navigate to refresh downstream
+    sections, so Run gets an after_run hook that rebuilds the mounted results
+    container in place; the handler's page.update() then paints it in one flush.
+    Tabs are avoided deliberately: an expanding TabBarView needs bounded
+    ancestor heights, which a scrolling column cannot provide.
+    """
+    results = ft.Container()
+
+    def refresh():
+        results.content = results_content(state, page)
+
+    refresh()
+    return ft.Column(
+        expand=True,
+        scroll=ft.ScrollMode.AUTO,
+        spacing=16,
+        controls=[
+            ui.heading("Theory"),
+            *theory.content(state),
+            divider(),
+            ui.heading("Simulation"),
+            *simulation.section(state, page, after_run=refresh),
+            divider(),
+            results,
+        ],
+    )

labforge/pages/simulation.py

@@ -0,0 +1,71 @@
+"""
+Simulation page: the worker's controls, a Run action and a status line.
+"""
+
+import flet as ft
+
+from .. import ui
+from ..controls import build_control
+
+
+def section(state, page, after_run=None):
+    """
+    Build the worker's intro prose and controls card as a stackable list.
+
+    Parameters
+    ----------
+    after_run: callable
+        Invoked after a successful run, before the page update — the scroll
+        layout uses it to rebuild the visualization and analysis sections.
+    """
+    worker = state.lab.worker
+    bindings = {
+        name: build_control(name, param, state.worker_values, page)
+        for name, param in worker.params.items()
+    }
+    # Flet 0.86 has no SnackBar, so status lives in the tree where page.update()
+    # always reaches it.
+    status = ui.mono(state.run_summary)
+
+    def on_run(e):
+        for name, binding in bindings.items():
+            state.worker_values[name] = binding.read()
+        try:
+            # Synchronous in the handler: workers are expected fast. page.run_task
+            # with a worker thread is the seam if long runs ever need a live UI.
+            state.run()
+            status.value = state.run_summary
+            if after_run is not None:
+                after_run()
+        except Exception as err:  # surface the worker's failure, keep the app alive
+            status.value = f"Worker raised {type(err).__name__}: {err}"
+        page.update()
+
+    scannable = [name for name, param in worker.params.items() if param.scan]
+    scan_note = (
+        f" Parameters marked scan ({', '.join(scannable)}) accept comma-separated "
+        "values; the worker then runs once per point of the cartesian grid."
+        if scannable
+        else ""
+    )
+    intro = ui.body(
+        f"Set the parameters of **{worker.func.__name__}** and press Run. "
+        "The visualization and analysis sections read the most recent result." + scan_note
+    )
+    controls_card = ui.card(
+        ft.Column(
+            spacing=12,
+            controls=[
+                ui.subheading("Parameters"),
+                *[binding.row for binding in bindings.values()],
+                ui.action_button("Run", on_run),
+                status,
+            ],
+        )
+    )
+    return [intro, controls_card]
+
+
+def build(state, page):
+    """Build the simulation page for the registered worker."""
+    return ui.page_scaffold("Simulation", section(state, page))

labforge/pages/theory.py

@@ -0,0 +1,40 @@
+"""
+Theory page: markdown prose with $$...$$ blocks rendered as LaTeX images.
+"""
+
+import re
+
+from .. import ui
+
+EQUATION_BLOCK = re.compile(r"\$\$(.+?)\$\$", re.DOTALL)
+
+EMPTY = "No theory registered — pass a markdown file or string to Lab.set_theory."
+
+
+def content(state):
+    """
+    The theory controls — prose and equations, or a placeholder when unset.
+
+    Flet's Markdown control has no reliable LaTeX support, so displayed
+    equations are carried in $$...$$ blocks and rendered as images instead.
+    Inline math should use Unicode symbols in the prose.
+    """
+    source = state.lab.theory_source
+    if not source:
+        return [ui.placeholder(EMPTY)]
+    controls = []
+    for index, piece in enumerate(EQUATION_BLOCK.split(source)):
+        piece = piece.strip()
+        if not piece:
+            continue
+        # split() alternates prose and captures, so odd indices are the equations.
+        # An equation collapses to one line: matplotlib renders each line of a
+        # multi-line string separately, and a line with an unmatched $ renders
+        # as literal text rather than math.
+        controls.append(ui.equation(" ".join(piece.split())) if index % 2 else ui.body(piece))
+    return controls
+
+
+def build(state, page):
+    """Build the Theory page from the lab's markdown source."""
+    return ui.page_scaffold("Theory", content(state))

labforge/pages/visualization.py

@@ -0,0 +1,30 @@
+"""
+Visualization page: one tab per registered viz, each rendering a figure.
+"""
+
+from .. import ui
+from ..figures import figure_to_base64, unpack_figure
+from . import panel
+
+EMPTY = "No visualizations registered — add one with Lab.add_viz."
+
+
+def section_controls(entry, state, page):
+    """
+    One viz's description, kwarg controls, Render action and figure, as a list
+    of controls. Shared by the tabbed page and the scroll layout.
+    """
+    image = ui.image("")
+
+    def show(value):
+        # Swap only the src: the mounted Image stays, so the open tab survives.
+        image.src = figure_to_base64(unpack_figure(value))
+
+    return panel.section_controls(
+        entry, state, state.viz_values[entry.title], page, "Render", image, show
+    )
+
+
+def build(state, page):
+    """Build the tabbed visualization page."""
+    return panel.build("Visualization", state.lab.vizzes, state, page, section_controls, EMPTY)

labforge/param.py

@@ -0,0 +1,186 @@
+"""
+Param specs and the registration-time normalization of an author's spec dict.
+"""
+
+import inspect
+import re
+from dataclasses import dataclass
+
+
+@dataclass
+class Param:
+    """
+    One adjustable kwarg of a worker, viz or analysis function.
+
+    Parameters
+    ----------
+    kind: str
+        "scalar" (float), "int", or "tuple".
+    default: object
+        Starting value; filled from the function signature default when None.
+    bounds: tuple
+        (lo, hi) numeric range. Bounded scalars and ints render as sliders,
+        unbounded ones as validated text fields.
+    step: float
+        Slider granularity; (hi - lo) / 100 when omitted, 1 for ints.
+    scan: bool
+        Worker kwargs only: accept comma-separated values to sweep a grid.
+    size: int
+        Tuple length (kind "tuple" only).
+    label: str
+        Control label; the kwarg name when omitted.
+    """
+
+    kind: str = "scalar"
+    default: object = None
+    bounds: tuple = None
+    step: float = None
+    scan: bool = False
+    size: int = 2
+    label: str = None
+
+
+# Shorthand strings accepted in spec dicts, checked before the N-tuple pattern.
+SHORTHANDS = {
+    "scalar": dict(kind="scalar"),
+    "int": dict(kind="int"),
+    "array": dict(kind="scalar", scan=True),
+    "scalar or array": dict(kind="scalar", scan=True),
+    "int or array": dict(kind="int", scan=True),
+}
+
+TUPLE_PATTERN = re.compile(r"^(\d+)-tuple$")
+
+
+def parse_shorthand(text):
+    """
+    Convert a shorthand string — a SHORTHANDS key or "N-tuple" (e.g. "2-tuple")
+    — into a Param with kind/scan/size set; default left to signature inference.
+    """
+    key = text.strip().lower()
+    if key in SHORTHANDS:
+        return Param(**SHORTHANDS[key])
+    match = TUPLE_PATTERN.match(key)
+    if match:
+        return Param(kind="tuple", size=int(match.group(1)))
+    raise ValueError(
+        f"Unknown param shorthand {text!r}; expected one of " f"{sorted(SHORTHANDS)} or 'N-tuple'."
+    )
+
+
+def infer_param(default):
+    """Infer a Param from a signature default: bool/int, tuple, else scalar."""
+    # bool before int: bool is an int subclass, and a checkbox-ish 0/1 is closer
+    # to the author's intent than a float slider.
+    if isinstance(default, bool):
+        return Param(kind="int", default=int(default))
+    if isinstance(default, int):
+        return Param(kind="int", default=default)
+    if isinstance(default, (tuple, list)):
+        return Param(kind="tuple", default=tuple(default), size=len(default))
+    return Param(kind="scalar", default=float(default))
+
+
+def normalize_spec(func, spec, skip_first=False, allow_scan=True):
+    """
+    Validate a spec dict against a function signature and fill in defaults.
+
+    Every named keyword-capable parameter of func gets a Param: spec entries
+    (Param instances or shorthand strings) take precedence, and unspecced
+    parameters are inferred from their signature defaults. Fails loudly at
+    registration on unknown spec keys, unresolvable defaults, out-of-bounds
+    defaults, or a scan spec where scanning is not allowed — so a malformed app
+    dies at assembly rather than mid-navigation.
+
+    Parameters
+    ----------
+    func: callable
+        The registered worker, viz or analysis function.
+    spec: dict
+        {kwarg name: Param or shorthand str}, or None for pure inference.
+    skip_first: bool
+        Skip the leading positional parameter (the data argument of viz and
+        analysis functions).
+    allow_scan: bool
+        Reject scan=True entries when False (scanning is a worker concept).
+
+    Returns
+    -------
+    dict of {name: Param} in signature order, every default resolved.
+    """
+    spec = dict(spec or {})
+    signature = inspect.signature(func)
+    parameters = list(signature.parameters.values())
+    if skip_first:
+        parameters = parameters[1:]
+
+    named = [
+        p
+        for p in parameters
+        if p.kind in (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY)
+    ]
+    # A **kwargs function can take spec keys its signature never names.
+    has_var_keyword = any(p.kind == inspect.Parameter.VAR_KEYWORD for p in parameters)
+
+    known = {p.name for p in named}
+    for key in spec:
+        if key not in known and not has_var_keyword:
+            raise ValueError(f"{func.__name__} has no parameter {key!r}.")
+
+    # Signature order drives the control layout; **kwargs-only entries trail it.
+    normalized = {}
+    order = [p.name for p in named] + [k for k in spec if k not in known]
+    defaults = {p.name: p.default for p in named}
+    for name in order:
+        entry = spec.get(name)
+        if isinstance(entry, str):
+            entry = parse_shorthand(entry)
+        # Resolve the default: spec first, signature second, error last.
+        signature_default = defaults.get(name, inspect.Parameter.empty)
+        if entry is None:
+            if signature_default is inspect.Parameter.empty:
+                raise ValueError(
+                    f"{func.__name__} parameter {name!r} needs a spec entry or a "
+                    "signature default."
+                )
+            entry = infer_param(signature_default)
+        elif entry.default is None:
+            if signature_default is inspect.Parameter.empty:
+                raise ValueError(
+                    f"{func.__name__} parameter {name!r} has no default in its spec "
+                    "or signature."
+                )
+            entry.default = signature_default
+        validate_param(func, name, entry, allow_scan)
+        normalized[name] = entry
+    return normalized
+
+
+def validate_param(func, name, param, allow_scan):
+    """
+    Check one resolved Param's internal consistency, raising ValueError.
+
+    Also coerces the default to the declared kind and fills a slider step for
+    bounded params, so controls.py can trust both.
+    """
+    where = f"{func.__name__} parameter {name!r}"
+    if param.kind not in ("scalar", "int", "tuple"):
+        raise ValueError(f"{where}: unknown kind {param.kind!r}.")
+    if param.scan and not allow_scan:
+        raise ValueError(f"{where}: scan specs are only valid on the worker.")
+    if param.kind == "tuple":
+        if param.scan:
+            raise ValueError(f"{where}: tuple params cannot be scanned.")
+        param.default = tuple(param.default)
+        if len(param.default) != param.size:
+            raise ValueError(f"{where}: default {param.default} does not match size {param.size}.")
+        return
+    param.default = int(param.default) if param.kind == "int" else float(param.default)
+    if param.bounds is not None:
+        if len(param.bounds) != 2 or not param.bounds[0] < param.bounds[1]:
+            raise ValueError(f"{where}: bounds must be an increasing (lo, hi) pair.")
+        lo, hi = param.bounds
+        if not lo <= param.default <= hi:
+            raise ValueError(f"{where}: default {param.default} outside bounds {param.bounds}.")
+        if param.step is None:
+            param.step = 1 if param.kind == "int" else (hi - lo) / 100

labforge/registry.py

@@ -0,0 +1,36 @@
+"""
+The value records the Lab stores per registered function.
+
+Dataclasses rather than bare tuples, so page code reads entry.title, not
+entry[1]. A shared contract between lab.py, state.py and the pages.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class WorkerSpec:
+    """The data-producing function and its control spec."""
+
+    func: callable
+    params: dict
+
+
+@dataclass
+class VizSpec:
+    """One visualization tab: a figure-returning function plus its controls."""
+
+    func: callable
+    title: str
+    desc: str
+    params: dict
+
+
+@dataclass
+class AnalysisSpec:
+    """One analysis tab: a result-returning function plus its controls."""
+
+    func: callable
+    title: str
+    desc: str
+    params: dict