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).
From Phase C (BOFF-9906): Python durable (tier-2) workflow functions
(fluidgrids_workflows.durable), the deterministic runtime that runs them,
TestWorkflowEnvironment, deterministic bundles (build_project), the
managed Python VM (fluidgrids_workflows.managed) and client profiles.
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.
Optional extras, each pinned: durable (Pydantic models as schemas),
build (ruff diagnostics in builds), managed (uvicorn for the managed VM),
worker, metrics, tuner, protobuf and keychain (keyring, for
keychain: token references).
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 needs self-hosted workers
durable_phase_issues(definition, self_hosted=False) (in
fluidgrids_workflows.ir) lists, with code durable.phaseC, what a definition
needs that a workspace without self-hosted workers cannot run:
code.exports.activities (user activities), task queues other than managed,
the userActivity feature, and any code.features value the SDK does not
know, so the check fails closed. Python bundles (determinism: "worker") and
the handler features (updates, queries, searchAttributes, dynamic,
interceptors) pass; the service still gates each of them by its workspace
flag. lower_project returns the issues as LowerResult.issues,
fluidgrids-workflows lower prints them under issues, and
validate(..., refuse_phase_c=True) (validate --refuse-phase-c [--self-hosted]) makes them errors. Without that option validate gives the
TypeScript SDK's verdict.
Tier 2: durable functions in Python
from fluidgrids_workflows import triggers
from fluidgrids_workflows.durable import define_signal, workflow
from fluidgrids_workflows.project import nodes as n
approve = define_signal("approve")
@workflow("process-order", trigger={"operation": triggers.webhook, "args": {"path": "orders"}})
async def processOrder(ctx, order):
charge = await ctx.run(n.stripe.create_charge, args={"amount": order["amount"]})
await ctx.signal_received(approve)
await ctx.sleep("1h")
return {"charge": charge["id"]}
Workflow code awaits only what the context returns (ctx.run, ctx.activity,
ctx.sleep, ctx.condition, ctx.child, ctx.gather, ctx.race, ...); the
runtime gives those awaitables JavaScript promise semantics, so a Python
function issues exactly the commands its TypeScript twin issues and both
record the same history. Modules run under an import guard that refuses the
clock, randomness, the file system, the network and processes; use
ctx.now(), ctx.random(), ctx.uuid() and activities instead.
TestWorkflowEnvironment (in fluidgrids_workflows.testing.environment) runs
workflows in process with time skipping, activity mocks, user activities,
signals, queries, updates, cancellation and resets. replay_history checks a
history file against the current code.
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 build [PROJECT] [--out bundle.pyz] [--entry ...] [--no-diagnostics]
fluidgrids-workflows replay HISTORY [--project DIR] [--entry ...]
fluidgrids-workflows test [PROJECT] [PYTEST_ARGS...]
fluidgrids-workflows validate FILE [--strict] [--allow-empty] [--refuse-phase-c] [--self-hosted]
fluidgrids-workflows hash FILE
fluidgrids-workflows normalize FILE
build gives the fluidgrids.python-build-result the managed build VM gives
for the same sources: the deterministic bundle (bundleBytes, base64), its
buildId (sha256: of the bundle), the lowered definitions, issues and
ruff diagnostics.
Self-hosted workers
fluidgrids_workflows.worker.Worker runs workflow tasks of Python bundles and
user activities on your own machines (spec 02 §7b, 11 §2.29-2.31). It is the
twin of @fluidgrids/workflows/worker and speaks the same bridge protocol
(v2), so Python and TypeScript workers can serve one task queue. It needs the
worker extra (pip install 'fluidgrids-workflows[worker]').
import asyncio
from fluidgrids_workflows.durable import define_activity
from fluidgrids_workflows.worker import Worker
@define_activity("billing.charge", task_queue="payments")
async def charge(ctx, args):
await ctx.heartbeat({"step": "charging"})
return {"chargeId": "ch_1"}
async def main() -> None:
worker = Worker(
"payments",
workflow_bundles=[".fluidgrids/build/bundle.pyz"],
activities=[charge],
max_concurrent_activities=16,
)
await worker.run() # SIGTERM or SIGINT drains and stops it
asyncio.run(main())
- The worker connects outbound to
FLUIDGRIDS_BRIDGE_URL(defaultwss://graphqlworkspaces.burdenoff.com/runner-bridge;ws://only to localhost) with the worker token inFLUIDGRIDS_WORKER_TOKEN(fgr_..., kind WORKER). The service accepts it only whilefluidgrids.self-hosted-workersis on for the workspace and a worker seat is free; a refusal for good (close codes 4001-4004 and 4010-4012, or an HTTP 401/403 upgrade) makesrun()raiseBridgeClosedError, anything else reconnects with capped, jittered backoff. - A queue is
orders(every environment of the queue) ororders@staging(only the staging-scoped queue;@dev,@stagingor@prod). Theenvironmentkeyword, orFLUIDGRIDS_WORKER_ENVIRONMENT, binds every plain name, so a staging worker never takes production tasks of the same queue name. A worker token bound toorders@stagingenforces the same on the service side, whatever the worker announces. - Workflow tasks replay the run's history in this SDK's runtime, from the
same bundle bytes (and
buildId) thatfluidgrids pushstored. By default each task runs in a process forked from aPYTHONHASHSEED=0forkserver with a SIGKILL deadline (runner="fork");runner="thread"runs them in this process, importing the bundle's workflow modules afresh for every task so module-level state never carries over (vendored third-party packages are imported once per process). Activity values with NaN or an infinity travel as null, asJSON.stringifywrites them. A sticky cache keeps each run's history so the service sends only the tail. Queries, updates, sinks and workflow interceptors (only when the lease enables theinterceptorsfeature) work as on the managed runtime; a task that asks for a local activity failsUNSUPPORTED_COMMAND. - Activities get
ctx.heartbeat()(throttled; the acknowledgement carries cancellation and pause),ctx.cancelled,ctx.complete_async(),ctx.connection(name)(only connections the activity declares and the token allows),ctx.logandctx.metrics. Plain functions run on a thread pool and can callctx.heartbeat_nowait(). The engine owns retries and timeouts: an attempt past its deadline, or of a lost session, is stopped and not reported. - Options:
max_concurrent_workflow_tasks(4),max_concurrent_activities(100),max_activities_per_second,max_cached_runs(1000),pollers, aresource_based()tuner (thetunerextra) instead of fixed limits,shutdown_grace_time(30 s), activity interceptors, sinks, a payloadcodecandpayload_converter(protobuf_payload_converterwith theprotobufextra), and metrics served as Prometheus text on127.0.0.1(metrics={"prometheus": {"port": 9464}}), pushed as OTLP/HTTP JSON, or added to aprometheus_clientregistry withprometheus_collector.
The managed Python VM
fluidgrids_workflows.managed.server:app is the ASGI app of the managed
runtime's MicroVM (no egress, no public ingress). Every call carries
x-fluidgrids-worker-secret; failed attempts are rate limited. PUT /bundles/{buildId} stores a bundle, POST /task runs a workflow task (the VM
keeps each run's history and answers 409 {"need": "bundle"} or
409 {"need": "history"} when it lacks one) and POST /build builds a
project. Each task runs in a process forked from a forkserver started with
PYTHONHASHSEED=0, under RLIMIT_AS (PY_TASK_MEMORY_BYTES) and a SIGKILL
deadline (PY_TASK_DEADLINE_SECONDS).
Profiles
fluidgrids_workflows.profiles reads ~/.fluidgrids/config.toml
(FLUIDGRIDS_CONFIG overrides the path): [profiles.<name>] tables and
defaultProfile, chosen with FLUIDGRIDS_PROFILE, with FLUIDGRIDS_<KEY>
overrides. Tokens never live in the file: tokenRef is env:VAR or
keychain:<service>/<account>, and FLUIDGRIDS_TOKEN always wins.
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; - re-records every history with the Python twin of its TypeScript source
(
conformance/histories/), requires the history to equal the TypeScript recording event for event, replays it to the TypeScript result and replays every recorded task; - 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.1114.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.1114.1.tar.gz | 311.2 kB | Without provenance | Details for fluidgrids_workflows-2026.1114.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| fluidgrids_workflows-2026.1114.1-py3-none-any.whl | Python 3 | none | any | Details for fluidgrids_workflows-2026.1114.1-py3-none-any.whl |
Total release size: 672.5 kB
Release files / fluidgrids_workflows-2026.1114.1.tar.gz
| Download URL | fluidgrids_workflows-2026.1114.1.tar.gz |
|---|---|
| Size | 311.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
54e2aa55b402b2b59d5d17627a5d6b4f32501e285b69fd0da1cddeeddbf556b6
|
|
BLAKE2b-256 checksum How to use checksums |
a5e7ec5fb6421bb2beae6afc91d9e659d64f0b32ea50ff941361221f123c2254
|
| 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.1114.1-py3-none-any.whl
| Download URL | fluidgrids_workflows-2026.1114.1-py3-none-any.whl |
|---|---|
| Size | 361.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
50abe400c12219845cbfc1df4825f743671379d252e96ed7a935527c0602b62c
|
|
BLAKE2b-256 checksum How to use checksums |
86464ac133af1009eaca4152249a56490d16166b261abaf993af816a33f4431f
|
| 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.1114.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.