Flow documents¶

A flow is a linear sequence of typed command steps. Its document uses apiVersion: ribbit/v1 and kind: Flow.

Field	Contract
`name`	Flow name
`input`	Optional input JSON Schema
`inference`	Optional default inference settings
`steps`	Between 1 and 100 ordered steps
`output`	Optional output binding; otherwise the last step's result

Each step has a unique id, a command, optional args, optional input, and optional inference. IDs begin with a letter and contain letters, digits, underscores, or hyphens. The default step input is the preceding output, or the flow input for the first step.

A complete exact flow:

apiVersion: ribbit/v1
kind: Flow
name: first-name
steps:
  - id: project
    command: select
    args:
      fields: name
  - id: first
    command: take
    args:
      count: 1

References¶

A reference is an object containing only a string $ref:

input: {$ref: input}

input: {$ref: steps.first.output.title}

Numeric array indices use [0]. Property keys use letters, digits, underscores, and hyphens with a letter or underscore first. Forward references, prototype-related keys, executable expressions, and string interpolation are rejected. References retain JSON types. Schema information that is unavailable during planning is validated at runtime.

CLI forms¶

ribbit flow validate FILE.yaml
ribbit flow plan FILE.yaml
ribbit flow run FILE.yaml --file INPUT --input jsonl

Inline flows use a standalone :: argv token between commands:

ribbit flow run --input jsonl --output jsonl -- select name :: take 1

The example reads stdin. A literal standalone :: is reserved even if shell-quoted; a longer instruction containing those characters remains an ordinary argument.

Planning and validation inspect declarations without importing extension code or contacting models. Steps share budgets. Single-use whole outputs stream where possible; reused outputs and nested references buffer within those limits. Flow output accounting is cumulative.

Route precedence is documented in configuration. For running supplied examples, see mixed-model routing.