hoanganhvu123/shoppinggpt

1. Purpose and entry points

ShoppingGPT is a Python shopping-assistant chatbot: it routes a user query, retrieves product/policy context when relevant, and uses Google Gemini to respond. The runnable web entry point is app.py; main.py is a secondary application/orchestration entry point. The browser UI is served from templates/index.html with styling in static/style.css.

2. Web request boundary

The Flask layer accepts chat input and returns assistant output, separating the browser-facing interface from LLM and retrieval logic. Its primary assets are:

• app.py

• templates/index.html

• static/style.css

3. Query orchestration and conversational path

The core domain package coordinates routing, chat generation, agent behavior, and conversation state. General conversation is handled through a chain backed by Gemini and conversation memory; shopping-oriented requests are delegated to the agent/tools.

• shoppinggpt/chain.py

• shoppinggpt/agent.py

• shoppinggpt/config.py

4. Semantic routing/classification

Before expensive retrieval or agent execution, the router distinguishes chitchat from product-related intent. The repository supports multiple classification approaches: semantic-router embeddings, cosine-similarity routing, and a fine-tuned Hugging Face classifier. This is the key control-flow fork between the chitchat chain and shopping agent.

• shoppinggpt/router/lib_semantic_router.py

• shoppinggpt/router/consine_algo_semantic.py

• shoppinggpt/router/pretrain_model_for_route.py

5. Product retrieval path

Product questions use SQLite-backed search with case-insensitive/partial matching, then provide structured inventory results to the agent/LLM for grounded responses. Product inventory is persisted separately from source CSV input.

• shoppinggpt/tool/product_search.py

• data/products.db

• data/products.csv

6. Policy RAG path

Policy questions use vector similarity retrieval over a persisted FAISS datastore. Retrieved company-policy passages are injected into the response-generation context rather than relying only on model knowledge.

• shoppinggpt/tool/policy_search.py

• data/datastore/index.faiss

• data/datastore/index.pkl

7. Runtime, models, and deployment

The system runs as a Flask/Python service with dependencies declared in requirements.txt. It requires GOOGLE_API_KEY (documented in .env.example) for Google Generative AI: Gemini 1.5 Flash for generation and Google embeddings for routing/retrieval. A remote Hugging Face model, hang1704/opendaisy, is an additional classification dependency. Production deployment automation is defined in .github/workflows/deploy-production.yml.