{"id":30621539,"url":"https://github.com/alwayssany/hybrid-search","last_synced_at":"2026-04-09T01:32:09.430Z","repository":{"id":311954527,"uuid":"1045306913","full_name":"AlwaysSany/hybrid-search","owner":"AlwaysSany","description":"A product search platform where users can browse, search, and filter products using a hybrid search mechanism that combines lexical and semantic techniques","archived":false,"fork":false,"pushed_at":"2025-08-27T17:21:49.000Z","size":1736,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-28T02:08:04.075Z","etag":null,"topics":["elasticsearch","fastapi","hybrid-search","lexical-search","python","react","vector-search"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","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/AlwaysSany.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-27T00:55:05.000Z","updated_at":"2025-08-27T17:24:18.000Z","dependencies_parsed_at":"2025-08-28T02:08:36.453Z","dependency_job_id":"f3338f0d-d354-4409-ab3a-54032c628773","html_url":"https://github.com/AlwaysSany/hybrid-search","commit_stats":null,"previous_names":["alwayssany/hybrid-search"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/AlwaysSany/hybrid-search","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlwaysSany%2Fhybrid-search","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlwaysSany%2Fhybrid-search/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlwaysSany%2Fhybrid-search/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlwaysSany%2Fhybrid-search/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlwaysSany","download_url":"https://codeload.github.com/AlwaysSany/hybrid-search/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlwaysSany%2Fhybrid-search/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272864646,"owners_count":25006040,"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-08-30T02:00:09.474Z","response_time":77,"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":["elasticsearch","fastapi","hybrid-search","lexical-search","python","react","vector-search"],"created_at":"2025-08-30T15:00:56.554Z","updated_at":"2025-12-30T21:34:49.123Z","avatar_url":"https://github.com/AlwaysSany.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hybrid Search Product Store (Front-end and API)\n\nThis project consists of two main components: a front-end application and an API. Together, they form a product search platform where users can browse, search, and filter products using a hybrid search mechanism that combines lexical and semantic techniques.\n\n## Working Demo\n\n![frontend_search_ui.png](frontend/public/frontend_search_ui.png)\n\n\n## Project Structure\n\n- **Front-end**: A React application responsible for displaying products, handling user interactions, and performing searches via the API.\n- **API**: A backend service that provides product data and search capabilities, including faceted filtering and hybrid search logic.\n\n### Front-end\n\n- Built with **React**.\n- Handles product display, search, and filtering.\n- Communicates with the API to retrieve and display products.\n  \n### API\n\n- Developed with Python\n- Provides endpoints for fetching product data and handling search/filter requests.\n- Implements hybrid search combining lexical and semantic search techniques.\n\n## Getting Started\n\n### Front-end Setup\n\n1. Read: [README.md](app-product-store%2FREADME.md)\n\n### API Setup\n\n1. Read: [README.md](product-store-search%2FREADME.md)\n\n---\n\n# Full Run Guide\n\nThis guide shows how to run the stack with or without Docker.\n\n## Prerequisites\n\n- Node.js 18+\n- Python 3.10+\n- Elasticsearch 9.x (via Docker or local install)\n\nDefault Elasticsearch dev credentials:\n- URL: http://localhost:9200\n- Username: elastic\n- Password: changeme\n\nThese are referenced in:\n- `backend/api/api.py` → `get_client_es()`\n- `backend/ingestion/ingestion.py` → `get_client_es()`\n- `backend/infra/create_index.py` → `get_client_es()`\n\n### Environment variables\n\nBackend loads settings from environment variables (via `python-dotenv`). Create `backend/.env` from the example:\n\n```bash\ncp backend/.env.example backend/.env\n```\n\nAvailable variables:\n\n```env\nES_HOST=http://localhost:9200\nES_USERNAME=elastic\nES_PASSWORD=changeme\n```\n\nThese are used by the API, ingestion, and index creation scripts.\n\n## Run with Docker (Recommended for ES)\n\n1) Start Elasticsearch + Kibana\n\n```bash\ncd backend/docker\ndocker compose up -d\n```\n\n- Elasticsearch: http://localhost:9200\n- Kibana: http://localhost:5601\n\n2) Create index and mappings\n\n```bash\ncd ../infra\nuv run create_index.py\n```\n\n3) Ingest dataset with vectors\n\n```bash\ncd ../ingestion\nuv run ingestion.py\n```\n\n4) Run the backend API (FastAPI)\n\n```bash\ncd ../api\nuv sync\nuv run uvicorn api:app --host 127.0.0.1 --port 5000 --reload\n```\n\n5) Run the frontend (React)\n\n```bash\ncd ../../frontend\nnpm install\nnpm start\n```\n\nOpen http://127.0.0.1:3000 (frontend) → API at http://127.0.0.1:5000.\n\n## Run without Docker\n\n1) Install and start Elasticsearch 9.x locally with:\n\n- `xpack.security.enabled=true`\n- `discovery.type=single-node`\n- Heap (example): `-Xms4g -Xmx4g`\n\n2) Create index and ingest\n\n```bash\n# terminal A\ncd backend/infra\nuv run create_index.py\n\n# terminal B\ncd ../ingestion\nuv run ingestion.py\n```\n\n3) Start backend API\n\n```bash\ncd backend/api\nuv sync\nuv run uvicorn api:app --host 127.0.0.1 --port 5000 --reload\n```\n\n4) Start frontend\n\n```bash\ncd frontend\nnpm install\nnpm start\n```\n\n## Endpoints (Backend)\n\n- `GET /api/products/search` — query with optional facets and `hybrid=true`\n- `GET /api/products/facets` — facet counts\n- `GET /api/products/id/{product_id}` — product details\n- `GET /api/products/suggest` — autocomplete\n\n## Troubleshooting\n\n- If API can’t reach ES: check `localhost:9200`, credentials, and index creation.\n- Hybrid search errors: ensure index created via `backend/infra/create_index.py` and data ingested.\n- Frontend CORS/issues: API runs on 127.0.0.1:5000; URLs are hard-coded in `frontend/src/App.js`.\n- Slow ingestion: first run downloads `sentence-transformers/all-MiniLM-L6-v2` model.\n\n## Quickstart Script (copy/paste)\n\n```bash\ncd backend/docker \u0026\u0026 docker compose up -d \\\n\u0026\u0026 cd ../infra \u0026\u0026 uv run create_index.py \\\n\u0026\u0026 cd ../ingestion \u0026\u0026 uv run ingestion.py \\\n\u0026\u0026 cd ../api \u0026\u0026 uv sync \u0026\u0026 uv run uvicorn api:app --host 127.0.0.1 --port 5000 --reload\n```\n\nIn another terminal:\n\n```bash\ncd frontend \u0026\u0026 npm install \u0026\u0026 npm start\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falwayssany%2Fhybrid-search","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falwayssany%2Fhybrid-search","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falwayssany%2Fhybrid-search/lists"}