Graph format and pipeline_hash

A graph is a JSON object made of nodes (blocks) connected by links between ports. The blocks actually available are those of GET /pipelines/capabilities.

Example

Layout blocks detect the regions; the condition sends tables to model_max and everything else to model_fast.

json
{
  "schema_version": 1,
  "kind": "ocr",
  "nodes": [
    { "id": "in",  "type": "input" },
    { "id": "n1",  "type": "layout" },
    { "id": "n2",  "type": "condition", "params": { "test": "table" } },
    { "id": "n3",  "type": "model_max" },
    { "id": "n4",  "type": "model_fast" },
    { "id": "out", "type": "output" }
  ],
  "links": [
    { "from": "in", "port": "out", "to": "n1" },
    { "from": "n1", "port": "out", "to": "n2" },
    { "from": "n2", "port": "yes", "to": "n3" },
    { "from": "n2", "port": "no",  "to": "n4" },
    { "from": "n3", "port": "out", "to": "out" },
    { "from": "n4", "port": "out", "to": "out" }
  ]
}

Rules

  • A single input node and a single output node.
  • ids are unique; at most one link per (from, port) pair.
  • All ports of a condition or confidence block must be connected.
  • No cycles.
  • A single block of the layout family per path, placed before the models.
  • condition requires a layout block upstream.
  • The handwritten and printed tests require a handwritten_detect block upstream on every path (otherwise invalid_param on the condition).
  • model_max is rejected downstream of a layout_word, on at least one path, including through a condition (422 forbidden_block_sequence).
  • Visual fields (x, y, label, caption) are ignored.

OCR blocks

typePortsparamsModel
layoutoutword_boxes, line_boxes (all), line_boxes_method 9 / 10 (same as word_boxes_method), line_paramsAlphaLayout (PP-DocLayoutV3)
layout_wordouthandwritten_threshold 0–1 (default 0.5)AlphaLayout-Word
layout_lineoutlimit_side_len 32–8000 (default 1280)AlphaLayout-Line
handwritten_detectout—alpha-writing-detect
model_maxoutextraction, extraction_prompt (not executed for now)alpha-digit-max
model_fastout—alpha-digit-fast
model_handwrittenout—alpha-digit-handwritten
conditionyes, notest among the capabilities' condition_testsnone (logic)
confidencehigh, lowthreshold 0–100, in steps of 5 (default 80)none (logic)

After layout_word or layout_line, the table, image, text, header, footer and aside tests always answer "no".

layout_word creates one region per word: placed before an OCR model, it triggers one invocation per word (slow on dense documents).

Layout blocks no longer classify writing (writing_type is unknown): handwritten_detect goes after a layout and classifies each region as handwritten or printed; before the OCR model, it gives it the handwriting hint.

line_boxes adds its lines to each region (regions[].lines: text, start, end, bbox_xyxy, polygon, writing_type) and returns lines without text in unmatched_line_boxes.

Audio blocks

typePortsparams
diarizationoutmin_speakers, max_speakers (1–32)
transcriptionoutmodel_slug (default alpha-audio-v1) — this block is required in the graph
confidencehigh, lowthreshold (default 85)
postcorrectout— (available only if listed in the capabilities)

pipeline_hash

The hash is the sha256 (lowercase hexadecimal) of the canonical form of the graph: sorted keys, no spaces, UTF-8, nodes sorted by id, links sorted by (from, port), params only when non-empty. Only schema_version, kind, nodes[id, type, params] and links[from, port, to] count.

When sent with the graph, it is checked: any difference returns 422 hash_mismatch. It also appears in responses and in run.started.

python
import hashlib, json

def pipeline_hash(graph: dict) -> str:
    canonical = {
        "schema_version": graph["schema_version"],
        "kind": graph["kind"],
        "nodes": sorted(
            ({"id": n["id"], "type": n["type"], **({"params": n["params"]} if n.get("params") else {})}
             for n in graph["nodes"]),
            key=lambda n: n["id"],
        ),
        "links": sorted(
            ({"from": l["from"], "port": l["port"], "to": l["to"]} for l in graph["links"]),
            key=lambda l: (l["from"], l["port"]),
        ),
    }
    raw = json.dumps(canonical, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
text
{"kind":"ocr","links":[{"from":"in","port":"out","to":"n1"},{"from":"n1","port":"out","to":"n2"},{"from":"n2","port":"yes","to":"n3"},{"from":"n3","port":"out","to":"out"}],"nodes":[{"id":"in","type":"input"},{"id":"n1","type":"layout"},{"id":"n2","params":{"test":"table"},"type":"condition"},{"id":"n3","type":"model_max"},{"id":"out","type":"output"}],"schema_version":1}
sha256 → 96c6be3b3fd6e5b48ae6100dbc1e53aacba50ca9400252d02d39864b539e489e

Test vector: graph in → layout → condition(table) → model_max → out, ids in, n1, n2, n3, out. This graph gives the canonical form above.

Validation error codes

Possible codes in error.errors[]:

CodeMeaning
unsupported_schema_versionschema_version not supported
unknown_block_typeUnknown block type
unknown_param, invalid_paramUnknown or invalid parameter
missing_input, missing_outputinput or output node missing
duplicate_node_id, duplicate_linkDuplicate identifier or link
unknown_port, dangling_portUnknown port, or port with no continuation
unreachable_nodeUnreachable node (warning)
graph_cycleThe graph contains a cycle
no_model_on_pathNo model on a path
condition_without_layoutcondition without layout upstream
confidence_without_modelconfidence without model upstream
transcription_requiredAudio graph without a transcription block
invalid_block_orderInvalid block order
hash_mismatchpipeline_hash differs from the graph
limit_exceededLimit exceeded (nodes, links, size)