gridaco/fx/grida-fx

Grida FX

Use FX to describe work as a dependency graph with declared inputs and outputs. The engine owns planning, scheduling, identities, caches, paid-call admission, retries, and run records. AI generation is one application; ordinary local code also runs as workflow steps.

Work in the user's project using installed packages. A repository clone, Rust, Bun, Docker, and a frontend build are not prerequisites. Preserve existing project structure and package-manager choices.

The full reference is <https://grida.co/fx/llms.txt>: the workflow file, every node type, route and command, complete recipes, and what to do about each error. This skill says how to work; llms.txt says what exists, and wins where the two disagree. It names the FX version it describes: compare it with grida fx --version, and trust the installed --help for anything newer.

Establish the installed interface

Prefer the user's existing installation. Check its version and command help before relying on a feature:

grida fx --version
grida fx --help

grida fx and grida-fx are the same FX

FX can be started three ways. All three are the same FX: the same verbs and options, the same project files, cache and run records.

• grida fx <verb>: FX inside the Grida CLI (npm install -g grida). This is the

usual way; updating grida updates FX.

• grida-fx <verb>: FX on its own, installed with the @grida/fx package (the

JavaScript SDK). Found where a project depends on @grida/fx, or on a server or CI image that needs only FX.

• python -m grida.fx <verb>: FX from the Python package (grida on PyPI).

Use whichever the project already has. Help, errors and hints name the command you ran; follow them as written. Two installations can hold different FX versions: --version prints the FX version for any of them (grida-fx 0.2.0), including under grida fx.

Choose the installation appropriate to the project:

# Node 24+: the grida command, which carries FX as `grida fx`.
npm install -g grida
grida fx --version
 
# Or run it without a global installation.
npx --yes grida fx --version
 
# JavaScript/TypeScript SDK in a project (Node 18+; TypeScript nodes and builders
# need Node 24+); it also provides `grida-fx`.
npm install @grida/fx
 
# Python 3.11+: install into the project's virtual environment.
python -m pip install 'grida>=0.2.0'
python -m grida.fx --version

These examples target FX 0.2; TypeScript nodes, builders and stand-in files need FX 0.6 or later. The Python version floor matters: the older grida 0.0.1 distribution is not FX. If a compatible release is unavailable for the user's platform, report that rather than silently accepting an older package or switching to a source build. Follow the project's lockfile when it pins FX.

The commands below use grida fx; substitute npx grida fx, npx grida-fx, or python -m grida.fx as the project calls for. The Python package installs no console command. Installing @grida/fx without optional dependencies leaves out FX itself, so do not omit them.

FX supports macOS and Linux with glibc on x64/arm64; confirm a package is available for the particular platform. Native Windows and Alpine/musl are not supported. Windows users can use WSL 2. Python nodes, Python builders, and local built-ins such as image.resize, files.copy, and package need Python with the grida package even when invoked through npm. GRIDA_FX_PYTHON can select that interpreter. TypeScript nodes, builders and stand-in files need Node 24 or later (not Bun or Deno); GRIDA_FX_NODE can select that Node. Install @grida/fx in the project for tsc and to pin the host; without one, grida fx hosts them with its own, but python -m grida.fx needs the project's. Installed viewers carry their own web client.

Set up a project

For a first setup, or when a live run fails for a missing key, read onboarding.md. Connecting an AI provider needs the user: they create the account and key, and you verify with grida fx doctor.

Author and plan

For new workflows or node bodies, read authoring.md. It includes runnable local examples and the supported Python/TypeScript paths.

1. Inspect the existing workflow and project settings. An fx.yaml is optional.

For a new project, grida fx init <folder> when the installed help lists it; to add FX to an existing folder, write fx.yaml (fx: project/v1), since recent releases refuse to init a non-empty folder without one (onboarding.md). Keep generated runs/ and .fx/ data out of source control.

1. Discover the installed interface instead of guessing node fields or routes:

grida fx nodes, grida fx nodes image.generate, and grida fx schema workflows/example.yaml.

1. Connect steps through ${{ steps.NAME.outputs.OUTPUT }}. These references

establish dependencies. Use needs: only for ordering without data flow.

1. Plan with the intended inputs and inspect refusals before execution:

grida fx plan workflows/example.yaml --inputs inputs/example.yaml --json
grida fx plan workflows/example.yaml --inputs inputs/example.yaml --check

Planning admits no FX paid calls, but it may import Python or TypeScript modules, invoke a builder, run declared local at: plan nodes, and cache results. Review unfamiliar author code before loading it. Planning is not a sandbox or a promise of no writes. Declared built-ins may be marked planned and lack an executable body or route; do not present every listed type as runnable.

Run within the user's intent

For local workflows, run without --live. This executes real local steps; it is not a dry run. Existing paid results can replay from cache, while an uncached paid call fails without live admission. For a workflow with paid steps, a supplied stand-in can answer those calls offline:

grida fx run workflows/example.yaml --inputs inputs/example.yaml --run runs/example
grida fx run workflows/example.yaml --inputs inputs/example.yaml --stand-in tests/stand_in.py#answer

A stand-in file is Python (file.py#function) or TypeScript (file.ts#function); SDK callers pass a function instead (stand_in= in Python, standIn in JavaScript). Stand-ins must implement FX's answer contract; they use a separate cache and cannot combine with --live or --yes-up-to. See the stand-in guide when authoring one.

A paid run requires the user's intent to make those calls and an agreed dollar cap. Existing authorization remains valid within its scope. Inspect the plan's routes and estimate, then pass the cap explicitly as --live --max-usd N, where N is that agreed cap. A budget in a file or an estimate is not user authorization. A run whose image steps use imagegen@codex needs no --max-usd, but it spends the user's own Codex plan: get the user's go for it as for any live run, and do not switch a step to Codex, or away from it, without asking. Use grida fx doctor workflows/example.yaml to diagnose prerequisites: its first uses lines say whether each route the workflow's paid steps use is servable, and it exits 1 when one is not. Let FX load credentials. Do not read or print .env or secret values, or embed them in workflow files. Never add provider retries outside FX or bypass the ceiling with direct provider calls.

Routes are model@provider choices for capabilities. Use the installed node catalog and current provider documentation when choosing them. Prefer the Grida Gateway routes (@gg) when setting up a project: one key, GG_API_KEY, serves text, images, video and 3D, so a user needs no account per provider. Sound, speech and music have no GG route; they need the provider's own key. onboarding.md covers what to ask the user for each provider, including GG's key setup and its API reference. Keep a route the user chose on another provider, and do not switch an existing project's routes without asking: a new route is a new cache key. Project route_tables: overlays the built-in table; explicit --routes files replace the built-in table. Do not invent prices to make a refused plan pass.

A model or provider FX does not list

FX 0.7 and later run models and providers its built-in table lacks; check grida fx --version first.

• A model FX does not list, on GG, OpenRouter or fal, needs only a route of

the project's own table (route_tables:): the model id as the provider names it, and price: { cap_usd: N } when its price is unknown. Each call holds the cap against the ceiling and is charged what the provider reports, else the cap: agree N with the user as you agree a ceiling. extends: copies another route of the same capability and provider and restates only what differs; the model's own parameters go in provider_options, keyed by provider. No adapter is needed.

• A provider FX does not ship is a community provider: declare it under

providers: in fx.yaml with the variable its key comes from, its base URL and its download hosts. A server that speaks the OpenAI Chat Completions API needs only family: openai-compatible (structured output and agent turns); any other provider needs adapter: <path>#<name>, an adapter written with adapter(...) from grida.fx or @grida/fx. Read the Community providers guide before writing one.

• Ask the user for the provider's key variable and address; they set the key, and

you never write it in fx.yaml, a route table, provider_options or an adapter. Check with grida fx plan, grida fx doctor (its provider, adapter and route lines), and GRIDA_FX_NETWORK=off grida fx run TARGET --live --max-usd N, which runs the adapter and refuses every request FX sends before it leaves, before any paid run.

• Never reach a provider from a node body to get around this: a direct call

escapes FX's pricing, ceiling, retries and cache. An adapter's version is part of its routes' identity: run grida fx lock after creating or bumping a versioned one, and commit fx.lock.

Inspect, resume, and deliver

grida fx inspect runs/example --verify --json
grida fx project runs/example

Check exit status and recorded failures. SDK calls can return a failed run without throwing: check result.ok and result.incomplete, then failures/stopped state. FX 0.2 and later support run TARGET --name NAME (create-only) and run TARGET --resume NAME (requires existing run); confirm installed help on older installations. Without a name or folder every command creates a fresh run record, even when cached. Names are scoped to recorded workflow ID/source within a project; do not overwrite or infer a new run from the last resumed time. Resume with the same target, inputs, routes, takes and execution mode, using --resume NAME or the same --run folder; a changed plan is refused. Prior arguments are not restored automatically. Put overlapping workflow inputs after --, for example run greeting --name baseline -- --name Ada, or use an inputs file. Inspect WORKFLOW_ID/NAME for a precise named run, or an actual folder; a workflow ID selects newest-created evidence and refuses ambiguous recorded sources. Preserve records while diagnosing failures. Do not clear caches or forget provider jobs merely to force another attempt.