| name | commerce-vector-search |
| description | Perform semantic and keyword search across products, customers, orders, and inventory. Use when searching by natural language queries, finding similar items, or doing hybrid semantic plus keyword search. |
Commerce Vector Search
Hybrid semantic and keyword search across commerce entities using OpenAI embeddings and BM25 full-text search.
How It Works
- Generate embeddings for products, customers, orders, and inventory items.
- Store embeddings in dedicated tables with metadata.
- Search using natural language queries that combine semantic similarity and keyword matching.
- Results are ranked by combined relevance score.
- Filter by entity type and minimum score threshold.
Usage
- MCP tools:
search_products, search_customers, search_orders, search_inventory, get_embedding_stats.
- Embedding model: OpenAI
text-embedding-3-small (1536 dimensions).
- BM25 full-text via SQLite FTS5.
Searchable Entities
- Products: name, description, attributes, category
- Customers: name, email, company, notes
- Orders: order details, item names, notes
- Inventory: SKU, product name, location, notes
Scoring
- Semantic similarity: cosine distance converted to score (1.0 = exact match)
- BM25 keyword: traditional term-frequency scoring
- Combined ranking for hybrid search results
min_score threshold to filter low-relevance results
Output
{"results":[{"entity_type":"product","entity_id":"prod_456","score":0.92,"name":"Wireless Bluetooth Headphones"},{"entity_type":"product","entity_id":"prod_789","score":0.87,"name":"Noise Cancelling Earbuds"}]}
Present Results to User
- Ranked list of matching entities with relevance scores.
- Entity type and key details (name, SKU, email, etc.).
- Total results found and search query used.
- Embedding statistics (total embeddings by entity type).
Troubleshooting
- No results: check that embeddings have been generated for the entity type.
- Low relevance scores: refine the search query or lower the min_score threshold.
- Missing embeddings: run embedding generation for new or updated entities.
- API key error: verify OpenAI API key in embedding configuration.
References
- references/vector-search-config.md
- /home/dom/stateset-icommerce/crates/stateset-core/src/models/vector.rs
- /home/dom/stateset-icommerce/crates/stateset-embedded/src/vector.rs
