Original en inglés: https://argusic.com/subject/shopkeeper-agent
shopkeeper-agent
AI Agent para consultas inteligentes en almacenes de datos de e-commerce, proyecto práctico ideal para aprender LangGraph: implementa con LangGraph, FastAPI, Qdrant, Elasticsearch, MySQL y React una base de conocimiento de metadatos, búsqueda híbrida, generación y validación de NL2SQL, ejecución de SQL y visualización en streaming. Código completo ejecutable, despliegue con un clic en Docker, incluye el tutorial gratuito ai-agents-from-zero y ramas por capítulos. Ideal para aprender aplicaciones LLM, agents de análisis de datos e ingeniería de IA empresarial.
Funciona con mocksfuente: GitHubsitio webPythonMITcommit 8045fa4d6160
Python, licencia MIT. El proyecto se describe a sí mismo como: agent workflow, ai agent, elasticsearch, fastapi, langchain, langgraph, llm y nl2sql.
shopkeeper-agent funciona, con sustitutos de los servicios de los que depende. Un agent de Argusic lo instaló en 28 minutos y encontró 4 errores, todos corregidos sin ayuda en una máquina limpia sin GPU, y toda la sesión quedó grabada.
With schema-correct mocks for the mandatory external services, the uvicorn-served app answers POST /api/query with a complete SSE pipeline and returns SQL aggregate result sales=10088 for '统计华北地区销售额'; uv sync installs all dependencies and the frontend pnpm build completes.
Lo que el agent consiguió en una máquina limpia, en sus propias palabras. Cómo se mide
Medido por Argusic en una máquina limpia cada vez. Cada cifra enlaza a su evidencia. Puntuación Argusic de 92 sobre 100 (la media de las puntuaciones de las ejecuciones de este proyecto).
De un vistazo
Datos del proyecto de GitHub, enlazados al principio de esta página, actualizado . Datos de prueba de Argusic (CC BY 4.0); cada cifra enlaza a una página de ejecución con el log completo, la grabación y sus hashes sha256.
Qué se midió
De la ejecución que decidió este veredicto. Cada línea es un valor registrado, no una estimación.
Qué salió mal, en palabras del propio agent
Las palabras del propio agent, de lo más grave a lo menos, nunca reescritas como consejos.
- App lifespan requires external MySQL/Qdrant/ES/TEI/LLM not present in container20 minutos
- pip install -e . fails: setuptools flat-layout (app, conf, docker, prompts, frontend)3 minutos
- Manual pip venv (langchain-huggingface 1.2.3) rejects embedding model=URL; uv pin 1.2.1 accepts it3 minutos
- Config requires LLM_API_KEY; omegaconf.InterpolationResolutionError without it2 minutos
- Tiempo de instalación
- 28 minutos
- De máquina en frío a terminar
- 31 minutos
- Errores encontrados y corregidos
- 4 encontrados, 4 corregidos sin ayuda humana
- Cómo se demostró el resultado
- uv run pytest tests/test_integration.py -v exited 0 with 1 passed (asserts /api/query 200 and SSE pipeline ends with result data [{'sales':10088}]); also curl -X POST http://127.0.0.1:8000/api/query returned HTTP 200 with full SSE stream ending in [{'sales':10088}]
- Tokens de modelo usados
- 497.338
- Commit exacto probado
- 8045fa4d6160
- Imagen del contenedor
- sha256:cdd920bce783
Qué no se midió
La otra mitad, para que veas exactamente hasta dónde llega esta evidencia. Un hueco se muestra como hueco y nunca se rellena.
- Memoria de GPU máxima
- se ejecutó en una máquina con CPU, así que no había GPU que muestrear
- Comportamiento en una ejecución larga
- cada intento usa la configuración documentada más pequeña y un presupuesto de tiempo fijo, así que esto mide si funciona, no cómo aguanta bajo carga
- Comportamiento con servicios reales
- esta ejecución solo se verificó con servicios sustitutos
El final de la grabación
Las últimas líneas de la sesión de terminal que decidió este veredicto, tal como se registraron.
- App imports under `uv run` (`import main` and `uv run fastapi dev main.py` path).
**Errors encountered and fixed**
1. Config fails without the LLM key (`omegaconf.InterpolationResolutionError: 'LLM_API_KEY' not fou…
2. `pip install -e .` (non-documented path) fails with setuptools flat-layout error (multiple top-l…
3. App lifespan requires external MySQL, Qdrant, Elasticsearch, TEI embedding, and an LLM — none pr…
4. A dependency-version nuance: in a pip venv with `langchain-huggingface 1.2.3`, the embedding `mo…
**Verification**
- `uv run pytest tests/test_integration.py -v` → **1 passed**.
- The test launches the app lifespan and POSTs to `/api/query` with `{"query":"统计华北地区销售额"}`; the SS…
- I also launched the real `uvicorn` (with mocks) and `curl -X POST http://127.0.0.1:8000/api/query…
**Final state**: dependencies install via `uv sync`; the app builds and runs; `/api/query` executes…
Notes on remaining work: the repo has no unit tests originally; I added `tests/test_integration.py`…Reproducir la sesión completa, cada comando desde una máquina limpia hasta este punto.
Cómo se probó
Un agent, un contenedor, sin ayuda humana. Instala el proyecto como indica su propia documentación, lo ejecuta y arregla lo que falla. Todo lo de abajo se registró tal como ocurrió: la sesión de terminal, el log y el commit exacto. La metodología completa.
Puntos fuertes y límites
Hechos medidos, no opiniones. Cómo se redacta.
Qué salió bien
- Se instaló en 28 minutos.
- Se recuperó de los 4 errores sin que interviniera una persona, lo que indica que los fallos están lo bastante documentados como para resolverlos.
- Licencia MIT, según su plataforma de origen.
Qué no salió bien, o no se sabe
- Solo llegó a funcionar con servicios sustitutos, así que nada de lo que hay aquí demuestra que funcione con los reales.
- Medido una sola vez hasta ahora. Un único intento demuestra que puede funcionar, no que funcione de forma fiable.
También probados, en la misma área
Argusic instaló y ejecutó cada uno de estos proyectos en una máquina limpia. Aquí no aparece nada que no se haya probado.
Historial de ejecuciones
| probado por | intento | resultado | puntuación | costo USD | cuándo |
|---|---|---|---|---|---|
| Argusic Runner | 1/3 | Funciona con mocks | 92,00 | 0,59 |
Temas (de GitHub)
agent-workflowai-agentelasticsearchfastapilangchainlanggraphllmnl2sqlqdrantragvector-database
Insertar el badge
Markdown para el README del proyecto. Enlaza de vuelta aquí; condiciones en la página de términos.
[](https://argusic.com/subject/shopkeeper-agent)Preguntas
- ¿Funciona shopkeeper-agent?
- shopkeeper-agent funciona, con mocks en lugar de los servicios externos. Argusic lo instaló y lo inició en una máquina limpia en 28 minutos, con 4 errores por el camino, y grabó la sesión.
- ¿Cómo probó Argusic shopkeeper-agent?
- En una máquina limpia y desechable, con cada comando grabado y el repositorio fijado en el commit 8045fa4d6160. Hay un intento registrado, y la metodología completa está en la página de metodología.
- ¿Cuánto costó probar shopkeeper-agent?
- La ejecución que produjo este veredicto costó 0,59 USD: costo real de cómputo y de modelo, no un precio de lista por millón de tokens. Consta en la página de esa ejecución.
- ¿Cuánto tarda shopkeeper-agent en instalarse?
- 28 minutos en la ejecución que decidió este veredicto, desde una máquina limpia hasta que funcionó. Es un intento medido, no una media.
- ¿Necesita shopkeeper-agent una GPU?
- No para arrancar. Argusic consiguió que funcionara en una máquina sin GPU.
- ¿Qué falla al instalar shopkeeper-agent?
- En la ejecución registrada fallaron 4 cosas, y 4 se corrigieron sin ayuda humana. Cada una, con el tiempo que costó, aparece en esta página.
- ¿Dónde está la evidencia de shopkeeper-agent?
- La ejecución registrada está en esta página, cada una enlazada a su log completo y a su grabación de terminal, guardados con una huella sha256 para que no se puedan alterar en silencio.