Noukai Docs

Create a New Flow with Blocks

1. hydrate_project(project_id)
   → See current state

2. create_flow(project_id, name="My Pipeline", slug="my-pipeline")
   → flow_id

3. add_block(flow_id, name="Step 1", processor_type="llm", prompt="...")
   → step-1

4. add_block(flow_id, name="Step 2", processor_type="llm", target_id="step-1", direction="right", prompt="...")
   → step-2

5. publish_version(flow_id, note="v1: initial")
   → version_id

6. set_production_version(flow_id, version_id)
   → Live at /seq/{org}/{project}/my-pipeline/execute

Update a Prompt and Republish

1. get_flow(flow_id)
   → See current blocks and their content versions

2. update_block_draft(flow_id, step_id, content="Improved prompt...")
   → Updated (content_version incremented)

3. create_block_checkpoint(flow_id, step_id, note="before v2 publish")
   → Snapshot saved

4. publish_version(flow_id, note="v2: improved prompt")
   → version_id

5. set_production_version(flow_id, version_id)
   → Live

Add a Loop Over Items

1. get_flow_structure(flow_id)
   → See tree topology

2. add_block(flow_id, name="Process Item", processor_type="llm", prompt="Process: {item}")
   → step-3

3. wrap_in_loop(flow_id, node_ids=["step-3"], array_field="items")
   → Loop created

4. publish_version(flow_id, note="v3: added item loop")
   → version_id

Add Structured Output with Object Models

1. create_object_model(project_id, name="SentimentResult", fields=[
     {"name": "sentiment", "type": "string", "description": "positive, negative, or neutral"},
     {"name": "confidence", "type": "number", "description": "0-1 confidence score"}
   ])
   → object_model_id

2. update_block_output_schema(flow_id, step_id, content={
     "type": "object",
     "properties": {
       "sentiment": {"type": "string"},
       "confidence": {"type": "number"}
     },
     "required": ["sentiment", "confidence"]
   })
   → Schema set

3. publish_version(flow_id, note="v4: structured output")
   → version_id

Reorganize Flow Structure

1. get_flow_structure(flow_id)
   → See current tree

2. wrap_in_container(flow_id, node_ids=["step-1", "step-2"], container_type="h")
   → container_id (sequential group)

3. move_block(flow_id, step_id="step-3", new_parent_id=container_id, new_position=2)
   → Block moved into container

4. reorder_children(flow_id, parent_id=container_id, child_order=["step-2", "step-1", "step-3"])
   → Reordered

Test a Flow

1. create_test_case(project_id, flow_id, scope="flow", name="Happy path",
     input_data={"message": "I love your product!", "parameters": {}})
   → test_case_id

2. run_test_case(test_case_id)
   → { runId, status: "completed", durationMs, steps: [...] }

3. run_all_tests(flow_id)
   → { total: 1, passed: 1, failed: 0, results: [...] }

Debug a Failed Test

1. run_test_case(test_case_id)
   → { runId, status: "failed", errorAtStep: "step-2", error: "..." }

2. get_test_run_trace(flow_run_id=runId)
   → Full trace: per-step input/output snapshots, token counts, errors

3. get_step_trace(flow_run_id=runId, step_id="step-2")
   → Detailed trace for the failed step (input context, output, error context)

4. Fix the block prompt/config based on trace data

5. run_test_case(test_case_id)
   → Re-run to verify the fix

Attach an Eval to a Flow

An eval is authored once in the project library, then attached wherever it should run. The two steps use different endpoints — definitions are project-scoped, bindings are flow-scoped.

1. create_eval(project_id, judge_prompt="Is the tone polite?",
               judge_model="anthropic/claude-sonnet-5",
               pass_criteria={"type": "boolean", "threshold": 0.7,
                              "optimizationDirection": "maximize"})
   → { evalId }        # definition only — not attached to anything yet

2. attach_eval(flow_id, eval_id=evalId, scope="pipeline", mode="observe")
   → { bindingId }     # now it runs with the flow

3. run_test_case(test_case_id)
   → { status, evalSummary: { passed, failed, warnings, skipped, outcome } }

judge_prompt and judge_model are required for every judge_type, including code. Use scope="block" with step_id to judge one step, or scope="test-case" with test_case_id — that is the only scope that accepts expected.

Retune an Eval

Both update tools require a content_version, and the two tokens are independent — a definition's version is not its binding's version. Read the current values from list_evals.

The server currently checks only that content_version is present, not that it matches. A stale value is accepted and the write goes through, so this does not yet protect you from a concurrent editor overwriting your change. Checkpoint first (step 2 below) if that matters.

1. list_evals(project_id)
   → { eval_library: [{ id, content_version: 3, ... }],
       eval_bindings: [{ id, content_version: 1, ... }], eval_checkpoints: [...] }

2. create_eval_checkpoint(project_id, eval_id, note="before rubric v2")
   → { checkpointId }        # freeze the current judge body first

3. update_eval(project_id, eval_id, content_version=3,
               judge_prompt="Stricter rubric...")
   → Updated                 # uses the LIBRARY token

4. update_eval_binding(flow_id, binding_id, content_version=1, mode="gate",
                       gate_params={"on_skip": "pass"})
   → Updated                 # uses the BINDING token — a different number

Switching a binding to mode="gate" makes a failing eval abort the run with EVAL_GATE_FAILED instead of merely recording the verdict.

Key Patterns

Always start with hydrate_project — understand state before making changes
Use sibling-relative mode for add_block when possible (target_id + direction)
Publish after changes — unpublished changes don't affect the API
Set production version to make a published version live
Checkpoint before major prompt changes — create_block_checkpoint for prompts, create_eval_checkpoint for judge bodies
Use run_all_tests after prompt changes — verify no regressions across all test cases
Use get_test_run_trace to debug failures — see exact inputs/outputs per block

Common Workflows