daggerml 0.1.0__tar.gz → 0.1.2__tar.gz

daggerml-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,242 @@
+name: CI
+on:
+  push:
+    branches:
+      - "**"
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  test:
+    strategy:
+      matrix:
+        py: ["3.11", "3.12", "3.13", "3.14"]
+        os: [ubuntu-latest, macos-latest]
+        exclude:
+          # Only test the first and latest stable Pythons on macOS to keep CI fast
+          # - os: macos-latest
+          #   py: "3.11"
+          - os: macos-latest
+            py: "3.12"
+          - os: macos-latest
+            py: "3.13"
+          # - os: macos-latest
+          #   py: "3.14"
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # full history
+          fetch-tags: true # redundant in v4, but explicit
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.py }}
+      - name: Install uv
+        run: pip install uv==0.11.7
+      - name: Sync dependencies
+        run: uv sync --group dev --all-extras
+      - name: pytest
+        run: uv run pytest .
+  sanitize:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Install uv
+        run: pip install uv==0.11.7
+      - name: Build with ASAN + UBSAN
+        env:
+          CMAKE_ARGS: "-DDML_ENABLE_ASAN=ON -DDML_ENABLE_UBSAN=ON"
+        run: uv sync --group dev --all-extras
+      - name: Run tests with sanitizers
+        env:
+          ASAN_OPTIONS: "detect_leaks=0:abort_on_error=1"
+          UBSAN_OPTIONS: "print_stacktrace=1:halt_on_error=1"
+        run: |
+          LIBASAN=$(gcc -print-file-name=libasan.so)
+          LD_PRELOAD="$LIBASAN" uv run pytest .
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Install uv
+        run: pip install uv==0.11.7
+      - name: Sync dependencies
+        run: uv sync --group dev --all-extras
+      - name: Run Ruff
+        run: uv run ruff check --output-format=github .
+      - name: Run Pyright
+        run: uv run pyright --project .
+  dashboard:
+    if: >-
+      github.event_name == 'pull_request' ||
+      startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Install uv
+        run: pip install uv==0.11.7
+      - name: Set up Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: dashboard-ui/package-lock.json
+      - name: Build verified dashboard assets
+        env:
+          DOCS_PYTHON: ${{ github.workspace }}/.venv/bin/python
+        run: bash ./docs/build.sh
+      - name: Upload verified dashboard assets
+        uses: actions/upload-artifact@v7
+        with:
+          name: dashboard-assets
+          path: src/daggerml/dashboard/static/
+          if-no-files-found: error
+          retention-days: 1
+  build-wheels:
+    needs: dashboard
+    if: >-
+      github.event_name == 'pull_request' ||
+      startsWith(github.ref, 'refs/tags/v')
+    strategy:
+      fail-fast: false
+      matrix:
+        python:
+          - version: "3.11"
+            identifier: cp311
+          - version: "3.12"
+            identifier: cp312
+          - version: "3.13"
+            identifier: cp313
+          - version: "3.14"
+            identifier: cp314
+        platform:
+          - id: linux
+            os: ubuntu-latest
+          - id: macos
+            os: macos-latest
+    # name: Build Python ${{ matrix.python.version }} wheel for ${{ matrix.platform.id }}
+    runs-on: ${{ matrix.platform.os }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Download verified dashboard assets
+        uses: actions/download-artifact@v8
+        with:
+          name: dashboard-assets
+          path: src/daggerml/dashboard/static/
+      - name: Build wheel
+        uses: pypa/cibuildwheel@v3.2.1
+        env:
+          CIBW_BUILD: "${{ matrix.python.identifier }}-*"
+          CIBW_ARCHS: auto
+          CIBW_TEST_EXTRAS: dashboard
+          CIBW_TEST_REQUIRES: httpx
+          CIBW_TEST_COMMAND: python -I {project}/tests/distribution/check_installed_docs.py
+      - name: Upload wheel
+        uses: actions/upload-artifact@v7
+        with:
+          name: wheel-${{ matrix.platform.id }}-${{ matrix.python.identifier }}
+          path: wheelhouse/*.whl
+          if-no-files-found: error
+          retention-days: 1
+  build-sdist:
+    needs: dashboard
+    if: >-
+      github.event_name == 'pull_request' ||
+      startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Download verified dashboard assets
+        uses: actions/download-artifact@v8
+        with:
+          name: dashboard-assets
+          path: src/daggerml/dashboard/static/
+      - name: Build source distribution
+        run: |
+          pip install hatch
+          hatch build --target sdist
+      - name: Check installed sdist-derived wheel
+        run: |
+          python -m pip wheel --no-deps --wheel-dir "$RUNNER_TEMP/sdist-wheel" dist/*.tar.gz
+          python -m venv "$RUNNER_TEMP/sdist-docs"
+          "$RUNNER_TEMP/sdist-docs/bin/python" -m pip install "$RUNNER_TEMP"/sdist-wheel/*.whl
+          "$RUNNER_TEMP/sdist-docs/bin/python" -m pip install 'daggerml[dashboard]' httpx
+          "$RUNNER_TEMP/sdist-docs/bin/python" -I tests/distribution/check_installed_docs.py
+      - name: Upload source distribution
+        uses: actions/upload-artifact@v7
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+          retention-days: 1
+  publish:
+    needs:
+      ["test", "lint", "sanitize", "dashboard", "build-wheels", "build-sdist"]
+    if: startsWith(github.ref, 'refs/tags/v')
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Download wheels
+        uses: actions/download-artifact@v8
+        with:
+          pattern: wheel-*
+          path: dist
+          merge-multiple: true
+      - name: Download source distribution
+        uses: actions/download-artifact@v8
+        with:
+          name: sdist
+          path: dist
+      - name: Cache pip
+        uses: actions/cache@v6
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-3.13-publish-${{ hashFiles('**/pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-3.13-
+            ${{ runner.os }}-pip-
+      - name: Install hatch
+        run: |
+          pip install hatch
+      - name: Publish distributions
+        env:
+          HATCH_INDEX_USER: __token__
+          HATCH_INDEX_AUTH: ${{ secrets.PYPI_TOKEN }}
+        run: hatch publish

daggerml-0.1.2/.gitignore

@@ -0,0 +1,182 @@
+# daggerml
+.dml/
+.opencode/
+/.tools/
+# scm writes version info now...
+__about__.py
+
+# jupytext .py to .ipynb ignore
+docs/examples/*.ipynb
+
+/build/
+/.dockerhome
+node_modules/
+__pycache__/
+.#*
+
+# copied from the gitignore project on github
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+/src/daggerml/dashboard/static/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+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/
+cover/
+
+# 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/
+docs/_autosummary/
+docs/contrib/plans/
+docs/contrib/*-plan.local.md
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .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
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__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/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+uv.lock

daggerml-0.1.2/CONTRIBUTING.md

@@ -0,0 +1,177 @@
+# Contributing to DaggerML
+
+Thank you for your interest in contributing! We welcome contributions via pull
+requests and appreciate your help in improving this project.
+
+## Contributor Workflow References
+
+- `AGENTS.md`: agent-specific working notes and script-executor caveats.
+- `DOC_MAP.md`: which project docs to read before editing a given code path.
+- `openspec/README.md`: change-planning artifacts and current OpenSpec spec surfaces.
+
+## Reporting Issues
+
+- Search [existing issues](https://github.com/daggerml/python-lib/issues) before submitting a new one.
+- When reporting a bug, please include:
+  - A clear, descriptive title.
+  - Steps to reproduce the issue.
+  - Expected and actual behavior.
+  - Python version and operating system.
+  - Relevant code snippets or error messages.
+
+## How to Contribute Code
+
+1. Create a new branch for your feature or bugfix (with the github issue in the name).
+2. Clone the repository and set it up:
+   ```bash
+   git clone https://github.com/daggerml/python-lib.git
+   ```
+3. Make your changes in the new branch.
+4. Write or update tests as needed.
+5. Ensure all tests pass locally.
+6. Push to your branch on GitHub.
+7. Open a pull request against the `master` branch of this repository.
+
+## Development Setup
+
+- Python 3.11 or newer, [uv](https://docs.astral.sh/uv/), and a C/C++ toolchain
+  with CMake are required for the Cython-backed LMDB extension.
+- Set up a checkout with `uv sync --dev --all-extras`.
+- The dashboard source and package-manager commands live in `dashboard-ui/`.
+  Distribution changes must include built static assets in
+  `src/daggerml/dashboard/`; installed `dml-dashboard` must not require Node.js.
+
+## Repository Orientation
+
+- `src/daggerml/README.md`: public package and CLI boundary.
+- `src/daggerml/_core/README.md`: repository, storage, execution, and remote boundary.
+- `src/daggerml/dashboard/README.md` and `dashboard-ui/README.md`: dashboard server and frontend boundary.
+- `openspec/spec-overview.md`: normative architecture and capability ownership.
+
+## Coding Standards
+
+- Follow [PEP 8](https://pep8.org/) for Python code style.
+- Use [numpy style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html) for all public modules, classes, functions, and methods.
+- Write clear, concise commit messages.
+- Keep pull requests focused and minimal.
+
+## Testing Guidelines
+
+- Add or update unit tests for any new features or bug fixes.
+- Use [pytest](https://pytest.org/) for running tests.
+- Standard local dev command pattern is:
+  ```bash
+  uv run --dev <python command>
+  ```
+- When a command needs optional dependencies, include all extras:
+  ```bash
+  uv run --dev --all-extras <python command>
+  ```
+- Run tests with:
+  ```bash
+  uv run --dev --all-extras pytest .
+  ```
+- Run lint with:
+  ```bash
+  uv run --dev --all-extras ruff check --fix .
+  ```
+- We mark tests with `@pytest.mark.slow` for those that take longer to run. You can run only the fast tests with:
+  ```
+  uv run --dev --all-extras pytest -m "not slow" .
+  ```
+- CI continues to run the full suite (`uv run pytest .`) to preserve complete coverage while local quick loops use `-m "not slow"`.
+- We mark tests under `tests/_core/` with `@pytest.mark.core`. Core tests are included by default. You can select or skip them with:
+  ```
+  uv run --dev --all-extras pytest -m core .
+  uv run --dev --all-extras pytest -m "not core" .
+  ```
+- Run all tests locally before submitting a pull request:
+- Ensure your code passes all tests and does not decrease code coverage.
+- If your changes introduce new dependencies, please update `pyproject.toml`, but we prefer to keep the dependencies to a minimum.
+
+## Documentation Build
+
+- Python, Node.js/npm, `uv`, Git, `curl`, `tar`, and the native package build
+  toolchain are host prerequisites. Executable documentation also requires
+  Docker with a running daemon to build and run the course's container image.
+  The build command owns project dependency
+  setup, frontend tests, the pinned Quarto/R bootstrap, documentation execution,
+  frontend compilation, and packaged-output validation:
+  ```bash
+  bash docs/build.sh
+  ```
+- The default automatic mode runs `uv sync`, `npm ci`, and frontend tests, then
+  fingerprints repository inputs and rebuilds stale components. A clean checkout
+  therefore performs the complete verified build. Use composable `--no-*` flags
+  to trust existing dependencies or preserve one packaged component, and use
+  `--full` to force selected outputs. Run `bash docs/build.sh --help` for every
+  option, stage interaction, and common command example.
+- Documentation and frontend output are assembled away from the installed
+  package tree. The existing packaged dashboard is replaced only after the
+  complete candidate validates, so failed builds retain the prior output.
+- The script installs its pinned Quarto/R toolchain and all related caches under
+  the ignored `.tools/` directory. Set `DOCS_PYTHON` when the project interpreter
+  is not `.venv/bin/python`:
+  ```bash
+  DOCS_PYTHON="/path/to/python" bash docs/build.sh
+  ```
+- The build executes all QMD examples against disposable fixtures; do not use it as a substitute for the full test suite.
+- CI builds and verifies the dashboard and executable documentation once in the
+  Linux `dashboard` job. Wheel and source-distribution jobs download its
+  `dashboard-assets` artifact and package those same verified files. macOS wheel
+  runners therefore do not need Docker or the documentation build toolchain.
+
+### Test taxonomy and naming
+
+This section is for contributors maintaining or restructuring the test suite.
+
+#### Directory layout
+
+- `tests/contracts/`: fast, isolated tests that verify one documented requirement or invariant.
+- `tests/integration/`: multi-component or infrastructure-dependent tests.
+- `tests/_core/contracts/`: fast, isolated tests for `daggerml._core` contracts.
+- `tests/_core/integration/`: multi-component or infrastructure-dependent tests for `daggerml._core`.
+- Subsystem-owned suites such as `tests/_core/`, `tests/api/`, and `tests/contrib/` keep `contracts/` and `integration/` subdirectories under the subsystem root.
+
+#### File naming
+
+- Contract tests should use `test_<surface>_<contract>.py`.
+- Integration tests should use `test_<surface>_<scenario>_integration.py`.
+- Avoid generic names such as `test_core.py` when a more specific contract surface is known.
+
+#### Function naming and contract IDs
+
+- Prefer `test_<contract_id_slug>__<behavior>()` where practical.
+- Example: `test_exec_lc_003__resume_uses_launch_state()`.
+- Specify canonical contract IDs directly as literal strings.
+- Use uppercase category prefixes and numeric suffixes such as `ADP-OUT-001`, `EXEC-LC-003`, and `EST-LOCK-004`.
+- For parameterized cases, include the canonical ID in `id=`, for example `id="EXEC-LC-003:resume-uses-launch-state"`.
+
+#### Lifecycle parameterization
+
+- Tests that exercise a lifecycle should prefer one parameterized test per contract family over multiple near-duplicate tests.
+- Make lifecycle stages explicit in case IDs, for example `kickoff`, `resume`, `terminal-succeeded`, and `terminal-failed`.
+
+#### Marker policy
+
+- Integration tests that require external processes, polling loops, remote roundtrips, or significant runtime orchestration must be marked `@pytest.mark.slow`.
+- Contract tests in `tests/contracts/` should stay unmarked and fast by default.
+- Tests under `tests/_core/` are marked `@pytest.mark.core` by `tests/_core/conftest.py` and remain included in default pytest runs.
+
+#### Taxonomy maintenance
+
+- Keep each maintained behavior in one taxonomy-aligned location.
+- Remove a superseded or duplicate test when its replacement coverage is added.
+- Preserve canonical contract IDs in replacement parameterized case IDs where applicable.
+
+## Migration Rollout Policy
+
+When migrating storage or execution paths, use phased rollouts with tests at each phase:
+
+1. Implement the new destination path first and test it.
+2. Write to both old and new paths and test.
+3. Read from the new path and test.
+4. Stop writing to the old path and test.
+5. Remove the old path and test.
+
+Thank you for helping make this project better!