Skip to main content

fluidgrids-workflows

Author FluidGrids workflows as code in Python. This package is the Python half of Phase A of the code-first workflows spec set (BOFF-9902 / BOFF-9904, fluidgrids-specs/product/specs/code-first/, spec 03):

  • the tier-1 graph builder: Python that constructs a canvas workflow;
  • lowering a Python project to the workflow IR, schema version 2, byte for byte the same as @fluidgrids/workflows lowers the TypeScript twin of the same graph;
  • ports of the IR tools: normalize_definition, validate, ir_hash, canonical JSON (RFC 8785), the structural diff, the executor view, the automatic layout, durations and schedule checks;
  • loading the typed node clients that fluidgrids codegen --lang python generates (.fluidgrids/nodes.py);
  • from Phase B (BOFF-9905): wf.code_workflow, which embeds a TypeScript durable function in a graph, and fluidgrids_workflows.history, the durable-function contract (event and command enums, the command and history JSON Schemas, command and history validation, load_history).

Python durable (tier-2) workflow functions and the Python worker are Phase C (BOFF-9906) and are not in this package yet; lower and validate --refuse-phase-c report what needs them as durable.phaseC. Lifting (IR to Python source) lives in the TypeScript package, which the service and the CLI use for fluidgrids pull --format py.

Install

uv add fluidgrids-workflows     # or: pip install fluidgrids-workflows

Python 3.11 or later. The floor matches fluidgrids-node-sdk (spec 03 §1) and the generated clients, which use typing.Required.

Tier 1: the graph builder

from fluidgrids_workflows import define_workflow, expr, triggers
from fluidgrids_workflows.project import nodes as n


@define_workflow(key="lead-enrichment", name="Lead enrichment")
def lead_enrichment(wf):
    inbound = wf.trigger(triggers.webhook, id="inbound", args={"path": "leads"})
    enrich = wf.http(
        id="enrich",
        after=inbound,
        connection="enrichment-api",
        args={
            "method": "GET",
            "url": "https://person.clearbit.com/v2/combined/find",
            "queryParams": {"email": wf.json.body.email},
        },
        retry={"maxRetries": 3, "retryDelay": 2000},
    )
    is_enterprise = wf.if_(
        id="is-enterprise",
        after=enrich,
        condition=enrich.output.body.company.metrics.employees >= 500,
    )
    wf.step(
        n.slack.send_message,
        id="notify-sales",
        after=is_enterprise.true,
        connection="slack-ops",
        args={
            "channelId": "C0SALES",
            "text": expr("New enterprise lead: ", enrich.output.body.person.name.fullName),
        },
    )

The decorated function runs once, immediately, and records a graph; to_ir(workflow, connections=..., layout=...) turns the recording into IR v2. Lowering is a pure function of the builder calls, so the same source always gives the same IR.

  • Builder methods and keyword options are snake_case (wf.if_, wf.wait_for_signal, on_error, execution_settings). Dictionary values (args, retry, config, extra, …) keep the IR's own keys (maxRetries, channelId) and lower byte for byte.
  • Every node needs an id (define_workflow(..., auto_ids=True) derives them from labels for quick scripts).
  • References lower to the expression language the workers evaluate: enrich.output.a.b becomes {{ $node["enrich"].item.a.b }} and wf.json.x becomes {{ $json.x }}. Use ref["key"] for keys that are not identifiers, are Python keywords, start with _ or are reference method names, and ref[0] for indices.
  • Comparisons (>=, ==, …, contains, is_empty, matches, the generic is_(operator, value)) and and_() / or_() become the condition tree internal:if evaluates. and, or, not and in raise, because they would be evaluated by Python at definition time.
  • expr("text ", ref, " more") concatenates text and references.
  • Leaving an option out writes the default; False for operation, version and edge id / type writes no such field; None is JSON null.
  • edge(source, id=..., type=..., target_handle=..., label=..., data=..., mapping=..., extra=...), wf.connect, wf.edge_order_is and the extra option on every node keep any stored definition expressible exactly.
  • An edge without an explicit id gets e-<source>-<target>[-<sourceHandle>][-<targetHandle>]; when that id is taken the later edges get -2, -3, … in declaration order.
  • connection="name" resolves to a connection id when the workflow is pushed; an unknown name raises UnresolvedConnectionsError.
  • Positions come from the layout sidecar workflows/<key>.layout.json, or the automatic layout the AI draft generator uses.

The complete surface is pinned by the shared fixtures; fixtures/README.md lists it.

Durable functions in a graph

wf.code_workflow("<exportName>", ...) adds an internal:code-workflow node that runs a workflow() function of the definition's code bundle as a durable child run. In Phase B the bundle is a TypeScript one, given with define_workflow(code=...):

from datetime import UTC, datetime

process = wf.code_workflow(
    "processOrder",
    id="process-order",
    after=received,
    input={"order": wf.json.body},  # inputMapping
    timeout_seconds=900,  # 0 or absent: no node-level timeout
    fail_on_error=False,
)
shipped = wf.wait_for_signal(
    id="await-shipment",
    after=process,
    name="shipped",
    consume="all",  # or "first" (the default)
    until=datetime(2026, 12, 1, tzinfo=UTC),  # limitWaitUntil; or limit="2d"
)

As with every builder option, an option left out writes nothing and the service applies the default: task_queue managed, wait_for_completion True, and the parent-close policy of decision DB13, TERMINATE when the node waits for the child and ABANDON when it does not (fluidgrids_workflows.history.code_workflow_parent_close_policy). validate warns about a fire-and-forget node with TERMINATE or REQUEST_CANCEL (codeWorkflow.closePolicyEndsChild) or a timeout (codeWorkflow.timeoutIgnored). until takes an ISO 8601 string or a timezone-aware datetime.

What arrives in Phase C

durable_phase_issues(definition) (in fluidgrids_workflows.ir) lists, with code durable.phaseC, what a definition needs that Phase B does not run: a Python code bundle, determinism: "worker", code.exports.activities (user activities), task queues other than managed, and every code.features entry that is not a Phase B runtime feature: the Phase C ones (userActivity, updates, queries, searchAttributes, dynamic, interceptors) and any value the SDK does not know, so the check fails closed (PHASE_B_CODE_FEATURES, PHASE_C_CODE_FEATURES). lower_project returns them as LowerResult.issues, fluidgrids-workflows lower prints them under issues, and validate(..., refuse_phase_c=True) (validate --refuse-phase-c) makes them errors. Without that option validate gives the TypeScript SDK's verdict.

Projects and generated node clients

A project is a directory with workflow modules in workflows/*.py, optional layout sidecars (workflows/<key>.layout.json), TEST-only pinned data (workflows/<key>.pinned.json) and the generated clients in .fluidgrids/nodes.py. Workflow modules import the clients with from fluidgrids_workflows.project import nodes as n, which resolves to the project being lowered, then FLUIDGRIDS_PROJECT_DIR, then the nearest .fluidgrids/nodes.py at or above the working directory.

from fluidgrids_workflows import lower_project

result = lower_project(".", connections={"slack-ops": {"connectionId": "c1", "adapter": "slack"}})
for workflow in result.workflows:
    print(workflow.key, workflow.definition)

lower_project imports the project's modules, so it is for code the caller trusts (the CLI lowering a developer's own project; services never run Python workflow code, spec decision D1). It imports the project twice and refuses a workflow whose graph changes between the two (LowerError(reason="determinism")), which catches definitions that read the clock or a random source.

Command line

fluidgrids-workflows lower [PROJECT] [--connections FILE] [--entry workflows/x.py]
fluidgrids-workflows validate FILE [--strict] [--allow-empty] [--refuse-phase-c]
fluidgrids-workflows hash FILE
fluidgrids-workflows normalize FILE

Every command prints JSON; FILE may be - for standard input. The FluidGrids CLI calls lower for Python projects; its result carries issues only when a workflow needs a Phase C feature.

The IR

fluidgrids_workflows.ir ports @fluidgrids/workflows/ir:

  • normalize_definition rewrites the builder's legacy mirrors into the canonical node fields following the executor's reading order; it is pure and idempotent.
  • ir_hash is sha256: + the SHA-256 of the RFC 8785 canonical JSON of the normalised definition without authoring, so both SDKs and the canvas hash a graph equally.
  • validate(definition, strict=..., is_task_queue_known=...) applies the service's structural rules and the version-2 rules of spec 01 §9. Issue codes match the TypeScript validator; messages are English and may differ in wording.
  • canonical_json, stable_stringify, diff_definitions, executor_view, auto_layout, duration_ms, check_schedule_spec and the {{ … }} reference parser are exact ports.
  • ir_v2_schema() is the IR v2 JSON Schema, vendored byte for byte from the TypeScript package.

The durable-function contract

fluidgrids_workflows.history is the Python side of @fluidgrids/workflows/history, the contract the service, the workers and both SDKs share:

  • EVENT_TYPES, COMMAND_TYPES, TASK_FAILURE_CAUSES, the Phase B core, parity and Phase C command sets, and the event classes, in the TypeScript order;
  • TypedDicts for events (RunEventRecord), every command, failures, retry policies, task requests and results, local-activity requests and results, run targets and history files; tests/test_history.py checks each one against the vendored schemas;
  • the runtime release the contract describes (RUNTIME_RELEASE, 2 from SDK R2) and the R2 enums: workflow-id reuse and conflict policies, versioning behaviours, workflow timeout types and LOCAL_ACTIVITY_MAX_TIMEOUT_MS;
  • history_schema(name) for the four vendored JSON Schemas (run-event, workflow-command, workflow-task, history-file);
  • validate_command, validate_commands (shape, the gate, unique ids, terminal command last, the activity allow-list), validate_history and validate_history_file, with the TypeScript verdicts and failure causes;
  • the command feature gate (C-GATE) the service applies: command_features, PHASE_B_CORE_FEATURES, PHASE_B_PARITY_FEATURES (what fluidgrids.durable-parity adds), is_relief_command and CommandRelief. Pass a feature set as validate_commands(..., enabled=PHASE_B_CORE_FEATURES) for the service's Phase B verdict. The default levels "core" and "parity" (and is_command_enabled) are deprecated: they keep their R1 meaning, decide by command type only and are not the service's gate (core accepts the R2 child options and workflow-id targets the service refuses without the parity flag, and refuses CONTINUE_AS_NEW, which it accepts);
  • load_history(path) / parse_history_file(text), which raise HistoryFileError for a file that does not match the schema;
  • is_activity_node_type_allowed (the activity allow-list) and code_workflow_parent_close_policy (DB13).
from fluidgrids_workflows.history import load_history

history = load_history("fixtures/histories/signal-wait.history.json")
print([event["type"] for event in history["events"]])

Python does not replay histories in Phase B; the replay runner is the TypeScript SDK's.

Conformance with the TypeScript SDK

fixtures/ is vendored from fluidgrids-workflows-sdk-node by scripts/sync_fixtures.py, together with reference outputs the published @fluidgrids/workflows computes (<fixture>/lowered.ts.json and fixtures/ts-vectors.json). The test suite:

  • lowers every fixture's workflows/<key_snake>.py and requires the canonical JSON to equal the TypeScript lowering of workflows/<key>.ts (apart from the provenance block) and the irHash to equal fixture.json;
  • checks normalisation, hashing, the executor view, validation codes, canonical JSON, SHA-256, durations, schedules, reference parsing, diffs and layouts against the TypeScript outputs;
  • lowers the Python-owned fixtures in conformance/ (features that are only sugar in a builder, such as wf.code_workflow, whose TypeScript twins the lifted fixtures cannot express) and compares them with the TypeScript lowering of their twin in the same directory;
  • loads and validates every history in fixtures/histories/ and compares the history contract with @fluidgrids/workflows/history;
  • checks fixtures/CHECKSUMS.sha256, so a hand edit to a vendored file (fixtures and the five schemas) fails.

scripts/ts-reference/ pins the @fluidgrids/workflows release the references come from. To pick up new fixtures, bump that pin (package.json and npm install --package-lock-only), then:

make ts-reference
make sync-fixtures NODE_SDK=../fluidgrids-workflows-sdk-node

CI recomputes the TypeScript reference outputs from the pinned package (make verify-references) and fails when they differ from the committed ones.

Development

uv sync --locked
make lint          # ruff check + ruff format --check
make typecheck     # mypy --strict
make test          # pytest with the 85% coverage gate
make sanity        # all of the above, plus a build of the sdist and wheel

Releases are CalVer (YYYY.MDD.PATCH) through .github/workflows/release.yml (the shared G60 workflow): push a CalVer tag or run the workflow from the Actions tab. The upload uses PyPI trusted publishing when the repository variable PYPI_TRUSTED_PUBLISHING is true, otherwise the PYPI_BURDENOFF_TOKEN secret; with neither, the publish job fails and names the missing secret.

License

Proprietary. Copyright (c) Algoshred Technologies Private Limited. See LICENSE.

Metadata

Release files for fluidgrids-workflows 2026.1030.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fluidgrids-workflows 2026.1030.2
File Size Uploaded Provenance Actions
fluidgrids_workflows-2026.1030.2.tar.gz 138.8 kB Without provenance Details for fluidgrids_workflows-2026.1030.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fluidgrids-workflows 2026.1030.2
File Interpreter ABI Platform Actions
fluidgrids_workflows-2026.1030.2-py3-none-any.whl Python 3 none any Details for fluidgrids_workflows-2026.1030.2-py3-none-any.whl

Total release size: 301.0 kB

Release files / fluidgrids_workflows-2026.1030.2.tar.gz

Download URL fluidgrids_workflows-2026.1030.2.tar.gz
Size 138.8 kB
Tags Source
SHA-256 checksum
How to use checksums
221f14c3a20cc4d3b13ca307d7152ea217d1fb8751a848be523d41424925c8c9
BLAKE2b-256 checksum
How to use checksums
17a6b42b393c32648e573f483ef32b5e3ff9e5d9a93b5583bdd9ce5ce055f012
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Release files / fluidgrids_workflows-2026.1030.2-py3-none-any.whl

Download URL fluidgrids_workflows-2026.1030.2-py3-none-any.whl
Size 162.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b8cee488c535d5b1dde3ba3fc45c2873374ee90e9b500f87353f9b14937ade1e
BLAKE2b-256 checksum
How to use checksums
b040508493132ea6c6caad64f16ecca0a936d41d3a96069465b5d11442e16b78
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for fluidgrids-workflows 2026.1030.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page