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
1---2name: commerce-vector-search3description: 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.4---5
6# Commerce Vector Search
7
8Hybrid semantic and keyword search across commerce entities using OpenAI embeddings and BM25 full-text search.
9
10## How It Works
11
121. Generate embeddings for products, customers, orders, and inventory items.
132. Store embeddings in dedicated tables with metadata.
143. Search using natural language queries that combine semantic similarity and keyword matching.
154. Results are ranked by combined relevance score.
165. Filter by entity type and minimum score threshold.
17
18## Usage
19
20- MCP tools: `search_products`, `search_customers`, `search_orders`, `search_inventory`, `get_embedding_stats`.
21- Embedding model: OpenAI `text-embedding-3-small` (1536 dimensions).
22- BM25 full-text via SQLite FTS5.
23
24## Searchable Entities
25
26- **Products**: name, description, attributes, category
27- **Customers**: name, email, company, notes
28- **Orders**: order details, item names, notes
29- **Inventory**: SKU, product name, location, notes
30
31## Scoring
32
33- Semantic similarity: cosine distance converted to score (1.0 = exact match)
34- BM25 keyword: traditional term-frequency scoring
35- Combined ranking for hybrid search results
36- `min_score` threshold to filter low-relevance results
37
38## Output
39
40```json
41{"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"}]}
42```
43
44## Present Results to User
45
46- Ranked list of matching entities with relevance scores.
47- Entity type and key details (name, SKU, email, etc.).
48- Total results found and search query used.
49- Embedding statistics (total embeddings by entity type).
50
51## Troubleshooting
52
53- No results: check that embeddings have been generated for the entity type.
54- Low relevance scores: refine the search query or lower the min_score threshold.
55- Missing embeddings: run embedding generation for new or updated entities.
56- API key error: verify OpenAI API key in embedding configuration.
57
58## References
59- references/vector-search-config.md
60- /home/dom/stateset-icommerce/crates/stateset-core/src/models/vector.rs
61- /home/dom/stateset-icommerce/crates/stateset-embedded/src/vector.rs
majiayu000