Skip to content

About

Hands-on playground for learning LangGraph and LangChain with a small local model (Ollama) or Claude

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

learn-langgraph

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

Setup

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.py

To use Claude instead, set LLM_PROVIDER=anthropic and ANTHROPIC_API_KEY in .env. Demo 08 still uses Ollama for embeddings.

Running the demos

uv run demos/03_state_graph_basics.py

Each 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.

Deploy (API + Postgres + n8n)

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.md

API 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.

Tests

uv run pytest -m "not llm"       # fast: tools + LLM-free demos (seconds)
uv run pytest                    # everything; LLM demos are skipped if the backend is unreachable

CI (GitHub Actions) runs the fast set, since no model is available there.

Notes on the small local model

  • qwen3:4b-instruct is the non-thinking Qwen3-4B-Instruct-2507 (the plain qwen3:4b tag is now the Thinking variant, which is slower and prints its reasoning). With OLLAMA_NUM_CTX=4096 it 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.7b or lower OLLAMA_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.

About

Hands-on playground for learning LangGraph and LangChain with a small local model (Ollama) or Claude

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages