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/workflowslowers 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 pythongenerates (.fluidgrids/nodes.py); - from Phase B (BOFF-9905):
wf.code_workflow, which embeds a TypeScript durable function in a graph, andfluidgrids_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.bbecomes{{ $node["enrich"].item.a.b }}andwf.json.xbecomes{{ $json.x }}. Useref["key"]for keys that are not identifiers, are Python keywords, start with_or are reference method names, andref[0]for indices. - Comparisons (
>=,==, …,contains,is_empty,matches, the genericis_(operator, value)) andand_()/or_()become the condition treeinternal:ifevaluates.and,or,notandinraise, 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;
Falseforoperation,versionand edgeid/typewrites no such field;Noneis JSONnull. edge(source, id=..., type=..., target_handle=..., label=..., data=..., mapping=..., extra=...),wf.connect,wf.edge_order_isand theextraoption on every node keep any stored definition expressible exactly.- An edge without an explicit
idgetse-<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 raisesUnresolvedConnectionsError.- 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_definitionrewrites the builder's legacy mirrors into the canonical node fields following the executor's reading order; it is pure and idempotent.ir_hashissha256:+ the SHA-256 of the RFC 8785 canonical JSON of the normalised definition withoutauthoring, 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_specand 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.pychecks 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 andLOCAL_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_historyandvalidate_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(whatfluidgrids.durable-parityadds),is_relief_commandandCommandRelief. Pass a feature set asvalidate_commands(..., enabled=PHASE_B_CORE_FEATURES)for the service's Phase B verdict. The default levels"core"and"parity"(andis_command_enabled) are deprecated: they keep their R1 meaning, decide by command type only and are not the service's gate (coreaccepts the R2 child options and workflow-id targets the service refuses without the parity flag, and refusesCONTINUE_AS_NEW, which it accepts); load_history(path)/parse_history_file(text), which raiseHistoryFileErrorfor a file that does not match the schema;is_activity_node_type_allowed(the activity allow-list) andcode_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>.pyand requires the canonical JSON to equal the TypeScript lowering ofworkflows/<key>.ts(apart from the provenance block) and theirHashto equalfixture.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 aswf.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.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| fluidgrids_workflows-2026.1030.1.tar.gz | 117.5 kB | Without provenance | Details for fluidgrids_workflows-2026.1030.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| fluidgrids_workflows-2026.1030.1-py3-none-any.whl | Python 3 | none | any | Details for fluidgrids_workflows-2026.1030.1-py3-none-any.whl |
Total release size: 255.2 kB
Release files / fluidgrids_workflows-2026.1030.1.tar.gz
| Download URL | fluidgrids_workflows-2026.1030.1.tar.gz |
|---|---|
| Size | 117.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
54979a42b998c7a960725d5a212aae9eed00d80402224a6061fca7605e0ab8c8
|
|
BLAKE2b-256 checksum How to use checksums |
0325ac61ba06d6e023dd4b0fe39a1f532c56a9cf7e25cc49eaa9797a2259011b
|
| 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.1-py3-none-any.whl
| Download URL | fluidgrids_workflows-2026.1030.1-py3-none-any.whl |
|---|---|
| Size | 137.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6bd1b95fb863d9432a533bda70785ebca755c746c17e87fb4eacb28f43dae6f1
|
|
BLAKE2b-256 checksum How to use checksums |
4154e481df6b1d74679ab676feabc82c8606a04c8546a7d0e32164b56e7ab941
|
| 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.1
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.