adagio-server 0.1.0__tar.gz

adagio_server-0.1.0/.gitignore

@@ -0,0 +1,130 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+# lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.DS_STORE
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/

adagio_server-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_server-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: adagio-server
+Version: 0.1.0
+Summary: Outbound self-hosted runtime server for Adagio
+Project-URL: Homepage, https://adagio.run
+Project-URL: Repository, https://github.com/cymis/adagio-local
+Author-email: John Chase <johnhchase@protonmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: adagio,pipelines,runner,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: adagio-cli<0.2,>=0.1.0
+Requires-Dist: adapter-schemas<0.4,>=0.3.1
+Requires-Dist: fastapi[standard]<0.117,>=0.116
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings<3.0.0,>=2.0.2
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tomli-w>=1.0
+Description-Content-Type: text/markdown
+
+# adagio-server
+
+Licensed under the [MIT License](LICENSE). This covers the server package only;
+it does not change the license of the hosted Adagio application or sibling projects.
+
+`adagio-server` is Adagio's outbound execution runner. It claims jobs over HTTPS,
+executes them with the existing `adagio-cli`, and reports status and artifact paths.
+It never requires an inbound network port. The initial server platform is Linux
+with Python 3.11+ and user-level systemd; Docker is needed for container-backed
+pipeline actions.
+
+Each claimed job starts independently, even while other jobs are running. Adagio
+does not impose a job-count limit or decide whether the host has spare CPU or
+memory; the server owner manages resource usage. The outbound handoff is not a
+resource scheduler. Slurm/SGE integration is separate future work.
+
+Install the server in a persistent virtual environment, then use the enrollment
+token and deployment URL shown under **Settings → Runtime Servers** in Adagio:
+
+```bash
+python3 -m venv ~/.local/share/adagio-server-venv
+source ~/.local/share/adagio-server-venv/bin/activate
+python -m pip install adagio-server
+adagio-server --version
+
+export ADAGIO_ENROLLMENT_TOKEN='<code from Adagio>'
+adagio-server install --url https://app.adagio.run
+```
+
+The install command exchanges the short-lived token for a machine credential,
+stores that credential with user-only permissions, then installs and starts the
+systemd user service. Jobs execute with the same Unix filesystem permissions as
+the user who installed it, including supplementary groups used for shared data.
+Docker-backed actions also run as that user. Images that require root during
+startup are therefore unsupported on a Runtime Server.
+Granting someone permission to use a server grants code execution as its Linux
+account. An account with access to a rootful Docker daemon can administer the
+host; this is a trusted execution environment, not a sandbox for untrusted users
+or plugins. Supplementary groups are preserved for shared-data access. Do not
+assume UID flags or dropped container capabilities isolate a Docker socket made
+accessible through mounted paths. Docker socket isolation needs separate review.
+The command prints a note when an administrator may need to enable
+systemd user lingering for service operation after logout.
+
+Install the package in a persistent virtual environment (or with `pipx`) rather
+than an ephemeral `uvx` environment. The systemd unit records the interpreter
+path that performed the installation.
+
+New installations select a stable loopback port from the Linux user id so
+different users on a shared host do not contend for port 8760. Pass
+`--port 23456` to choose an explicit port. The listener remains bound to
+`127.0.0.1` and requires a per-process bearer token.
+
+For an interactive foreground process, use `adagio-server start`. Plain HTTP and
+disabled TLS verification are refused unless `install --insecure` is passed for a
+development deployment.
+
+## Updates and reporting
+
+Contract mismatches stop with exit code 42 and an update-required message;
+credential rejection uses exit code 41. Neither condition should restart the
+same configuration repeatedly. After upgrading an existing installation, rerun
+`adagio-server install` with a fresh enrollment token to update its systemd unit
+(older units only suppress restarts for code 41).
+
+Telemetry uploads have bounded text, metadata, and batch sizes. Large logs are
+sent in small batches with continued long lines; full logs remain on the server.
+Oversized optional event/provenance data is replaced by a `telemetry_truncated`
+marker rather than losing the job's lifecycle report. These limits do not apply
+to input/output file sizes or job counts.
+
+This revision requires the adapter-schemas 0.3.1 release. Source builds
+use the exact commit recorded in `vendor/adapter-schemas/VENDOR_PIN`; publication
+and release-tag verification must be completed before package-index installation.
+
+Release operators and QA testers should follow `RELEASING.md` in the repository.

adagio_server-0.1.0/README.md

@@ -0,0 +1,76 @@
+# adagio-server
+
+Licensed under the [MIT License](LICENSE). This covers the server package only;
+it does not change the license of the hosted Adagio application or sibling projects.
+
+`adagio-server` is Adagio's outbound execution runner. It claims jobs over HTTPS,
+executes them with the existing `adagio-cli`, and reports status and artifact paths.
+It never requires an inbound network port. The initial server platform is Linux
+with Python 3.11+ and user-level systemd; Docker is needed for container-backed
+pipeline actions.
+
+Each claimed job starts independently, even while other jobs are running. Adagio
+does not impose a job-count limit or decide whether the host has spare CPU or
+memory; the server owner manages resource usage. The outbound handoff is not a
+resource scheduler. Slurm/SGE integration is separate future work.
+
+Install the server in a persistent virtual environment, then use the enrollment
+token and deployment URL shown under **Settings → Runtime Servers** in Adagio:
+
+```bash
+python3 -m venv ~/.local/share/adagio-server-venv
+source ~/.local/share/adagio-server-venv/bin/activate
+python -m pip install adagio-server
+adagio-server --version
+
+export ADAGIO_ENROLLMENT_TOKEN='<code from Adagio>'
+adagio-server install --url https://app.adagio.run
+```
+
+The install command exchanges the short-lived token for a machine credential,
+stores that credential with user-only permissions, then installs and starts the
+systemd user service. Jobs execute with the same Unix filesystem permissions as
+the user who installed it, including supplementary groups used for shared data.
+Docker-backed actions also run as that user. Images that require root during
+startup are therefore unsupported on a Runtime Server.
+Granting someone permission to use a server grants code execution as its Linux
+account. An account with access to a rootful Docker daemon can administer the
+host; this is a trusted execution environment, not a sandbox for untrusted users
+or plugins. Supplementary groups are preserved for shared-data access. Do not
+assume UID flags or dropped container capabilities isolate a Docker socket made
+accessible through mounted paths. Docker socket isolation needs separate review.
+The command prints a note when an administrator may need to enable
+systemd user lingering for service operation after logout.
+
+Install the package in a persistent virtual environment (or with `pipx`) rather
+than an ephemeral `uvx` environment. The systemd unit records the interpreter
+path that performed the installation.
+
+New installations select a stable loopback port from the Linux user id so
+different users on a shared host do not contend for port 8760. Pass
+`--port 23456` to choose an explicit port. The listener remains bound to
+`127.0.0.1` and requires a per-process bearer token.
+
+For an interactive foreground process, use `adagio-server start`. Plain HTTP and
+disabled TLS verification are refused unless `install --insecure` is passed for a
+development deployment.
+
+## Updates and reporting
+
+Contract mismatches stop with exit code 42 and an update-required message;
+credential rejection uses exit code 41. Neither condition should restart the
+same configuration repeatedly. After upgrading an existing installation, rerun
+`adagio-server install` with a fresh enrollment token to update its systemd unit
+(older units only suppress restarts for code 41).
+
+Telemetry uploads have bounded text, metadata, and batch sizes. Large logs are
+sent in small batches with continued long lines; full logs remain on the server.
+Oversized optional event/provenance data is replaced by a `telemetry_truncated`
+marker rather than losing the job's lifecycle report. These limits do not apply
+to input/output file sizes or job counts.
+
+This revision requires the adapter-schemas 0.3.1 release. Source builds
+use the exact commit recorded in `vendor/adapter-schemas/VENDOR_PIN`; publication
+and release-tag verification must be completed before package-index installation.
+
+Release operators and QA testers should follow `RELEASING.md` in the repository.

adagio_server-0.1.0/RELEASING.md

@@ -0,0 +1,113 @@
+# Releasing `adagio-server`
+
+Current release candidate: **0.1.0**. The source repository remains private;
+the published Python distributions and their included code are public and
+MIT-licensed. This license applies to the server package, not the hosted Adagio
+application or other repositories. Both wheel and source archives include LICENSE.
+
+## One-time account setup
+
+In https://pypi.org/manage/account/publishing/ add a pending GitHub publisher:
+
+| Field | Value |
+| --- | --- |
+| PyPI project | `adagio-server` |
+| GitHub owner | `cymis` |
+| Repository | `adagio-local` |
+| Workflow filename | `server-package.yml` |
+| Environment | Leave blank |
+
+The release policy uses explicit GitHub release publication, without a GitHub
+environment or a separate reviewer gate. Repository writers can initiate a
+release; access to this workflow must therefore be treated as publishing access.
+No PyPI API-token secret is needed. The package license is MIT.
+
+The repository name above identifies where the workflow lives. It does not
+publish `adagio-local`: only the `adagio-server` distributions built from
+`adagio-local-adapter` are uploaded. Desktop and sibling projects are excluded.
+
+The `release: published` event runs the workflow from the tagged release commit.
+That commit must contain this workflow. The workflow requires prerelease commits
+to be contained in `dev` and stable release commits to be contained in `main`.
+This allows reviewed QA builds without prematurely promoting Desktop changes.
+Publishing a GitHub release is the explicit authorization to publish its package
+to PyPI after checks pass; saving a draft or pushing a tag is not. No PyPI
+publisher configuration changes are needed. Only `server-v*` releases are
+eligible; Desktop `v*` releases are ignored.
+
+## Release gates
+
+1. Merge the reviewed runner and packaging changes into `dev` and validate them
+   against the matching hosted changes in the development environment.
+2. Publish `adapter-schemas==0.3.1` first. Confirm
+   `adagio-cli==0.1.0` is available, and re-sync vendored contracts to the
+   verified release tag. A local `uv sync` does not prove a pip install will work.
+3. Run Server package CI. It builds wheel and source archives with explicit file
+   allowlists, validates metadata, and tests installed wheels on Python 3.11/3.13
+   with the public CLI. Only pre-publication CI uses a locally built schema wheel.
+4. Promote `dev` to `main`, then push `server-v0.1.0` on the exact reviewed main
+   merge commit. **Do not use `v0.1.0`: `v*` tags belong to Desktop releases.**
+   Prerelease commits must be in `dev`; stable server release commits must be in
+   `main`.
+5. A separate clean job must install the server wheel using only PyPI for its
+   dependencies. No candidate schema wheel or private source checkout is available
+   in that job. If this fails, publication is blocked.
+6. Explicitly publish the GitHub release with the command below (or publish it
+   from the GitHub release UI). Only the publishing job
+   receives OIDC permission, after all required checks pass. There is no second
+   approval prompt. PR/branch/tag pushes and manual workflow dispatch never
+   publish. The `published` event covers both prereleases and stable releases.
+7. Repeat installation from PyPI on a clean Linux/systemd machine and record
+   `adagio-server --version` and `python -m pip freeze` in the validation report.
+
+Publishing command (do not run until release approval):
+
+```bash
+gh release create server-v0.1.0 --repo cymis/adagio-local --verify-tag --title 'adagio-server 0.1.0' --notes 'First public Runtime Server release for self-hosted Linux execution.'
+```
+
+For a build/test dry run, push the reviewed tag without publishing a GitHub
+release. This still checks that dependencies are available from PyPI. A draft
+release does not publish to PyPI. A failed publishing job can be rerun on the
+same release; do not move the tag to different code.
+
+Never replace a published artifact or move a released tag. Publish a new patch or
+prerelease version for subsequent builds and update any setup snippet pin.
+Publishing a server package does not release Desktop.
+
+## Validation after publication
+
+Use a dedicated Linux account with Python 3.11+, a working systemd user session,
+and access to the execution environment (for example, Docker). These are host
+prerequisites; pip does not install or configure Docker or systemd.
+
+```bash
+python3 -m venv ~/.local/share/adagio-server-venv
+source ~/.local/share/adagio-server-venv/bin/activate
+python -m pip install "adagio-server==0.1.0"
+adagio-server --version
+adagio-server install --url https://app.adagio.run
+```
+
+Create a Runtime Server in the target Adagio deployment and paste its temporary
+enrollment token at the hidden prompt. The same one-time token can instead be
+supplied through `ADAGIO_ENROLLMENT_TOKEN`, as shown in the app. Keep this
+virtual environment: the user service records its interpreter path. Do not use
+`sudo pip`.
+
+Check the install output and the app's green connection indicator, then use
+`systemctl --user status adagio-server` and
+`journalctl --user -u adagio-server -n 100` for troubleshooting. If jobs need to
+continue after logout or reboot, ask the host administrator to enable user lingering
+with `loginctl enable-linger USERNAME` and test that behavior explicitly.
+
+Test remote input/metadata and output paths, multiple simultaneous jobs, canceling
+only one job, service stop/restart, interrupted-job reporting, re-enrollment, token
+revocation, large logs, and an ordinary Desktop run against the same dev deployment.
+For upgrades, wait for active work to finish (or explicitly cancel it), install the
+new pinned version in the same environment, and rerun install with a fresh token.
+Existing systemd units need the updated restart policy. Confirm the running process
+actually restarts; pip installation alone does not restart an existing service.
+
+Do not include enrollment tokens, machine credentials, or private scientific data
+in validation reports. Record versions, sanitized logs, host OS, and the reproduction steps.

adagio_server-0.1.0/adagio_server/__init__.py

@@ -0,0 +1,8 @@
+"""Adagio's outbound self-hosted runtime server."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("adagio-server")
+except PackageNotFoundError:  # Source checkout without an installed distribution.
+    __version__ = "unknown"

adagio_server-0.1.0/adagio_server/agent/__init__.py

@@ -0,0 +1 @@
+"""Outbound pull-agent core (register / claim / lease / run / report)."""

adagio_server-0.1.0/adagio_server/agent/artifacts.py

@@ -0,0 +1,118 @@
+"""QIIME ``.qza``/``.qzv`` artifact introspection.
+
+This is the **only** domain-aware code in the agent (design §5). It is kept
+verbatim in behavior from the legacy ``jobs.py`` so that when the agent relays a
+CLI ``output_saved`` event to action as an :class:`ArtifactReport`, it can fill in
+``artifact_type`` (the QIIME semantic type) and ``provenance`` (the recorded
+action graph). All parsing is best-effort and degrades gracefully - a file that
+is not a QIIME archive simply yields ``(None, None)``.
+
+Everything else in the agent treats artifacts as opaque URIs.
+"""
+
+from __future__ import annotations
+
+import zipfile
+from pathlib import Path
+from typing import Any
+
+from fastapi.encoders import jsonable_encoder
+
+try:
+    import yaml
+except Exception:  # noqa: BLE001 - yaml is optional; degrade to no introspection
+    yaml = None  # type: ignore[assignment]
+
+#: QIIME repr tags that a plain YAML loader cannot resolve.
+_Q2_REPRS = ("!ref", "!no-provenance", "!metadata", "!color", "!cite")
+
+
+def read_qiime_archive(file_path: Path) -> tuple[str | None, dict[str, Any] | None]:
+    """Return ``(artifact_type, provenance)`` for a QIIME archive, else ``(None, None)``.
+
+    ``artifact_type`` comes from ``*/metadata.yaml``'s ``type`` field; ``provenance``
+    from ``*/provenance/action/action.yaml``. Non-archives and parse failures return
+    ``(None, None)`` / partial results rather than raising.
+    """
+    if not zipfile.is_zipfile(file_path):
+        return None, None
+
+    try:
+        with zipfile.ZipFile(file_path, "r") as zf:
+            metadata = _read_yaml_member(zf, ["/metadata.yaml"])
+            provenance = _read_yaml_member(
+                zf,
+                ["/provenance/action/action.yaml", "/action/action.yaml"],
+            )
+    except Exception:  # noqa: BLE001
+        return None, None
+
+    archive_type: str | None = None
+    if isinstance(metadata, dict):
+        type_name = metadata.get("type")
+        if isinstance(type_name, str):
+            archive_type = type_name
+
+    if isinstance(provenance, dict):
+        # YAML timestamps become date/datetime objects. Normalize before the
+        # telemetry size validator calls json.dumps, not just at HTTP upload.
+        return archive_type, jsonable_encoder(provenance)
+    return archive_type, None
+
+
+def _read_yaml_member(
+    zf: zipfile.ZipFile, suffixes: list[str]
+) -> dict[str, Any] | None:
+    names = zf.namelist()
+    for suffix in suffixes:
+        match = next((name for name in names if name.endswith(suffix)), None)
+        if match is None:
+            continue
+        text = zf.read(match).decode("utf-8", errors="replace")
+        parsed = yaml_load_with_qiime_tags(text)
+        if isinstance(parsed, dict):
+            return parsed
+    return None
+
+
+def yaml_load_with_qiime_tags(text: str) -> Any:
+    """Load YAML tolerating QIIME repr tags; degrade progressively on failure."""
+    if yaml is None:
+        return None
+
+    class _Loader(yaml.SafeLoader):
+        pass
+
+    def _unknown_tag(loader: yaml.SafeLoader, node: yaml.Node) -> Any:
+        if isinstance(node, yaml.ScalarNode):
+            return loader.construct_scalar(node)
+        if isinstance(node, yaml.SequenceNode):
+            return loader.construct_sequence(node)
+        if isinstance(node, yaml.MappingNode):
+            return loader.construct_mapping(node)
+        return None
+
+    _Loader.add_constructor(None, _unknown_tag)
+    try:
+        return yaml.load(text, Loader=_Loader)
+    except Exception:  # noqa: BLE001
+        pass
+
+    stripped = text
+    for qrepr in _Q2_REPRS:
+        stripped = stripped.replace(qrepr, "")
+
+    try:
+        return yaml.safe_load(stripped)
+    except Exception:  # noqa: BLE001
+        pass
+
+    try:
+        return yaml.load(stripped, Loader=yaml.BaseLoader)
+    except Exception:  # noqa: BLE001
+        return {
+            "_parse_warning": (
+                "Unable to fully parse QIIME provenance YAML. "
+                "Some provenance details were omitted."
+            ),
+        }