nanoLangchain

一个面向学习的最小化 LangChain / LangGraph 项目骨架。

当前阶段先提供：

• 清晰的目录结构
• 面向后续实现的模块边界
• 学习与搭建文档
• 交给 Claude 继续开发时可直接使用的说明

目标

这个仓库的定位不是一上来做"大而全"的框架，而是先用 nano 级别的结构把核心学习路径固定下来：

1. 先学会 LangChain 的基础组件如何协作
2. 再学会 LangGraph 的状态、节点、边和执行流
3. 最后在一个非常小的项目中把两者串起来

当前项目结构

nanoLangchain/
├── README.md
├── CLAUDE.md
├── pyproject.toml
├── .env.example
├── .gitignore
├── docs/
│   ├── README.md
│   ├── architecture.md
│   ├── learning-roadmap.md
│   ├── todo.md
│   └── handoff-to-claude.md
├── examples/
│   ├── README.md
│   ├── run_chain.py
│   └── run_graph.py
├── tests/
│   ├── README.md
│   ├── test_core.py
│   ├── test_chain.py
│   └── test_graph.py
└── src/
    └── nano_langchain/
        ├── __init__.py
        ├── core/
        │   ├── __init__.py
        │   ├── config.py
        │   └── models.py
        ├── chains/
        │   ├── __init__.py
        │   └── simple_chain.py
        ├── graphs/
        │   ├── __init__.py
        │   └── simple_graph.py
        └── prompts/
            └── __init__.py

推荐后续实现顺序

1. 在 core/ 中补配置与模型初始化
2. 在 chains/ 中完成第一个最小 LangChain 示例
3. 在 graphs/ 中完成第一个最小 LangGraph 示例
4. 在 examples/ 中增加可运行 demo
5. 在 tests/ 中补最基础测试

启动前准备

1. 创建虚拟环境

   python -m venv venv
   source venv/bin/activate  # Linux/Mac
   # 或 venv\Scripts\activate  # Windows

2. 安装依赖

   pip install langchain langgraph langchain-openai python-dotenv pytest

3. 复制 .env.example 到 .env 并设置你的 OpenAI API Key

   cp .env.example .env
   # 编辑 .env 文件，设置 OPENAI_API_KEY

运行示例

运行 LangChain 示例

python examples/run_chain.py

运行 LangGraph 示例

python examples/run_graph.py

运行测试

python -m pytest tests/ -v

已实现功能

核心模块 (core/)

• config.py: 配置加载和环境变量管理
• models.py: 模型初始化和工厂函数

LangChain 示例 (chains/)

• simple_chain.py: 最小问答链示例，展示 prompt + model + output parser 的组合

LangGraph 示例 (graphs/)

• simple_graph.py: 最小状态图示例，包含两个节点（思考节点和回答节点）

示例脚本 (examples/)

• run_chain.py: 运行 LangChain 示例的脚本
• run_graph.py: 运行 LangGraph 示例的脚本

测试 (tests/)

• test_core.py: 核心模块测试
• test_chain.py: 链模块测试
• test_graph.py: 图模块测试

说明

当前仓库故意保持轻量，重点是先把架构和文档约束好，避免后面一边学一边把目录长歪。

学习路线

详细学习路线请参考 docs/learning-roadmap.md

下一步

根据 docs/todo.md 中的计划，下一步可以：

1. 增加更复杂的链示例（如带记忆的对话链）
2. 增加带条件分支的图示例
3. 将 prompt 模板抽离到 prompts/ 目录
4. 接入 LangSmith 进行链路追踪