fancy-flow 0.1.0__py3-none-any.whl

fancy_flow/__init__.py

@@ -0,0 +1,97 @@
+"""fancy-flow for Python -- the third runtime for fancy-flow workflow graphs.
+
+The guarantee, and the only thing that matters: **the same WorkflowSchema JSON
+in produces the same RunResult.outputs out**, on Node, on PHP, and here. This
+is a faithful PORT, not a redesign; behaviour questions are settled against
+``@particle-academy/fancy-flow`` and ``particle-academy/fancy-flow-php``, and
+parity is asserted by shared fixture tables rather than claimed.
+
+Getting started::
+
+    from fancy_flow import FlowRunner, RunOptions, builtin, import_workflow
+
+    builtin.register()                       # install the built-in kinds
+    result = import_workflow(schema_json)
+    run = FlowRunner().run(
+        result.graph,
+        builtin.executors(),
+        options=RunOptions(initial_inputs={"trigger-1": {"payload": body}}),
+    )
+"""
+
+from __future__ import annotations
+
+from . import capabilities
+from .contracts import NativeResolver, NodeExecutor, Resolver, TriggerGuard
+from .engine.runner import FlowRunner
+from .exceptions import FlowError, RunAborted, UnsafeGraph
+from .executors import ExecutorRegistry
+from .registry import builtin
+from .registry.node_kind import ConfigField, NodeKind
+from .registry.registry import NodeKindRegistry, default_registry, reset_default_registry
+from .runtime import (
+    AbortController,
+    AbortSignal,
+    ExecutionContext,
+    NodeStatus,
+    Pause,
+    PauseSignal,
+    Port,
+    RunEvent,
+    RunOptions,
+    RunResult,
+)
+from .schema import (
+    FlowEdge,
+    FlowGraph,
+    FlowNode,
+    ImportIssue,
+    ImportResult,
+    PortDescriptor,
+    WorkflowMetadata,
+)
+from .workflow import SCHEMA_URL, SCHEMA_VERSION, export_workflow, import_workflow, to_json
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "SCHEMA_URL",
+    "SCHEMA_VERSION",
+    "AbortController",
+    "AbortSignal",
+    "ConfigField",
+    "ExecutionContext",
+    "ExecutorRegistry",
+    "FlowEdge",
+    "FlowError",
+    "FlowGraph",
+    "FlowNode",
+    "FlowRunner",
+    "ImportIssue",
+    "ImportResult",
+    "NativeResolver",
+    "NodeExecutor",
+    "NodeKind",
+    "NodeKindRegistry",
+    "NodeStatus",
+    "Pause",
+    "PauseSignal",
+    "Port",
+    "PortDescriptor",
+    "Resolver",
+    "RunAborted",
+    "RunEvent",
+    "RunOptions",
+    "RunResult",
+    "TriggerGuard",
+    "UnsafeGraph",
+    "WorkflowMetadata",
+    "__version__",
+    "builtin",
+    "capabilities",
+    "default_registry",
+    "export_workflow",
+    "import_workflow",
+    "reset_default_registry",
+    "to_json",
+]

fancy_flow/capabilities/__init__.py

@@ -0,0 +1,212 @@
+"""Host capabilities -- the services core nodes need but must never depend on.
+
+A node that imports a provider SDK forces every consumer to install it: a
+workflow app that never calls a model should not inherit an LLM dependency. So
+core declares the CONTRACT and the host supplies the implementation.
+
+Two ways in: the module-level setters below (so the framework-free core stays
+usable with no container), or an adapter package that registers on the host's
+behalf at startup.
+
+Unlike the PHP twin there is **no auto-detection**. PHP can afford it because
+``class_exists()`` is free; the Python equivalent is importing a candidate
+package to find out whether it is there, which has side effects, costs start-up
+time, and silently picks a provider the author never named. A missing client
+therefore aborts the node with :func:`llm_unavailable_message`, which says what
+to register -- an outcome the author can act on, rather than a guess they have
+to discover.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+from ..schema.graph import FlowGraph
+
+__all__ = [
+    "LlmClient",
+    "LlmRoute",
+    "LlmRouteChoice",
+    "LlmRouteRequest",
+    "WorkflowResolutionFailure",
+    "WorkflowResolver",
+    "llm_client",
+    "llm_unavailable_message",
+    "reset",
+    "set_llm_client",
+    "set_workflow_resolver",
+    "status",
+    "workflow_resolver",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class LlmRoute:
+    """One route a model may choose between.
+
+    The description is what the model actually reads when deciding, so it is
+    the field that determines routing quality.
+    """
+
+    port: str
+    description: str | None = None
+
+    @staticmethod
+    def from_dict(raw: dict[str, Any]) -> LlmRoute:
+        return LlmRoute(
+            port=str(raw.get("port") or "").strip(),
+            description=str(raw["description"]) if raw.get("description") is not None else None,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class LlmRouteRequest:
+    prompt: str
+    routes: tuple[LlmRoute, ...]
+    system: str | None = None
+    provider: str | None = None
+    model: str | None = None
+    credential: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class LlmRouteChoice:
+    """The port the model picked, and why.
+
+    ``reason`` travels with the value down the graph, so a completed run
+    explains itself without the model call being replayed.
+    """
+
+    port: str
+    reason: str | None = None
+
+
+@runtime_checkable
+class LlmClient(Protocol):
+    """The only thing core asks of an LLM: given routes, pick one.
+
+    ``llm_router`` is a shuttle, not an engine. It carries the routes out to
+    whatever the host registered and carries the choice back -- no provider
+    SDK, no prompt engineering, no response parsing, no retry policy. That is
+    what lets an opinionated node ship as a builtin without every consumer
+    inheriting an LLM dependency.
+
+    Implementations should constrain the model to the declared ports
+    (structured output / enum) rather than parsing a port name out of a
+    sentence.
+    """
+
+    def choose_route(
+        self, request: LlmRouteRequest
+    ) -> LlmRouteChoice: ...  # pragma: no cover - protocol
+
+
+@dataclass(frozen=True, slots=True)
+class WorkflowResolutionFailure:
+    """Why a ``subflow`` reference could not be honoured.
+
+    A version mismatch and a missing workflow want different errors: reporting
+    a mismatch as "not found" sends an author looking for a workflow that is
+    sitting right there.
+    """
+
+    reason: str
+    available: int | None = None
+    message: str | None = None
+
+    VERSION_MISMATCH = "version-mismatch"
+    NOT_FOUND = "not-found"
+
+    @property
+    def is_version_mismatch(self) -> bool:
+        return self.reason == self.VERSION_MISMATCH
+
+
+@runtime_checkable
+class WorkflowResolver(Protocol):
+    """Resolve a workflow reference to a runnable graph.
+
+    ``subflow`` NAMES another workflow rather than embedding it, so the host
+    owns where workflows live -- a database, a file, an API.
+
+    ``version`` is a parameter rather than part of the reference string because
+    a stringly-typed protocol (``invoice-triage@3``) is one every host invents
+    differently. A workflow another workflow depends on is an INTERFACE, and
+    interfaces need pins: without one, a parent goes on calling
+    ``invoice-triage``, someone edits that child, and the parent runs different
+    logic having reported success the whole time.
+    """
+
+    def resolve(
+        self, ref: str, version: int | None = None
+    ) -> FlowGraph | WorkflowResolutionFailure | None: ...  # pragma: no cover - protocol
+
+
+# -- module state --------------------------------------------------------
+
+_llm_client: LlmClient | None = None
+_workflow_resolver: WorkflowResolver | None = None
+
+
+def set_llm_client(client: LlmClient | None) -> Callable[[], None]:
+    """Install the host's LLM client. Returns an unregister callable."""
+    global _llm_client
+    _llm_client = client
+
+    def unregister() -> None:
+        global _llm_client
+        if _llm_client is client:
+            _llm_client = None
+
+    return unregister
+
+
+def llm_client() -> LlmClient | None:
+    return _llm_client
+
+
+def llm_unavailable_message() -> str:
+    """Why no client is available, phrased as what to do about it."""
+    return (
+        "No LLM client is registered, so llm_router cannot ask a model which route to "
+        "take. Register one with fancy_flow.capabilities.set_llm_client(client) - any "
+        "object with choose_route(LlmRouteRequest) -> LlmRouteChoice will do."
+    )
+
+
+def set_workflow_resolver(resolver: WorkflowResolver | None) -> Callable[[], None]:
+    """Install the host's workflow resolver. Returns an unregister callable."""
+    global _workflow_resolver
+    _workflow_resolver = resolver
+
+    def unregister() -> None:
+        global _workflow_resolver
+        if _workflow_resolver is resolver:
+            _workflow_resolver = None
+
+    return unregister
+
+
+def workflow_resolver() -> WorkflowResolver | None:
+    return _workflow_resolver
+
+
+def status() -> dict[str, bool]:
+    """Which capabilities are currently satisfied.
+
+    Exists so a host -- or an agent over MCP -- can answer "what does this
+    graph need that I have not wired?" BEFORE a run fails halfway through.
+    """
+    return {
+        "llm": _llm_client is not None,
+        "workflow_resolver": _workflow_resolver is not None,
+    }
+
+
+def reset() -> None:
+    """Clear everything. Test isolation."""
+    global _llm_client, _workflow_resolver
+    _llm_client = None
+    _workflow_resolver = None

fancy_flow/contracts.py

@@ -0,0 +1,62 @@
+"""The seams a host plugs into.
+
+Structural :class:`typing.Protocol` rather than nominal base classes, because a
+host's existing service should be usable as an executor without inheriting from
+us. That is the same freedom the PHP twin gets from accepting a callable, an
+interface implementation, or a class-string interchangeably.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from .runtime.context import ExecutionContext
+
+__all__ = ["NodeExecutor", "Resolver", "TriggerGuard"]
+
+
+@runtime_checkable
+class NodeExecutor(Protocol):
+    """Behaviour for one node kind.
+
+    An executor may equally be a plain callable taking the context; this
+    protocol exists for the class-shaped case, which is what constructor
+    injection wants.
+    """
+
+    def execute(self, ctx: ExecutionContext) -> Any:  # pragma: no cover - protocol
+        ...
+
+
+@runtime_checkable
+class Resolver(Protocol):
+    """Turns a class into an instance.
+
+    The default calls the class with no arguments. A host with a DI container
+    supplies its own so executors get constructor injection -- the analogue of
+    the PHP twin's ``ContainerResolver``.
+    """
+
+    def make(self, cls: type) -> Any:  # pragma: no cover - protocol
+        ...
+
+
+@runtime_checkable
+class TriggerGuard(Protocol):
+    """The precondition a queued cohort run re-checks just before it starts.
+
+    Fails CLOSED by design: when the guard cannot answer, the run does not
+    start. Several runs fired by one event are serialized, and each re-asks
+    whether it still should happen -- because by the time the third one is
+    picked up, the first two may have made it wrong.
+    """
+
+    def should_run(self, run_key: str, context: dict[str, Any]) -> bool:  # pragma: no cover
+        ...
+
+
+class NativeResolver:
+    """The default :class:`Resolver` -- constructs with no arguments."""
+
+    def make(self, cls: type) -> Any:
+        return cls()

fancy_flow/durable/__init__.py

@@ -0,0 +1,51 @@
+"""Durable, resumable runs -- with no queue library anywhere in sight.
+
+The research behind this is written up in the envelope's
+``.ai/plans/fancy-flow-py.md``; the short version is that a JSON-graph engine
+wants **checkpoint-per-node keyed by node id**, not Temporal-style event-sourced
+replay. Replay exists to police arbitrary user code for non-determinism; an
+interpreter over a declarative graph is deterministic by construction, so the
+sandbox, the history limits and the versioning tax buy nothing. And node-id
+keying survives a graph being edited while a run is parked on an approval,
+where an ordinal-keyed checkpoint cannot.
+
+So durability lives here, in the pure core:
+
+- :mod:`.state`       what a run remembers, and the claim contract a database implements
+- :mod:`.frontier`    which nodes are unblocked, restated from the engine's own rule
+- :mod:`.replay`      run one node THROUGH the engine, never around it
+- :mod:`.retry`       how many attempts a node gets, per node
+- :mod:`.human`       gates that pause and cannot be walked past
+- :mod:`.coordinator` the two operations a queue adapter dispatches
+
+A queue adapter supplies transport and nothing else.
+"""
+
+from .coordinator import Coordinator, DurableRunResult, NodeOutcome
+from .frontier import Frontier, FrontierResult
+from .human import DurableApproval, DurableUserInput, NotAwaitingHuman, Submissions
+from .replay import BOUNDARY, ReplayResult, is_boundary, replay_up_to
+from .retry import UNSAFE_TO_REPLAY, RetryPolicy
+from .state import InMemoryClaimStore, NodeClaimStore, NodeRunStatus, NodeState
+
+__all__ = [
+    "BOUNDARY",
+    "UNSAFE_TO_REPLAY",
+    "Coordinator",
+    "DurableApproval",
+    "DurableRunResult",
+    "DurableUserInput",
+    "Frontier",
+    "FrontierResult",
+    "InMemoryClaimStore",
+    "NodeClaimStore",
+    "NodeOutcome",
+    "NodeRunStatus",
+    "NodeState",
+    "NotAwaitingHuman",
+    "ReplayResult",
+    "RetryPolicy",
+    "Submissions",
+    "is_boundary",
+    "replay_up_to",
+]