Learning path

Teff is a small framework with a large surface. The fastest way to "get it" is to follow a path instead of reading the docs alphabetically. Each stage below points at the examples and guides that matter, in the order that makes concepts build on each other.

Every example runs offline on a local Ollama (ollama pull llama3.1:8b) or needs no model at all — no API keys required. After each stage, teff run, teff validate and the tests in the example should "just work".

Stage 0 — Fit and install (10 minutes)

Decide if Teff is for you and get it running.

• Install — uv/pip, extras, first teff new.
• Quick start — your first graph in three minutes.
• Concepts — the mental model: graph → runtime → state.

You should know: what a node, an edge, state and a run are; how a workflow is declared; how to launch it from YAML and from Python.

Stage 1 — Declare workflows (30 minutes)

The core idea: workflow as data. Topology lives in YAML (or the Flow DSL), not in prompts or node bodies.

• basic_pipeline — minimal YAML pipeline.
• branching — conditional edges + Flow API.
• parallel — concurrent branches + typed State.
• map_repair_plans — dynamic fan-out (Map) + {key} prompt templates.
• Guides: YAML workflows, Flow YAML (sugar), Flow builder, State, Structured output.

You should know: how to write workflow.yaml (and when the concise flow.yaml idiom surface is a better fit), when to prefer YAML vs the Flow DSL, how reducers merge branch results, and how Map differs from Parallel.

Stage 2 — Durable runs and humans in the loop (30 minutes)

Teff's differentiator: a run is checkpointable and resumable, and it can pause for approval.

• checkpoint_resume — crash mid-LLM run, resume from the failed node (counters prove no node re-ran).
• checkpoint_stores — file / SQLite / PG.
• human_in_loop — Interrupt + loop() + resume (Python and YAML).
• ask_strategies — validate interrupt answers (Ask: regex, equals, LLM classifier) — offline.
• agent_approval — every tool call pauses for human sign-off.
• Guide: Durable (checkpoints).

You should know: how to add a checkpoint: block, how resume works, the difference between an interrupt and a retry, and when a workflow must be durable.

Stage 3 — Agents and tools (45 minutes)

Composition: agent loops, tool calling, skills, and MCP.

• react_agent — ReAct loop + calculator tool + streaming.
• harness_agent — parallel tool calls in one round + __error__ fallback.
• skills and pdf_agent — SKILL.md folders and vendored tool-bundling skills.
• mcp — call tools from an MCP server (stdio).
• Guides: Agents, Skills, Plugins, Tools.

You should know: Agent vs ReActAgent, how to register custom tools and node types, how skills scope tools, and how to bridge MCP servers.

Stage 4 — Retrieval and memory (30 minutes)

Grounded answers and long-term state.

• rag_search — RAG over a local CSV, in-memory store.
• rag_stores — the same RAG agent on every vector store.
• memory_assistant and memory_chat — long-term memory.
• Guides: RAG, Long-term memory.

You should know: how to pick a vector store, how the RAG tool is wired, and when memory vs RAG is the right answer.

Stage 5 — Production concerns (45 minutes)

Validation, resilience, observability, testing, evaluation.

• streaming and structured_output — live events and schema-validated JSON.
• self_refine, plan_and_execute, deep_research — multi-step agent patterns (mocked, no API key).
• time_travel — rewind / edit / replay a run.
• release_features — validation, typed errors, teff eval, cost reports, response cache.
• Guides: Testing, Evaluation, Observability, Logging, Best practices.

You should know: how to test a graph without the LLM, how to gate a release on teff eval, how to read the trace dashboard, and how to budget tokens.

Stage 6 — Full applications (deploy as a reference)

Real, closed, production-shaped apps to copy.

• repair-ai-chat — FastAPI app: route() supervisor, five agents, tools, RAG, streaming.
• service_desk — FastAPI + RAG + run management.
• fraud_gate — review/publish flow with HITL and durable checkpoints.
• repo-health, github-reviewer, gitlab-reviewer — CI-adjacent automations.
• Scaffolding: teff new (fastapi/cli/daemon variants).

You should know: how a real app is structured (config → container → graph → API → storage), and where each piece of the framework appears.

Instead of re-reading these, see the Recipes — each closes a real business case (fraud review, release approval, support triage, ops daemon) in one consistent pattern.

---

"I have a problem X" — where to look

Not sure which example matches your need? Start here.

I want to…	Read / run
Write my first workflow	quickstart, basic_pipeline
Branch on a condition	branching
Run steps in parallel	parallel
Fan out over a list of inputs	map_repair_plans
Survive crashes / resume a run	checkpoint_resume, durable
Add human approval	human_in_loop, agent_approval
Build an agent that uses tools	react_agent, agents
Run several tool calls at once	harness_agent
Give an agent a skill / a bundle of tools	skills, pdf_agent
Call tools from an MCP server	mcp
Answer from my own documents	rag_search, rag
Keep long-term user context	memory_assistant, memory
Stream tokens to the UI	streaming
Force valid JSON output	structured_output
Route between multiple agents	simple_router, supervisors
Test without the LLM	testing, simple_router
Evaluate / gate a release	release_features, evaluation
Debug a run after the fact	observability, time_travel
Ship a FastAPI app	repair-ai-chat, teff new fastapi

Before you add a new example, re-check this list — the pattern you need is probably already documented.