{"id":31618075,"url":"https://github.com/ki-ian/semantic-search","last_synced_at":"2026-05-03T01:37:42.611Z","repository":{"id":316599339,"uuid":"1061640896","full_name":"KI-IAN/semantic-search","owner":"KI-IAN","description":"Upload PDFs, ask natural-language questions, and get context-aware answers powered by LangChain, ChromaDB, and NVIDIA/Gemini LLMs — all wrapped in a clean Gradio interface. Docker-ready and deployable on Hugging Face Spaces.","archived":false,"fork":false,"pushed_at":"2025-09-25T13:50:08.000Z","size":14,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-25T15:38:14.863Z","etag":null,"topics":["chromadb","docker","docker-compose","gemini-api","gradio","huggingface-spaces","langchain","nvidia-nim-api","python"],"latest_commit_sha":null,"homepage":"https://huggingface.co/spaces/frkhan/semantic-search-app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KI-IAN.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-22T07:34:43.000Z","updated_at":"2025-09-25T13:50:11.000Z","dependencies_parsed_at":"2025-09-25T15:38:18.498Z","dependency_job_id":null,"html_url":"https://github.com/KI-IAN/semantic-search","commit_stats":null,"previous_names":["ki-ian/semantic-search"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/KI-IAN/semantic-search","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KI-IAN%2Fsemantic-search","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KI-IAN%2Fsemantic-search/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KI-IAN%2Fsemantic-search/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KI-IAN%2Fsemantic-search/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KI-IAN","download_url":"https://codeload.github.com/KI-IAN/semantic-search/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KI-IAN%2Fsemantic-search/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278621843,"owners_count":26017253,"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-10-06T02:00:05.630Z","response_time":65,"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":["chromadb","docker","docker-compose","gemini-api","gradio","huggingface-spaces","langchain","nvidia-nim-api","python"],"created_at":"2025-10-06T13:45:23.373Z","updated_at":"2025-10-06T13:45:30.238Z","avatar_url":"https://github.com/KI-IAN.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\ntitle: Semantic Search App\nemoji: 📄🔗🧠❓🔗🤖\ncolorFrom: indigo\ncolorTo: pink\nsdk: gradio\nsdk_version: 5.46.1\napp_file: app.py\npinned: false\n---\n\n# Semantic Search App (📄 → 🔗 → 🧠 → ❓ → 🔗 → 🤖)\n\nUpload a PDF, ask questions, and get context-aware answers powered by LangChain, ChromaDB, and NVIDIA/Google LLMs — all wrapped in a clean Gradio interface.\n\n🔗 **Live Demo**: [Semantic Search App](https://huggingface.co/spaces/frkhan/semantic-search-app)\n\n### 📖 Read the Full Story\n\nWant to learn more about the journey behind building this project? Check out the full story on Medium:\n\n- [**When the Credits Ran Out, Curiosity Didn’t: A Journey into LLMs, AI Agents \u0026 RAG**](https://frkhan.medium.com/when-the-credits-ran-out-curiosity-didnt-a-journey-into-llms-ai-agents-rag-6fcd5299c49a)\n---\n\n\n### 🚀 Features\n\n- 📄 Upload and process PDF documents  \n- 🔍 Perform semantic search using vector embeddings  \n- 🤖 Get answers from powerful LLMs (NVIDIA or Google Gemini)  \n- 🧠 Uses LangChain + ChromaDB for retrieval  \n- 📈 Integrated with Langfuse for tracing and observability.\n- 🧰 Docker-ready and Hugging Face Spaces–compatible  \n\n---\n\n### 🛠️ Tech Stack\n\n| Component        | Purpose                                 |\n|------------------|-----------------------------------------|\n| LangChain        | Orchestration of embedding + LLM calls  |\n| ChromaDB         | Vector database for semantic retrieval  |\n| NVIDIA / Gemini  | Embedding + LLM APIs                    |\n| Gradio           | Interactive UI                          |\n| Langfuse         | Tracing and Observability               |\n| Docker           | Containerized deployment                |\n\n---\n\n\n\n## 📦 Installation\n\n### Option 1: Run Locally\n\n```bash\ngit clone https://github.com/KI-IAN/semantic-search.git\ncd semantic-search\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n```\n\n\nCreate a .env file in the root directory:\n\n```env\nGOOGLE_API_KEY=your_google_api_key\nNVIDIA_API_KEY=your_nvidia_api_key\nCHROMA_DIR=./chroma_db\nLANGFUSE_PUBLIC_KEY=your_langfuse_public_key\nLANGFUSE_SECRET_KEY=your_langfuse_secret_key\nLANGFUSE_HOST=https://cloud.langfuse.com\n```\n\nThen run:\n\n```bash\npython app.py\n```\n\n---\n\n### Option 2: Run with Docker\n\n```bash\n# To Run in Live environment. It automatically uses the docker-compose.yml\ndocker-compose up --build \n\n# Or If you use the latest docker compose command, use the following\n\ndocker compose up --build\n```\n\nAccess the app at http://localhost:12100\n\n---\n\n\n```bash\n# To Run in local environment use docker-compose.dev.yml if you want to reflect your code changes without rebuilding docker container\ndocker-compose -f docker-compose.dev.yml up --build\n\n# Or If you use the latest docker compose command, use the following\ndocker compose -f docker-compose.dev.yml up --build\n\n```\n\nAccess the app at http://localhost:12100\n\n\n\n---\n\n### Option 3: Deploy on Hugging Face Spaces\n\nCreate a new Space → choose Gradio as the SDK\n\nUpload your project files (including app/, Dockerfile, requirements.txt, .env)\n\nSet Secrets in the “Secrets” tab:\n\nGOOGLE_API_KEY\n\nNVIDIA_API_KEY\n\n(Optional) CHROMA_DIR (defaults to ./chroma_db)\n\nHugging Face will auto-detect and launch the app via Gradio\n\n---\n\n## 🔑 Getting API Keys\n\nTo use this app, you'll need API keys for both **Gemini** and **NVIDIA NIM**. Here's how to obtain them:\n\n### 🌐 Gemini API Key\nGemini is Google's family of generative AI models. To get an API key:\n\n1. Visit the [Google AI Studio](https://aistudio.google.com/api-keys).\n2. Sign in with your Google account.\n3. Click **\"Create API Key\"** and copy the key shown.\n4. Use this key in your `.env` file or configuration as `GEMINI_API_KEY`.\n\n\u003e Note: Gemini API access may be limited based on region or account eligibility. Check the Gemini API [Rate Limits here](https://ai.google.dev/gemini-api/docs/rate-limits)\n\n### 🚀 NVIDIA NIM API Key\nNIM (NVIDIA Inference Microservices) provides hosted models via REST APIs. To get started:\n\n1. Go to the [NVIDIA API Catalog](https://build.nvidia.com/?integrate_nim=true\u0026hosted_api=true\u0026modal=integrate-nim).\n2. Choose a model (e.g., `nim-gemma`, `nim-mistral`, etc.) and click **\"Get API Key\"**.\n3. Sign in or create an NVIDIA account if prompted.\n4. Copy your key and use it as `NVIDIA_NIM_API_KEY` in your environment.\n\n\u003e Tip: You can test NIM endpoints directly in the browser before integrating.\n\n---\n\nOnce you have both keys, store them securely and never commit them to version control.\n\n---\n\n\n### 🧪 How to Use\nUpload a PDF — drag and drop your document\n\nClick “📄 Process Document” — the app will split, embed, and store the content\n\nEnter a query — ask a question like:\n\n“What are the key findings?”\n\n“Summarize the methodology.”\n\n“What does the report say about climate change?”\n\nClick “🔍 Ask a Question” — get semantic search results and an LLM-generated answer\n\n---\n\n### ⚙️ Configuration\nAll secrets are loaded from .env or Hugging Face Secrets tab:\n\n| Variable        | Description                                 |\n|------------------|-----------------------------------------|\n| GOOGLE_API_KEY        | Gemini LLM API key  |\n| NVIDIA_API_KEY         | NVIDIA LLM API key  |\n| CHROMA_DIR  | Path to store Chroma vector DB                    |\n\n---\n\n### 🧩 Customization\n\nSwitch between NVIDIA and Gemini embeddings in process_pdf()\n\nChange LLM model in search_query() (bytedance/seed-oss-36b-instruct, gemini-2.5-pro, etc.)\n\nTune chunk size and overlap in RecursiveCharacterTextSplitter\n\nAdd dropdowns to UI for model selection (optional)\n\n---\n\n### 📁 File Structure\n\n```Code\nsemantic-search/\n├── .env \n├── .github/\n├── .gitignore\n├── docker-compose.yml\n├── docker-compose.dev.yml\n├── Dockerfile\n├── requirements.txt\n├── app.py\n├── config.py\n```\n\n\u003e .env file is not tracked in git. Use it only for local development and do not push it to git if you save secrets there.\n\n---\n\n## 📜 License\n\nThis project is open-source and distributed under the **[MIT License](https://opensource.org/licenses/MIT)**. Feel free to use, modify, and distribute it with attribution.\n\n---\n\n\n## 🤝 Acknowledgements\n\n- [LangChain](https://www.langchain.com) — Powerful framework for orchestrating LLMs, embeddings, and retrieval pipelines.\n- [ChromaDB](https://www.trychroma.com/) — Fast and flexible open-source vector database for semantic search.\n- [NVIDIA AI Endpoints](https://build.nvidia.com/models) — Hosted LLM and embedding APIs including Seed OSS and NV-Embed.\n- [Google Gemini](https://aistudio.google.com/welcome) — Robust multimodal LLM platform offering text embeddings and chat models.\n- [Gradio](https://www.gradio.app) — Simple and elegant Python library for building machine learning interfaces.\n- [PyMuPDF](https://pymupdf.readthedocs.io) — Lightweight PDF parser for fast and accurate text extraction.\n- [Docker](https://www.docker.com) — Containerization platform for reproducible deployment across environments.\n- [Hugging Face Spaces](https://huggingface.co/spaces) — Free hosting platform for ML demos with secret management and GPU support.\n-   [Langfuse](https://langfuse.com/) for providing excellent observability tools.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fki-ian%2Fsemantic-search","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fki-ian%2Fsemantic-search","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fki-ian%2Fsemantic-search/lists"}