AI features (Snap to Shop)

Two features read photos with AI:

• Snap to Shop (customer app): a customer photographs an item, such as a carton of milk or a phone charger, and the app shows matching products from stores that deliver to them.
• Snap to List (seller app): a seller photographs a product and gets a draft title, description, tags and price to check and save.

Both use one AI provider that you choose: Google Gemini or OpenAI. Without a key, both features stay off. The camera button is hidden in the customer app, and the seller app asks for the details by hand. RapidMart never shows guessed results.

Get a key

Gemini (recommended):

1. Go to Google AI Studio and sign in.
2. Select Create API key.
3. Set up billing on the key’s Google Cloud project before going live. The free tier is fine for testing, but it is rate limited.

OpenAI:

1. Go to OpenAI API keys and select Create new secret key.
2. Add a payment method under Billing.

Each photo search is one small vision call plus one embedding call. Your provider bills you for these at its own rates.

Add it to RapidMart

1. In the admin, go to Settings → AI.
2. Pick Gemini or OpenAI, and a model. The default models are a good balance of speed and cost.
3. Paste the key, then select Test. A successful test saves the provider, model and key.
4. In the Snap to Shop card, leave Enable visual product search on and save.

You can also put the key in .env as GEMINI_API_KEY or OPENAI_API_KEY. A key saved in the admin wins over the one in .env. A saved key is only ever sent to the provider it was saved for.

Catalog indexing

Snap to Shop compares the photo with every product. For that, each product needs an embedding, which is a list of numbers made from its title, category, tags and description. RapidMart keeps these up to date for you:

• When you first add a key, or switch provider, every product is indexed in the background.
• When a product is added or changed, it is re-indexed straight away.
• Every night at 03:00, anything missing is filled in.

The Snap to Shop card shows the progress, for example “120 of 151 products are ready for photo search”. Photo search works while indexing runs. Until a product is indexed, it can still be found by the words the AI reads from the photo.

Indexing runs on the queue, so the queue worker and scheduler must be running. To rebuild every product at once, for example after a large import, run:

php artisan products:reindex-embeddings --all

Without --all, the command only fills in the products that are missing or out of date.

Tuning

Similarity threshold (default 0.66): how close a product has to be to the photo to count as a visual match. If no product scores this high, the app shows text matches for what the AI read from the photo instead, labelled as closest matches. Raise it if customers see loose matches; lower it if good matches go missing.

Troubleshooting

The camera button doesn’t appear in the app. Check that the AI card shows a key, and that Enable visual product search is on. The app picks up the change the next time it opens.

“Photo search isn’t available” in the app. The server has no working key for the chosen provider. Run Test in Settings → AI.

“We couldn’t read that photo.” The provider rejected the call. The cause is usually an invalid key, missing billing or the free-tier rate limit. storage/logs/laravel.log has the provider’s exact message.

The card stays at “Indexing the catalog”. The queue worker isn’t running. Start it, or run php artisan products:reindex-embeddings once.