nipact 0.0.1a1__tar.gz

nipact-0.0.1a1/LICENSE

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

nipact-0.0.1a1/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: nipact
+Version: 0.0.1a1
+Summary: Lightweight Snakemake wrapper and orchestrator for NIPACT workflows.
+Author-email: liuforest <lshangming@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://liuforest.github.io/nipact-docs/
+Project-URL: Documentation, https://liuforest.github.io/nipact-docs/
+Project-URL: Source, https://github.com/liuforest/nipact
+Project-URL: Issues, https://github.com/liuforest/nipact/issues
+Keywords: snakemake,workflow,orchestration,provenance,neuroimaging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.115
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.7
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: snakemake<10,>=9
+Requires-Dist: uvicorn>=0.30
+Dynamic: license-file
+
+# NIPACT
+
+NIPACT is a Python package and CLI tool for orchestrating, executing, and auditing scientific workflows. Currently it is built around Snakemake and uses a SQLite registry for tracking steps and artifacts.
+
+Public documentation lives in a separate repository, `nipact-docs`. See: https://liuforest.github.io/nipact-docs/.
+
+Contents:
+- a `nipact` Python package under `src/`
+- deterministic packaged demo generators used by the tests
+
+Features:
+- Workflow inspection commands (`workflow list`, `workflow steps`, `workflow plan`, `workflow graph`)
+- Workflow execution via Snakemake (`workflow run`)
+- Runtime artifact provenance auditing in a SQLite registry (`trace`)
+- Project-specific GUI viewer for browsing workflow runs, artifacts, and provenance (`gui`)
+- Fully runnable colors demo with synthetic data and no external dependencies
+
+Work in Progress:
+- fMRI and dFC demos
+
+
+## Installation
+
+Initial pre-release is `0.0.1a1`. Install it from PyPI in a clean
+environment:
+
+```bash
+python -m pip install nipact==0.0.1a1
+nipact --version
+```
+
+For development from this repo:
+
+```bash
+python -m pip install -e . pytest
+```
+
+## Local Setup
+
+Install the package and test runner from the repo root:
+
+```bash
+python -m pip install -e . pytest
+```
+
+Run the Python tests:
+
+```bash
+python -m pytest
+```
+
+
+## Colors Demo via CLI
+
+See more details in the documentation at https://liuforest.github.io/nipact-docs/
+
+The current release supports three packaged demos:
+
+```bash
+nipact init \
+  --demo colors \
+  --project-dir demos/colors/project \
+  --runtime-dir demos/colors/runtime
+
+nipact validate --context colors
+```
+
+```bash
+nipact init \
+  --demo fmri \
+  --project-dir demos/fmri/project \
+  --runtime-dir demos/fmri/runtime
+
+nipact validate --context fmri
+```
+
+```bash
+nipact init \
+  --demo dfc \
+  --project-dir demos/dfc/project \
+  --runtime-dir demos/dfc/runtime
+
+nipact validate --context dfc
+```
+
+NOTES:
+`--project-dir` and `--runtime-dir` must be empty and must not contain each other.
+
+`init` creates a generated demo project plus mutable runtime files. The project contains `nipact.yaml`, `sources.yaml`, manifests, step YAML, and workflow YAML.
+
+The runtime contains demo source files under `data/` and `database/registry.db`. It also writes `nipact.contexts.yaml` in the current workspace so later commands can resolve `--context <demo>` to the generated project root. The context index is workspace-local state; this repository ignores the root file so source-checkout testing does not add tutorial state to version control. `validate` is read-only.
+
+Workflow inspection and execution:
+
+```bash
+nipact workflow list \
+  --context colors
+
+nipact workflow steps \
+  --context colors \
+  --workflow base
+
+nipact workflow plan \
+  --context colors \
+  --workflow base \
+  --step color_sector_analysis
+
+nipact workflow graph \
+  --context colors \
+  --workflow base \
+  --step color_sector_analysis
+
+nipact workflow run \
+  --context colors \
+  --workflow base \
+  --step color_sector_analysis \
+  --dry-run
+
+nipact workflow run \
+  --context colors \
+  --workflow base \
+  --step color_sector_analysis \
+  --cores 1
+
+nipact trace \
+  --context colors \
+  --workflow base \
+  --step color_sector_analysis \
+  --output sector_counts \
+  --address init
+
+nipact gui \
+  --context colors \
+  --port 8765
+```
+
+`trace` and `gui` read `runtime/database/registry.db`. The GUI binds to `127.0.0.1` and serves a local browser view for current workflows, manifests, artifacts, workflow topology, and focused artifact lineage.
+
+The gui is for viewing only, not to execute workflows, registry rows, etc.
+

nipact-0.0.1a1/README.md

@@ -0,0 +1,140 @@
+# NIPACT
+
+NIPACT is a Python package and CLI tool for orchestrating, executing, and auditing scientific workflows. Currently it is built around Snakemake and uses a SQLite registry for tracking steps and artifacts.
+
+Public documentation lives in a separate repository, `nipact-docs`. See: https://liuforest.github.io/nipact-docs/.
+
+Contents:
+- a `nipact` Python package under `src/`
+- deterministic packaged demo generators used by the tests
+
+Features:
+- Workflow inspection commands (`workflow list`, `workflow steps`, `workflow plan`, `workflow graph`)
+- Workflow execution via Snakemake (`workflow run`)
+- Runtime artifact provenance auditing in a SQLite registry (`trace`)
+- Project-specific GUI viewer for browsing workflow runs, artifacts, and provenance (`gui`)
+- Fully runnable colors demo with synthetic data and no external dependencies
+
+Work in Progress:
+- fMRI and dFC demos
+
+
+## Installation
+
+Initial pre-release is `0.0.1a1`. Install it from PyPI in a clean
+environment:
+
+```bash
+python -m pip install nipact==0.0.1a1
+nipact --version
+```
+
+For development from this repo:
+
+```bash
+python -m pip install -e . pytest
+```
+
+## Local Setup
+
+Install the package and test runner from the repo root:
+
+```bash
+python -m pip install -e . pytest
+```
+
+Run the Python tests:
+
+```bash
+python -m pytest
+```
+
+
+## Colors Demo via CLI
+
+See more details in the documentation at https://liuforest.github.io/nipact-docs/
+
+The current release supports three packaged demos:
+
+```bash
+nipact init \
+  --demo colors \
+  --project-dir demos/colors/project \
+  --runtime-dir demos/colors/runtime
+
+nipact validate --context colors
+```
+
+```bash
+nipact init \
+  --demo fmri \
+  --project-dir demos/fmri/project \
+  --runtime-dir demos/fmri/runtime
+
+nipact validate --context fmri
+```
+
+```bash
+nipact init \
+  --demo dfc \
+  --project-dir demos/dfc/project \
+  --runtime-dir demos/dfc/runtime
+
+nipact validate --context dfc
+```
+
+NOTES:
+`--project-dir` and `--runtime-dir` must be empty and must not contain each other.
+
+`init` creates a generated demo project plus mutable runtime files. The project contains `nipact.yaml`, `sources.yaml`, manifests, step YAML, and workflow YAML.
+
+The runtime contains demo source files under `data/` and `database/registry.db`. It also writes `nipact.contexts.yaml` in the current workspace so later commands can resolve `--context <demo>` to the generated project root. The context index is workspace-local state; this repository ignores the root file so source-checkout testing does not add tutorial state to version control. `validate` is read-only.
+
+Workflow inspection and execution:
+
+```bash
+nipact workflow list \
+  --context colors
+
+nipact workflow steps \
+  --context colors \
+  --workflow base
+
+nipact workflow plan \
+  --context colors \
+  --workflow base \
+  --step color_sector_analysis
+
+nipact workflow graph \
+  --context colors \
+  --workflow base \
+  --step color_sector_analysis
+
+nipact workflow run \
+  --context colors \
+  --workflow base \
+  --step color_sector_analysis \
+  --dry-run
+
+nipact workflow run \
+  --context colors \
+  --workflow base \
+  --step color_sector_analysis \
+  --cores 1
+
+nipact trace \
+  --context colors \
+  --workflow base \
+  --step color_sector_analysis \
+  --output sector_counts \
+  --address init
+
+nipact gui \
+  --context colors \
+  --port 8765
+```
+
+`trace` and `gui` read `runtime/database/registry.db`. The GUI binds to `127.0.0.1` and serves a local browser view for current workflows, manifests, artifacts, workflow topology, and focused artifact lineage.
+
+The gui is for viewing only, not to execute workflows, registry rows, etc.
+

nipact-0.0.1a1/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nipact"
+dynamic = ["version"]
+description = "Lightweight Snakemake wrapper and orchestrator for NIPACT workflows."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "liuforest", email = "lshangming@gmail.com"},
+]
+keywords = [
+    "snakemake",
+    "workflow",
+    "orchestration",
+    "provenance",
+    "neuroimaging",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "fastapi>=0.115",
+    "numpy>=1.26",
+    "pydantic>=2.7",
+    "PyYAML>=6.0",
+    "rich>=13.7",
+    "snakemake>=9,<10",
+    "uvicorn>=0.30",
+]
+
+[project.urls]
+Homepage = "https://liuforest.github.io/nipact-docs/"
+Documentation = "https://liuforest.github.io/nipact-docs/"
+Source = "https://github.com/liuforest/nipact"
+Issues = "https://github.com/liuforest/nipact/issues"
+
+[project.scripts]
+nipact = "nipact.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"nipact.gui" = ["static/index.html", "static/assets/*"]
+
+[tool.setuptools.dynamic]
+version = {attr = "nipact._version.__version__"}
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

nipact-0.0.1a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nipact-0.0.1a1/src/nipact/__init__.py

@@ -0,0 +1,5 @@
+"""NIPACT package."""
+
+from ._version import __version__
+
+__all__ = ["__version__"]

nipact-0.0.1a1/src/nipact/_version.py

@@ -0,0 +1,3 @@
+"""Package version."""
+
+__version__ = "0.0.1a1"

nipact-0.0.1a1/src/nipact/artifacts.py

@@ -0,0 +1,44 @@
+"""Small helpers for published artifact filenames."""
+
+from __future__ import annotations
+
+from .errors import ValidationError
+from .identity import validate_hash_alias, validate_path_token
+
+
+def output_filename(*, address: str, output_hash: str, declared_extension: str) -> str:
+    """Return the final hash-named output filename."""
+    address = validate_path_token(address, label="output address")
+    output_hash = validate_hash_alias(output_hash)
+    _validate_declared_extension(declared_extension)
+    return f"{address}.{output_hash}{declared_extension}"
+
+
+def parse_output_filename(
+    filename: str,
+    *,
+    declared_extension: str,
+) -> tuple[str, str]:
+    """Parse a final output filename using the declared extension, not Path.suffix."""
+    if not isinstance(filename, str) or not filename:
+        raise ValidationError("output filename must be a non-empty string")
+    _validate_declared_extension(declared_extension)
+    if not filename.endswith(declared_extension):
+        raise ValidationError("output filename does not end with declared extension")
+    stem = filename[: -len(declared_extension)]
+    try:
+        address, output_hash = stem.rsplit(".", maxsplit=1)
+    except ValueError as exc:
+        raise ValidationError("output filename must include output_hash") from exc
+    return (
+        validate_path_token(address, label="output address"),
+        validate_hash_alias(output_hash),
+    )
+
+
+def _validate_declared_extension(value: object) -> str:
+    if not isinstance(value, str) or not value.startswith("."):
+        raise ValidationError("declared extension must start with '.'")
+    if "/" in value or "\\" in value or value in {".", ".."}:
+        raise ValidationError("declared extension must be a file extension")
+    return value