scistack-gui 0.1.28__tar.gz

scistack_gui-0.1.28/.gitignore

@@ -0,0 +1,32 @@
+.venv
+.DS_Store
+*/*/__pycache__
+others_projects/sciforge
+scistack-gui/extension/node_modules/
+scistack-gui/frontend/node_modules/__pycache__/ 
+*.pyc 
+__pycache__/ 
+*.pyc
+*.pyo
+*.egg-info/
+# Python package build output (rebuilt fresh by CI on every publish; a
+# committed dist/ gets deleted by `rm -rf dist` mid-build and dirties the
+# tree for hatch-vcs). Excludes scistack-gui/extension/dist/, which is an
+# intentionally committed compiled bundle, not a Python build artifact.
+/dist/
+/*/dist/
+# Generated database artifacts (DuckDB data/lineage + write-ahead logs)
+*.duckdb
+*.duckdb.wal
+*.wal
+scistack-gui/frontend/node_modules/
+# Compiled output of the frontend's React-free unit tests (npm test in
+# scistack-gui/frontend). Regenerated by `tsc -p tsconfig.test.json`; unlike
+# extension/dist/, nothing loads it at runtime.
+scistack-gui/frontend/dist/
+# mkdocs build output (regenerated by `mkdocs build`)
+/site/
+# Runtime output of code_export_service (pipeline-to-code export) — timestamped
+# per-run files, not source.
+/exports/
+*.log

scistack_gui-0.1.28/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.5
+Name: scistack-gui
+Version: 0.1.28
+Summary: GUI for SciStack pipelines
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: duckdb>=0.9.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: pydantic>=2.0
+Requires-Dist: scifor
+Requires-Dist: scimatlab
+Requires-Dist: scistack-db
+Requires-Dist: scistackplot[mpl]>=0.1.23
+Requires-Dist: scistackplotdb>=0.1.23
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: uvicorn[standard]>=0.20.0

scistack_gui-0.1.28/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+raw-options = { search_parent_directories = true, local_scheme = "no-local-version" }
+
+[project]
+name = "scistack-gui"
+dynamic = ["version"]
+description = "GUI for SciStack pipelines"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.100.0",
+    # [standard] pulls in a WebSocket protocol library — bare uvicorn
+    # rejects /ws upgrades ("Unsupported upgrade request") and the GUI
+    # silently never receives run_output/run_done/dag_updated pushes.
+    "uvicorn[standard]>=0.20.0",
+    # Top-level import in 9 × api/*.py. Arrives via fastapi today; declared
+    # because metadata states intent, not coincidence.
+    "pydantic>=2.0",
+    "scistack-db",
+    # Top-level import in config.py and registry.py (scifor.discovery).
+    "scifor",
+    # matlab_registry.py, config.py, api/pipeline.py.
+    "scimatlab",
+    # Plot Studio. [mpl] is required, not optional: the save/export path
+    # calls render_matplotlib(). Both packages first shipped in v0.1.23.
+    "scistackplot[mpl]>=0.1.23",
+    "scistackplotdb>=0.1.23",
+    # plot_service.py imports matplotlib directly for PNG export, on top of
+    # whatever scistackplot[mpl] pulls in.
+    "matplotlib>=3.8",
+    "duckdb>=0.9.0",
+    # config.py falls back to tomli when tomllib is unavailable (<3.11).
+    "tomli>=2.0 ; python_version < '3.11'",
+]
+
+[project.scripts]
+scistack-gui = "scistack_gui.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["scistack_gui"]
+
+# Without this, hatchling's default file selection sweeps the whole directory
+# into the sdist — frontend/ and extension/ TypeScript sources plus committed
+# sourcemaps, ~11MB. The wheel only ever needs the Python package and the
+# built standalone bundle under scistack_gui/static/.
+[tool.hatch.build.targets.sdist]
+include = ["/scistack_gui"]

scistack_gui-0.1.28/scistack_gui/__main__.py

@@ -0,0 +1,149 @@
+"""
+CLI entry point: scistack-gui [path/to/experiment.duckdb]
+
+What happens:
+  1. If a db_path is given: import pipeline code, open (or create, with
+     --schema-keys) the database via scistack_gui.bootstrap.
+  2. If no db_path is given: skip straight to step 3 with no project loaded
+     — the browser opens onto the project-creation wizard
+     (POST /api/bootstrap/create, /api/bootstrap/open), which runs the same
+     bootstrap sequence from a running server.
+  3. Start uvicorn on localhost:8765
+  4. Open the browser
+"""
+
+import argparse
+import sys
+import webbrowser
+from pathlib import Path
+
+import uvicorn
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="scistack-gui",
+        description="Launch the SciStack GUI for a pipeline database.",
+    )
+    parser.add_argument(
+        "db_path",
+        type=Path,
+        nargs="?",
+        default=None,
+        help="Path to the SciStack .duckdb file (e.g. experiment.duckdb). "
+        "If omitted, the GUI opens onto a wizard to create or open one.",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8765,
+        help="Port to serve on (default: 8765)",
+    )
+    parser.add_argument(
+        "--module",
+        "-m",
+        type=Path,
+        default=None,
+        help="Path to your pipeline .py file (single-file mode).",
+    )
+    parser.add_argument(
+        "--project",
+        "-p",
+        type=Path,
+        default=None,
+        help="Path to pyproject.toml or directory containing one "
+        "(project mode — reads [tool.scistack] config).",
+    )
+    parser.add_argument(
+        "--schema-keys",
+        type=str,
+        default=None,
+        help="Comma-separated schema keys; if provided and db_path "
+        "does not exist, a new database is created.",
+    )
+    parser.add_argument(
+        "--project-root",
+        type=Path,
+        default=None,
+        help="Directory to treat as the project root when no "
+        "pyproject.toml/scistack.toml exists yet. Determines where a new "
+        "scistack.toml and entities file are written; defaults to the "
+        "working directory.",
+    )
+    parser.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="Don't open the browser automatically",
+    )
+    args = parser.parse_args()
+
+    if args.project_root is not None:
+        from scistack_gui.config import set_project_root_hint
+
+        set_project_root_hint(args.project_root)
+
+    if args.module and args.project:
+        print("Error: --module and --project are mutually exclusive.", file=sys.stderr)
+        sys.exit(1)
+
+    if args.db_path is not None:
+        db_path = args.db_path.resolve()
+        schema_keys = None
+        if args.schema_keys:
+            schema_keys = [k.strip() for k in args.schema_keys.split(",") if k.strip()]
+
+        if not db_path.exists() and not schema_keys:
+            print(f"Error: database file not found: {db_path}", file=sys.stderr)
+            sys.exit(1)
+
+        from scistack_gui.bootstrap import open_or_create_project
+
+        try:
+            result = open_or_create_project(
+                db_path,
+                schema_keys=schema_keys,
+                module=args.module,
+                project=args.project,
+            )
+        except (FileNotFoundError, ValueError, FileExistsError) as e:
+            print(f"Error: {e}", file=sys.stderr)
+            sys.exit(1)
+        except Exception as e:
+            print(f"Error opening database: {e}", file=sys.stderr)
+            sys.exit(1)
+
+        print(f"Opened database: {db_path}")
+        print(f"Schema keys: {result.schema_keys}")
+        print(
+            f"Loaded: {result.functions_loaded} functions, "
+            f"{result.variables_loaded} variables"
+        )
+        if result.matlab_functions_loaded or result.matlab_variables_loaded:
+            print(
+                f"MATLAB: {result.matlab_functions_loaded} functions, "
+                f"{result.matlab_variables_loaded} variables"
+            )
+        for w in result.warnings:
+            print(f"Warning: {w}", file=sys.stderr)
+    else:
+        print("No database given — open the browser to create or open one.")
+
+    url = f"http://localhost:{args.port}"
+    print(f"SciStack GUI running at {url}")
+
+    if not args.no_browser:
+        # Open after a short delay to let uvicorn bind the port
+        import threading
+
+        threading.Timer(1.0, lambda: webbrowser.open(url)).start()
+
+    uvicorn.run(
+        "scistack_gui.app:app",
+        host="localhost",
+        port=args.port,
+        log_level="warning",  # suppress uvicorn's per-request logs
+    )
+
+
+if __name__ == "__main__":
+    main()

scistack_gui-0.1.28/scistack_gui/api/artifacts.py

@@ -0,0 +1,52 @@
+"""
+Endpoint-presentation routes (plan-endpoint-presentation.md).
+
+GET  /api/endpoints/{fn_name}/artifacts — finalized figures/stats manifest
+GET  /api/artifacts/file?path=          — serve one artifact (project-dir
+                                          guarded; 403 outside, 404 missing)
+POST /api/report                        — write the endpoint report,
+                                          return its index.html path
+"""
+
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import FileResponse
+from scidb.database import DatabaseManager
+
+from scistack_gui.db import get_db
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+@router.get("/endpoints/{fn_name}/artifacts")
+def get_endpoint_artifacts(fn_name: str, db: DatabaseManager = Depends(get_db)) -> dict:
+    from scistack_gui.services.endpoint_service import endpoint_artifacts
+
+    return endpoint_artifacts(db, fn_name)
+
+
+@router.get("/artifacts/file")
+def get_artifact_file(path: str, db: DatabaseManager = Depends(get_db)):
+    from scistack_gui.services.endpoint_service import artifact_file_path
+
+    try:
+        resolved = artifact_file_path(db, path)
+    except ValueError as exc:
+        raise HTTPException(status_code=403, detail=str(exc))
+    except FileNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+    return FileResponse(resolved)
+
+
+@router.post("/report")
+def post_report(db: DatabaseManager = Depends(get_db)) -> dict:
+    from scistack_gui.services.endpoint_service import write_report
+
+    try:
+        return write_report(db)
+    except Exception as exc:
+        logger.exception("[api/artifacts] report generation failed")
+        raise HTTPException(status_code=500, detail=str(exc))

scistack_gui-0.1.28/scistack_gui/api/bootstrap.py

@@ -0,0 +1,161 @@
+"""
+Browser-frontend project-creation wizard endpoints.
+
+POST /api/bootstrap/create — create a new .duckdb (folder + filename +
+                              schema keys) and load pipeline code into it.
+                              Also gives loose-script projects a scistack.toml
+                              + an entities file (default
+                              src/scistack_entities.toml) if they have none,
+                              so a freshly-created project never sits in the
+                              pure-folder-scan config state that
+                              pre-existing projects opened without ever
+                              running this endpoint still can (see
+                              docs/claude/code-discovery-categories.md).
+                              Create-only: a project that already declares
+                              an entities file keeps it, whatever the
+                              wizard's field says -- see
+                              services.project_init_service.
+POST /api/bootstrap/open   — open an existing .duckdb and load pipeline code
+
+These exist so the standalone browser frontend can bootstrap a project the
+same way the VS Code extension's "SciStack: Open Pipeline" wizard does
+(extension/src/extension.ts), without requiring a --db path to already
+exist when the server process starts. Both endpoints run the same sequence
+__main__.py runs at CLI startup — see scistack_gui.bootstrap.
+
+VS Code never hits these: server.py's JSON-RPC entry point always opens or
+creates the database before the webview is shown, so its React bundle never
+observes ``db_loaded: false`` from GET /api/info.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from scistack_gui.bootstrap import open_or_create_project
+from scistack_gui.services.pipeline_service import get_info
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/bootstrap", tags=["bootstrap"])
+
+
+class CreateProjectRequest(BaseModel):
+    folder: str
+    filename: str
+    schema_keys: list[str]
+    module: str | None = None
+    project: str | None = None
+    entities_file: str | None = "src/scistack_entities.toml"
+    """Where to create an entities file *if this project has none*.
+
+    Relative to the *project root*, not to ``folder`` -- ``folder`` is where
+    the database goes, which is typically a datasets directory. See
+    ``config.resolve_project_root``. An explicit ``null`` opts out of project
+    initialization entirely."""
+
+
+class OpenProjectRequest(BaseModel):
+    db_path: str
+    module: str | None = None
+    project: str | None = None
+
+
+def _resolve_db_path(folder: str, filename: str) -> Path:
+    filename = filename.strip()
+    if not filename:
+        raise HTTPException(status_code=400, detail="Filename must not be empty.")
+    if "/" in filename or "\\" in filename:
+        raise HTTPException(
+            status_code=400, detail="Filename must not contain path separators."
+        )
+    if not filename.endswith(".duckdb"):
+        filename += ".duckdb"
+    return Path(folder).expanduser() / filename
+
+
+@router.post("/create")
+def create_project(req: CreateProjectRequest) -> dict:
+    """Create a new database (folder must already exist) and load pipeline code."""
+    logger.info(
+        "[api.bootstrap] create request: folder=%s filename=%s schema_keys=%s "
+        "module=%s project=%s",
+        req.folder,
+        req.filename,
+        req.schema_keys,
+        req.module,
+        req.project,
+    )
+    folder = Path(req.folder).expanduser()
+    if not folder.is_dir():
+        raise HTTPException(
+            status_code=404, detail=f"Folder does not exist: {folder}"
+        )
+
+    db_path = _resolve_db_path(req.folder, req.filename)
+    if db_path.exists():
+        # Checked here as well as inside open_or_create_project so the
+        # frontend gets a 409 with this message rather than a bare
+        # FileExistsError string.
+        raise HTTPException(
+            status_code=409, detail=f"Database already exists: {db_path}"
+        )
+    module = Path(req.module).expanduser() if req.module else None
+    project = Path(req.project).expanduser() if req.project else None
+
+    try:
+        open_or_create_project(
+            db_path,
+            schema_keys=req.schema_keys,
+            module=module,
+            project=project,
+            # An explicit null entities_file is an opt-out, so bootstrap's
+            # own initialization must not put the files back.
+            init_project_files=bool(req.entities_file),
+            # Where to put one IF the project has none. This used to be a
+            # separate eager config_mod.set_entities_file call right here,
+            # which unconditionally re-pointed the key -- so creating a
+            # database in a project that already declared its entities
+            # somewhere else silently swapped in a new empty file and the
+            # existing declarations vanished from the GUI. Routing it
+            # through project_init_service makes it create-only, like every
+            # other step there.
+            entities_file=req.entities_file,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    except FileExistsError as exc:
+        raise HTTPException(status_code=409, detail=str(exc))
+    except FileNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+
+    logger.info("[api.bootstrap] created database at %s", db_path)
+    return get_info()
+
+
+@router.post("/open")
+def open_project(req: OpenProjectRequest) -> dict:
+    """Open an existing database and load pipeline code."""
+    logger.info(
+        "[api.bootstrap] open request: db_path=%s module=%s project=%s",
+        req.db_path,
+        req.module,
+        req.project,
+    )
+    db_path = Path(req.db_path).expanduser()
+    module = Path(req.module).expanduser() if req.module else None
+    project = Path(req.project).expanduser() if req.project else None
+
+    try:
+        open_or_create_project(db_path, module=module, project=project)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    except FileNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+
+    logger.info("[api.bootstrap] opened database at %s", db_path)
+    return get_info()

scistack_gui-0.1.28/scistack_gui/api/builtin_functions.py

@@ -0,0 +1,31 @@
+"""
+POST /api/functions/builtin — manual built-in/library function references.
+
+Thin FastAPI wrapper; the actual validation/registration logic lives in
+``services/builtin_function_service.py`` so it can be shared with the
+JSON-RPC handler used by the VS Code extension (``server.py``,
+``create_builtin_function`` method).
+"""
+
+import logging
+
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+class CreateBuiltinFunctionRequest(BaseModel):
+    language: str  # "python" | "matlab"
+    reference: str  # e.g. "numpy.mean", "len", "mean"
+
+
+@router.post("/functions/builtin")
+def create_builtin_function(req: CreateBuiltinFunctionRequest) -> dict:
+    from scistack_gui.services.builtin_function_service import (
+        create_builtin_function as _create,
+    )
+
+    return _create(req.language, req.reference)

scistack_gui-0.1.28/scistack_gui/api/glue.py

@@ -0,0 +1,108 @@
+"""
+Glue-node endpoints — list, create, read, save, remove, and the live column
+list the code panel shows beside the editor.
+
+A glue node has **no run endpoint**, by design (D5). It is transient by
+construction, so a standalone run would produce nothing and a state badge
+would describe nothing; it executes only as part of a consuming function's
+run. See ``docs/claude/free-code-glue-nodes.md`` §5, and ``api/run.py``'s
+refusal of a glue node id.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+from scistack_gui.api import ws
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+class CreateGlueRequest(BaseModel):
+    name: str
+    param: str = "value"
+    language: str = "python"
+
+
+class SaveGlueRequest(BaseModel):
+    name: str
+    source: str
+
+
+@router.get("/glue")
+def list_glue() -> dict:
+    from scistack_gui.services import glue_service
+
+    return {"nodes": glue_service.list_glue_nodes()}
+
+
+@router.get("/glue/{name}")
+def get_glue(name: str) -> dict:
+    from scistack_gui.services import glue_service
+
+    return glue_service.read_glue_source(name)
+
+
+@router.get("/glue/{name}/columns")
+def get_glue_columns(name: str, variable_type: str = "") -> dict:
+    """The columns a glue on ``variable_type`` actually receives.
+
+    Read live on every panel open rather than scaffolded into the file as a
+    comment: a comment goes stale the moment the node is rewired.
+    """
+    from scistack_gui.services import glue_service
+
+    if not variable_type:
+        return {
+            "ok": False,
+            "error": (
+                "This glue node is not wired to a variable yet, so there are "
+                "no columns to show."
+            ),
+        }
+    return glue_service.input_columns(variable_type)
+
+
+@router.post("/glue")
+async def create_glue(req: CreateGlueRequest) -> dict:
+    from scistack_gui.services import glue_service
+
+    result = glue_service.create_glue_node(
+        req.name, param=req.param, language=req.language
+    )
+    if result.get("ok"):
+        await ws.broadcast({"type": "dag_updated"})
+    return result
+
+
+@router.put("/glue")
+async def save_glue(req: SaveGlueRequest) -> dict:
+    """Write the edited body, then refresh the registry.
+
+    The refresh is the whole point of the round-trip: the new body has a new
+    hash, so the consuming function's glue chain hash changes, so its next
+    run recomputes instead of skipping. Saving without refreshing would look
+    identical in the panel and silently keep running the old body.
+    """
+    from scistack_gui.services import glue_service
+
+    result = glue_service.update_glue_source(req.name, req.source)
+    if result.get("ok"):
+        await ws.broadcast({"type": "dag_updated"})
+    return result
+
+
+@router.delete("/glue/{name}")
+async def delete_glue(name: str) -> dict:
+    """Remove the node from the canvas. The source file is never unlinked."""
+    from scistack_gui.services import glue_service
+
+    result = glue_service.delete_glue_node(name)
+    if result.get("ok"):
+        await ws.broadcast({"type": "dag_updated"})
+    return result