adag 0.1.1__tar.gz

adag-0.1.1/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Build artifacts
+/dist/
+/build/
+/site/
+/public/
+
+# uv / venv
+.venv/
+uv.lock.bak
+
+# Tool caches
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.mypy_cache/
+.moon/cache/
+
+# Editor
+.vscode/
+.idea/
+*.swp
+
+# Local session logs
+logs/
+
+# Personal, machine-specific agent overrides (AGENTS.md is tracked)
+AGENTS.local.md
+CLAUDE.local.md
+
+# Claude Code: per-machine local settings + worktrees are local; .claude/settings.json IS tracked.
+.claude/settings.local.json
+.claude/worktrees/
+
+# Local agent wiring: names cabildo-issues-mcp, which is not a dependency of this
+# package. docs/issues/ IS tracked — the register is plain markdown anyone can read.
+.mcp.json

adag-0.1.1/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial release.

adag-0.1.1/LICENSE

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

adag-0.1.1/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: adag
+Version: 0.1.1
+Summary: Another DAG: a cached, content-addressed DAG engine for Python data pipelines.
+Project-URL: Homepage, https://gitlab.com/cardona-oss/adag
+Project-URL: Repository, https://gitlab.com/cardona-oss/adag
+Project-URL: Documentation, https://cardona-oss.gitlab.io/adag/
+Project-URL: Changelog, https://gitlab.com/cardona-oss/adag/-/blob/main/CHANGELOG.md
+Project-URL: Issues, https://gitlab.com/cardona-oss/adag/-/issues
+Author-email: Jorge Cardona <jorgeecardona@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: pydantic>=2.12
+Requires-Dist: structlog
+Requires-Dist: typing-extensions>=4.4
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: sql
+Requires-Dist: sqlalchemy>=2.0; extra == 'sql'
+Description-Content-Type: text/markdown
+
+# adag
+
+[![pipeline status](https://gitlab.com/cardona-oss/adag/badges/main/pipeline.svg)](https://gitlab.com/cardona-oss/adag/-/pipelines)
+[![PyPI version](https://img.shields.io/pypi/v/adag.svg)](https://pypi.org/project/adag/)
+[![Python versions](https://img.shields.io/pypi/pyversions/adag.svg)](https://pypi.org/project/adag/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://gitlab.com/cardona-oss/adag/-/blob/main/LICENSE)
+
+Another DAG: a cached, content-addressed DAG engine for Python data pipelines.
+
+## Install
+
+```bash
+pip install adag
+```
+
+Requires Python 3.13+.
+
+## Quickstart
+
+Each step is a frozen dataclass. Call a step to wire it into the graph, then run the
+graph with a `Pipeline`.
+
+```python
+from dataclasses import dataclass
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from adag import InputParam, Pipeline, Step
+
+
+class Number(BaseModel):
+    value: int
+
+
+@dataclass(frozen=True)
+class Square(Step[Number]):
+    def run(self, x: int) -> Number:
+        print("computing square")
+        return Number(value=x * x)
+
+
+@dataclass(frozen=True)
+class AddOne(Step[Number]):
+    def run(self, n: Number) -> Number:
+        return Number(value=n.value + 1)
+
+
+x = InputParam[int]("x")
+total = AddOne()(n=Square()(x=x))
+pipeline = Pipeline(total, cache_dir=Path("cache"))
+
+print(pipeline.execute(x=4))  # computes both steps
+print(pipeline.execute(x=4))  # served from the cache
+```
+
+The second run reads both results from `cache/` and does not call `Square.run` again:
+
+```text
+computing square
+value=17
+value=17
+```
+
+(output trimmed: structlog lines removed)
+
+## Why adag
+
+A step's cache key is a hash of its fields, its inputs, and its source code. Change any of
+them and that step and everything downstream recompute; nothing else does. Use it for data
+and ML pipelines where steps are slow and you rerun the graph often.
+
+## Key features
+
+- Content-addressed cache: a code edit invalidates only the steps it touches.
+- Sync and async steps (`Step`, `AsyncStep`), with a parallel executor.
+- `FanOutStep` runs a sub-graph per key; `BatchStep` caches each item on its own.
+- Cache backends: filesystem, memory, SQLite, SQLAlchemy (`adag[sql]`), Redis (`adag[redis]`).
+- Save a pipeline to disk and load it back with identical hashes.
+- SVG rendering of the graph, and an `adag run pipeline.py` CLI.
+- Run fan-out branches in subprocesses or AWS Batch jobs, joined through the cache.
+
+## Links
+
+- **Documentation:** https://cardona-oss.gitlab.io/adag/
+- **Source:** https://gitlab.com/cardona-oss/adag
+- **Issues:** https://gitlab.com/cardona-oss/adag/-/issues
+- **PyPI:** https://pypi.org/project/adag/
+- **Changelog:** [CHANGELOG.md](https://gitlab.com/cardona-oss/adag/-/blob/main/CHANGELOG.md)
+
+## Contributing
+
+Developer setup, the dev loop, and the release process live in
+[CONTRIBUTING.md](https://gitlab.com/cardona-oss/adag/-/blob/main/CONTRIBUTING.md). In short: `uv sync && make install-hooks`, then
+`make check` runs the same gate CI runs.
+
+## License
+
+MIT © 2026 Jorge Cardona (see [LICENSE](https://gitlab.com/cardona-oss/adag/-/blob/main/LICENSE)).

adag-0.1.1/README.md

@@ -0,0 +1,99 @@
+# adag
+
+[![pipeline status](https://gitlab.com/cardona-oss/adag/badges/main/pipeline.svg)](https://gitlab.com/cardona-oss/adag/-/pipelines)
+[![PyPI version](https://img.shields.io/pypi/v/adag.svg)](https://pypi.org/project/adag/)
+[![Python versions](https://img.shields.io/pypi/pyversions/adag.svg)](https://pypi.org/project/adag/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://gitlab.com/cardona-oss/adag/-/blob/main/LICENSE)
+
+Another DAG: a cached, content-addressed DAG engine for Python data pipelines.
+
+## Install
+
+```bash
+pip install adag
+```
+
+Requires Python 3.13+.
+
+## Quickstart
+
+Each step is a frozen dataclass. Call a step to wire it into the graph, then run the
+graph with a `Pipeline`.
+
+```python
+from dataclasses import dataclass
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from adag import InputParam, Pipeline, Step
+
+
+class Number(BaseModel):
+    value: int
+
+
+@dataclass(frozen=True)
+class Square(Step[Number]):
+    def run(self, x: int) -> Number:
+        print("computing square")
+        return Number(value=x * x)
+
+
+@dataclass(frozen=True)
+class AddOne(Step[Number]):
+    def run(self, n: Number) -> Number:
+        return Number(value=n.value + 1)
+
+
+x = InputParam[int]("x")
+total = AddOne()(n=Square()(x=x))
+pipeline = Pipeline(total, cache_dir=Path("cache"))
+
+print(pipeline.execute(x=4))  # computes both steps
+print(pipeline.execute(x=4))  # served from the cache
+```
+
+The second run reads both results from `cache/` and does not call `Square.run` again:
+
+```text
+computing square
+value=17
+value=17
+```
+
+(output trimmed: structlog lines removed)
+
+## Why adag
+
+A step's cache key is a hash of its fields, its inputs, and its source code. Change any of
+them and that step and everything downstream recompute; nothing else does. Use it for data
+and ML pipelines where steps are slow and you rerun the graph often.
+
+## Key features
+
+- Content-addressed cache: a code edit invalidates only the steps it touches.
+- Sync and async steps (`Step`, `AsyncStep`), with a parallel executor.
+- `FanOutStep` runs a sub-graph per key; `BatchStep` caches each item on its own.
+- Cache backends: filesystem, memory, SQLite, SQLAlchemy (`adag[sql]`), Redis (`adag[redis]`).
+- Save a pipeline to disk and load it back with identical hashes.
+- SVG rendering of the graph, and an `adag run pipeline.py` CLI.
+- Run fan-out branches in subprocesses or AWS Batch jobs, joined through the cache.
+
+## Links
+
+- **Documentation:** https://cardona-oss.gitlab.io/adag/
+- **Source:** https://gitlab.com/cardona-oss/adag
+- **Issues:** https://gitlab.com/cardona-oss/adag/-/issues
+- **PyPI:** https://pypi.org/project/adag/
+- **Changelog:** [CHANGELOG.md](https://gitlab.com/cardona-oss/adag/-/blob/main/CHANGELOG.md)
+
+## Contributing
+
+Developer setup, the dev loop, and the release process live in
+[CONTRIBUTING.md](https://gitlab.com/cardona-oss/adag/-/blob/main/CONTRIBUTING.md). In short: `uv sync && make install-hooks`, then
+`make check` runs the same gate CI runs.
+
+## License
+
+MIT © 2026 Jorge Cardona (see [LICENSE](https://gitlab.com/cardona-oss/adag/-/blob/main/LICENSE)).

adag-0.1.1/pyproject.toml

@@ -0,0 +1,155 @@
+[project]
+name = "adag"
+dynamic = ["version"]  # the single source of truth is __version__ in src/adag/__init__.py (see [tool.hatch.version])
+description = "Another DAG: a cached, content-addressed DAG engine for Python data pipelines."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Jorge Cardona", email = "jorgeecardona@gmail.com" }]
+keywords = []
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.12",
+    "structlog",
+    "typing-extensions>=4.4",
+]
+
+[project.scripts]
+adag = "adag.cli:main"
+
+[project.optional-dependencies]
+sql = ["sqlalchemy>=2.0"]  # SqlCacheStore
+redis = ["redis>=5.0"]  # RedisCacheStore
+# docs are an *extra* (not a uv dependency-group) so Read the Docs can install them via pip
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.27",
+]
+
+[project.urls]
+Homepage = "https://gitlab.com/cardona-oss/adag"
+Repository = "https://gitlab.com/cardona-oss/adag"
+Documentation = "https://cardona-oss.gitlab.io/adag/"
+Changelog = "https://gitlab.com/cardona-oss/adag/-/blob/main/CHANGELOG.md"
+Issues = "https://gitlab.com/cardona-oss/adag/-/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+# The version lives as __version__ in the package itself; hatchling reads it (by regex, no import) so
+# pyproject and the runtime never disagree. scripts/bump-version rewrites that literal.
+path = "src/adag/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/adag"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "CHANGELOG.md", "LICENSE"]
+
+[tool.uv]
+# The version is dynamic (hatchling reads __version__ from the file below), so uv must watch it too:
+# declaring cache-keys REPLACES uv's defaults, so pyproject.toml is listed explicitly alongside it.
+# Without __init__.py here, bumping the version would not trigger an editable reinstall.
+cache-keys = [{ file = "pyproject.toml" }, { file = "src/adag/__init__.py" }]
+
+[dependency-groups]
+dev = ["ruff>=0.6", "pyright[nodejs]>=1.1.390", "pytest>=8", "sqlalchemy>=2.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+# The canonical base ignore list shared across the oss/ libraries. E501 (line length) is handled by
+# the formatter; COM812/ISC001 conflict with the formatter; D1/D401 relax docstring presence/mood;
+# TRY003/EM101/EM102 allow inline exception messages; CPY001 drops the copyright-header demand;
+# PLC0415 allows non-top-level imports; TC001/TC002/TC003 don't force type-only import blocks.
+ignore = [
+    "E501",
+    "COM812",
+    "ISC001",
+    "D1",
+    "D401",
+    "TRY003",
+    "EM101",
+    "EM102",
+    "CPY001",
+    "PLC0415",
+    "TC001",
+    "TC002",
+    "TC003",
+    # adag-specific: Step.run() takes **kwargs resolved from the graph, so Any is the honest type.
+    "ANN401",
+    # Multi-line docstring summaries are used throughout the imported engine.
+    "D205",
+    # Modules inside the package read each other's private helpers on purpose.
+    "SLF001",
+    # Step and Pipeline constructors take many keyword options by design.
+    "PLR0913",
+    "PLR0917",
+    "PLR0911",
+    "PLR0912",
+    "PLR0915",
+    "C901",
+    # Generic[...] classes still pair with typing_extensions.TypeVar(default=...).
+    "UP046",
+    "UP040",
+    # The engine catches any step failure to record it and re-raise or report it.
+    "BLE001",
+    "TRY300",
+    # Hook and protocol overrides keep the base signature even when an argument is unused.
+    "ARG002",
+    "ARG004",
+    # StepTimeout is public API; renaming it would break callers.
+    "N818",
+    # Cache paths are built as str and handed to os functions; converting is churn, not a fix.
+    "PTH",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+[tool.ruff.lint.per-file-ignores]
+# Tests may assert (S101), use magic values (PLR2004), take unused fixtures (ARG), pass Any to typed
+# calls (ANN401), and group assertions pytest would otherwise split (PT018).
+"tests/**/*.py" = ["S101", "PLR2004", "ARG", "ANN", "PT018", "PT011", "D", "T201", "S108", "RUF043", "RUF059", "RUF009", "N818", "BLE001", "S603", "FBT001"]
+# The CLI and the run-tree observer print to stdout on purpose.
+"src/adag/cli.py" = ["T201"]
+"src/adag/observers.py" = ["T201"]
+# SVG layout uses literal pixel and ratio constants; asserts guard layout invariants.
+"src/adag/visualization.py" = ["PLR2004", "S101", "FBT001"]
+# The worker command is built from our own module name, never from user input.
+"src/adag/dispatch.py" = ["S603"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["adag"]
+
+[tool.pyright]
+include = ["src", "tests"]
+extraPaths = ["src"]
+pythonVersion = "3.13"
+typeCheckingMode = "strict"
+venvPath = "."
+venv = ".venv"
+# Modules inside the package share private helpers and ResolveContext internals on purpose
+# (same reason as ruff SLF001).
+reportPrivateUsage = false
+# Step subclasses narrow run(self, **kwargs: Any) into a typed signature on purpose.
+reportIncompatibleMethodOverride = false

adag-0.1.1/src/adag/__init__.py

@@ -0,0 +1,109 @@
+"""adag — content-addressable DAG engine for data pipelines.
+
+Core engine:
+    Deferred, InputParam, ResolveContext — value abstraction
+    PipelineObserver, NullObserver       — instrumentation hook on ResolveContext
+    LoggingObserver                      — default observer; logs each step's lifecycle
+    RunTreeObserver                      — renders a run as an indented timing tree
+    Executor, LocalExecutor              — pluggable step execution on ResolveContext
+    AsyncExecutor, LocalAsyncExecutor    — the awaitable counterparts (the async resolve path)
+    Step                                — single step base class
+    AsyncStep                           — Step whose body awaits I/O; resolve via Pipeline.aexecute()
+    CachedStep                          — Step with content-addressable caching
+    SerializableStep                    — Step with save/load support
+    StepResult                          — deferred result of a Step
+    FileSource, LinesSource, JSONLSource — file leaf Deferreds (text / lines / parsed)
+    Config, ItemCache                    — input/cache types
+    Pipeline                            — DAG executor
+    BatchItem, BatchStep                — per-item batch processing with ItemCache
+
+Backward compatibility:
+    Parameter                           — alias for InputParam
+"""
+
+__version__ = "0.1.1"
+
+from adag.base import CachedStep
+from adag.batch import BatchItem, BatchStep
+from adag.config import Config
+from adag.deferred import (
+    AsyncExecutor,
+    BranchDispatcher,
+    BranchRef,
+    Deferred,
+    Executor,
+    InlineDispatcher,
+    InputParam,
+    LocalAsyncExecutor,
+    LocalExecutor,
+    NullObserver,
+    PipelineObserver,
+    Progress,
+    ResolveContext,
+    current_observer,
+    observing,
+)
+from adag.dir_source import DirSource
+from adag.dispatch import BatchDispatcher, BranchExecutionError, BranchPolicy, SubprocessDispatcher
+from adag.fan_out import FanOutBranchError, FanOutStep
+from adag.io import FileSource, JSONLSource, LinesSource
+from adag.item_cache import ItemCache
+from adag.observers import LoggingObserver, RunTreeObserver
+from adag.parameter import Parameter
+from adag.pipeline import CyclicPipelineError, Pipeline, UnboundInputError
+from adag.serializable import SerializableStep
+from adag.sinks import WriteJSONL
+from adag.step import AsyncStep, Step, StepResult, StepTimeout
+from adag.step_mode import StepMode
+from adag.visualization import SVG, SvgOptions, dag, render_pipeline_svg, walk
+
+__all__ = [
+    "SVG",
+    "AsyncExecutor",
+    "AsyncStep",
+    "BatchDispatcher",
+    "BatchItem",
+    "BatchStep",
+    "BranchDispatcher",
+    "BranchExecutionError",
+    "BranchPolicy",
+    "BranchRef",
+    "CachedStep",
+    "Config",
+    "CyclicPipelineError",
+    "Deferred",
+    "DirSource",
+    "Executor",
+    "FanOutBranchError",
+    "FanOutStep",
+    "FileSource",
+    "InlineDispatcher",
+    "InputParam",
+    "ItemCache",
+    "JSONLSource",
+    "LinesSource",
+    "LocalAsyncExecutor",
+    "LocalExecutor",
+    "LoggingObserver",
+    "NullObserver",
+    "Parameter",
+    "Pipeline",
+    "PipelineObserver",
+    "Progress",
+    "ResolveContext",
+    "RunTreeObserver",
+    "SerializableStep",
+    "Step",
+    "StepMode",
+    "StepResult",
+    "StepTimeout",
+    "SubprocessDispatcher",
+    "SvgOptions",
+    "UnboundInputError",
+    "WriteJSONL",
+    "current_observer",
+    "dag",
+    "observing",
+    "render_pipeline_svg",
+    "walk",
+]

adag-0.1.1/src/adag/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m adag`` to invoke the CLI."""
+
+from adag.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())