{"id":29672648,"url":"https://github.com/nmdra/semantic-search","last_synced_at":"2026-05-19T03:08:50.225Z","repository":{"id":305111591,"uuid":"1021046186","full_name":"nmdra/Semantic-Search","owner":"nmdra","description":"Semantic search implementation with PgVector and Gemini Text Embedding ","archived":false,"fork":false,"pushed_at":"2025-07-18T08:24:00.000Z","size":38,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-18T12:09:20.127Z","etag":null,"topics":["db-migration","echo-framework","full-text-search","gemini-api","golang","pgvector","postgresql","semantic-search","text-embedding"],"latest_commit_sha":null,"homepage":"","language":"Go","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/nmdra.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}},"created_at":"2025-07-16T19:45:18.000Z","updated_at":"2025-07-18T08:07:27.000Z","dependencies_parsed_at":"2025-07-20T22:16:46.891Z","dependency_job_id":null,"html_url":"https://github.com/nmdra/Semantic-Search","commit_stats":null,"previous_names":["nmdra/semantic-search"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/nmdra/Semantic-Search","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmdra%2FSemantic-Search","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmdra%2FSemantic-Search/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmdra%2FSemantic-Search/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmdra%2FSemantic-Search/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nmdra","download_url":"https://codeload.github.com/nmdra/Semantic-Search/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmdra%2FSemantic-Search/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266572776,"owners_count":23950092,"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-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"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":["db-migration","echo-framework","full-text-search","gemini-api","golang","pgvector","postgresql","semantic-search","text-embedding"],"created_at":"2025-07-22T21:06:58.767Z","updated_at":"2026-05-19T03:08:50.200Z","avatar_url":"https://github.com/nmdra.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Semantic Book Search with Go, pgvector, and Gemini API \u003cimg src=\"https://github.com/egonelbre/gophers/blob/master/.thumb/animation/gopher-dance-long.gif?raw=true\" alt=\"Gopher Dancing\" width=\"30\"/\u003e\n\n[![Release with GoReleaser](https://github.com/nmdra/Semantic-Search/actions/workflows/release.yaml/badge.svg)](https://github.com/nmdra/Semantic-Search/actions/workflows/release.yaml)\n[![golangci-lint](https://github.com/nmdra/Semantic-Search/actions/workflows/golangci-lint.yaml/badge.svg)](https://github.com/nmdra/Semantic-Search/actions/workflows/golangci-lint.yaml)\n[![Go Version](https://img.shields.io/badge/go-1.25-blue.svg)](https://golang.org/dl/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Docker Image](https://img.shields.io/badge/docker-ghcr.io%2Fnmdra%2Fsemantic--search-blue?logo=docker)](https://ghcr.io/nmdra/semantic-search)\n\nA Golang-based API for semantic search over a book dataset using vector embeddings. Books are embedded using the Gemini API and stored in PostgreSQL with `pgvector`, enabling fast, meaningful similarity search via approximate nearest neighbor indexing (IVFFLAT). Built with Echo, `sqlc`, `go-migrate`, and `pgx`.\n\n```mermaid\nC4Context\n  title System Context Diagram for Book Semantic Search\n  Enterprise_Boundary(b0, \"Book Search Platform\") {\n    Person(user, \"Book Searcher\", \"User searching for books\")\n    System(api, \"Semantic Search API\", \"Go service for searching books via embeddings and semantic queries\")\n    SystemDb(db, \"PostgreSQL + pgvector\", \"Stores books and vector embeddings\")\n    System_Ext(gemini, \"Gemini API\", \"External API for generating text embeddings\")\n\n    Rel(user, api, \"Uses\", \"HTTP\\n/Books (POST)\\n/Search (GET)\")\n    Rel(api, db, \"Reads \u0026 writes\", \"pgx (SQL)\")\n    Rel(api, gemini, \"Requests text embeddings\", \"Embed API\")\n    Rel(gemini, api, \"Returns embeddings\", \"Embedding Response\")\n    Rel(db, api, \"Returns Books/Search Results\")\n  }\n  UpdateRelStyle(user, api, $offsetY=\"-40\", $offsetX=\"30\")\n  UpdateRelStyle(api, db, $offsetY=\"50\", $offsetX=\"-35\")\n  UpdateRelStyle(api, gemini, $offsetY=\"-30\", $offsetX=\"-40\")\n  UpdateRelStyle(gemini, api, $offsetY=\"0\", $offsetX=\"80\")\n  UpdateRelStyle(db, api, $offsetY=\"40\", $offsetX=\"50\")\n  UpdateLayoutConfig($c4ShapeInRow=\"3\", $c4BoundaryInRow=\"1\")\n````\n\n\u003e \\[!CAUTION]\n\u003e This project is intended for learning and demonstration purposes only.\n\u003e While it tries to follow best and security practices, it may contain errors or incomplete implementations.\n\n## Features\n\n* **Semantic Search** — Search books by semantic similarity using vector embeddings\n* **Gemini API Integration** — Generates high-quality embeddings via Google's Gemini API\n* **PostgreSQL + pgvector** — Efficient storage and approximate nearest neighbor search\n* **Redis-powered Cache** — Speeds up repeated search queries with vector caching\n* **Run Migrations via CLI** — Run `-migrate` to apply database schema changes at startup\n* **Multi-Platform Support** — Build and release for Linux, macOS, Windows, amd64, and arm64\n* **Docker \u0026 GitHub Container Registry** — Easy deployment with multi-arch Docker images\n* **Automated Releases** — GitHub Actions + GoReleaser for continuous delivery\n\n## Getting Started\n\n### Prerequisites\n\n* Go 1.25+\n* PostgreSQL with `pgvector` extension installed\n* Gemini API Key ([Get API Key Here](https://aistudio.google.com/app/apikey))\n* Redis (for vector caching)\n* Docker (optional, for containerized deployment)\n\n### API Endpoints\n\n#### `POST /books`\n\nAdd a new book by providing its title, description, and ISBN.\nThe service generates and stores a **semantic embedding** and full-text index.\n\n#### `GET /search/vector?q=your+query`\n\nPerform a **semantic search** on stored books using vector similarity with the query.\nReturns books ranked by **cosine similarity** of embeddings.\n\n#### `GET /search/text?q=your+query`\n\nPerform a **full-text search** using PostgreSQL’s full-text index on title and description.\nReturns books ranked by **textual relevance (ts\\_rank)**.\n\n#### `GET /ping`\n\nHealth check endpoint to verify if the service is running.\n\n#### Example Usage\n\nSearch for books related to *Science fiction that describe Social Hierarchy*:\n\n```bash\ncurl -sG \"http://localhost:8080/search\" --data-urlencode \"q=Science fiction that describe Social Hierarchy\" | jq\n```\n\u003cimg width=\"1331\" height=\"705\" alt=\"image\" src=\"https://github.com/user-attachments/assets/d11a4a23-1260-4809-8416-bcf2986f5154\" /\u003e\n\n### Setup PostgreSQL\n\n1. Create your database:\n\nRun migrations:\n\n```bash\nmake migrate-up\n```\n\nOr via the binary:\n\n```bash\nsemantic-search-api -migrate=true\n```\n### Environment Variables\n\n```\nDATABASE_URL=postgres://user:password@localhost:5432/semantic_search?sslmode=disable\nGEMINI_API_KEY=your_gemini_api_key_here\nREDIS_URL=localhost:6379\n```\n\n### Running Locally\n\n```bash\ngo run ./cmd/main.go\n```\n\nAPI will be available at `http://localhost:8080`.\n\n### Docker\n\nRun Database migrations:\n\n```bash\ndocker run --rm \\\n  --network=host \\\n  ghcr.io/nmdra/semantic-search:latest \\\n  -apikey=\"$GEMINI_API_KEY\" \\\n  -db-dsn=\"$DATABASE_URL\" \\\n  -migrate\n```\n\nRun container:\n\n```bash\ndocker run --rm \\\n  --network=host \\\n  ghcr.io/nmdra/semantic-search:latest \\\n  -apikey=\"$GEMINI_API_KEY\" \\\n  -db-dsn=\"$DATABASE_URL\" \\\n  -redis=\"localhost:6379\" \\\n  -loglevel=\"warn\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnmdra%2Fsemantic-search","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnmdra%2Fsemantic-search","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnmdra%2Fsemantic-search/lists"}