Lesson 04: What Is MeshFlow?

Lesson Goal

This lesson introduces MeshFlow as an artifact-driven orchestration style for AI workflows. You do not need to know the real library yet. First learn the mental model:

define a workflow
  -> validate the graph
  -> run nodes in dependency order
  -> pass named artifacts forward
  -> stop at gates when needed
  -> inspect the trace

MeshFlow is useful because real AI systems need more than prompts. They need structure.

1. Why Plain Prompt Chains Break

A prompt chain is a sequence of model calls:

prompt 1 -> prompt 2 -> prompt 3

This works for simple demos, but it becomes fragile when:

• Step 2 expects data that Step 1 did not produce.
• A model skips an instruction.
• A tool fails silently.
• A later step uses stale context.
• A risky action happens without approval.
• No one can explain what happened after a bad result.
• The process is hidden inside a giant prompt.

MeshFlow-style orchestration moves important control out of the prompt and into an explicit workflow.

2. The Core Idea

In MeshFlow, the workflow is the source of truth.

node A produces artifact X
node B consumes artifact X and produces artifact Y
gate C checks Y
node D runs only if the gate passes

The model still matters, but the workflow controls the process.

3. Core Vocabulary

4. Node Types

The mini runner in this tutorial uses simple node types:

Real MeshFlow systems can be richer, but these types are enough to learn the architecture.

5. Artifacts Make Work Visible

Without artifacts:

"Do research, write an answer, check it, and publish it."

Everything is hidden in one instruction.

With artifacts:

research_questions
source_notes
draft_answer
quality_check
approval_record
final_answer

Now each important output can be inspected, tested, and reused.

6. Gates Make Risk Visible

A gate is a controlled pause. It says:

Do not continue until this condition is satisfied.

Examples:

• Human approval is required before publishing.
• Quality score must be at least 0.8.
• Budget must be under the configured limit.
• Required citations must exist.
• Policy review must pass.

Gates are how a workflow expresses judgment, risk, and accountability.

7. Traces Make Execution Visible

A trace answers:

• Which nodes ran?
• In what order?
• What did each node consume?
• What did each node produce?
• Which tools were called?
• Which gate blocked?
• What error happened?

Beginner rule: if you cannot trace it, you cannot reliably debug it.

8. Compile Before Run

Compilation means checking the workflow before doing expensive or risky work.

Good compile checks include:

• Every dependency exists.
• Required artifacts are produced before they are consumed.
• The graph has no cycles.
• Tool names are valid.
• Gate configuration is valid.
• Node IDs are unique.

This course's mini runner has a small compile command:

python3 -m src.mini_meshflow compile examples/02_tools_and_memory.json

9. Draw The Graph

Diagrams help you catch design mistakes.

Run:

python3 -m src.mini_meshflow diagram examples/02_tools_and_memory.json

Read the graph from left to right:

what starts first -> what depends on it -> what produces final output

If you cannot explain the graph in plain English, simplify it.

10. MeshFlow Design Pattern

Use this pattern for almost every AI workflow:

1. Capture the user's goal.
2. Gather or retrieve context.
3. Produce a draft artifact.
4. Check the draft.
5. Branch, retry, or revise if needed.
6. Gate risky actions.
7. Produce final output.
8. Store useful memory.
9. Inspect the trace.

11. Hands-On

Compile a workflow:

python3 -m src.mini_meshflow compile examples/02_tools_and_memory.json

Draw the workflow:

python3 -m src.mini_meshflow diagram examples/02_tools_and_memory.json

Run an agent workflow:

python3 -m src.mini_meshflow run examples/03_agent_with_gate.json

When it stops at the gate, do not treat that as a failure. The pause is the workflow doing its job.

12. Common Beginner Mistakes

Mistake 1: Starting with code before naming artifacts.

Correction: First decide what each step must produce.

Mistake 2: Letting prompts control everything.

Correction: Put process control in the graph.

Mistake 3: Treating gates as optional decoration.

Correction: Gates are required anywhere risk, cost, or human judgment matters.

Mistake 4: Ignoring trace output.

Correction: Read traces after every run until you can predict them.

13. Summary

MeshFlow-style orchestration is about making AI work explicit. Nodes do work, dependencies define order, artifacts carry state, gates control risk, and traces explain what happened. This makes agentic systems easier to learn, debug, and trust.

Exercises

Exercise 1: Compile A Workflow

python3 -m src.mini_meshflow compile examples/02_tools_and_memory.json

Record the node count and artifact list.

Exercise 2: Generate A Diagram

python3 -m src.mini_meshflow diagram examples/02_tools_and_memory.json

Explain which node runs first and why.

Exercise 3: Inspect The Graph

Open ../../examples/02_tools_and_memory.json and find every depends_on field.