renderflow 0.1.1__tar.gz

renderflow-0.1.1/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: renderflow
+Version: 0.1.1
+Summary: Generic workflow app runtime and Streamlit renderer with provider plugins
+Author: Brian Day
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: streamlit>=1.31.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: plotly>=5.18.0
+Requires-Dist: kaleido>=0.2.1
+
+# renderflow
+
+Workflow runtime and rendering API for:
+- Streamlit UI
+- CLI execution
+- HTML report export
+- Individual figure export
+
+## Core Idea
+
+`renderflow` owns the interface contract and rendering behavior.
+Provider packages should mostly define workflows (`run_workflow` + params), not custom UI/CLI plumbing.
+
+## Demo App
+
+Live Streamlit demo:
+
+https://demo-for-renderflow.streamlit.app/
+
+## CLI
+
+List installed providers:
+
+```bash
+renderflow list-providers
+```
+
+List provider workflows:
+
+```bash
+renderflow list-workflows --provider crsd-inspector
+```
+
+Show interpreted workflow parameters:
+
+```bash
+renderflow show-params --provider crsd-inspector --workflow signal_analysis
+```
+
+Execute a workflow in terminal mode:
+
+```bash
+renderflow execute \
+  --provider crsd-inspector \
+  --workflow signal_analysis \
+  --param crsd_directory=examples \
+  --param prf_hz=1000 \
+  --output terminal
+```
+
+Execute and export both:
+- one combined report file (`--html`)
+- per-figure files (`--save-figures-dir` + `--figure-format`)
+
+```bash
+renderflow execute \
+  --provider crsd-inspector \
+  --workflow signal_analysis \
+  --param crsd_directory=examples \
+  --html output/report.html \
+  --save-figures-dir output/figures \
+  --figure-format html
+```
+
+Add per-figure JSON in the same run:
+
+```bash
+renderflow execute \
+  --provider crsd-inspector \
+  --workflow signal_analysis \
+  --param crsd_directory=examples \
+  --html output/report.html \
+  --save-figures-dir output/figures \
+  --figure-format html \
+  --figure-format json
+```
+
+Export multiple figure formats in a single run:
+
+```bash
+renderflow execute \
+  --provider crsd-inspector \
+  --workflow signal_analysis \
+  --param crsd_directory=examples \
+  --save-figures-dir output/figures \
+  --figure-format html \
+  --figure-format json
+```
+
+Comma-separated format lists are also accepted:
+
+```bash
+renderflow execute \
+  --provider crsd-inspector \
+  --workflow signal_analysis \
+  --param crsd_directory=examples \
+  --html output/report.html \
+  --save-figures-dir output/figures \
+  --figure-format html,json
+```
+
+If `--figure-format` is omitted, per-figure export defaults to `html`.
+Image formats (`png`, `jpg`, `jpeg`, `svg`, `pdf`) require Kaleido. `renderflow` includes `kaleido` as a dependency.
+
+Launch Streamlit:
+
+```bash
+renderflow run --provider crsd-inspector
+```
+
+## Workflow Result Contract
+
+Use `renderflow.workflow.Workflow` inside provider workflows:
+
+```python
+from renderflow.workflow import Workflow
+
+workflow = Workflow(name="My Workflow", description="...")
+workflow.params = {
+    "threshold": {"type": "number", "default": 0.5, "label": "Threshold"},
+}
+
+workflow.add_text("Summary text")
+workflow.add_table("Metrics", {"name": ["a"], "value": [1]})
+workflow.add_plot(fig, title="Spectrum", figure_id="spectrum", save=True)
+workflow.add_code("print('debug')", language="python")
+return workflow.build()
+```
+
+`add_plot(..., save=False)` marks a plot as not exportable when using figure-save operations.
+
+Minimum return contract from `run_workflow(...)`:
+- must return a `dict`
+- either:
+  - modern shape: `{"results": [ ... ]}`
+  - legacy shape: `{"text": [...], "tables": [...], "plots": [...]}`
+- for modern shape, each item in `results` must be a dict with:
+  - `type` in `text | table | plot | code`
+  - if `type == "plot"`, item must include `figure`
+
+## Provider Contract Options
+
+### 1) Explicit `AppSpec` (fully explicit)
+
+Entry point:
+
+```toml
+[project.entry-points."renderflow.providers"]
+my-provider = "my_provider.app_definition:get_app_spec"
+```
+
+`get_app_spec()` returns `renderflow.contracts.AppSpec`.
+
+### 2) Auto-Defined Provider (minimal)
+
+If no `app_definition` exists, `renderflow` auto-builds from:
+- `<provider>.workflows.*` modules with `run_workflow(...)`
+- optional `<provider>.renderflow` module:
+  - `APP_NAME = "..."`
+  - `WORKFLOWS_PACKAGE = "provider.custom_workflows"` (optional)
+  - optional custom metadata constants for provider setup
+
+Workflow parameters are pulled from:
+1. `workflow.params` if a `workflow` object exists in the module
+2. `PARAMS` module global
+3. inferred function signature defaults
+
+This lets packages like `crsd-inspector` keep only workflow definitions and optional init logic, while `renderflow` handles CLI + Streamlit parameter interpretation and rendering.

renderflow-0.1.1/README.md

@@ -0,0 +1,168 @@
+# renderflow
+
+Workflow runtime and rendering API for:
+- Streamlit UI
+- CLI execution
+- HTML report export
+- Individual figure export
+
+## Core Idea
+
+`renderflow` owns the interface contract and rendering behavior.
+Provider packages should mostly define workflows (`run_workflow` + params), not custom UI/CLI plumbing.
+
+## Demo App
+
+Live Streamlit demo:
+
+https://demo-for-renderflow.streamlit.app/
+
+## CLI
+
+List installed providers:
+
+```bash
+renderflow list-providers
+```
+
+List provider workflows:
+
+```bash
+renderflow list-workflows --provider crsd-inspector
+```
+
+Show interpreted workflow parameters:
+
+```bash
+renderflow show-params --provider crsd-inspector --workflow signal_analysis
+```
+
+Execute a workflow in terminal mode:
+
+```bash
+renderflow execute \
+  --provider crsd-inspector \
+  --workflow signal_analysis \
+  --param crsd_directory=examples \
+  --param prf_hz=1000 \
+  --output terminal
+```
+
+Execute and export both:
+- one combined report file (`--html`)
+- per-figure files (`--save-figures-dir` + `--figure-format`)
+
+```bash
+renderflow execute \
+  --provider crsd-inspector \
+  --workflow signal_analysis \
+  --param crsd_directory=examples \
+  --html output/report.html \
+  --save-figures-dir output/figures \
+  --figure-format html
+```
+
+Add per-figure JSON in the same run:
+
+```bash
+renderflow execute \
+  --provider crsd-inspector \
+  --workflow signal_analysis \
+  --param crsd_directory=examples \
+  --html output/report.html \
+  --save-figures-dir output/figures \
+  --figure-format html \
+  --figure-format json
+```
+
+Export multiple figure formats in a single run:
+
+```bash
+renderflow execute \
+  --provider crsd-inspector \
+  --workflow signal_analysis \
+  --param crsd_directory=examples \
+  --save-figures-dir output/figures \
+  --figure-format html \
+  --figure-format json
+```
+
+Comma-separated format lists are also accepted:
+
+```bash
+renderflow execute \
+  --provider crsd-inspector \
+  --workflow signal_analysis \
+  --param crsd_directory=examples \
+  --html output/report.html \
+  --save-figures-dir output/figures \
+  --figure-format html,json
+```
+
+If `--figure-format` is omitted, per-figure export defaults to `html`.
+Image formats (`png`, `jpg`, `jpeg`, `svg`, `pdf`) require Kaleido. `renderflow` includes `kaleido` as a dependency.
+
+Launch Streamlit:
+
+```bash
+renderflow run --provider crsd-inspector
+```
+
+## Workflow Result Contract
+
+Use `renderflow.workflow.Workflow` inside provider workflows:
+
+```python
+from renderflow.workflow import Workflow
+
+workflow = Workflow(name="My Workflow", description="...")
+workflow.params = {
+    "threshold": {"type": "number", "default": 0.5, "label": "Threshold"},
+}
+
+workflow.add_text("Summary text")
+workflow.add_table("Metrics", {"name": ["a"], "value": [1]})
+workflow.add_plot(fig, title="Spectrum", figure_id="spectrum", save=True)
+workflow.add_code("print('debug')", language="python")
+return workflow.build()
+```
+
+`add_plot(..., save=False)` marks a plot as not exportable when using figure-save operations.
+
+Minimum return contract from `run_workflow(...)`:
+- must return a `dict`
+- either:
+  - modern shape: `{"results": [ ... ]}`
+  - legacy shape: `{"text": [...], "tables": [...], "plots": [...]}`
+- for modern shape, each item in `results` must be a dict with:
+  - `type` in `text | table | plot | code`
+  - if `type == "plot"`, item must include `figure`
+
+## Provider Contract Options
+
+### 1) Explicit `AppSpec` (fully explicit)
+
+Entry point:
+
+```toml
+[project.entry-points."renderflow.providers"]
+my-provider = "my_provider.app_definition:get_app_spec"
+```
+
+`get_app_spec()` returns `renderflow.contracts.AppSpec`.
+
+### 2) Auto-Defined Provider (minimal)
+
+If no `app_definition` exists, `renderflow` auto-builds from:
+- `<provider>.workflows.*` modules with `run_workflow(...)`
+- optional `<provider>.renderflow` module:
+  - `APP_NAME = "..."`
+  - `WORKFLOWS_PACKAGE = "provider.custom_workflows"` (optional)
+  - optional custom metadata constants for provider setup
+
+Workflow parameters are pulled from:
+1. `workflow.params` if a `workflow` object exists in the module
+2. `PARAMS` module global
+3. inferred function signature defaults
+
+This lets packages like `crsd-inspector` keep only workflow definitions and optional init logic, while `renderflow` handles CLI + Streamlit parameter interpretation and rendering.

renderflow-0.1.1/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "renderflow"
+version = "0.1.1"
+description = "Generic workflow app runtime and Streamlit renderer with provider plugins"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Brian Day" }
+]
+dependencies = [
+    "streamlit>=1.31.0",
+    "pandas>=2.0.0",
+    "plotly>=5.18.0",
+    "kaleido>=0.2.1"
+]
+
+[project.scripts]
+renderflow = "renderflow.cli:main"
+workflow-renderer-streamlit = "renderflow.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["renderflow*"]

renderflow-0.1.1/renderflow/__init__.py

@@ -0,0 +1,7 @@
+"""Renderflow core package."""
+
+from renderflow.cli import main
+from renderflow.progress import emit_progress, wrap_with_timing
+from renderflow.workflow import Workflow
+
+__all__ = ["main", "Workflow", "emit_progress", "wrap_with_timing"]

renderflow-0.1.1/renderflow/app.py

@@ -0,0 +1,6 @@
+"""Backward-compatible module for the Streamlit renderer entrypoint."""
+
+from renderflow.cli import main
+from renderflow.streamlit_renderer import launch_streamlit_renderer, run_renderer
+
+__all__ = ["launch_streamlit_renderer", "main", "run_renderer"]

renderflow-0.1.1/renderflow/autodefine.py

@@ -0,0 +1,227 @@
+"""Automatic provider definition from workflow modules."""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+import pkgutil
+from dataclasses import asdict, is_dataclass
+from typing import Any, Callable
+
+from renderflow.contracts import AppSpec, InitializerSpec, ParamSpec, WorkflowSpec
+
+
+def _param_specs_from_mapping(params: dict[str, Any] | None) -> list[ParamSpec]:
+    specs: list[ParamSpec] = []
+    for key, cfg in (params or {}).items():
+        if isinstance(cfg, ParamSpec):
+            specs.append(cfg)
+            continue
+        cfg = cfg or {}
+        specs.append(
+            ParamSpec(
+                key=key,
+                label=cfg.get("label", key),
+                type=cfg.get("type", "text"),
+                default=cfg.get("default"),
+                min=cfg.get("min"),
+                max=cfg.get("max"),
+                step=cfg.get("step"),
+                options=cfg.get("options", []),
+                help=cfg.get("help", ""),
+            )
+        )
+    return specs
+
+
+def _coerce_param_specs(value: Any) -> list[ParamSpec]:
+    if value is None:
+        return []
+    if isinstance(value, dict):
+        return _param_specs_from_mapping(value)
+    specs: list[ParamSpec] = []
+    for item in value:
+        if isinstance(item, ParamSpec):
+            specs.append(item)
+        elif isinstance(item, dict):
+            specs.append(ParamSpec(**item))
+    return specs
+
+
+def _infer_params_from_signature(func: Callable[..., Any]) -> list[ParamSpec]:
+    reserved = {"signal_data", "metadata", "context", "kwargs", "args", "self"}
+    specs: list[ParamSpec] = []
+    for name, param in inspect.signature(func).parameters.items():
+        if name in reserved or param.kind in {inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD}:
+            continue
+        default = None if param.default is inspect.Parameter.empty else param.default
+        param_type = "text"
+        if isinstance(default, bool):
+            param_type = "checkbox"
+        elif isinstance(default, (int, float)):
+            param_type = "number"
+        specs.append(ParamSpec(key=name, label=name.replace("_", " ").title(), type=param_type, default=default))
+    return specs
+
+
+def _invoke_workflow(func: Callable[..., dict[str, Any]], context: dict[str, Any], params: dict[str, Any]):
+    if not isinstance(context, dict):
+        raise TypeError(f"Workflow context must be a dict, got {type(context).__name__}")
+    if not isinstance(params, dict):
+        raise TypeError(f"Workflow params must be a dict, got {type(params).__name__}")
+
+    sig = inspect.signature(func)
+    kwargs: dict[str, Any] = {}
+    merged_metadata: dict[str, Any] = {}
+    base_metadata = context.get("metadata")
+    if isinstance(base_metadata, dict):
+        merged_metadata.update(base_metadata)
+    for key, value in context.items():
+        if key != "metadata":
+            merged_metadata[key] = value
+    merged_metadata.update(params)
+
+    if "signal_data" in sig.parameters and "signal_data" in context:
+        kwargs["signal_data"] = context["signal_data"]
+    if "metadata" in sig.parameters:
+        kwargs["metadata"] = merged_metadata
+    if "context" in sig.parameters:
+        kwargs["context"] = context
+
+    for key, value in params.items():
+        if key in sig.parameters and key not in kwargs:
+            kwargs[key] = value
+
+    result = func(**kwargs)
+    if not isinstance(result, dict):
+        raise TypeError(
+            f"Workflow '{func.__module__}.{func.__name__}' must return a dict, got {type(result).__name__}"
+        )
+    return result
+
+
+def _discover_workflows(provider_name: str, package_name: str) -> list[WorkflowSpec]:
+    pkg = importlib.import_module(package_name)
+    specs: list[WorkflowSpec] = []
+    for module_info in sorted(pkgutil.iter_modules(pkg.__path__), key=lambda m: m.name):
+        if module_info.name.startswith("_"):
+            continue
+        module = importlib.import_module(f"{package_name}.{module_info.name}")
+        run_workflow = getattr(module, "run_workflow", None)
+        if not callable(run_workflow):
+            continue
+
+        workflow_obj = getattr(module, "workflow", None)
+        wf_id = module_info.name
+        wf_name = getattr(workflow_obj, "name", None) or getattr(module, "WORKFLOW_NAME", wf_id)
+        wf_desc = getattr(workflow_obj, "description", None) or getattr(module, "WORKFLOW_DESCRIPTION", "")
+        raw_params = getattr(workflow_obj, "params", None)
+        if raw_params is None:
+            raw_params = getattr(module, "PARAMS", None)
+        if raw_params is None:
+            param_specs = _infer_params_from_signature(run_workflow)
+        else:
+            param_specs = _coerce_param_specs(raw_params)
+
+        def _make_run(func):
+            def _run(context: dict[str, Any], params: dict[str, Any]) -> dict[str, Any]:
+                return _invoke_workflow(func, context, params)
+
+            return _run
+
+        specs.append(
+            WorkflowSpec(
+                id=wf_id,
+                name=wf_name,
+                description=wf_desc,
+                params=param_specs,
+                run=_make_run(run_workflow),
+            )
+        )
+    if not specs:
+        raise RuntimeError(f"No workflow modules with run_workflow() found under {package_name}")
+    return specs
+
+
+def _dict_to_app_spec(raw: dict[str, Any]) -> AppSpec:
+    if {"app_name", "initializers", "workflows"} - set(raw.keys()):
+        raise TypeError("Dictionary provider spec missing one of: app_name, initializers, workflows")
+    initializers: list[InitializerSpec] = []
+    for item in raw["initializers"]:
+        if isinstance(item, InitializerSpec):
+            initializers.append(item)
+        else:
+            initializers.append(
+                InitializerSpec(
+                    id=item["id"],
+                    name=item["name"],
+                    description=item.get("description", ""),
+                    params=_coerce_param_specs(item.get("params")),
+                    initialize=item["initialize"],
+                )
+            )
+
+    workflows: list[WorkflowSpec] = []
+    for item in raw["workflows"]:
+        if isinstance(item, WorkflowSpec):
+            workflows.append(item)
+        else:
+            workflows.append(
+                WorkflowSpec(
+                    id=item["id"],
+                    name=item["name"],
+                    description=item.get("description", ""),
+                    params=_coerce_param_specs(item.get("params")),
+                    run=item["run"],
+                )
+            )
+    return AppSpec(app_name=raw["app_name"], initializers=initializers, workflows=workflows)
+
+
+def coerce_to_app_spec(obj: Any, provider_name: str | None = None) -> AppSpec:
+    if callable(obj) and not isinstance(obj, type):
+        obj = obj()
+    if isinstance(obj, AppSpec):
+        return obj
+    if is_dataclass(obj):
+        return _dict_to_app_spec(asdict(obj))
+    if isinstance(obj, dict):
+        return _dict_to_app_spec(obj)
+    raise TypeError(f"Unsupported provider definition object for {provider_name or 'provider'}: {type(obj)}")
+
+
+def auto_build_app_spec(provider_name: str) -> AppSpec:
+    provider_pkg = importlib.import_module(provider_name)
+
+    cfg_module = None
+    try:
+        cfg_module = importlib.import_module(f"{provider_name}.renderflow")
+    except ModuleNotFoundError:
+        cfg_module = None
+
+    app_name = getattr(cfg_module, "APP_NAME", None) or getattr(provider_pkg, "APP_NAME", None) or provider_name
+    workflow_package = (
+        getattr(cfg_module, "WORKFLOWS_PACKAGE", None) or getattr(provider_pkg, "WORKFLOWS_PACKAGE", None)
+    )
+    if not workflow_package:
+        workflow_package = f"{provider_name}.workflows"
+
+    initializers: list[InitializerSpec] = []
+    init_func = getattr(cfg_module, "initialize", None) or getattr(provider_pkg, "initialize", None)
+    init_params = getattr(cfg_module, "INIT_PARAMS", None) or getattr(provider_pkg, "INIT_PARAMS", None)
+    if callable(init_func):
+        initializers.append(
+            InitializerSpec(
+                id="default_initializer",
+                name="Initialization",
+                description="Provider initialization context",
+                params=_coerce_param_specs(init_params),
+                initialize=init_func,
+            )
+        )
+
+    return AppSpec(
+        app_name=app_name,
+        initializers=initializers,
+        workflows=_discover_workflows(provider_name, workflow_package),
+    )