OpenViSTAI · Agents · Blockchain · Crypto
Submit a project
Menu
Data Agents

Shopkeeper Agent

Shopkeeper Agent is a self-hostable application for asking natural-language questions about an e-commerce data warehouse. It retrieves relevant metadata and field values, orchestrates SQL generation and validation through LangGraph, executes queries, and streams progress and results to a React interface. Its documented stack includes FastAPI, MySQL, Qdrant, Elasticsearch and Docker.

Explore the practical guide ↓

Independent OpenViST project profile, based on linked sources.

Shopkeeper Agent — OpenViST project profile in Data Agents.
OpenViST project illustration. See the linked sources for product details.
Understand the project

Practical overview

When it fits

Use it when you want a self-hosted e-commerce warehouse question-answering workflow or a concrete codebase for learning how metadata retrieval and SQL generation can be connected in a LangGraph application.

Who it is for

  • Teams or developers exploring natural-language analytics over e-commerce warehouse data.
  • Learners studying LangGraph agent workflows and the integration of retrieval, SQL execution, APIs and a web interface.
  • Developers adapting a metadata-aware NL-to-SQL project to another data domain.

Documented uses

  • Ask warehouse questions in natural language and retrieve relevant fields, metrics and values.
  • Generate, validate, correct and execute SQL against the configured warehouse.
  • Follow query progress and view streamed analysis results in a web interface.
  • Study a full-stack example of metadata indexing, hybrid retrieval and a multi-stage agent workflow.
Before you choose

Requirements & limits

The repository is public and MIT-licensed. The documented local setup requires an LLM API key and separately obtained embedding model files.

  • The example is designed around an e-commerce teaching warehouse and MySQL; another domain or database may need schema, connection and SQL-dialect changes.
  • Local setup depends on Docker services, a configured LLM endpoint, and a separately downloaded embedding model.
  • The project combines backend services and retrieval infrastructure with a React frontend, so it is a full-stack project rather than a standalone model or hosted analytics service.

Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.

Source-based practical guide

Prepare the local development environment

Install the documented backend dependencies and prepare the model configuration and embedding files before starting the project.

Before you start

  • Python 3.14 or later
  • uv
  • Docker and Docker Compose
  • Node.js and pnpm
  • An LLM API key

Steps

  1. Clone the repository and change into the project directory.

  2. Install backend dependencies with uv sync.

  3. Copy .env.example to .env and set LLM_API_KEY to a real key; adjust the model name and base URL in conf/app_config.yaml if using another OpenAI-compatible model service.

  4. Download BAAI/bge-large-zh-v1.5 into docker/embedding/bge-large-zh-v1.5, or manually place the extracted model files in that directory.

Expected outcome

The documented local prerequisites, backend dependencies, model credential configuration and embedding files are prepared.

Guide limitations

  • These steps cover preparation only; they do not start the services or verify a working deployment.
  • The embedding model files are not included in the repository and must be obtained separately.
Documentation 1 ↗
Evidence and transparency

Sources & review

Official repository ↗
Source record details
Source availability
Active
Sources checked
13 October 2026
Original website title
didilili/shopkeeper-agent · Official homepage title · retained in its source language
How we review sourcesSuggest a correction