Skip to content

docs(examples): add dependency markers for all examples #99

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Teingi merged 1 commit into from
Jul 31, 2026
Merged

docs(examples): add dependency markers for all examples #99

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 27 additions & 15 deletions examples/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,25 @@

示例按依赖复杂度分为三组，建议按顺序探索。

**依赖标记说明：**

| 标记 | 含义 |
|---|---|
| `零依赖` | 仅需项目本身，无需外部服务 |
| `需 LLM API` | 需要配置 LLM API 密钥（如 OpenAI） |
| `需 OceanBase` | 需要 OceanBase >= 4.2.2 或 seekdb |
| `需可选依赖` | 需要安装可选依赖（如 langchain、powermem） |

## [basic/](basic/) — 入门示例

依赖最小，适合初次了解 ContextSeek。

| 文件 | 后端 | 说明 |
| 文件 | 依赖 | 说明 |
|---|---|---|
| `pipeline_file.py` | FileBackend（无需外部服务） | 本地文件后端，关键词检索 |
| `pipeline_ob.py` | OceanBase | 向量 + 全文混合检索 |
| `langchain.py` | FileBackend | LangChain Memory / Retriever 桥接 |
| `langchain_deepagents_example.py` | FileBackend（无需外部服务） | LangChain + DeepAgents + ContextSeek 的真实集成示例 |
| `pipeline_file.py` | `零依赖` | 本地文件后端，关键词检索 |
| `pipeline_ob.py` | `需 OceanBase` | 向量 + 全文混合检索 |
| `langchain.py` | `需可选依赖` | LangChain Memory / Retriever 桥接 |
| `langchain_deepagents_example.py` | `需 LLM API` | LangChain + DeepAgents + ContextSeek 的真实集成示例 |

```bash
uv run python examples/basic/pipeline_file.py # 零外部依赖，推荐首选
Expand All @@ -23,11 +32,12 @@ uv run python examples/basic/pipeline_file.py # 零外部依赖，推荐首选

| 文件 | 依赖 | 说明 |
|---|---|---|
| `research_agent.py` | 仅项目本身 | 所有核心功能综合演示（推荐） |
| `evidence_chain.py` | 仅项目本身 | 证据链溯源：`upstream` / `evidence_chain` / `chain_confidence` |
| `llm_full_pipeline_ob.py` | OB + LLM API | Phase 1/2/3 完整 LLM 流水线 |
| `powermem_minimal.py` | 仅项目本身 | PowerMem 最小集成路径（~50 行） |
| `powermem_plug.py` | 可选 powermem | PowerMem DataPlug 完整演示 |
| `research_agent.py` | `零依赖` | 所有核心功能综合演示（推荐） |
| `evidence_chain.py` | `零依赖` | 证据链溯源：`upstream` / `evidence_chain` / `chain_confidence` |
| `self_evolution_demo.py` | `零依赖` | 自演进四项特性：冲突检测、双时态、utility 反馈、pitfall 反思 |
| `llm_full_pipeline_ob.py` | `需 OceanBase` + `需 LLM API` | Phase 1/2/3 完整 LLM 流水线 |
| `powermem_minimal.py` | `零依赖` | PowerMem 最小集成路径（~50 行） |
| `powermem_plug.py` | `需可选依赖` | PowerMem DataPlug 完整演示 |

```bash
uv run python examples/advanced/research_agent.py # 推荐：零外部依赖的完整演示
Expand All @@ -37,11 +47,13 @@ uv run python examples/advanced/research_agent.py # 推荐：零外部依赖的

需要 OceanBase >= 4.2.2（或 seekdb）且 `GEO_ENABLED=true`。

| 文件 | 场景 |
|---|---|
| `poi_search.py` | 地图 POI 关键词 + 地理混合搜索 |
| `ride_hailing.py` | 打车调度：司机 / 订单 / 热力区域 |
| `autonomous_driving.py` | 智能驾驶：HD 地图 / ODD / 道路事件 |
| 文件 | 依赖 | 场景 |
|---|---|---|
| `poi_search.py` | `需 OceanBase` | 地图 POI 关键词 + 地理混合搜索 |
| `ride_hailing.py` | `需 OceanBase` | 打车调度：司机 / 订单 / 热力区域 |
| `autonomous_driving.py` | `需 OceanBase` | 智能驾驶：HD 地图 / ODD / 道路事件 |
| `gis_memory.py` | `需 OceanBase` | GPS 轨迹 → 地点事实 → 行为知识 |
| `smart_swap.py` | `需 OceanBase` | GIS 记忆驱动的分层换电推荐 |

```bash
GEO_ENABLED=true uv run python examples/gis/poi_search.py
Expand Down
12 changes: 7 additions & 5 deletions examples/advanced/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@

完整能力展示，涵盖 LLM 集成、演进流水线和 DataPlug 扩展。

## research_agent.py — 综合功能演示（推荐新用户看完 basic 后从这里开始）
> 依赖标记说明见 [examples/README.md](../README.md#依赖标记说明)。

## research_agent.py — 综合功能演示（推荐新用户看完 basic 后从这里开始） `零依赖`

```bash
uv run python examples/advanced/research_agent.py
Expand All @@ -25,7 +27,7 @@ uv run python examples/advanced/research_agent.py

---

## evidence_chain.py — 证据链与溯源 API 演示
## evidence_chain.py — 证据链与溯源 API 演示 `零依赖`

```bash
uv run python examples/advanced/evidence_chain.py
Expand All @@ -43,7 +45,7 @@ uv run python examples/advanced/evidence_chain.py

---

## llm_full_pipeline_ob.py — 真实 LLM + OceanBase 完整流水线
## llm_full_pipeline_ob.py — 真实 LLM + OceanBase 完整流水线 `需 OceanBase` `需 LLM API`

```bash
uv run python examples/advanced/llm_full_pipeline_ob.py
Expand All @@ -63,7 +65,7 @@ pip install "contextseek[oceanbase,langchain,openai]"

---

## powermem_minimal.py — PowerMem 最小集成路径
## powermem_minimal.py — PowerMem 最小集成路径 `零依赖`

```bash
uv run python examples/advanced/powermem_minimal.py
Expand All @@ -76,7 +78,7 @@ uv run python examples/advanced/powermem_minimal.py

---

## powermem_plug.py — PowerMem DataPlug 完整演示
## powermem_plug.py — PowerMem DataPlug 完整演示 `需可选依赖`

```bash
uv run python examples/advanced/powermem_plug.py
Expand Down
10 changes: 6 additions & 4 deletions examples/basic/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@

入门示例，依赖最小，适合初次了解 ContextSeek 的用户。

## pipeline_file.py — FileBackend 本地文件后端
> 依赖标记说明见 [examples/README.md](../README.md#依赖标记说明)。

## pipeline_file.py — FileBackend 本地文件后端 `零依赖`

```bash
uv run python examples/basic/pipeline_file.py
Expand All @@ -19,7 +21,7 @@ uv run python examples/basic/pipeline_file.py

---

## pipeline_ob.py — OceanBase 后端 + 语义检索
## pipeline_ob.py — OceanBase 后端 + 语义检索 `需 OceanBase`

```bash
uv run python examples/basic/pipeline_ob.py
Expand All @@ -43,7 +45,7 @@ pip install "contextseek[dashscope]" # 阿里云百炼 / DashScope

---

## langchain.py — LangChain 桥接层
## langchain.py — LangChain 桥接层 `需可选依赖`

```bash
uv run python examples/basic/langchain.py
Expand All @@ -62,7 +64,7 @@ pip install "contextseek[langchain]"

---

## langchain_deepagents_example.py — LangChain + DeepAgents 集成示例
## langchain_deepagents_example.py — LangChain + DeepAgents 集成示例 `需 LLM API`

```bash
uv run python examples/basic/langchain_deepagents_example.py
Expand Down
13 changes: 8 additions & 5 deletions examples/gis/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@

地理空间场景示例，展示 ContextSeek 在位置感知应用中的能力。

> 依赖标记说明见 [examples/README.md](../README.md#依赖标记说明)。
> 本目录所有示例均为 `需 OceanBase`。

## 运行前提（所有示例通用）

- OceanBase >= 4.2.2 或 seekdb
Expand Down Expand Up @@ -43,7 +46,7 @@ export OB_DB_NAME=contextseek

---

## poi_search.py — 地图 POI 搜索
## poi_search.py — 地图 POI 搜索 `需 OceanBase`

```bash
uv run python examples/gis/poi_search.py
Expand All @@ -57,7 +60,7 @@ uv run python examples/gis/poi_search.py

---

## ride_hailing.py — 打车调度场景
## ride_hailing.py — 打车调度场景 `需 OceanBase`

```bash
uv run python examples/gis/ride_hailing.py
Expand All @@ -71,7 +74,7 @@ uv run python examples/gis/ride_hailing.py

---

## autonomous_driving.py — 智能驾驶场景
## autonomous_driving.py — 智能驾驶场景 `需 OceanBase`

```bash
uv run python examples/gis/autonomous_driving.py
Expand All @@ -87,7 +90,7 @@ uv run python examples/gis/autonomous_driving.py

---

## gis_memory.py — GIS 记忆生成（运行 smart_swap.py 前必跑）
## gis_memory.py — GIS 记忆生成（运行 smart_swap.py 前必跑） `需 OceanBase`

```bash
uv run python examples/gis/gis_memory.py
Expand All @@ -104,7 +107,7 @@ uv run python examples/gis/gis_memory.py

---

## smart_swap.py — GIS 记忆驱动的智能换电推荐
## smart_swap.py — GIS 记忆驱动的智能换电推荐 `需 OceanBase`

> **前提：先运行 `gis_memory.py`**，否则场景 1/2 降级为常规推荐

Expand Down
Loading