{"id":29486584,"url":"https://github.com/bma32/faq-chatbot","last_synced_at":"2026-05-03T10:39:12.748Z","repository":{"id":304060919,"uuid":"1017637233","full_name":"BMA32/faq-chatbot","owner":"BMA32","description":"FAQ Chatbot for a fictional e-commerce site using LLM and semantic search","archived":false,"fork":false,"pushed_at":"2025-07-10T22:15:00.000Z","size":11,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-11T04:15:18.332Z","etag":null,"topics":["chatbot","chroma","cli","customer-support","data-science","ecommerce","faq-bot","langchain","llm","nlp","openai","portfolio-project","prompt-engineering","pytest","python","rag","semantic-search","vector-database","virtualenv"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BMA32.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-10T21:14:52.000Z","updated_at":"2025-07-10T22:15:03.000Z","dependencies_parsed_at":"2025-07-11T04:15:59.195Z","dependency_job_id":"048c9fdf-ce7a-45fa-a73e-2420350f453b","html_url":"https://github.com/BMA32/faq-chatbot","commit_stats":null,"previous_names":["bma32/faq-chatbot"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/BMA32/faq-chatbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BMA32%2Ffaq-chatbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BMA32%2Ffaq-chatbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BMA32%2Ffaq-chatbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BMA32%2Ffaq-chatbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BMA32","download_url":"https://codeload.github.com/BMA32/faq-chatbot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BMA32%2Ffaq-chatbot/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266998013,"owners_count":24018949,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-25T02:00:09.625Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatbot","chroma","cli","customer-support","data-science","ecommerce","faq-bot","langchain","llm","nlp","openai","portfolio-project","prompt-engineering","pytest","python","rag","semantic-search","vector-database","virtualenv"],"created_at":"2025-07-15T08:01:14.945Z","updated_at":"2025-10-30T16:17:30.981Z","avatar_url":"https://github.com/BMA32.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TechShop FAQ Chatbot\n\nA retrieval-augmented chatbot for a fictional e-commerce platform called **TechShop**. This chatbot answers customer support questions by combining semantic search over a FAQ database with a large language model (LLM), built for modern e-commerce use cases. This project serves as a portfolio example for practical data science, LLMs and RAG systems.\n\n## Demo\n\n```bash\n$ python -m chatbot.cli\n\n🤖 TechShop FAQ Chatbot (type 'exit' to quit)\n\nYou: How long does delivery to Lisbon usually take?\nBot: Delivery to Lisbon takes 2–4 working days, depending on stock availability.\n\nYou: How can I become a TechShop ambassador?\nBot: I'm sorry, I couldn't find an answer to your question in our FAQs. Please contact our support team at support@techshop.com for further assistance.\n\n```\n\n## Motivation\n\nCompanies increasingly want reliable, AI-powered support bots — but real-world systems must avoid “hallucinations” and keep answers grounded in actual business knowledge. This project demonstrates a robust solution: combining semantic search over trusted FAQs with a state-of-the-art LLM, ensuring the chatbot never invents answers and always stays on brand.\n\nBuilt as a practical exercise for my data science portfolio, it showcases:\n- Good prompt engineering and RAG practices,\n- Effective use of vector databases,\n- Clear, maintainable code ready for adaptation or extension.\n\n## How it works\n\n1. **Vectorisation**: Every FAQ is embedded using OpenAI embeddings and stored in a Chroma vector database.\n2. **Retrieval**: When a user asks a question, the bot finds the most semantically similar FAQ (using embedding search).\n3. **Threshold**: Only if the FAQ is genuinely relevant (below a certain similarity threshold) does the bot answer; otherwise, it politely says it cannot help.\n4. **LLM Paraphrase**: The LLM reformulates the FAQ answer in a customer-friendly tone, but never invents details.\n\nThis structure ensures both accuracy and a smooth customer experience.\n\n## Features \u0026 Good Practices\n\n- Retrieval-augmented generation: answers always grounded in trusted FAQs.\n- Score threshold to prevent unrelated answers (avoiding hallucination).\n- LLM only paraphrases, never invents facts.\n- Configurable: easy to swap embeddings or vector store.\n- Written in English, with clear structure and docstrings for readability and reuse.\n- Portable: designed for both local demo and easy cloud deployment.\n\n## Requirements\n\n- Python 3.10.6 (recommended)\n- [pyenv](https://github.com/pyenv/pyenv) and [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv) for environment management\n\nIf using pyenv (recommended):\n\n```bash\npyenv install 3.10.6\npyenv virtualenv 3.10.6 chatbot-faq\npyenv local chatbot-faq\n```\n\n## Quickstart\n\n1. **Clone the repo**\n    ```bash\n    git clone https://github.com/seu-utilizador/Chatbot-FAQ.git\n    cd Chatbot-FAQ\n    ```\n\n2. **Create and activate your Python virtual environment**\n    ```bash\n    python3 -m venv .venv\n    source .venv/bin/activate\n    ```\n\n3. **Install dependencies**\n    ```bash\n    pip install -r requirements.txt\n    ```\n\n4. **Set up your OpenAI API key**\n    - Create a `.env` file in the root folder with:\n        ```\n        OPENAI_API_KEY=sk-...\n        ```\n\n5. **Build the vector database**\n    ```bash\n    python src/chatbot/vector_store.py\n    ```\n\n6. **Run the chatbot**\n    ```bash\n    python -m chatbot.cli\n    ```\n\n## Embeddings and Thresholds\n\n- By default, this project uses OpenAI embeddings for best performance.\n- The similarity threshold is set to `0.3` — only questions closely matching a FAQ will be answered directly.\n- You can tune the threshold in `agent.py` to make the bot stricter or more permissive.\n- If you want a local-only version (no OpenAI cost), you can swap for `sentence-transformers` embeddings (see code comments).\n\n## Customising FAQs\n\n- All FAQs live in `data/faqs.json` — you can add, remove, or change questions and answers easily.\n- The system is designed for e-commerce, but can be adapted for any sector.\n\n## Dependencies\n\n- Python 3.10+\n- openai\n- langchain-openai\n- langchain-chroma\n- chromadb\n- python-dotenv\n\n(See `requirements.txt` for the full list.)\n\n## Development \u0026 Automation\n\nFor developer convenience, you can use the included `Makefile` to automate common tasks:\n\n| Command            | Description                            |\n|--------------------|----------------------------------------|\n| `make install`     | Install project dependencies           |\n| `make vectors`   | Build/rebuild the FAQ vector database  |\n| `make test`        | Run all tests with pytest              |\n| `make run`         | Start the chatbot CLI                  |\n| `make lint`        | Lint code with flake8 (optional)       |\n\nFeel free to adapt or extend these targets for your workflow.\n\n## Extensions \u0026 Future Work\n\n- **Database Integration**:\n  This project uses a JSON file for demo purposes, but it can easily be adapted to fetch FAQs from a SQL or NoSQL database for production use.\n\n- **Web/App Frontend**:\n  The CLI can be extended with a web-based frontend (e.g. Streamlit or Gradio) for user-friendly interaction and live demos.\n\n- **Cloud Deployment**:\n  Ready to be containerised with Docker for deployment on cloud platforms (AWS, GCP, Azure, etc.).\n\n- **Multi-language Support**:\n  The chatbot can be extended to handle multiple languages or locales by changing the embedding model and FAQ sources.\n\n- **Analytics/Logging**:\n  Add user interaction logging and analytics for insight into customer queries and FAQ coverage.\n\n## How to Adapt\n\n- To use other LLMs or embeddings, just swap the relevant lines in `agent.py`.\n- To increase the FAQ base, edit `data/faqs.json` — no code change needed.\n- All code is modular and can be reused for other support/chatbot projects.\n\n## Note on CI (GitHub Actions) Failures:\n\nThis project uses GitHub Actions to run basic continuous integration checks, including testing imports and code quality.\nSome steps require a valid OPENAI_API_KEY to be set as a secret.\nBecause this is a public portfolio project, no real API keys are included in the repository, and for security reasons, the CI will show as failed unless you add your own key.\n\nHow to fix this if you fork or clone the project:\n\n- Add your own OPENAI_API_KEY as a secret in your GitHub repository settings (Settings \u003e Secrets and variables \u003e Actions).\n\n- Alternatively, you can comment out or skip the steps that require the key.\n\nThis does not affect running the code locally, as long as you set your own key in your .env file.\n\n## Author\n\nBruno Malheiro\n[LinkedIn](https://www.linkedin.com/in/bruno-malheiro/)\n[Your portfolio site](https://troopl.com/bruno-malheiro)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbma32%2Ffaq-chatbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbma32%2Ffaq-chatbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbma32%2Ffaq-chatbot/lists"}