adagio-cli 0.1.0__tar.gz

adagio_cli-0.1.0/LICENSE

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

adagio_cli-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: adagio-cli
+Version: 0.1.0
+Summary: Command-line runner for Adagio pipeline files.
+Keywords: adagio,bioinformatics,cli,pipelines,qiime2,workflow
+Author: Cymis
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: cyclopts>=4.5.3
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: rich>=14.1.0
+Requires-Dist: tomli>=2.2.1 ; python_full_version < '3.11'
+Requires-Python: >=3.10
+Project-URL: Changelog, https://github.com/cymis/adagio-cli/blob/dev/CHANGELOG.md
+Project-URL: Homepage, https://github.com/cymis/adagio-cli
+Project-URL: Issues, https://github.com/cymis/adagio-cli/issues
+Project-URL: Repository, https://github.com/cymis/adagio-cli
+Description-Content-Type: text/markdown
+
+# Adagio CLI
+
+`adagio-cli` is the Python command-line interface for Adagio pipeline execution.
+
+For user-facing documentation and product guides, please reference the docs:
+
+- [Adagio Docs](https://docs.adagiodata.com)
+
+The adagio frontend is used to build pipelines that can be run with this package on the command line
+It can be found here:
+
+- [Adagio](https://adagio.run)
+
+## Development
+
+Set up the project and run the test suite with:
+
+```bash
+uv sync --group dev
+uv run pytest
+```
+
+## Runtime environments
+
+Every plugin action requires an explicit execution environment. A runtime config
+passed with `--config` can define one default and override it per plugin or task;
+the CLI never guesses an image from a plugin name.
+
+Conda environments are supported with `kind = "conda"`:
+
+```toml
+version = 1
+
+[defaults]
+kind = "conda"
+prefix = "/opt/conda/envs/qiime2-2026.1"
+
+[plugins]
+dada2 = { kind = "conda", prefix = "/opt/conda/envs/q2-dada2" }
+```
+
+The environment must already exist and contain QIIME 2 plus the plugins needed
+by the pipeline. Adagio enters it with `conda run`; it does not create or manage
+the environment.
+
+## Task resource requests
+
+A runtime config can also declare the requested shape of each task execution:
+
+```toml
+[resources.tasks."denoise-node"]
+cpus = 4
+memory = "8 GiB"
+```
+
+`cpus` is a positive whole number and `memory` is a positive, unit-bearing
+quantity. Each entry describes one independently schedulable execution of that
+task, not an aggregate pipeline allocation. If a task is later expanded into
+parallel subtasks, each subtask requests this shape and the scheduler determines
+the total concurrent allocation.
+
+The current serial executor parses and validates these fields but intentionally
+does not apply them yet. Omitting either field leaves that resource at the
+executor's default.
+
+## Plugin submission defaults
+
+QAPI submissions can persist the environment that Adagio should use for the
+submitted plugins:
+
+```bash
+adagio qapi build --plugin my-plugin \
+  --default-conda-prefix /opt/conda/envs/my-plugin
+
+adagio qapi build --plugin my-plugin \
+  --default-docker-image registry.example.org/my-plugin:2026.1
+```
+
+These options are explicit and mutually exclusive. Omitting both leaves the
+plugin without a default; the Adagio app will flag that plugin until an
+environment is selected for a run.
+
+## Catalog pipelines
+
+Run a pipeline from the Adagio pipeline catalog:
+
+```bash
+adagio pipeline show @adagio/microbial-diversity
+adagio run @adagio/microbial-diversity --cache-dir /path/to/cache --arguments run-arguments.json
+```
+
+`@adagio/<slug>` first resolves against a nearby local `adagio-pipelines`
+checkout when one is available. If no local catalog is found, Adagio fetches
+`pipeline.adg` from `cymis/adagio-pipelines` on GitHub, checking `official`
+before `community`.
+
+During `adagio run`, remote catalog pipelines are downloaded under the selected
+`--cache-dir` and reused by source name and slug on later runs. `adagio pipeline
+show` uses a temporary download when it fetches from GitHub because it does not
+take a cache directory.
+
+Private GitHub access is explicit: set `GITHUB_TOKEN` or `GH_TOKEN` to a token
+that can read `cymis/adagio-pipelines`; with a token, the CLI fetches through
+the GitHub contents API. The CLI does not read browser, git, or `gh` credentials
+automatically.

adagio_cli-0.1.0/README.md

@@ -0,0 +1,105 @@
+# Adagio CLI
+
+`adagio-cli` is the Python command-line interface for Adagio pipeline execution.
+
+For user-facing documentation and product guides, please reference the docs:
+
+- [Adagio Docs](https://docs.adagiodata.com)
+
+The adagio frontend is used to build pipelines that can be run with this package on the command line
+It can be found here:
+
+- [Adagio](https://adagio.run)
+
+## Development
+
+Set up the project and run the test suite with:
+
+```bash
+uv sync --group dev
+uv run pytest
+```
+
+## Runtime environments
+
+Every plugin action requires an explicit execution environment. A runtime config
+passed with `--config` can define one default and override it per plugin or task;
+the CLI never guesses an image from a plugin name.
+
+Conda environments are supported with `kind = "conda"`:
+
+```toml
+version = 1
+
+[defaults]
+kind = "conda"
+prefix = "/opt/conda/envs/qiime2-2026.1"
+
+[plugins]
+dada2 = { kind = "conda", prefix = "/opt/conda/envs/q2-dada2" }
+```
+
+The environment must already exist and contain QIIME 2 plus the plugins needed
+by the pipeline. Adagio enters it with `conda run`; it does not create or manage
+the environment.
+
+## Task resource requests
+
+A runtime config can also declare the requested shape of each task execution:
+
+```toml
+[resources.tasks."denoise-node"]
+cpus = 4
+memory = "8 GiB"
+```
+
+`cpus` is a positive whole number and `memory` is a positive, unit-bearing
+quantity. Each entry describes one independently schedulable execution of that
+task, not an aggregate pipeline allocation. If a task is later expanded into
+parallel subtasks, each subtask requests this shape and the scheduler determines
+the total concurrent allocation.
+
+The current serial executor parses and validates these fields but intentionally
+does not apply them yet. Omitting either field leaves that resource at the
+executor's default.
+
+## Plugin submission defaults
+
+QAPI submissions can persist the environment that Adagio should use for the
+submitted plugins:
+
+```bash
+adagio qapi build --plugin my-plugin \
+  --default-conda-prefix /opt/conda/envs/my-plugin
+
+adagio qapi build --plugin my-plugin \
+  --default-docker-image registry.example.org/my-plugin:2026.1
+```
+
+These options are explicit and mutually exclusive. Omitting both leaves the
+plugin without a default; the Adagio app will flag that plugin until an
+environment is selected for a run.
+
+## Catalog pipelines
+
+Run a pipeline from the Adagio pipeline catalog:
+
+```bash
+adagio pipeline show @adagio/microbial-diversity
+adagio run @adagio/microbial-diversity --cache-dir /path/to/cache --arguments run-arguments.json
+```
+
+`@adagio/<slug>` first resolves against a nearby local `adagio-pipelines`
+checkout when one is available. If no local catalog is found, Adagio fetches
+`pipeline.adg` from `cymis/adagio-pipelines` on GitHub, checking `official`
+before `community`.
+
+During `adagio run`, remote catalog pipelines are downloaded under the selected
+`--cache-dir` and reused by source name and slug on later runs. `adagio pipeline
+show` uses a temporary download when it fetches from GitHub because it does not
+take a cache directory.
+
+Private GitHub access is explicit: set `GITHUB_TOKEN` or `GH_TOKEN` to a token
+that can read `cymis/adagio-pipelines`; with a token, the CLI fetches through
+the GitHub contents API. The CLI does not read browser, git, or `gh` credentials
+automatically.

adagio_cli-0.1.0/pyproject.toml

@@ -0,0 +1,91 @@
+[project]
+name = "adagio-cli"
+version = "0.1.0"
+description = "Command-line runner for Adagio pipeline files."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Cymis" }]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+  "adagio",
+  "bioinformatics",
+  "cli",
+  "pipelines",
+  "qiime2",
+  "workflow",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "cyclopts>=4.5.3",
+  "pydantic>=2.12.5",
+  "rich>=14.1.0",
+  "tomli>=2.2.1; python_version < '3.11'",
+]
+
+[project.urls]
+Homepage = "https://github.com/cymis/adagio-cli"
+Repository = "https://github.com/cymis/adagio-cli"
+Issues = "https://github.com/cymis/adagio-cli/issues"
+Changelog = "https://github.com/cymis/adagio-cli/blob/dev/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+  "build>=1.2.2",
+  "nox>=2024.4.15,<2025.0.0",
+  "pytest>=8.4.0",
+  "pytest-cov>=6.0.0",
+  "ruff>=0.13.0",
+  "twine>=6.2.0",
+]
+
+[project.scripts]
+adagio = "adagio.cli.main:main"
+
+[build-system]
+requires = ["uv_build>=0.8.17,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "adagio"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+
+[tool.ruff.lint.isort]
+
+
+known-first-party = ["adagio"]
+section-order = [
+  "future",
+  "standard-library",
+  "third-party",
+  "first-party",
+  "local-folder",
+]
+[tool.mypy]
+plugins = ['pydantic.mypy']
+
+[[tool.mypy.overrides]]
+
+module = ["qiime2.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]

adagio_cli-0.1.0/src/adagio/__init__.py

@@ -0,0 +1,15 @@
+from importlib.metadata import PackageNotFoundError, version
+
+
+def _resolve_version() -> str:
+    for dist_name in ("adagio-cli", "adagio"):
+        try:
+            return version(dist_name)
+        except PackageNotFoundError:
+            continue
+    return "0.0.0"
+
+
+__version__ = _resolve_version()
+
+__all__ = ["__version__"]

adagio_cli-0.1.0/src/adagio/app/parsers/pipeline.py

@@ -0,0 +1,89 @@
+"""Helpers for pulling promoted parameter specs from pipeline JSON."""
+
+from typing import Any, List, Optional
+from uuid import UUID
+
+from pydantic import BaseModel
+
+
+class Parameter(BaseModel):
+    id: UUID
+    name: str
+    required: bool
+    default: Optional[Any] = None
+    type: str
+    description: Optional[str] = None
+
+
+class Input(BaseModel):
+    id: UUID
+    name: str
+    required: bool
+    type: str
+    description: Optional[str] = None
+
+
+class Output(BaseModel):
+    id: UUID
+    name: str
+    type: str
+    description: Optional[str] = None
+
+
+def _extract_signature(data: Any) -> dict[str, Any]:
+    signature = (
+        data.get("spec", {}).get("signature")
+        if isinstance(data, dict)
+        else None
+    ) or (data.get("signature") if isinstance(data, dict) else None)
+
+    if not isinstance(signature, dict):
+        raise ValueError(
+            "Invalid pipeline: missing 'signature' section in pipeline JSON."
+        )
+
+    return signature
+
+
+def parse_parameters(data: Any) -> List[Parameter]:
+    """Parse promoted parameters from supported pipeline JSON layouts.
+
+    We currently accept either:
+    - {"spec": {"signature": {"parameters": [...]}}}
+    - {"signature": {"parameters": [...]} }
+    """
+    signature = _extract_signature(data)
+
+    raw_parameters = signature.get("parameters")
+    if not isinstance(raw_parameters, list):
+        raise ValueError(
+            "Invalid pipeline: missing 'signature.parameters' list in pipeline JSON."
+        )
+
+    return [Parameter(**param) for param in raw_parameters]
+
+
+def parse_inputs(data: Any) -> List[Input]:
+    """Parse promoted inputs from supported pipeline JSON layouts."""
+    signature = _extract_signature(data)
+
+    raw_inputs = signature.get("inputs")
+    if not isinstance(raw_inputs, list):
+        raise ValueError(
+            "Invalid pipeline: missing 'signature.inputs' list in pipeline JSON."
+        )
+
+    return [Input(**input_item) for input_item in raw_inputs]
+
+
+def parse_outputs(data: Any) -> List[Output]:
+    """Parse pipeline outputs from supported pipeline JSON layouts."""
+    signature = _extract_signature(data)
+
+    raw_outputs = signature.get("outputs")
+    if not isinstance(raw_outputs, list):
+        raise ValueError(
+            "Invalid pipeline: missing 'signature.outputs' list in pipeline JSON."
+        )
+
+    return [Output(**output_item) for output_item in raw_outputs]

adagio_cli-0.1.0/src/adagio/check.py

@@ -0,0 +1,16 @@
+
+
+def check_dependencies(spec):
+    pass
+
+
+def check_version(spec):
+    pass
+
+
+def check_graph(spec):
+    pass
+
+
+def check_arguments(spec, arguments):
+    pass

adagio_cli-0.1.0/src/adagio/cli/__init__.py

@@ -0,0 +1 @@
+__all__: list[str] = []

adagio_cli-0.1.0/src/adagio/cli/args.py

@@ -0,0 +1,62 @@
+import re
+from enum import Enum
+
+try:
+    from enum import StrEnum
+except ImportError:  # pragma: no cover - Python < 3.11
+    class StrEnum(str, Enum):
+        pass
+
+
+class ParamType(StrEnum):
+    INPUT = "input"
+    PARAM = "param"
+    OUTPUT = "output"
+
+
+class ShowParamsMode(StrEnum):
+    ALL = "all"
+    MISSING = "missing"
+    REQUIRED = "required"
+
+
+def promote_positional_pipeline(argv: list[str]) -> tuple[list[str], str | None]:
+    """Allow `adagio run <pipeline>` by rewriting it to `--pipeline <pipeline>`."""
+    if len(argv) < 2 or argv[0] != "run":
+        return argv, None
+
+    candidate = argv[1]
+    if candidate.startswith("-"):
+        return argv, None
+
+    rewritten = ["run", "--pipeline", candidate, *argv[2:]]
+    return rewritten, candidate
+
+
+def extract_flag_value(argv: list[str], *flags: str) -> str | None:
+    """Supports: --flag value, -f value, --flag=value."""
+    flag_set = set(flags)
+    for i, tok in enumerate(argv):
+        if tok in flag_set:
+            return argv[i + 1] if i + 1 < len(argv) else None
+        for flag in flags:
+            if tok.startswith(flag + "="):
+                return tok.split("=", 1)[1]
+    return None
+
+
+def to_identifier(name: str, prefix: str | None = None) -> str:
+    """Turn arbitrary names into valid Python identifiers for kwargs keys."""
+    clean = (name or "").strip()
+    clean = re.sub(r"[^0-9a-zA-Z_]+", "_", clean)
+    if not clean:
+        raise ValueError("Empty parameter name in pipeline file.")
+    if clean[0].isdigit():
+        clean = "_" + clean
+    if prefix:
+        return f"{prefix}_{clean}"
+    return clean
+
+
+def dynamic_opt(name: str, param_type: ParamType) -> str:
+    return f"--{param_type}-{name.replace('_', '-')}"

adagio_cli-0.1.0/src/adagio/cli/cache.py

@@ -0,0 +1,82 @@
+import re
+import shutil
+from pathlib import Path
+from typing import Annotated
+
+from cyclopts import App, Group, Parameter
+from rich.console import Console
+
+from ..executors.cache_support import CACHE_DIR_HELP, resolve_cache_dir_path
+
+QIIME_CACHE_CONTENTS = {"VERSION", "data", "keys", "pools", "processes"}
+QIIME_CACHE_LINE_RE = re.compile(r"cache: v?\d+\Z")
+
+
+def run_cache(argv: list[str], *, console: Console) -> None:
+    app = App(
+        name="adagio cache",
+        help="Manage Adagio's shared QIIME cache directory.",
+    )
+    command_group = Group("Command Options", sort_key=0)
+
+    @app.command
+    def clear(
+        *,
+        cache_dir: Annotated[
+            Path,
+            Parameter(
+                name=("--cache-dir",),
+                group=command_group,
+                help=CACHE_DIR_HELP,
+            ),
+        ],
+    ) -> None:
+        """Delete an existing QIIME cache directory."""
+        resolved_cache_dir = resolve_cache_dir_path(
+            cwd=Path.cwd().resolve(),
+            raw_value=str(cache_dir),
+        )
+        _clear_cache(cache_dir=resolved_cache_dir, console=console)
+
+    app(argv)
+
+
+def _clear_cache(*, cache_dir: Path, console: Console) -> None:
+    _require_qiime_cache(cache_dir)
+    shutil.rmtree(cache_dir)
+    console.print(f"Cleared cache directory: {cache_dir}")
+
+
+def _require_qiime_cache(cache_dir: Path) -> None:
+    if not cache_dir.exists():
+        raise SystemExit(f"Cache directory does not exist: {cache_dir}")
+    if not cache_dir.is_dir():
+        raise SystemExit(f"Cache path is not a directory: {cache_dir}")
+
+    contents = set(item.name for item in cache_dir.iterdir())
+    if not contents.issuperset(QIIME_CACHE_CONTENTS):
+        raise SystemExit(f"Path is not a QIIME cache: {cache_dir}")
+
+    version_file = cache_dir / "VERSION"
+    try:
+        version_text = version_file.read_text(encoding="utf-8").strip()
+    except OSError as exc:
+        raise SystemExit(f"Could not read cache version file: {version_file}") from exc
+
+    if not _looks_like_qiime_cache_version(version_text):
+        raise SystemExit(f"Path is not a QIIME cache: {cache_dir}")
+
+
+def _looks_like_qiime_cache_version(version_text: str) -> bool:
+    lines = version_text.splitlines()
+    if len(lines) != 3:
+        return False
+
+    if lines[0] != "QIIME 2":
+        return False
+
+    if not QIIME_CACHE_LINE_RE.fullmatch(lines[1]):
+        return False
+
+    framework_prefix = "framework: "
+    return lines[2].startswith(framework_prefix) and bool(lines[2][len(framework_prefix) :].strip())