clankloop 0.0.0__py3-none-any.whl

clankloop/__init__.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""clankloop — Integrate agents into deterministic workflows.
+
+Clankloop compiles workflow specification files ("loopfiles") into graphs of
+tasks, runs or analyzes them, and reports results.
+
+Typical usage::
+
+    from clankloop import compile_pipeline, Runner
+
+    runtime = compile_pipeline(yaml_data, "my_pipeline")
+    runner = Runner()
+    runner.register(runtime)
+    runner.run("my_pipeline", parameters, environ={})
+
+At runtime a compiled :class:`~clankloop.runner.Pipeline` is executed by a
+:class:`~clankloop.runner.Runner`, which drives the
+:class:`~clankloop.core.graph.ExecutionGraph` forward through conditions and actions.
+"""
+
+from clankloop.loopfile import compile_pipeline
+from clankloop.runner import (
+    Runner,
+    Pipeline,
+)
+from clankloop.core.errors import (
+    ClankloopError,
+    UnexpectedTerminationError,
+    UnknownTaskError,
+    InfiniteLoopError,
+    UnassignedDataDependencyError,
+    MissingParameterError,
+    UnknownParameterError,
+)
+
+__all__ = [
+    "compile_pipeline",
+    "Runner",
+    "Pipeline",
+    "ClankloopError",
+    "UnexpectedTerminationError",
+    "UnknownTaskError",
+    "InfiniteLoopError",
+    "UnassignedDataDependencyError",
+    "MissingParameterError",
+    "UnknownParameterError",
+]

clankloop/cli.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+"""Command-line interface for clankloop.
+
+The CLI provides three subcommands:
+
+- ``run`` — Execute a named pipeline from a loopfile.
+- ``plantuml`` — Export a pipeline's execution graph as a PlantUML state diagram.
+- ``taskcar`` — Run a pipeline as a taskcar task script: reads a JSON object
+  of parameters from stdin, runs the pipeline with subprocess output
+  discarded, and prints a taskcar-protocol JSON result on stdout.
+"""
+
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Sequence, TextIO
+import logging
+from importlib.metadata import version as pkg_version
+import yaml
+
+from clankloop.loopfile import compile_pipeline
+from clankloop.loopfile.versions import SUPPORTED_VERSIONS, CURRENT_VERSION, normalize_version
+from clankloop.runner import Runner
+from clankloop.core.graph import UnexpectedTerminationError, IOChannels
+from clankloop.logger import setup_logging
+
+logger = logging.getLogger("clankloop")
+
+#: Taskcar task-script output when the pipeline succeeds with no declarable
+#: result data or new tasks. The loopfile schema does not yet declare result
+#: exports or task spawning; until it does, both fields are empty. taskcar
+#: treats non-zero exit as task failure, so this is only reached on success.
+TASKCAR_EMPTY_RESULT: dict[str, object] = {"data": {}, "new_tasks": []}
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    """Build the argument parser and parse *argv*.
+
+    Args:
+        argv: Optional list of arguments (defaults to ``sys.argv[1:]``).
+
+    Returns:
+        The parsed namespace with ``command``, ``loopfile``, ``pipeline``,
+        and command-specific options.
+    """
+    parser = argparse.ArgumentParser(
+        prog="clankloop",
+        description="Clank Loop — Compile and execute pipeline graphs.",
+    )
+
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {pkg_version('clankloop')}",
+    )
+
+    parser.add_argument(
+        "-l",
+        "--loglevel",
+        nargs="?",
+        default="WARNING",
+        help="Set the logging level (default: WARNING)",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # run command
+    run_parser = subparsers.add_parser("run", help="Compile and run a pipeline")
+    run_parser.add_argument(
+        "loopfile",
+        help="Path to the loopfile YAML definition",
+    )
+    run_parser.add_argument(
+        "pipeline",
+        help="The name of the pipeline to run",
+    )
+    run_parser.add_argument(
+        "-p",
+        "--parameter",
+        action="append",
+        metavar="KEY=VALUE",
+        help="Define or override parameter values (can be used multiple times)",
+    )
+    run_parser.add_argument(
+        "-i",
+        "--interactive",
+        action="store_true",
+        default=False,
+        help="Allow interactive tasks to inherit the terminal (stdin/stdout/stderr)",
+    )
+
+    # plantuml command
+    plant_parser = subparsers.add_parser(
+        "plantuml",
+        help="Export a pipeline's execution graph as a PlantUML activity diagram",
+    )
+    plant_parser.add_argument(
+        "loopfile",
+        help="Path to the loopfile YAML definition",
+    )
+    plant_parser.add_argument(
+        "pipeline",
+        help="The name of the pipeline to inspect",
+    )
+
+    # taskcar command
+    taskcar_parser = subparsers.add_parser(
+        "taskcar",
+        help="Run a pipeline as a taskcar task script (JSON params on stdin, JSON result on stdout)",
+    )
+    taskcar_parser.add_argument(
+        "loopfile",
+        help="Path to the loopfile YAML definition",
+    )
+    taskcar_parser.add_argument(
+        "pipeline",
+        help="The name of the pipeline to run",
+    )
+
+    return parser.parse_args(argv)
+
+
+def parse_parameter(parameter_strings: list[str] | None) -> dict[str, str]:
+    """Parse ``KEY=VALUE`` parameter override strings into a dict.
+
+    Args:
+        parameter_strings: List of ``"KEY=VALUE"`` strings (or ``None``).
+
+    Returns:
+        A mapping of parameter names to their string values.
+
+    Raises:
+        ValueError: If any string does not contain an ``=`` sign.
+    """
+    parameters: dict[str, str] = {}
+    if not parameter_strings:
+        return parameters
+
+    for item in parameter_strings:
+        if "=" not in item:
+            raise ValueError(
+                f"Parameter override must be in KEY=VALUE format, got: {item!r}"
+            )
+        key, value = item.split("=", 1)
+        parameters[key.strip()] = value.strip()
+
+    return parameters
+
+
+def parse_parameters_from_json(raw: str) -> dict[str, str]:
+    """Parse a JSON object from *raw* and return it as a ``dict[str, str]``.
+
+    Every top-level value must be a string.
+    """
+    try:
+        obj = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"stdin is not valid JSON: {exc}") from exc
+
+    if not isinstance(obj, dict):
+        raise ValueError(f"stdin JSON must be an object, got {type(obj).__name__!r}")
+
+    result: dict[str, str] = {}
+    for key, value in obj.items():
+        if not isinstance(value, str):
+            raise ValueError(
+                f"Parameter {key!r} must be a string, got {type(value).__name__!r}"
+            )
+        result[key] = value
+
+    return result
+
+
+def main(argv: Sequence[str] | None = None, *, stdin: TextIO | None = None) -> int:
+    """Entry point for the ``clankloop`` CLI.
+
+    Dispatches to the requested subcommand (``run``, ``plantuml``, or
+    ``taskcar``), compiles the loopfile, and executes or inspects the
+    named pipeline.
+
+    Args:
+        argv: Optional argument list (defaults to ``sys.argv[1:]``).
+        stdin: Optional stdin stream for the ``taskcar`` subcommand
+            (defaults to ``sys.stdin``).
+
+    Returns:
+        Exit code: ``0`` on success, ``1`` on error.
+    """
+    try:
+        args = parse_args(argv)
+
+        if args.command == "taskcar":
+            setup_logging(args.loglevel, json_format=True, stream=sys.stderr)
+        else:
+            setup_logging(args.loglevel)
+
+        loopfile_path = Path(args.loopfile)
+        if not loopfile_path.exists():
+            print(f"Error: Loopfile {args.loopfile!r} not found", file=sys.stderr)
+            return 1
+
+        with loopfile_path.open() as f:
+            yaml_data = yaml.safe_load(f)
+
+        version = normalize_version(yaml_data.get("version", CURRENT_VERSION))
+        if version not in SUPPORTED_VERSIONS:
+            raise ValueError(
+                f"unsupported loopfile version: {version!r}; supported: {SUPPORTED_VERSIONS}"
+            )
+
+        runtime = compile_pipeline(yaml_data, args.pipeline)
+        runner = Runner()
+        runner.register(runtime)
+
+        if args.command == "plantuml":
+            print(runner.to_plantuml(runtime.name))
+            return 0
+
+        parameters: dict[str, str] = {}
+
+        if args.command == "run":
+            parameters = parse_parameter(args.parameter)
+        elif args.command == "taskcar":
+            in_stream = stdin if stdin is not None else sys.stdin
+            parameters = parse_parameters_from_json(in_stream.read())
+
+        try:
+            if args.command == "run":
+                run_stdin = None
+                if args.interactive:
+                    run_stdin = stdin if stdin is not None else sys.stdin
+                runner.run(
+                    runtime.name,
+                    parameters,
+                    environ=os.environ,
+                    io=IOChannels(
+                        stdin=run_stdin,
+                        stdout=sys.stdout,
+                        stderr=sys.stderr,
+                    ),
+                    interactive=args.interactive,
+                )
+            elif args.command == "taskcar":
+                runner.run(runtime.name, parameters, environ=os.environ)
+        except UnexpectedTerminationError as e:
+            logger.error("Pipeline %r terminated unexpectedly: %s", runtime.name, e)
+            logger.debug(
+                f"Pipeline {runtime.name!r} execution details",
+                extra={"pipeline": runtime},
+            )
+            return 1
+        logger.info("Pipeline %r completed successfully", runtime.name)
+
+        if args.command == "taskcar":
+            print(json.dumps(TASKCAR_EMPTY_RESULT))
+
+        return 0
+
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

clankloop/core/__init__.py

@@ -0,0 +1,6 @@
+#!/usr/bin/env python3
+"""Core execution primitives.
+
+This package contains the runtime graph engine (:mod:`clankloop.core.graph`)
+and the environment/templating system (:mod:`clankloop.core.env`).
+"""

clankloop/core/bash.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""Bash subprocess execution behind the :class:`~clankloop.core.types.Execution` protocol.
+
+The only module in the core that touches ``asyncio`` or ``subprocess``. It
+renders the command template, extracts pipeline-declared env vars, and routes
+through one of three IO paths (passthrough / pumped-interactive /
+pumped-captured) based on whether the supplied streams are real OS file
+descriptors.
+"""
+
+
+import asyncio
+import logging
+import subprocess
+from typing import Any, Coroutine, TextIO
+
+from clankloop.core.env import ClankTemplate, EnvPath
+from clankloop.core.types import (
+    ExecutionContext,
+    ExecutionResult,
+    IOChannels,
+    extract_env,
+)
+
+logger = logging.getLogger("clankloop")
+
+
+def _stream_is_fd(stream: TextIO | None) -> bool:
+    """Whether *stream* is a real OS file (has a usable fileno)."""
+    if stream is None:
+        return False
+    try:
+        stream.fileno()
+    except (AttributeError, OSError, ValueError):
+        return False
+    return True
+
+
+def _all_streams_are_fds(io: IOChannels) -> bool:
+    """Whether every channel of *io* is a real OS file.
+
+    Pass-through (inheriting the tty) requires all three to be file
+    descriptors; in-memory streams (tests, capsys capture) must be pumped.
+    """
+    return _stream_is_fd(io.stdin) and _stream_is_fd(io.stdout) and _stream_is_fd(io.stderr)
+
+
+class BashExecution:
+    """Executes a bash command with environment extraction and template rendering.
+
+    The command string may be a :class:`~clankloop.core.env.ClankTemplate` that
+    is rendered against the environment before execution.
+    """
+
+    def __init__(self, name: str, cmds: str | ClankTemplate, exports: dict[str, EnvPath]):
+        self.name = name
+        self.cmds = cmds
+        self.exports = exports
+        self.rendered_cmds: str | None = None
+
+    def consumes(self) -> frozenset[str]:
+        """Template identifiers in the command."""
+        if isinstance(self.cmds, ClankTemplate):
+            return frozenset(self.cmds.get_identifiers())
+        return frozenset()
+
+    def execute(self, context: ExecutionContext) -> ExecutionResult:
+        # Pipeline-declared values override the base process environment.
+        proc_env = {**context.environ, **extract_env(context.env, self.exports)}
+
+        logger.debug(
+            f"Task details {self.name}: {self.cmds} {type(self.cmds)}",
+            extra={
+                "task": self.name,
+                "cmds": self.cmds,
+            },
+        )
+
+        if isinstance(self.cmds, ClankTemplate):
+            logger.info("Rendering cmd template")
+            self.rendered_cmds = self.cmds.render(context.env)
+        else:
+            self.rendered_cmds = self.cmds
+
+        script = "set -euo pipefail\n" + self.rendered_cmds
+        argv = ["bash", "-c", script]
+
+        io = context.io
+        if io.stdin is not None and _all_streams_are_fds(io):
+            # Interactive with a real terminal: inherit the tty directly so
+            # full-screen apps (nano) work. No capture.
+            return self._run_passthrough(argv, proc_env, io)
+        if io.stdin is not None:
+            # Interactive with in-memory streams (tests): pump stdin from the
+            # source and stdout/stderr to the sinks, without capturing.
+            return asyncio.run(self._run_pumped(argv, proc_env, io, capture=False))
+        # Non-interactive: stdin closed (DEVNULL); stdout/stderr pumped to the
+        # sinks (if any) and captured for SetActions / conditions.
+        return asyncio.run(self._run_pumped(argv, proc_env, io, capture=True))
+
+    def _run_passthrough(
+        self, argv: list[str], env: dict[str, str], io: IOChannels
+    ) -> ExecutionResult:
+        assert io.stdin is not None and io.stdout is not None and io.stderr is not None
+        completed = subprocess.run(
+            argv,
+            env=env,
+            stdin=io.stdin,
+            stdout=io.stdout,
+            stderr=io.stderr,
+        )
+        return ExecutionResult(stdout="", stderr="", returncode=completed.returncode)
+
+    async def _run_pumped(
+        self,
+        argv: list[str],
+        env: dict[str, str],
+        io: IOChannels,
+        *,
+        capture: bool,
+    ) -> ExecutionResult:
+        proc = await asyncio.create_subprocess_exec(
+            *argv,
+            env=env,
+            stdin=asyncio.subprocess.PIPE if io.stdin is not None else subprocess.DEVNULL,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        assert proc.stdout is not None and proc.stderr is not None
+
+        tasks: list[Coroutine[Any, Any, None]] = []
+        if io.stdin is not None:
+            assert proc.stdin is not None
+            tasks.append(self._feed(io.stdin, proc.stdin))
+        out_buf: list[str] = []
+        err_buf: list[str] = []
+        tasks.append(self._pump(proc.stdout, io.stdout, out_buf if capture else None))
+        tasks.append(self._pump(proc.stderr, io.stderr, err_buf if capture else None))
+        await asyncio.gather(*tasks)
+        rc = await proc.wait()
+        return ExecutionResult(
+            stdout="".join(out_buf) if capture else "",
+            stderr="".join(err_buf) if capture else "",
+            returncode=rc,
+        )
+
+    @staticmethod
+    async def _feed(source: TextIO, sink: asyncio.StreamWriter) -> None:
+        data = source.read().encode()
+        if data:
+            try:
+                sink.write(data)
+                await sink.drain()
+            except (BrokenPipeError, ConnectionResetError):
+                pass
+        try:
+            sink.close()
+        except (BrokenPipeError, ConnectionResetError):
+            pass
+
+    @staticmethod
+    async def _pump(
+        source: asyncio.StreamReader,
+        sink: TextIO | None,
+        buf: list[str] | None,
+    ) -> None:
+        while True:
+            chunk = await source.read(4096)
+            if not chunk:
+                break
+            text = chunk.decode()
+            if buf is not None:
+                buf.append(text)
+            if sink is not None:
+                sink.write(text)
+                sink.flush()