daedalus-flow 0.1.0__tar.gz

daedalus_flow-0.1.0/.editorconfig

@@ -0,0 +1,24 @@
+# EditorConfig (https://editorconfig.org): baseline whitespace hygiene,
+# matching the pre-commit end-of-file-fixer / trailing-whitespace hooks.
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+
+[*.py]
+indent_size = 4
+max_line_length = 88
+
+[*.{yaml,yml,toml,json}]
+indent_size = 2
+
+[justfile]
+indent_size = 4
+
+[*.md]
+# Markdown uses trailing double-space line breaks.
+trim_trailing_whitespace = false

daedalus_flow-0.1.0/.envrc.defaults

@@ -0,0 +1,16 @@
+# Auto-activate the daedalus dev shell (flake.nix) on entry.
+#
+# WHY: under a Nix-store Python interpreter the ELF loader is the Nix glibc
+# loader, which does NOT search the host FHS library path
+# (/usr/lib/x86_64-linux-gnu), so the science stack's binary wheels (numpy,
+# scipy, ...) cannot find libstdc++.so.6 (the gcc runtime) or libz.so.1 at
+# import time. The flake's dev shell sets a narrow, Nix-store, ABI-matched
+# LD_LIBRARY_PATH (zlib + gcc runtime) that fixes exactly this. direnv exports
+# that environment the moment you cd in, so `uv run python -c "import scipy"`
+# works with zero manual steps.
+#
+# SETUP (one time): `cp .envrc.defaults .envrc && direnv allow`. Needs
+# direnv >= 2.30 for the built-in `use flake`.
+#
+# IF DIRENV IS DISABLED: run `nix develop` by hand to enter the same shell.
+use flake

daedalus_flow-0.1.0/.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,22 @@
+# Code of conduct
+
+This project is a welcoming, safe and equitable space for everyone who takes
+part in good faith. That holds whatever a person's race, ethnicity, caste,
+color, age, disability, neurodiversity, sex, gender identity or expression,
+sexual orientation, language, religion, origin, class or education.
+
+The following behavior is not accepted, and neither are threats of it:
+
+- Violating someone's stated boundaries, or continuing personal attention after a request to stop.
+- Insulting, demeaning or pejorative comments aimed at a person or a group.
+- Characterizing anyone's personality or behavior on the basis of identity or traits.
+- Behavior that is inappropriately intimate for the context.
+- Sharing or acting on someone's private information without permission.
+- Causing, encouraging or threatening violence or other harm.
+- Impersonating someone, failing to credit sources, or posting commercial content outside the norms of the project.
+
+Report a problem privately to the maintainer,
+[@preller](https://github.com/preller). Reports are handled in confidence.
+
+Adapted from the [Contributor Covenant 3.0](https://www.contributor-covenant.org/version/3/0/),
+licensed under [Creative Commons Attribution-ShareAlike 4.0](https://creativecommons.org/licenses/by-sa/4.0/).

daedalus_flow-0.1.0/.github/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing
+
+## Setup
+
+daedalus-flow uses [uv](https://docs.astral.sh/uv/) and needs Python 3.12 or
+newer. The recipes run through [just](https://github.com/casey/just), a system
+binary (`nix profile install nixpkgs#just` or `cargo install just`).
+
+```sh
+uv sync --locked --all-groups
+```
+
+A plain `uv sync` leaves `just typecheck` and `just test` failing at import,
+because the scientific stack sits behind dependency groups.
+`uv run pre-commit install` adds the commit-time hooks, which run the fast part
+of the gate.
+
+Nix users can copy `.envrc.defaults` to `.envrc` and run `direnv allow`; direnv
+then loads the flake dev shell on entry.
+
+## Gate
+
+Run `just gate` before you open a pull request. It runs lint (ruff check and format), typecheck (mypy), imports (the
+import-layer contracts), test (the fast suite under the coverage floor), and audit. `just test` skips the real samplers and `just test-slow` runs them;
+`just --list` shows the other tiers.
+
+## Code style
+
+- ruff is pinned to `0.15.16` in the pre-commit hook, `just lint` and CI; let it decide formatting.
+- mypy runs in strict mode.
+- Write in American English and follow the conventions of the file you are editing.
+
+## Pull requests
+
+- One change per pull request, with a test.
+- Say what the change does and why, and link the issue if there is one.
+- Open an issue first for a new dependency or a change to a public contract: a CLI command, a `lab.yaml` field, the `--json` envelope or an outcome code.
+
+## Generated code
+
+Tools that write code are welcome. Name the tool in the pull request and take
+responsibility for every line. Do not submit generated code you have not read.
+
+## Security
+
+Report a vulnerability privately as described in `SECURITY.md`, not in a public issue.

daedalus_flow-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,50 @@
+name: Bug report
+description: Report something that is not working as expected.
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: Describe the problem, including what you expected to happen instead.
+      placeholder: When I run ..., I expected ... but got ...
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: The exact commands or steps that trigger the problem. A minimal example helps most.
+      placeholder: |
+        1. Run `dae ...`
+        2. ...
+        3. See the error
+    validations:
+      required: true
+  - type: textarea
+    id: version
+    attributes:
+      label: Version
+      description: The output of `dae --version`.
+      placeholder: Paste the output of `dae --version` here.
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Your operating system and Python version (`python --version`).
+      placeholder: |
+        OS: e.g. Ubuntu 24.04, macOS 15
+        Python: e.g. 3.12.7
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs or traceback
+      description: Any relevant error output. This will be rendered as code, so no backticks are needed.
+      render: shell
+    validations:
+      required: false

daedalus_flow-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Documentation
+    url: https://daedalus-flow.readthedocs.io
+    about: Guides and reference.

daedalus_flow-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,4 @@
+<!-- What changed and why. Link the issue if there is one. -->
+
+- [ ] `just gate` passes locally
+- [ ] Tools that generated code, and what for, or none:

daedalus_flow-0.1.0/.github/SECURITY.md

@@ -0,0 +1,11 @@
+# Security
+
+Do not open a public issue for a vulnerability. Report it through GitHub's
+private vulnerability reporting: the repository's Security tab, then "Report a
+vulnerability".
+
+A useful report gives the version (`dae --version`), the operating system and
+Python version, a minimal way to reproduce the problem, and any traceback or
+input that triggers it.
+
+Reports must reproduce; unverified tool output is closed.

daedalus_flow-0.1.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# Monthly grouped bumps of the SHA-pinned GitHub Actions. Python deps are pinned in uv.lock
+# and bumped with `uv lock`, so only the github-actions ecosystem is tracked here.
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      actions:
+        patterns: ["*"]

daedalus_flow-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,107 @@
+# CI for daedalus. Every job installs `just` and calls the justfile recipes, so the gate is
+# defined once. Third-party actions are pinned to a full commit SHA; the comment names the tag.
+
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 6 * * 1" # weekly, Monday 06:00 UTC
+
+permissions:
+  contents: read
+
+# A newer push to the same ref cancels the in-progress run.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          version: "0.7.22"
+      - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4.0.0
+      - run: uv sync --locked
+      - run: just lint
+      - run: just imports
+
+  # mypy covers tests/, which import the science stack, so this job syncs every group.
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          version: "0.7.22"
+      - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4.0.0
+      - run: uv sync --locked --all-groups
+      - run: just typecheck
+
+  # The publish gate; the fast suite on both shipped interpreters, Linux only.
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          version: "0.7.22"
+          python-version: "${{ matrix.python-version }}"
+      - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4.0.0
+      - run: uv sync --locked --all-groups
+      - run: just test
+
+  # pip-audit of the locked closure, weekly and on dispatch, advisory.
+  audit:
+    if: github.event_name == 'workflow_dispatch' || github.event_name == 'schedule'
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          version: "0.7.22"
+      - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4.0.0
+      - run: uv sync --locked
+      - run: just audit
+
+  # The Nix-only isolation tests (uv2nix per-module build), weekly and on dispatch, advisory.
+  nix-tests:
+    if: github.event_name == 'workflow_dispatch' || github.event_name == 'schedule'
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: DeterminateSystems/determinate-nix-action@9adf02b41cfdac2632e1c16f0480ff5bf3b05dd6 # v3.21.1
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          version: "0.7.22"
+      - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4.0.0
+      - run: uv sync --locked --all-groups
+      - run: just test-nix
+
+  # Wheel-portability smoke: build the wheel, install it into a clean venv with no
+  # dev shell, and run the lean CLI journey (scripts/portability_smoke.sh).
+  portability:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          # hatch-vcs reads the version from the git history and tags.
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          version: "0.7.22"
+      - run: bash scripts/portability_smoke.sh

daedalus_flow-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,57 @@
+# Release pipeline. Build once, `twine check`, then trusted publishing (OIDC) with attestations.
+# The PyPI pending publisher must match this repository, the file name publish.yml and the
+# environment (`pypi`, or `testpypi` for the rehearsal); register one publisher per index.
+
+name: publish
+
+on:
+  push:
+    # hatch-vcs derives the version from the tag. A clean vX.Y.Z tag publishes to PyPI;
+    # an rc or dev tag rehearses on TestPyPI.
+    tags: ["v*"]
+  # Manual trigger for a TestPyPI rehearsal without a tag.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          # hatch-vcs needs the full history and tags, or the build gets the wrong version.
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          version: "0.7.22"
+      - run: uv build
+      # Confirm the wheel and sdist metadata render on PyPI before an upload consumes a version.
+      - run: uvx twine check dist/*
+      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # The environment name is half of the OIDC claim and gates the required reviewer.
+    environment: ${{ (github.event_name == 'workflow_dispatch' || contains(github.ref, 'rc') || contains(github.ref, 'dev')) && 'testpypi' || 'pypi' }}
+    permissions:
+      # Mints the short-lived OIDC token; no PyPI API token is used.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        if: github.event_name == 'push' && !contains(github.ref, 'rc') && !contains(github.ref, 'dev')
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+      - name: Publish to TestPyPI
+        if: github.event_name == 'workflow_dispatch' || contains(github.ref, 'rc') || contains(github.ref, 'dev')
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          repository-url: https://test.pypi.org/legacy/

daedalus_flow-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Build / publish artifacts
+build/
+dist/
+*.whl
+
+# Virtual environment
+.venv/
+
+# direnv (copy .envrc.defaults to .envrc and `direnv allow` to load the flake dev shell)
+.direnv/
+.envrc
+
+# Tooling caches
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.import_linter_cache/
+.cache/
+
+# Coverage
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Generated engine output (a `dae lab run` writes these into its cwd)
+dae-outputs/
+.daedalus/
+
+# OS / editor cruft
+.DS_Store
+*.swp
+*~
+
+# Sphinx docs build output + generated AutoAPI pages (autoapi_root = "api")
+docs/_build/
+docs/api/

daedalus_flow-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,45 @@
+# The fast local subset of the `just gate` checks; pip-audit stays in CI.
+# Install from the repo root with `uv run pre-commit install`.
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      # examples/ holds module artifacts (expected/ goldens, input/ data) that
+      # the gallery tests compare byte-for-byte; whitespace-normalizing them
+      # changes test truth, so the fixers skip the whole examples tree.
+      - id: end-of-file-fixer
+        exclude: ^(src/daedalus/examples|tests/fixtures)/
+      - id: trailing-whitespace
+        exclude: ^(src/daedalus/examples|tests/fixtures)/
+      - id: check-merge-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # rev equals the ruff version pyproject pins (ruff==0.15.16), so
+    # pre-commit, `just lint` and CI run the same ruff.
+    rev: v0.15.16
+    hooks:
+      # Scope matches the gate definition (`just lint`: ruff over src + tests).
+      - id: ruff-check
+        args: [--fix]
+        files: ^(src|tests)/
+      - id: ruff-format
+        files: ^(src|tests)/
+
+  - repo: https://github.com/gitleaks/gitleaks
+    # Secret scanning on staged changes. rev pinned.
+    rev: v8.9.0
+    hooks:
+      - id: gitleaks
+
+  - repo: local
+    hooks:
+      # A local hook rather than a mirror, so it runs the project-pinned mypy
+      # with the pyproject.toml strict config.
+      - id: mypy
+        name: mypy (project venv, strict)
+        entry: uv run mypy
+        language: system
+        # scripts/ is in [tool.mypy].files, so it must also trigger the hook.
+        files: ^(src|tests|scripts)/.*\.py$|^pyproject\.toml$
+        pass_filenames: false

daedalus_flow-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

daedalus_flow-0.1.0/.readthedocs.yaml

@@ -0,0 +1,22 @@
+# Read the Docs build configuration (v2).
+# Mirrors the local `just docs` discipline: uv-synced docs group, fail on warning.
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12" # daedalus requires-python >=3.12; 3.12 validated
+
+python:
+  install:
+    - method: uv
+      command: sync # respects uv.lock
+      groups:
+        - docs
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true # mirror the -W discipline on RTD too
+
+# No htmlzip: the singlehtml builder crashes in an html-page-context handler
+# ("junk after document element"); the html build is the product anyway.

daedalus_flow-0.1.0/AGENTS.md

@@ -0,0 +1,9 @@
+# AGENTS.md
+
+Notes for coding agents working in this repository. Read
+`.github/CONTRIBUTING.md` first; the list below is the short form.
+
+- Set up with `uv sync --locked --all-groups`; every `just` recipe runs through `uv run`.
+- Run `just gate` before a pull request: lint, typecheck, imports, test and audit.
+- Do not change the bundled labs under `src/daedalus/examples/**`; the tests treat them as goldens.
+- Say in the pull request which agent or tool wrote or changed the code.

daedalus_flow-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and
+versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-09-01
+
+- The `dae` CLI: scaffold examples (`dae example`), design and inspect labs
+  (`dae lab init`, `dae lab validate`, `dae lab visualize`), run them
+  (`dae lab run`), and follow flows (`dae flow status`, `dae flow resume`).
+- Module workbench: `dae module create`, `dae module try`,
+  `dae module validate`, and `dae module convert` to bring an existing script
+  into a lab.
+- A machine-readable `--json` envelope on every command, with a stable
+  outcome-code contract (see `docs/reference/outcome-codes.md`).
+- Local engine with per-module environment isolation (ambient, uv, or nix)
+  and opt-in parallelism; optional Prefect backend via the `engine` extra.
+- A bundled example ladder, from `minimal` to the full `demo` reference lab.

daedalus_flow-0.1.0/CITATION.cff

@@ -0,0 +1,26 @@
+cff-version: 1.2.0
+message: >-
+  If you use daedalus-flow in academic work, please cite it using this
+  metadata. See the "How to cite" section of the README.
+title: "daedalus-flow"
+abstract: >-
+  daedalus-flow (the dae command) is a reproducible analysis-pipeline framework,
+  "labs of modules", for data-intensive science, with a focus on astronomy and
+  exoplanet / space-science workflows.
+type: software
+authors:
+  - given-names: Patricio
+    family-names: Reller
+    affiliation: "Centre for Data Intensive Science and Industry (DISI), Department of Physics and Astronomy, University College London"
+    orcid: "https://orcid.org/0000-0003-3161-9239"
+version: "0.1.0"
+date-released: "2026-09-01"
+license: Apache-2.0
+url: "https://github.com/preller/daedalus-flow"
+repository-code: "https://github.com/preller/daedalus-flow"
+keywords:
+  - reproducibility
+  - data pipeline
+  - workflow
+  - astronomy
+  - exoplanets