shopkeeper-agent, presented as 电商问数 (E-commerce Data Q&A), is an MIT-licensed AI agent that answers natural-language questions against an e-commerce data warehouse and is packaged as a full-stack, runnable LangGraph learning project for developers who want to study LLM application engineering from data preparation through to frontend integration.

What it is

The project is a complete natural-language-to-SQL (NL2SQL) analytics agent built on LangGraph, FastAPI, Qdrant, Elasticsearch, MySQL and React, with LangChain wrapping the LLM and embedding calls. It ships both the backend and the frontend, a Docker environment for deployment, and a free companion tutorial series (ai-agents-from-zero) whose chapters map to Git branches in the repository, so the codebase can be read as a staged progression rather than a finished monolith. The backend is organised around app/agent, app/api, app/clients, app/conf and app/core, separating the LangGraph graph and nodes from routing, client management, configuration and logging concerns. It lives squarely in the Python AI-agent ecosystem around LangGraph and LangChain.

The concrete problem it addresses is the failure mode of handing a business question straight to a large model. In real warehouse Q&A, business users do not write SQL, and analysts cannot memorise every table structure, field meaning, metric definition and value domain, so one-shot prompting produces wrong tables, wrong fields, misread metrics and SQL hallucination. shopkeeper-agent replaces that single model call — and the prompt-only SQL demos it explicitly positions itself against — with a pipeline that first builds a metadata knowledge base, then recalls relevant fields, metrics and field values, then reasons in stages before generating and executing SQL.

Key capabilities

• Hybrid retrieval across three stores: Qdrant holds semantic vectors for fields and metrics, Elasticsearch performs full-text retrieval over real field values, and MySQL keeps the authoritative structured metadata via SQLAlchemy.
• Coordinated recall of three information types — fields, metrics and field values — rather than table-level or field-level retrieval alone.
• LangGraph-orchestrated multi-stage workflow covering recall, context assembly, SQL generation, validation, correction and execution.
• Streaming delivery over SSE, pushing node progress, query results and error messages to the client in real time.
• Embeddings served by TEI using BAAI/bge-large-zh-v1.5, with Jieba handling Chinese segmentation in the retrieval path.
• Request-scoped tracing through ContextVar and loguru, injecting a request_id per concurrent request.
• A React, Vite and Tailwind CSS chat interface that displays the LangGraph execution flow alongside the generated SQL and result tables.

Who uses it and how

• Learners working through the tutorial chapter by chapter, checking out the matching Git branch to see how each stage of the agent evolves.
• Developers who want MySQL, Qdrant, Elasticsearch and an LLM combined in one coherent business scenario rather than in isolated samples.
• Engineers building a portfolio project who need to explain what the data layer, retrieval layer, agent layer, service layer and frontend layer each do.
• Teams prototyping enterprise Q&A scenarios, with the README noting extension points for permission control, SQL review and result visualisation.
• Chinese-language analytics contexts, since the retrieval stack, tutorial and sample data warehouse are all built around Chinese text.

Getting started

The README points to a Quick Start section and states that a Docker environment provides one-click deployment, with uv managing Python backend dependencies and pnpm managing the frontend. The full illustrated tutorial is hosted online at the didilili.github.io/ai-agents-from-zero site under the 实战项目-电商问数 section.

How it compares

The facts provided name no paid products that this project replaces and no directly comparable tools, so it stands alone in this registry as a full-stack NL2SQL agent reference implementation. It is built on LangGraph and LangChain rather than competing with them, and its distinguishing asset is the accompanying free tutorial and per-chapter branches.

When to use it — and when not

A self-hoster must operate a MySQL instance serving as both the teaching warehouse and the metadata store, a Qdrant vector database, an Elasticsearch cluster, a TEI embedding service running BAAI/bge-large-zh-v1.5, and access to an LLM. Readers who need a production-hardened BI product with access control, SQL auditing and visualisation already built in should look elsewhere, since the README lists those as extensions to add. The documentation is written in Chinese and the framing is openly pedagogical and hedged, so non-Chinese readers or teams wanting a drop-in commercial analytics tool will find the learning curve and the scope mismatched to their needs.

shopkeeper-agent/
├── app/
│   ├── agent/            # LangGraph 图、状态、上下文和各类节点
│   ├── api/              # FastAPI 路由、依赖注入、生命周期和请求结构
│   ├── clients/          # MySQL、Qdrant、Elasticsearch、Embedding 客户端管理
│   ├── conf/             # 配置 dataclass 与配置加载工具
│   ├── core/             # 日志、request_id 上下文等通用能力
│   ├── entities/         # 更贴近业务语义的数据对象
│   ├── models/           # SQLAlchemy ORM 模型
│   ├── prompt/           # Prompt 加载工具
│   ├── repositories/     # MySQL、Qdrant、Elasticsearch 数据访问层
│   ├── scripts/          # 元数据知识库构建脚本
│   └── services/         # 元数据构建服务和问数查询服务
├── conf/                 # app_config.yaml、meta_config.yaml
├── docker/               # Docker Compose、MySQL 初始化 SQL、ES 插件、Embedding 挂载目录
├── frontend/             # React + Vite + Tailwind CSS 前端项目
├── prompts/              # SQL 生成、修正、过滤等 Prompt 模板
├── main.py               # FastAPI 应用入口
└── pyproject.toml        # Python 项目依赖与工具配置

git clone https://github.com/didilili/shopkeeper-agent.git
cd shopkeeper-agent

uv sync

cp .env.example .env

LLM_API_KEY=your_real_api_key

llm:
    model_name: Pro/zai-org/GLM-5.1
    api_key: ${oc.env:LLM_API_KEY}
    base_url: https://api.siliconflow.cn/v1

uv run hf download BAAI/bge-large-zh-v1.5 --local-dir docker/embedding/bge-large-zh-v1.5

docker compose -f docker/docker-compose.yaml up -d

uv run python -m app.scripts.build_meta_knowledge -c conf/meta_config.yaml

uv run fastapi dev main.py

POST http://127.0.0.1:8000/api/query

{
    "query": "统计华北地区的销售总额"
}

cd frontend
pnpm install
pnpm dev

cd frontend
cp .env.example .env

VITE_DEV_PROXY_TARGET=http://127.0.0.1:8000

git checkout 04-structure-config
git checkout main