A hands-on playground for learning LangGraph and LangChain, running on a small local model (Ollama) or on Anthropic.
learn-langgraph/
├── docs/
│ ├── langgraph-intro.html # visual intro: key classes, patterns, diagrams (open in a browser)
│ ├── REFERENCES.md # short curated reading list
│ └── NOTES.md # technical notes: evals, tracing, MCP, n8n, serving, gotchas
├── src/learn_langgraph/ # shared core library used by every demo
│ ├── config.py # settings loaded from .env
│ ├── llm.py # get_chat_model() / get_embeddings() (Ollama or Anthropic)
│ ├── tools.py # toy tools (weather, add, multiply)
│ ├── display.py # stream printing + Mermaid graph export
│ └── tracing.py # optional Langfuse tracing (no-op without keys)
├── demos/ # numbered, basic → advanced
│ ├── 00_check_setup.py
│ ├── 01_chat_model_basics.py LangChain: messages, stream, LCEL
│ ├── 02_tools_and_structured_output.py tool calls by hand, Pydantic output
│ ├── 03_state_graph_basics.py State, reducers, edges, loops (no LLM)
│ ├── 04_llm_router.py workflow: classify → branch
│ ├── 05_tool_agent.py ReAct agent as an explicit graph + memory
│ ├── 06_create_agent.py the same agent, prebuilt
│ ├── 07_human_in_the_loop.py interrupt() / Command(resume=)
│ ├── 08_rag_agent.py embeddings + vector store as a tool
│ ├── 09_map_reduce_send.py parallel fan-out with Send
│ ├── 10_persistence_time_travel.py SQLite checkpoints, replay, fork
│ ├── 11_multi_agent_supervisor.py supervisor delegating to sub-agents (Command)
│ ├── 12_subgraphs_and_streaming.py subgraph as a node; updates/custom/messages stream modes
│ ├── 13_agent_evals.py eval dataset: trajectory + answer checks, LLM-as-judge, pass-rate gate
│ ├── 14_mcp_tools.py agent using tools from an MCP server (langchain-mcp-adapters)
│ ├── 15_n8n_mcp_tools.py agent using an n8n workflow as MCP tools (needs the deploy stack)
│ ├── 16_api_client.py HTTP client for the deployed agent: threads, SSE streaming (needs the deploy stack)
│ ├── mcp_server.py tiny FastMCP stdio server used by demo 14
│ └── output/ generated .mmd diagrams, sqlite db (git-ignored)
├── deploy/ # Docker stack: see "Deploy" below
│ ├── README.md # run guide, troubleshooting, production checklist
│ ├── compose.yaml # api + postgres + n8n
│ ├── Dockerfile # uv-based image for the api
│ ├── api/app.py # FastAPI serving an agent, Postgres checkpointer, SSE streaming
│ └── n8n/toolbox.workflow.json # n8n workflow exposing tools via the MCP Server Trigger
├── tests/ # pytest: tools, config, and each demo run end to end
├── .github/workflows/tests.yml # CI: fast tests on every push / PR
├── CLAUDE.md # notes for Claude Code sessions
├── .env.example
└── pyproject.toml # managed with uv, Python 3.14
uv sync # create .venv and install dependencies
copy .env.example .env # adjust if needed
# Local model (Ollama in Docker)
docker start ollama
docker exec ollama ollama pull qwen3:4b-instruct # ~2.5 GB, tool calling, fits a 4 GB GPU
docker exec ollama ollama pull nomic-embed-text # embeddings for demo 08
uv run demos/00_check_setup.pyTo use Claude instead, set LLM_PROVIDER=anthropic and ANTHROPIC_API_KEY in .env. Demo 08 still uses Ollama for embeddings.
uv run demos/03_state_graph_basics.pyEach demo begins with a docstring explaining the concepts it covers. Demos that build a graph save a Mermaid diagram to demos/output/*.mmd; paste one into https://mermaid.live to view it.
A local, production-like Docker stack: the agent served by FastAPI with conversations in Postgres, plus n8n exposing a workflow as MCP tools (used by demo 15).
docker compose -f deploy/compose.yaml up -d --build
# one-time n8n workflow import/publish: see deploy/README.mdAPI docs at http://localhost:8000/docs, n8n at http://localhost:5678. Full guide, troubleshooting and a production checklist: deploy/README.md. Lessons learned: docs/NOTES.md.
uv run pytest -m "not llm" # fast: tools + LLM-free demos (seconds)
uv run pytest # everything; LLM demos are skipped if the backend is unreachableCI (GitHub Actions) runs the fast set, since no model is available there.
qwen3:4b-instructis the non-thinking Qwen3-4B-Instruct-2507 (the plainqwen3:4btag is now the Thinking variant, which is slower and prints its reasoning). WithOLLAMA_NUM_CTX=4096it runs 100% on a 4 GB GPU. Its tool calling is good enough for these demos, but it will sometimes make mistakes that a large model would not. Switching to Anthropic is a useful comparison.- If VRAM is tight, set
OLLAMA_MODEL=qwen3:1.7bor lowerOLLAMA_NUM_CTX. - Removing models you no longer need frees disk space:
docker exec ollama ollama list # what is installed (and sizes) docker exec ollama ollama rm qwen3:4b # thinking variant, not used by the demos docker exec ollama ollama rm qwen3:8b qwen3:8b-32k gemma4:e2b gemma4:e2b-32k # too big for 4 GB VRAM
- Optional tracing: set the
LANGFUSE_*keys in.env(self-hosted Langfuse or Langfuse Cloud) and demo 13 sends each eval case to Langfuse as a trace with its scores.tracing_config()adds the same to any demo. LangSmith also works (LANGSMITH_TRACING=true,LANGSMITH_API_KEY=...) with no code changes.