didilili/shopkeeper-agent

What it solves

This project addresses the common challenges in business data analysis where users need to query databases using natural language but lack SQL expertise. It solves the issues of "hallucinations" and incorrect data retrieval (such as selecting the wrong tables or fields) by implementing a structured, multi-stage reasoning pipeline rather than relying on a simple, direct LLM-to-SQL prompt.

How it works

The system uses a sophisticated agentic workflow built with LangGraph. It first constructs a metadata knowledge base by indexing table schemas, metrics, and field values across MySQL, Qdrant (for semantic vector search), and Elasticsearch (for keyword-based value search). When a user asks a question, the agent performs a multi-path retrieval to gather relevant context, generates and validates SQL, executes the query, and streams the results back to a React frontend.

Who it’s for

It is designed for developers who want to learn how to build production-grade AI agents. It is particularly useful for those looking to master LangGraph, integrate multiple data stores (MySQL, Qdrant, Elasticsearch) into a single AI application, and understand the full lifecycle of an agentic project from data preparation to frontend delivery.

Highlights

• Multi-stage Reasoning: Moves beyond simple prompt engineering by using LangGraph to orchestrate retrieval, SQL generation, validation, and correction.
• Hybrid Retrieval: Combines semantic search (Qdrant) and keyword search (Elasticsearch) to ensure accurate mapping of natural language to database schemas and values.
• Full-Stack Implementation: Includes a complete, runnable codebase with a FastAPI backend, React frontend, and Docker-based infrastructure.
• Educational Focus: Accompanied by a comprehensive, chapter-by-chapter tutorial series that maps directly to Git branches for hands-on learning.
• Engineering Best Practices: Demonstrates professional patterns like dependency injection, structured configuration, and request-id logging for tracing.