Semantic Search Skill

Search products using natural language with Azure OpenAI embeddings.

Overview

This skill enables semantic search across the Zava product catalog. Users can search using natural language queries like "womens summer athletic wear" and get relevant results even if exact keywords don't match.

How It Works

•Pre-computed Embeddings: All products have embeddings stored in embeddings.json
•Query Embedding: User query is converted to an embedding via Azure OpenAI
•Similarity Search: Cosine similarity finds the most relevant products
•Ranked Results: Products returned sorted by relevance score

Usage

Command Line

bash

# Search for products
python .github/skills/semantic-search/agent.py "womens summer workout clothes"

# Regenerate all product embeddings
python .github/skills/semantic-search/agent.py --reindex

API Endpoint

bash

POST /api/search
Content-Type: application/json

{"query": "warm winter jacket for skiing"}

Response

json

{
  "query": "warm winter jacket for skiing",
  "results": [
    {
      "name": "Insulated Ski Jacket",
      "category": "Outerwear",
      "unitPrice": 180.0,
      "score": 0.92
    },
    {
      "name": "Thermal Cycling Jacket",
      "category": "Outerwear", 
      "unitPrice": 110.0,
      "score": 0.85
    }
  ]
}

Example Queries

Query	Expected Top Results
"womens summer clothes"	Summer Pro Performance Tee, Endurance Cycling Shorts
"cold weather gear"	Insulated Ski Jacket, Snow Trail Gloves, Thermal Cycling Jacket
"running shoes"	Lightweight Running Shoes
"gym bag"	Team Sports Backpack
"warm layers"	All-Weather Base Layer, Corporate Training Hoodie

Files

File	Purpose
`agent.py`	Main skill logic
`embeddings.json`	Pre-computed product embeddings
`SKILL.md`	This documentation

Configuration

Uses Azure OpenAI with:

•Endpoint: AZURE_OPENAI_ENDPOINT environment variable
•Model: text-embedding-ada-002
•Authentication: DefaultAzureCredential (Managed Identity)

Regenerating Embeddings

Run this when products.json changes:

bash

python .github/skills/semantic-search/agent.py --reindex

This will:

•Load all products from data/products.json
•Create text representation of each product
•Generate embeddings via Azure OpenAI
•Save to embeddings.json