wfc-client 0.1.0__tar.gz

wfc_client-0.1.0/LICENSE

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

wfc_client-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.1
+Name: wfc-client
+Version: 0.1.0
+Summary: Pure-stdlib Tier-1 sugar for writing Workflow Canvas (wfc) methods
+Home-page: https://github.com/ddpoe/workflow-canvas
+License: MIT
+Keywords: workflow,pipeline,methods,reproducibility,provenance
+Author: Dante
+Author-email: dantepoe@noboundssolutions.com
+Requires-Python: >=3.8
+Classifier: Development Status :: 3 - Alpha
+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.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Project-URL: Repository, https://github.com/ddpoe/workflow-canvas
+Description-Content-Type: text/markdown
+
+# wfc-client
+
+Pure-stdlib Tier-1 sugar for writing [Workflow Canvas](https://github.com/ddpoe/workflow-canvas) (`wfc`) methods.
+
+`wfc-client` is the *opt-in ergonomic* way to write a wfc method. The
+canonical interface is the Tier-2 env-var + file contract — `wfc-client`
+is a thin, zero-dependency wrapper over it. It never installs `wfc`,
+pandas, or any third-party package into your environment, and it never
+copies, reads, or serializes your data bytes: it is a metadata recorder.
+
+```python
+import wfc_client as wfc
+
+@wfc.method
+def qc(ctx):
+    clean_path = ctx.workdir / "clean.csv"
+    # ... write your file with whatever library you like ...
+    ctx.save_artifact("clean", clean_path)
+    ctx.log_metric("kept_rows", 100)
+
+if __name__ == "__main__":
+    wfc.run()
+```
+
+## The `ctx` surface
+
+| Member | Purpose |
+|---|---|
+| `ctx.input(slot)` | Resolved input paths (`list[Path]`) for an input slot. |
+| `ctx.params` | Parsed params dict. |
+| `ctx.workdir` | Scratch dir at `WFC_RUN_DIR/_workdir/` (auto-created). |
+| `ctx.run_dir` | `WFC_RUN_DIR` (advanced). |
+| `ctx.save_artifact(name, path)` | Record that `path` is the declared output `name`. Path only. |
+| `ctx.log_metric(name, value)` | Record a scalar metric. |
+
+At `wfc.run()` exit, `wfc-client` writes one `_wfc_results.json` manifest
+of `{outputs, metrics}` with run-dir-relative paths. The host reads it.
+
+Exactly one `@wfc.method` per method module is required.
+

wfc_client-0.1.0/README.md

@@ -0,0 +1,39 @@
+# wfc-client
+
+Pure-stdlib Tier-1 sugar for writing [Workflow Canvas](https://github.com/ddpoe/workflow-canvas) (`wfc`) methods.
+
+`wfc-client` is the *opt-in ergonomic* way to write a wfc method. The
+canonical interface is the Tier-2 env-var + file contract — `wfc-client`
+is a thin, zero-dependency wrapper over it. It never installs `wfc`,
+pandas, or any third-party package into your environment, and it never
+copies, reads, or serializes your data bytes: it is a metadata recorder.
+
+```python
+import wfc_client as wfc
+
+@wfc.method
+def qc(ctx):
+    clean_path = ctx.workdir / "clean.csv"
+    # ... write your file with whatever library you like ...
+    ctx.save_artifact("clean", clean_path)
+    ctx.log_metric("kept_rows", 100)
+
+if __name__ == "__main__":
+    wfc.run()
+```
+
+## The `ctx` surface
+
+| Member | Purpose |
+|---|---|
+| `ctx.input(slot)` | Resolved input paths (`list[Path]`) for an input slot. |
+| `ctx.params` | Parsed params dict. |
+| `ctx.workdir` | Scratch dir at `WFC_RUN_DIR/_workdir/` (auto-created). |
+| `ctx.run_dir` | `WFC_RUN_DIR` (advanced). |
+| `ctx.save_artifact(name, path)` | Record that `path` is the declared output `name`. Path only. |
+| `ctx.log_metric(name, value)` | Record a scalar metric. |
+
+At `wfc.run()` exit, `wfc-client` writes one `_wfc_results.json` manifest
+of `{outputs, metrics}` with run-dir-relative paths. The host reads it.
+
+Exactly one `@wfc.method` per method module is required.

wfc_client-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[tool.poetry]
+name = "wfc-client"
+version = "0.1.0"
+description = "Pure-stdlib Tier-1 sugar for writing Workflow Canvas (wfc) methods"
+authors = ["Dante <dantepoe@noboundssolutions.com>"]
+readme = "README.md"
+license = "MIT"
+homepage = "https://github.com/ddpoe/workflow-canvas"
+repository = "https://github.com/ddpoe/workflow-canvas"
+keywords = ["workflow", "pipeline", "methods", "reproducibility", "provenance"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+packages = [{ include = "wfc_client" }]
+
+# Zero third-party dependencies by design (ADR-020): wfc-client is a
+# metadata recorder that imports only the Python standard library.
+[tool.poetry.dependencies]
+python = ">=3.8"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

wfc_client-0.1.0/wfc_client/__init__.py

@@ -0,0 +1,30 @@
+"""wfc-client — pure-stdlib Tier-1 sugar for writing wfc methods.
+
+Usage::
+
+    import wfc_client as wfc
+
+    @wfc.method
+    def qc(ctx):
+        clean_path = ctx.workdir / "clean.csv"
+        ...  # write the file
+        ctx.save_artifact("clean", clean_path)
+        ctx.log_metric("kept_rows", 100)
+
+    if __name__ == "__main__":
+        wfc.run()
+
+This package is a strict subset focused on the canonical Tier-2 env-var +
+file contract (ADR-020). It has zero third-party dependencies and never
+imports the full ``wfc`` package, pandas, or sqlmodel. It is a metadata
+recorder: it never copies, reads, or serializes your data bytes.
+"""
+
+from __future__ import annotations
+
+from .context import RunContext
+from .decorator import method
+from .errors import ContractViolation
+from .main import run
+
+__all__ = ["method", "run", "RunContext", "ContractViolation"]

wfc_client-0.1.0/wfc_client/context.py

@@ -0,0 +1,137 @@
+"""RunContext — the ``ctx`` object handed to ``@wfc.method`` functions.
+
+This is the Tier-1 sugar over the canonical Tier-2 env-var + file contract
+(ADR-020). It is a *metadata recorder*: it never copies, moves, reads, or
+serializes the user's data bytes. ``save_artifact(name, path)`` records a
+path; ``log_metric(name, value)`` records a scalar; at exit ``_finalize()``
+writes a single ``_wfc_results.json`` manifest the host reads.
+
+Pure stdlib: only ``json``, ``os``, ``pathlib``. No wfc / pandas /
+sqlmodel imports, and no ``method.yaml`` read.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+# Filename of the single results channel (outputs + metrics) the host reads.
+RESULTS_FILENAME = "_wfc_results.json"
+
+
+class RunContext:
+    """Runtime context for a wfc-managed method script.
+
+    Reads the canonical ``WFC_*`` environment variables the host sets
+    before launching the user process, and records declared outputs and
+    metrics for the host to archive after the process exits.
+
+    Attributes:
+        run_dir: ``WFC_RUN_DIR`` — the directory the host can read after
+            the container exits. All declared outputs must resolve inside
+            this directory.
+        workdir: A scratch directory at ``WFC_RUN_DIR/_workdir/``, created
+            on access. The host deletes it after archiving.
+        params: Parsed ``WFC_PARAMS`` dict.
+    """
+
+    def __init__(self):
+        run_dir_env = os.environ.get("WFC_RUN_DIR")
+        if not run_dir_env:
+            raise RuntimeError(
+                "WFC_RUN_DIR is not set. wfc-client methods must be launched "
+                "by `wfc run-step`, which sets WFC_RUN_DIR / WFC_INPUT_PATHS / "
+                "WFC_PARAMS before running your script."
+            )
+        self.run_dir = Path(run_dir_env).resolve()
+        self.params = json.loads(os.environ.get("WFC_PARAMS", "{}"))
+
+        self._input_paths = json.loads(os.environ.get("WFC_INPUT_PATHS", "{}"))
+        self._outputs: "dict[str, str]" = {}
+        self._metrics: "dict[str, object]" = {}
+        self._workdir: "Path | None" = None
+
+    @property
+    def workdir(self) -> Path:
+        """Scratch directory at ``WFC_RUN_DIR/_workdir/`` (created on access).
+
+        Located inside ``WFC_RUN_DIR`` so files written here automatically
+        satisfy ``save_artifact``'s path-inside-run_dir constraint and are
+        reachable by the host after the container exits.
+
+        Returns:
+            The path to the scratch directory.
+        """
+        if self._workdir is None:
+            wd = self.run_dir / "_workdir"
+            wd.mkdir(parents=True, exist_ok=True)
+            self._workdir = wd
+        return self._workdir
+
+    def input(self, slot_name: str) -> "list[Path]":
+        """Return resolved input paths for an input slot.
+
+        Args:
+            slot_name: The input slot name as declared in ``method.yaml``.
+
+        Returns:
+            A list of resolved :class:`~pathlib.Path` objects from
+            ``WFC_INPUT_PATHS`` for that slot, or an empty list if the
+            slot has no inputs.
+        """
+        paths = self._input_paths.get(slot_name, [])
+        return [Path(p) for p in paths]
+
+    def save_artifact(self, name: str, source_path) -> None:
+        """Record that the file at ``source_path`` is the declared output ``name``.
+
+        Does **not** copy, move, read, or serialize the file. The only
+        guard is that ``source_path`` must resolve to a path inside
+        ``WFC_RUN_DIR`` (the bind-mounted directory the host can read
+        after the container exits). Output *type/extension* correctness is
+        validated host-side after the run, not here.
+
+        Args:
+            name: The declared output name (from ``method.yaml``).
+            source_path: Path to the already-written output file. Must
+                resolve inside ``WFC_RUN_DIR``; use ``ctx.workdir`` or
+                ``ctx.run_dir / 'name.ext'``.
+
+        Raises:
+            ValueError: If ``source_path`` resolves outside ``WFC_RUN_DIR``.
+        """
+        resolved = Path(source_path).resolve()
+        try:
+            rel = resolved.relative_to(self.run_dir)
+        except ValueError:
+            raise ValueError(
+                f"save_artifact source must be inside WFC_RUN_DIR (got {source_path}). "
+                f"Use ctx.workdir or write to ctx.run_dir / 'name.ext'."
+            )
+        self._outputs[name] = rel.as_posix()
+
+    def log_metric(self, name: str, value) -> None:
+        """Record a scalar metric.
+
+        Args:
+            name: Metric name.
+            value: Scalar value (number, string, bool).
+        """
+        self._metrics[name] = value
+
+    def _finalize(self) -> Path:
+        """Write the ``_wfc_results.json`` manifest to ``WFC_RUN_DIR``.
+
+        The manifest is the single results channel for both declared
+        outputs and metrics. Output paths are relative to ``WFC_RUN_DIR``
+        so the host can join them against its own run-dir without any
+        container-vs-host path translation.
+
+        Returns:
+            The path to the written manifest.
+        """
+        manifest = {"outputs": self._outputs, "metrics": self._metrics}
+        manifest_path = self.run_dir / RESULTS_FILENAME
+        manifest_path.write_text(json.dumps(manifest, default=str))
+        return manifest_path

wfc_client-0.1.0/wfc_client/decorator.py

@@ -0,0 +1,35 @@
+"""The ``@wfc.method`` marker decorator.
+
+Pure stdlib; no wfc / pandas imports.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+# Module-level registry of @method-decorated functions for this method module.
+# ``run()`` resolves exactly one entry; zero or more than one is an error.
+_registry: "list[Callable]" = []
+
+
+def method(func: Callable) -> Callable:
+    """Mark a function as the wfc method entry point.
+
+    The decorated function takes a single ``ctx`` argument (a
+    :class:`wfc_client.context.RunContext`). It produces outputs by
+    calling ``ctx.save_artifact(name, path)`` and metrics via
+    ``ctx.log_metric(name, value)``. Its return value is ignored — there
+    is no return-value parsing.
+
+    Decorating is a no-op at import time beyond registration; dispatch
+    happens when :func:`wfc_client.main.run` is called.
+
+    Args:
+        func: The method function to decorate. Should accept ``(ctx)``.
+
+    Returns:
+        The original function, unchanged, with ``_wfc_method = True`` set.
+    """
+    func._wfc_method = True  # type: ignore[attr-defined]
+    _registry.append(func)
+    return func

wfc_client-0.1.0/wfc_client/errors.py

@@ -0,0 +1,87 @@
+"""Exceptions for wfc-client.
+
+Pure stdlib; no wfc / pandas / sqlmodel imports.
+"""
+
+from __future__ import annotations
+
+
+class ContractViolation(RuntimeError):
+    """Raised when a method's outputs/metrics don't satisfy its contracts.
+
+    Provides an actionable error message showing what was missing,
+    what was produced, and where contracts are defined. The message
+    shape is preserved from the original in-tree ``wfc.method`` decorator
+    so error-message assertions remain stable across the extraction.
+    """
+
+    def __init__(
+        self,
+        method: str,
+        module: "str | None" = None,
+        missing_outputs: "list[str] | None" = None,
+        missing_metrics: "list[str] | None" = None,
+        available_outputs: "list[str] | None" = None,
+        available_metrics: "list[str] | None" = None,
+        extra_outputs: "list[str] | None" = None,
+        # ADR-005: content-level column validation fields
+        missing_columns: "list[str] | None" = None,
+        available_columns: "list[str] | None" = None,
+        slot_name: str = "",
+    ):
+        self.method = method
+        self.module = module
+        self.missing_outputs = missing_outputs or []
+        self.missing_metrics = missing_metrics or []
+        self.available_outputs = available_outputs or []
+        self.available_metrics = available_metrics or []
+        self.extra_outputs = extra_outputs or []
+        self.missing_columns = missing_columns or []
+        self.available_columns = available_columns or []
+        self.slot_name = slot_name
+
+        lines = [f"ContractViolation: Method '{method}'"]
+        if module:
+            lines[0] += f" (module '{module}')"
+
+        if self.missing_columns:
+            lines.append("")
+            slot_label = f" (slot '{slot_name}')" if slot_name else ""
+            lines.append(f"  Missing required input columns{slot_label}:")
+            for name in self.missing_columns:
+                lines.append(f"    - {name}")
+            if self.available_columns:
+                lines.append(f"  Available columns: {self.available_columns}")
+
+        if self.missing_outputs:
+            lines.append("")
+            lines.append("  Missing required outputs:")
+            for name in self.missing_outputs:
+                lines.append(f"    - {name}")
+
+        if self.missing_metrics:
+            lines.append("")
+            lines.append("  Missing required metrics:")
+            for name in self.missing_metrics:
+                lines.append(f"    - {name}")
+
+        if self.extra_outputs:
+            lines.append("")
+            lines.append("  Undeclared outputs returned (not in contract):")
+            for name in self.extra_outputs:
+                lines.append(f"    - {name}")
+
+        if self.available_outputs or self.available_metrics:
+            lines.append("")
+            lines.append("  You returned:")
+            if self.available_outputs:
+                lines.append(f"    outputs: {self.available_outputs}")
+            if self.available_metrics:
+                lines.append(f"    metrics: {self.available_metrics}")
+
+        lines.append("")
+        lines.append("  Module contracts are defined by register_module(contracts=[...]).")
+        lines.append("  Declare each output with ctx.save_artifact(name, path) in your @wfc.method function.")
+        lines.append("  Log scalars with ctx.log_metric(name, value).")
+
+        super().__init__("\n".join(lines))

wfc_client-0.1.0/wfc_client/main.py

@@ -0,0 +1,46 @@
+"""The ``wfc.run()`` entrypoint.
+
+Resolves exactly one ``@wfc.method``-decorated function from the module
+registry, builds a :class:`RunContext`, calls the function with ``ctx``,
+and finalizes (writes the ``_wfc_results.json`` manifest). There is no
+return-value parsing — the function's return value is ignored.
+
+Pure stdlib.
+"""
+
+from __future__ import annotations
+
+from .context import RunContext
+from .decorator import _registry
+
+
+def run() -> None:
+    """Run the single ``@wfc.method``-decorated function in this module.
+
+    Resolves exactly one decorated function. Builds a ``RunContext`` from
+    the ``WFC_*`` env vars, calls ``func(ctx)``, then writes the results
+    manifest. The function's return value is ignored; all outputs flow
+    through ``ctx.save_artifact`` and all metrics through ``ctx.log_metric``.
+
+    Raises:
+        RuntimeError: If zero or more than one ``@wfc.method`` function is
+            registered in this module.
+    """
+    if len(_registry) == 0:
+        raise RuntimeError(
+            "wfc.run() found no @wfc.method function. Decorate exactly one "
+            "function with @wfc.method before the "
+            "if __name__ == '__main__': block."
+        )
+    if len(_registry) > 1:
+        names = ", ".join(getattr(f, "__name__", repr(f)) for f in _registry)
+        raise RuntimeError(
+            f"wfc.run() found {len(_registry)} @wfc.method functions ({names}); "
+            f"exactly one is required per method module. Keep one entry point "
+            f"and move helpers into undecorated functions."
+        )
+
+    func = _registry[0]
+    ctx = RunContext()
+    func(ctx)
+    ctx._finalize()