flw-studio 0.1.0__py3-none-any.whl

agentic_flow/__init__.py

@@ -0,0 +1,186 @@
+"""agentic_flow: define agents (tools + system prompt) in YAML, run them as a pipeline."""
+import logging as _logging
+
+# Library default: attach a NullHandler to the package logger so a run is silent until
+# the application calls configure_logging (or adds its own handler). Done here — not as
+# an import-time side effect of the layer-2 `log` module — so it runs on any
+# `agentic_flow.*` import and the engine never depends on `log` for it (ADR 0004).
+_logging.getLogger("agentic_flow").addHandler(_logging.NullHandler())
+
+from .core.authority import ReplanRejected, maybe_replan, parse_delta, validate_replan
+from .core.agent import (
+    DEFAULT_MODEL,
+    DEFAULT_PROVIDER,
+    Agent,
+    AgentError,
+    AgentRefusal,
+    AgentTimeout,
+    MaxStepsExceeded,
+    OutputParseError,
+    TokenBudgetExceeded,
+)
+from .core.tools.builtin import register_builtins  # registers shared-state tools on the default registry
+from .core.checkpoint import (
+    Checkpointer,
+    InMemoryCheckpointer,
+    JsonFileCheckpointer,
+    get_checkpointer,
+    register_checkpointer,
+)
+from .console import console_tracer, print_final_state
+from .core.context import Context
+from .core.cursor_format import CheckpointRecord, Pending
+from .core.events import EventBus, Subscription
+from .core.graph import (
+    END,
+    AddEdge,
+    AddNode,
+    AgentBody,
+    Authority,
+    ConditionalEdge,
+    Graph,
+    GraphError,
+    HumanBody,
+    ModelDriven,
+    Node,
+    Prune,
+    Replan,
+    ReplanDelta,
+    StaticEdge,
+    SubgraphBody,
+    ToolBody,
+    render_graph,
+)
+from .core.limits import Limits
+from .loader import LoadedProgram, LoaderError, build_program, lower_pipeline
+from .log import configure_logging, event_logger, logger
+from .pipeline import Loop, Step
+from .program import Orchestrator
+from .core.providers import (
+    AnthropicProvider,
+    Completion,
+    GeminiProvider,
+    Provider,
+    get_provider,
+    register_provider,
+)
+from .core.retry import RetryPolicy, run_with_retry
+from .core.runtime import (
+    Budget,
+    FrontierDeadlock,
+    HumanInputRequired,
+    MaxVisitsExceeded,
+    NodeOutputError,
+    NodePaused,
+    RouteOutOfSet,
+    RunStepsExceeded,
+    RunTimeout,
+    RuntimeFailure,
+    resolve_out_edges,
+    resolve_route,
+)
+from .core.runtime import resume as resume_graph
+from .core.runtime import run as run_graph
+from .core.store import (
+    REDUCERS,
+    Channel,
+    MessageLog,
+    Reducer,
+    ReducerTypeError,
+    Store,
+    TodoBoard,
+    UnsupportedSnapshotVersion,
+)
+from .core.tools import Tool, ToolRegistry, registry, tool
+
+__all__ = [
+    "AddEdge",
+    "AddNode",
+    "Agent",
+    "AgentBody",
+    "AgentError",
+    "AgentRefusal",
+    "AgentTimeout",
+    "AnthropicProvider",
+    "Authority",
+    "Budget",
+    "Channel",
+    "CheckpointRecord",
+    "Checkpointer",
+    "Completion",
+    "ConditionalEdge",
+    "Context",
+    "DEFAULT_MODEL",
+    "DEFAULT_PROVIDER",
+    "END",
+    "EventBus",
+    "FrontierDeadlock",
+    "GeminiProvider",
+    "Graph",
+    "GraphError",
+    "HumanBody",
+    "HumanInputRequired",
+    "InMemoryCheckpointer",
+    "JsonFileCheckpointer",
+    "Limits",
+    "LoadedProgram",
+    "LoaderError",
+    "Loop",
+    "MaxStepsExceeded",
+    "MaxVisitsExceeded",
+    "MessageLog",
+    "ModelDriven",
+    "Node",
+    "NodeOutputError",
+    "NodePaused",
+    "Orchestrator",
+    "OutputParseError",
+    "Pending",
+    "Provider",
+    "Prune",
+    "REDUCERS",
+    "Reducer",
+    "ReducerTypeError",
+    "Replan",
+    "ReplanDelta",
+    "ReplanRejected",
+    "RetryPolicy",
+    "RouteOutOfSet",
+    "RunStepsExceeded",
+    "RunTimeout",
+    "RuntimeFailure",
+    "StaticEdge",
+    "Step",
+    "Store",
+    "SubgraphBody",
+    "TodoBoard",
+    "UnsupportedSnapshotVersion",
+    "Subscription",
+    "Tool",
+    "ToolBody",
+    "render_graph",
+    "TokenBudgetExceeded",
+    "ToolRegistry",
+    "build_program",
+    "configure_logging",
+    "console_tracer",
+    "event_logger",
+    "print_final_state",
+    "get_checkpointer",
+    "get_provider",
+    "logger",
+    "lower_pipeline",
+    "maybe_replan",
+    "parse_delta",
+    "register_checkpointer",
+    "register_provider",
+    "register_builtins",
+    "registry",
+    "resolve_out_edges",
+    "resolve_route",
+    "resume_graph",
+    "run_graph",
+    "run_with_retry",
+    "tool",
+    "validate_replan",
+]

agentic_flow/cli.py

@@ -0,0 +1,232 @@
+"""Command-line entry point: run a pipeline YAML.
+
+    agentic-flow path/to/pipeline.yaml --tools mypkg.tools
+    agentic-flow examples/shared_state/pipeline.yaml --tools examples.shared_state.tools --dry-run
+
+``--tools`` imports modules that register ``@tool`` functions (their import is the
+side effect that populates the registry). ``--set KEY=VALUE`` seeds initial state.
+"""
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import logging
+import sys
+import uuid
+from pathlib import Path
+
+from .core.checkpoint import get_checkpointer
+from .console import console_tracer, print_final_state
+from .core.graph import KIND_HUMAN, render_graph
+from .log import configure_logging, event_logger
+from .program import Orchestrator
+from .core.runtime import HumanInputRequired, NodePaused
+from .core.tools import registry
+
+
+def _has_human_node(graph) -> bool:
+    """True if ``graph`` contains a ``human:`` (pause) node — such a run is only
+    resumable with a durable checkpoint."""
+    return any(node.kind == KIND_HUMAN for node in graph.nodes.values())
+
+
+def _resume_command(pipeline: str, spec: str, run_id: str) -> str:
+    """A copy-pasteable command to resume this paused run (the human fills in the answer)."""
+    return (
+        f"agentic-flow {pipeline} --checkpoint {spec} --run-id {run_id} "
+        f'--resume --human-input "<your answer>"'
+    )
+
+
+def _print_pause(prompt: str, pipeline: str, spec: str, run_id: str) -> None:
+    """Surface a pause: the rendered prompt + how to resume. (Exit code 2 follows.)"""
+    print(f"\n[paused] run {run_id!r} awaits human input:")
+    print(f"  {prompt}")
+    print(f"  resume:  {_resume_command(pipeline, spec, run_id)}")
+
+
+def _resolve_human_input(args, parser) -> object | None:
+    """The human's answer from at most one of the three --human-input* flags.
+
+    Returns the string / parsed-JSON value / file contents, or ``None`` when none
+    is supplied (the "not provided" sentinel — resume then prompts on a TTY or
+    continues straight through for a crash-resume). More than one is a usage error.
+    """
+    given = [
+        name for name, value in (
+            ("--human-input", args.human_input),
+            ("--human-input-json", args.human_input_json),
+            ("--human-input-file", args.human_input_file),
+        ) if value is not None
+    ]
+    if len(given) > 1:
+        parser.error(f"only one of {', '.join(given)} may be given")
+    if args.human_input is not None:
+        return args.human_input
+    if args.human_input_json is not None:
+        try:
+            return json.loads(args.human_input_json)
+        except json.JSONDecodeError as exc:
+            parser.error(f"--human-input-json is not valid JSON: {exc}")
+    if args.human_input_file is not None:
+        return Path(args.human_input_file).read_text(encoding="utf-8")
+    return None
+
+
+def _run_to_exit(produce_state, *, pipeline: str, spec: str | None, run_id: str | None) -> int:
+    """Run ``produce_state()`` and map the engine's signals to a process exit code.
+
+    The single place the run/resume outcomes become exit codes: a ``human:`` pause
+    (``NodePaused``) or a non-interactive resume that still needs an answer
+    (``HumanInputRequired``) → 2 (print how to resume); any real failure → 1
+    (message on stderr); success → 0 (print the final state). Shared by all three
+    CLI run paths (plain, durable, resume) so the mapping lives once.
+    """
+    try:
+        state = produce_state()
+    except (NodePaused, HumanInputRequired) as paused:
+        _print_pause(paused.prompt, pipeline, spec, run_id)
+        return 2
+    except Exception as exc:  # any real failure → exit 1
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    print_final_state(state)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="agentic-flow", description=__doc__.splitlines()[0])
+    parser.add_argument("pipeline", help="Path to a pipeline YAML file.")
+    parser.add_argument(
+        "-t", "--tools", action="append", default=[], metavar="MODULE",
+        help="Import a module that registers @tool functions (repeatable).",
+    )
+    parser.add_argument(
+        "--set", action="append", default=[], metavar="KEY=VALUE",
+        help="Seed an initial state value (repeatable).",
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true",
+        help="Build and print the pipeline without calling any model.",
+    )
+    parser.add_argument(
+        "--log-level", metavar="LEVEL", default=None,
+        help="Trace through Python logging at this level (DEBUG/INFO/WARNING/…) "
+             "instead of the default console printer.",
+    )
+    parser.add_argument(
+        "--checkpoint", metavar="SPEC", default=None,
+        help="Persist the run durably via a named backend, e.g. 'json:./runs' or "
+             "'memory'. With no --run-id one is generated and printed.",
+    )
+    parser.add_argument(
+        "--run-id", metavar="ID", default=None,
+        help="Opaque key for the durable run (the checkpoint record key). "
+             "Required to --resume; auto-generated for a fresh --checkpoint run.",
+    )
+    parser.add_argument(
+        "--resume", action="store_true",
+        help="Continue an existing run from its checkpoint (needs --checkpoint + --run-id).",
+    )
+    parser.add_argument(
+        "--human-input", metavar="TEXT", default=None,
+        help="On --resume, the human's answer as a string.",
+    )
+    parser.add_argument(
+        "--human-input-json", metavar="JSON", default=None,
+        help="On --resume, the human's answer parsed as a JSON value (e.g. "
+             "'{\"approved\": true}').",
+    )
+    parser.add_argument(
+        "--human-input-file", metavar="PATH", default=None,
+        help="On --resume, read the human's answer from a file (large / multiline).",
+    )
+    args = parser.parse_args(argv)
+
+    for module in args.tools:
+        importlib.import_module(module)
+
+    # --log-level routes events through standard logging; otherwise use the console printer.
+    tracer = console_tracer()
+    if args.log_level:
+        level = getattr(logging, args.log_level.upper(), None)
+        if not isinstance(level, int):
+            parser.error(f"invalid --log-level {args.log_level!r} (use DEBUG/INFO/WARNING/ERROR)")
+        configure_logging(level)
+        tracer = event_logger()
+
+    orch = Orchestrator.from_yaml(
+        args.pipeline, registry, on_event=None if args.dry_run else tracer
+    )
+
+    if args.dry_run:
+        print(f"pipeline: {args.pipeline}")
+        for name, agent in orch.agents.items():
+            print(
+                f"  agent {name}: provider={agent.provider.name} model={agent.model} "
+                f"tools={[t.name for t in agent.tools]}"
+            )
+        print(render_graph(orch.graph))
+        return 0
+
+    # --- RESUME: continue a checkpointed run; _run_to_exit maps the outcome ---
+    if args.resume:
+        if not args.checkpoint or not args.run_id:
+            parser.error("--resume requires --checkpoint and --run-id")
+        human = _resolve_human_input(args, parser)  # at most one --human-input*; None if absent
+        cp = get_checkpointer(args.checkpoint)
+
+        def _resume() -> object:
+            nonlocal human
+            while True:
+                try:
+                    return orch.resume(args.run_id, cp, human_input=human)
+                except HumanInputRequired as need:
+                    # pending pause, no answer given. Non-interactive: re-raise so
+                    # _run_to_exit prints how to resume and exits 2. On a TTY: prompt
+                    # and re-resume with the typed answer. A *subsequent* gate raises
+                    # NodePaused → exit 2 (distinct pauses loop across invocations,
+                    # not within one process — the stateless resume model).
+                    if not sys.stdin.isatty():
+                        raise
+                    print(need.prompt)
+                    human = input("> ")
+
+        return _run_to_exit(
+            _resume, pipeline=args.pipeline, spec=args.checkpoint, run_id=args.run_id
+        )
+
+    # A human: gate pauses the run; with no durable checkpoint the pause cannot be
+    # resumed (and a printed resume command would name a throwaway in-memory sink).
+    # Fail fast with guidance rather than pausing into an unrecoverable state.
+    if not args.checkpoint and _has_human_node(orch.graph):
+        parser.error(
+            "this pipeline has a human: gate and needs --checkpoint to be resumable "
+            "(e.g. --checkpoint memory, or --checkpoint json:./runs for a durable run)"
+        )
+
+    initial = {}
+    for item in args.set:
+        key, _, value = item.partition("=")
+        initial[key] = value
+
+    # --- RUN with a checkpointer: durable run (pause → exit 2, completion → exit 0) ---
+    if args.checkpoint:
+        cp = get_checkpointer(args.checkpoint)
+        run_id = args.run_id or uuid.uuid4().hex
+        if not args.run_id:
+            print(f"run-id: {run_id}")  # generated — print it so the user can resume
+        return _run_to_exit(
+            lambda: orch.run(initial, run_id=run_id, checkpointer=cp),
+            pipeline=args.pipeline, spec=args.checkpoint, run_id=run_id,
+        )
+
+    # --- RUN with no checkpointer: no I/O, run_id unnecessary ---
+    return _run_to_exit(
+        lambda: orch.run(initial), pipeline=args.pipeline, spec=None, run_id=None
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agentic_flow/console.py

@@ -0,0 +1,114 @@
+"""The built-in console sink for the ``on_event`` seam.
+
+A run reports progress through a single ``on_event(event, data)`` callback. This
+module turns that stream into human-readable console lines — the **one** place the
+event taxonomy is rendered for a terminal, shared by the CLI (``agentic-flow …``)
+and every example's ``run.py``. Its sibling sink, :func:`agentic_flow.event_logger`,
+routes the same events through Python :mod:`logging` (with per-event severity
+instead of layout); both trim long values through :func:`clip`.
+
+The event taxonomy this renders (the ``data`` keys each event carries — the graph
+runtime's :func:`agentic_flow.runtime._emit` calls are the source of truth):
+
+* ``node_start``         — ``node`` + ``kind`` (the node's body kind: agent/tool/human/subgraph)
+* ``node_input``         — ``node`` + ``kind`` + ``input`` (the rendered prompt str / args dict; not rendered here — layer-2 tracing)
+* ``node_end``           — ``node`` + ``output``
+* ``node_error``         — ``node`` + ``error`` (exception class) + ``message`` (not rendered here — layer-2 tracing)
+* ``checkpoint``         — ``run_id`` + ``frontier`` (the ready node ids saved at this boundary)
+* ``human``              — ``node`` + ``output`` [+ ``prompt`` (pause) | ``resumed`` (resume)]
+* ``route``              — ``src`` + ``dst`` + ``seq`` (a fresh model-driven authority-L1 route choice)
+* ``replan``             — ``replans_used`` (an accepted authority-L2 graph amendment)
+* ``replan_rejected``    — ``gate`` + ``message`` (the validation gate the planner's batch failed)
+* ``tool_call``          — ``agent`` + ``tool`` + ``input``
+* ``tool_result``        — ``agent`` + ``tool`` + ``result`` + ``is_error``
+* ``messages_delivered`` — ``agent`` + ``count`` + ``todos``
+* ``retry``              — ``label`` + ``attempt`` + ``attempts`` + ``error`` [+ ``sleep``]
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Callable
+
+EventHook = Callable[[str, dict[str, Any]], None]
+
+
+def clip(value: Any, limit: int = 200) -> str:
+    """Collapse whitespace and truncate ``value`` to ``limit`` chars for a one-line trace."""
+    text = " ".join(str(value).split())
+    return text if len(text) <= limit else text[:limit] + "…"
+
+
+def _render(value: Any) -> str:
+    """Pretty-print a structured (dict/list) output; leave text as-is."""
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, indent=2, ensure_ascii=False)
+    return str(value)
+
+
+def _indent(text: str, prefix: str = "    ") -> str:
+    return "\n".join(prefix + line for line in str(text).splitlines())
+
+
+def console_tracer(*, show_output: bool = False) -> EventHook:
+    """Return an ``on_event`` hook that prints each event to stdout.
+
+    Pass ``show_output=True`` to also print each node's output value inline,
+    pretty-printing ``dict``/``list`` results (handy for examples). The CLI leaves
+    it ``False`` and prints the final state once at the end via
+    :func:`print_final_state` instead.
+    """
+
+    def on_event(event: str, data: dict[str, Any]) -> None:
+        if event == "node_start":
+            print(f"\n=== node '{data['node']}'  ({data['kind']}) ===")
+        elif event == "checkpoint":
+            frontier = ", ".join(data.get("frontier") or []) or "(empty)"
+            print(f"  ~ checkpoint {data['run_id']} | frontier: {frontier}")
+        elif event == "human":
+            prompt = f": {clip(data['prompt'])}" if data.get("prompt") else ""
+            verb = "resumed" if data.get("resumed") else "paused"
+            print(f"  ? human {verb} at '{data['node']}'{prompt}")
+        elif event == "replan":
+            print(f"  * replan accepted (replans used: {data['replans_used']})")
+        elif event == "replan_rejected":
+            print(f"  * replan rejected at gate '{data['gate']}': {clip(data['message'])}")
+        elif event == "route":
+            print(f"  > route {data['src']} → {data['dst']}")
+        elif event == "tool_call":
+            print(f"  [{data['agent']}] -> {data['tool']}({clip(data['input'])})")
+        elif event == "tool_result":
+            tag = "ERROR" if data["is_error"] else "ok"
+            print(f"  [{data['agent']}] <- {data['tool']} [{tag}]: {clip(data['result'])}")
+        elif event == "messages_delivered":
+            bits = []
+            if data.get("count"):
+                bits.append(f"{data['count']} message(s)")
+            if data.get("todos"):
+                bits.append(f"{data['todos']} todo(s)")
+            print(f"  [{data['agent']}] inbox: {', '.join(bits) or 'nothing'} delivered")
+        elif event == "retry":
+            sleep = f"; sleeping {data['sleep']}s" if data.get("sleep") is not None else ""
+            print(
+                f"  ! retry {data['label']} ({data['attempt']}/{data['attempts']}) "
+                f"after {data['error']}{sleep}"
+            )
+        elif event == "node_end":
+            if show_output:
+                print(f"  = node {data['node']!r} done:\n{_indent(_render(data['output']))}")
+            else:
+                print(f"  = node {data['node']!r} done")
+
+    return on_event
+
+
+def print_final_state(state: Any) -> None:
+    """Print the final shared state: store keys, the message log, and the todo board."""
+    print("\n=== final state ===")
+    for key in state:
+        print(f"  {key}: {clip(state[key])}")
+    if state.log:
+        print(f"  messages: {state.log}")
+    if state.todos:
+        print("  todos:")
+        for t in state.todos:
+            print(f"    [{t['status']:>11}] #{t['id']} ({t['owner'] or '-'}) {t['text']}")

agentic_flow/core/__init__.py

@@ -0,0 +1,6 @@
+"""The core engine: the self-sufficient graph executor (layers 0+1).
+
+Given a ``Graph``, a ``Store``, agents, and tools, ``core.runtime.run(...)``
+executes and checkpoints with no layer-2 module imported. Imports nothing
+upward (ADR 0004) — the one-way boundary enforced by ``tests/test_layering.py``.
+"""