Skip to main content
This guide will help you set up and run your first semantic search query in minutes.

​
Prerequisites

Before you begin, ensure you have:
  • Python 3.11 or higher installed
  • Docker and Docker Compose installed
  • API keys from Google (Gemini) and Anthropic (Claude)
You’ll need API keys from both providers to enable the multi-LLM failover feature. Get your keys from:

​
Quick setup

1

Clone the repository

git clone https://github.com/Pama205/sku-semantic-search.git
cd sku-semantic-search
2

Create environment file

Create a .env file in the project root:
PROJECT_NAME="SKU Semantic Search"
VERSION="1.0.0"
DATABASE_URL="postgresql://skuuser:skupass@localhost:5435/skudb"
GEMINI_API_KEY="your_gemini_api_key_here"
ANTHROPIC_API_KEY="your_anthropic_api_key_here"
JWT_SECRET="your-secret-key-min-32-characters-long"
Never commit your .env file to version control. It contains sensitive credentials.
3

Start the database

The project uses PostgreSQL with the pgvector extension:
docker-compose up -d db
This starts PostgreSQL with pgvector on port 5435.
4

Install Python dependencies

Create a virtual environment and install dependencies:
python -m venv venv
source venv/bin/activate  # On Windows: .\venv\Scripts\Activate
pip install -r requirements.txt
5

Start the API server

python -m uvicorn app.main:app --reload
The API will be available at http://localhost:8000.

​
Make your first API call

Now that your server is running, let’s test the semantic search functionality.

​
Create a product

First, create a product with a description: 
curl -X POST "http://localhost:8000/products/" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Professional Floor Mop",
    "description": "Heavy-duty microfiber mop for cleaning hardwood and tile floors",
    "category": "cleaning"
  }'
The API automatically generates a 3072-dimensional embedding vector from the product description using Google Gemini. Response: 
{
  "id": 1,
  "name": "Professional Floor Mop",
  "description": "Heavy-duty microfiber mop for cleaning hardwood and tile floors",
  "category": "cleaning"
}
Now search using natural language - notice we’re not using the exact product name: 
curl -X POST "http://localhost:8000/products/search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "something to clean my kitchen floor",
    "limit": 5
  }'
Response: 
{
  "query": "something to clean my kitchen floor",
  "recommendation": "[GOOGLE - models/gemini-2.5-flash] Based on your query, I recommend the Professional Floor Mop. This heavy-duty microfiber mop is ideal for cleaning hardwood and tile floors, making it perfect for your kitchen.",
  "results": [
    {
      "id": 1,
      "name": "Professional Floor Mop",
      "description": "Heavy-duty microfiber mop for cleaning hardwood and tile floors",
      "category": "cleaning"
    }
  ]
}
Notice how the system understood “clean my kitchen floor” and returned the mop product, even though the query didn’t contain the word “mop”. This is the power of semantic search!

​
How it works

When you perform a semantic search:
  1. Embedding generation: Your query “something to clean my kitchen floor” is converted to a 3072-dimensional vector using Google Gemini
  2. Vector similarity search: PostgreSQL with pgvector finds products whose embedding vectors are most similar using cosine distance
  3. RAG (Retrieval-Augmented Generation): The top matching products are passed as context to the LLM
  4. AI recommendation: Gemini (or Claude if Gemini fails) generates a natural language recommendation based only on the retrieved products

​
Seed sample data

To test with more products, run the seed script: 
python seed_data.py
This populates your database with sample SKU products across various categories.

​
Next steps

Architecture overview

Learn how the RAG pattern and vector search work together

Environment setup

Configure advanced settings and environment variables

API reference

Explore all available endpoints

Docker deployment

Deploy the full stack with Docker Compose

Build docs developers (and LLMs) love

Get started for freeTalk to us