spree_menu_chat 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e773d5fcf8ca557cd5fc7cb58930c80ebeb82a9a2d4d9adc1ee06a0743fac99c
+  data.tar.gz: f86c96e4b2212539847eb6f2786b90d71047c4dffd87ecd6562e176d15a2e27a
+SHA512:
+  metadata.gz: '0941702474b90131942c7e33d83826d84bbfe77fb89b8f5cb554d92406905b1b665b925bee32828337b47fb61ea3b01447b2ae8b70f1e91120b3ef2c59068749'
+  data.tar.gz: 5668abbbbcffdc651d591849f1e4c98dca3b11622bfa8501c2b7f0b0a2fb3b88db0134f068aadb8bcfb9d3210cc2e79ffe29fb0501a9761a4ed9fd0848987ed7

data/.env

@@ -0,0 +1,7 @@
+# Loaded via `dotenv/load` in spec/spec_helper.rb, for the dummy test app
+# only — not read by anything that ships. Test-only Active Record Encryption
+# keys (SpreeMenuChat::Credential) so specs can save/load encrypted columns;
+# generated with SecureRandom, no real secret behind them.
+ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=NRCoSclmJmMJNmoyFqWPrH5fdkeL2tox
+ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=qdzUbi7VbUaAqmTDn7qHHnaXxlN1CE1u
+ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=HxVDWyTgl04erZuEZCqd7nhVmHtkIRFJ

data/.env.local.example

@@ -0,0 +1,12 @@
+# Copy this file to .env.local (gitignored) and fill in real keys to run
+# this extension's manual verification rake tasks against the live APIs.
+#
+# Gemini — free key at https://aistudio.google.com, no billing account
+# required for the free tier (see README.md). Used by
+# spree_menu_chat:verify_connection.
+GEMINI_API_KEY=
+
+# Voyage AI — free key at https://www.voyageai.com, first 200M tokens free
+# per account (see README.md). Used by M2's embedding pipeline and its own
+# verify_embeddings rake task.
+VOYAGE_API_KEY=

data/.github/workflows/test.yml

@@ -0,0 +1,111 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test-postgres:
+    name: "PostgreSQL"
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        # pgvector/pgvector, not plain postgres — this extension's embeddings
+        # table (landing in M2) needs `CREATE EXTENSION vector`, which the
+        # official postgres image doesn't ship. Using this image from M1
+        # onward avoids a CI-only migration later.
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      DB: postgres
+      DB_HOST: localhost
+      DB_USERNAME: postgres
+      DB_PASSWORD: postgres
+      BUNDLE_JOBS: 4
+      BUNDLE_RETRY: 3
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Install libvips
+        run: sudo apt-get update && sudo apt-get install -y libvips-dev
+
+      - name: Create test app
+        run: bundle exec rake test_app
+
+      - name: Run tests
+        run: bundle exec rspec --format documentation
+
+  test-mysql:
+    name: "MySQL"
+    runs-on: ubuntu-latest
+    services:
+      mysql:
+        image: mysql:8.0
+        env:
+          MYSQL_ROOT_PASSWORD: password
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd="mysqladmin ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      DB: mysql
+      DB_HOST: 127.0.0.1
+      DB_USERNAME: root
+      DB_PASSWORD: password
+      BUNDLE_JOBS: 4
+      BUNDLE_RETRY: 3
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Install libvips
+        run: sudo apt-get update && sudo apt-get install -y libvips-dev
+
+      - name: Create test app
+        run: bundle exec rake test_app
+
+      - name: Run tests
+        run: bundle exec rspec --format documentation
+
+  brakeman:
+    name: Brakeman
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Run Brakeman
+        run: bundle exec brakeman --exit-on-warn --exit-on-error

data/.gitignore

@@ -0,0 +1,27 @@
+\#*
+*~
+.#*
+.DS_Store
+.idea
+.localeapp/locales
+.project
+.vscode
+coverage
+default
+Gemfile.lock
+tmp
+nbproject
+pkg
+*.sw?
+spec/dummy
+.rvmrc
+.sass-cache
+public/spree
+.ruby-version
+.ruby-gemset
+*.gem
+*/*.gem
+
+# Real Gemini/Voyage API keys for manual verification — never committed,
+# unlike the test-only encryption keys in .env.
+.env.local

data/.rspec

@@ -0,0 +1,3 @@
+--color
+-r spec_helper
+-f documentation

data/CHANGELOG.md

@@ -0,0 +1,164 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## 0.1.0 (unreleased)
+
+Initial development. M1 (foundation) — `SpreeMenuChat::Credential` (encrypted per-store Gemini +
+Voyage AI API keys), `SpreeMenuChat::LlmClient` (Gemini `generateContent` REST calls — no official
+Ruby SDK exists for the Gemini API, same "plain REST" situation `spree_doordash` already handles
+for DoorDash's Drive API), and a plain credential-entry admin form.
+
+One real bug caught only by `spree_menu_chat:verify_connection` against a genuinely fresh Gemini
+API key, not by the spec suite (which stubs the request and never touches Google's model
+availability): the pinned model `gemini-2.5-flash-lite` returned a real `404 "no longer available
+to new users"` — despite still being listed by the `models.list` endpoint, which apparently doesn't
+reflect real per-account availability. Fixed by switching the default `generation_model` from a
+pinned dated model string to the `gemini-flash-lite-latest` alias (currently resolves to
+`gemini-3.5-flash-lite`, confirmed live), which should avoid this exact rot going forward.
+
+M2 (pgvector + embeddings pipeline) — `SpreeMenuChat::Embedding` (polymorphic, `has_neighbors`),
+`SpreeMenuChat::EmbeddingClient` (Voyage `embeddings` REST calls), `ContentBuilder`, `Embedder`,
+`ReembedProductJob`/`ReembedCatalogJob`, the `Spree::Product` re-embed hook, and
+`spree_menu_chat:reembed_all`.
+
+Three real bugs found only by running `reembed_all` against `spree_host`'s actual, live,
+Square-synced catalog (39 products, 4 policies) — none of them visible to this gem's own isolated,
+SQLite-backed dummy-app spec suite:
+
+- `neighbor`'s `t.vector` migration helper raised `NoMethodError` — it's only a gemspec
+  (transitive) dependency of this gem, and `Bundler.require` doesn't auto-require those. Fixed with
+  an explicit `require 'neighbor'` in `lib/spree_menu_chat.rb`.
+- `SpreeMenuChat::EmbeddingClient::RequestError` raised `NameError: uninitialized constant` under
+  `rails runner`'s lazy autoloading, despite passing every spec (Zeitwerk's `eager_load_all`, which
+  `spec/zeitwerk_spec.rb` exercises, loads every file regardless of order and masked the bug). Root
+  cause: it was defined as a second class inside `llm_client.rb` instead of its own file. Fixed by
+  giving it its own `app/services/spree_menu_chat/request_error.rb`.
+- `ContentBuilder#modifier_summary` called `SpreeSquare::Modifier#display_price`, a method that
+  doesn't exist on that model (only a JSON key of the same name in `SpreeSquare::ProductSerializer`)
+  — raised `NoMethodError` on every product with a real Square modifier list attached. Invisible to
+  this gem's own specs because the dummy app never has `spree_square` installed at all (the
+  `defined?` soft-dependency guard short-circuits before reaching this code). Fixed to call the
+  model's real `#price` method instead, formatted as a plain `+$X.XX` string; added a regression
+  spec that stubs the `SpreeSquare` constants so this exact path is exercised going forward without
+  taking a hard gemspec dependency on `spree_square`.
+
+Also discovered live, not a code bug but a real operating constraint worth documenting plainly:
+Voyage AI accounts with no payment method on file are capped at 3 requests/minute, 10K
+tokens/minute — separate from, and far tighter than, the genuinely generous 200M free-token
+allowance. A tight per-record loop over even a ~40-item menu hits this within the first few calls.
+`EmbeddingClient` now self-throttles every request to that limit (tracking this process's own
+recent request timestamps, sleeping proactively before the next call would exceed it) rather than
+firing calls as fast as the caller loops and hoping `ReembedCatalogJob`'s job-level `retry_on`
+eventually catches up — see the class comment on `SpreeMenuChat::EmbeddingClient` for the full
+reasoning, including why an earlier reactive-retry-only version of this fix undershot in practice.
+
+M3 (retrieval + generation, no streaming) — `SpreeMenuChat::Retriever` (embeds the question with
+Voyage's `query` input type, pgvector cosine-distance search scoped to the store, filters below the
+configured similarity floor, caps at `retrieval_top_k`), `SpreeMenuChat::AnswerGenerator` (builds a
+menu/FAQ-scoped system prompt, injects retrieved context, calls Gemini; returns a canned
+"contact us" fallback — using the store's real `customer_support_email`/`contact_phone` — whenever
+retrieval finds nothing above the floor or Gemini fails, rather than a raw error or a hallucinated
+answer), and `SpreeMenuChat::ChatController` (`POST /menu_chat/chat`, authenticated with the store's
+Storefront publishable key — the same `pk_...` key type `spree_api`'s Store API accepts).
+
+The read-only guardrail is enforced structurally, not just described in the system prompt:
+`AnswerGenerator` never builds or passes a `tools`/function-declarations argument to
+`LlmClient#generate`, and no write-capable Spree model is referenced anywhere in the request path —
+covered by a spec that inspects the real outgoing Gemini request body for the absence of a `tools`
+key.
+
+One real calibration bug, again only found by curling real questions against the real synced
+catalog: the originally-planned `similarity_floor` default of 0.7 (max cosine distance 0.3) was
+picked speculatively, before ever querying real embeddings, and was badly miscalibrated. Real
+Voyage cosine distances for genuinely correct, on-topic matches ranged 0.32-0.63 across a set of
+real test questions — a 0.7 floor rejected nearly all of them, meaning the assistant would have
+given the canned fallback for almost every real, answerable question ("what comes with the buffalo
+wings?" initially returned "I don't have information about that," despite Buffalo Wings being a
+real menu item with a real matching description). Fixed by lowering the default to 0.35, based on
+that live calibration data; a genuinely off-topic/unanswerable question in the same test batch
+landed at 0.76 distance, comfortably excluded with margin to spare. See the class comment on
+`SpreeMenuChat::Configuration` for the full data.
+
+Manually verified against the real dev app: real curl'd questions ("what comes with the buffalo
+wings?", "do you have vegetarian options?", "is the chicken parmesan spicy?") return accurate,
+grounded answers; a request to place an order is correctly refused while still answering the
+underlying menu question; a genuinely off-topic question ("what is the capital of France?")
+triggers the no-context fallback rather than a hallucinated answer.
+
+M4 (streaming) — `SpreeMenuChat::LlmClient#generate_stream` (Gemini's `streamGenerateContent?alt=sse`
+endpoint, via Faraday's `on_data` streaming callback), `SpreeMenuChat::AnswerGenerator.stream` (yields
+each real fragment as Gemini produces it, or the same canned fallback as a single fragment if there's
+no context/generation fails), and `SpreeMenuChat::ChatController` now streams SSE
+(`ActionController::Live`) instead of returning one JSON blob — the storefront widget's Next.js proxy
+streams the response straight through unmodified.
+
+**One serious real bug, found only by curling the live streaming endpoint against the real Gemini
+API** — every spec passed and it looked completely broken in practice. `LlmClient#generate_stream`'s
+SSE frame parser searched for a literal `"\n\n"` to split `data: <json>` frames — matching this gem's
+own hand-written WebMock fixtures (which used bare `\n`, the natural-looking assumption) but not
+Gemini's real wire format, which uses `\r\n` line endings. The parser never found a match, so every
+real streaming request silently yielded zero chunks and zero errors — no exception, nothing logged —
+and `AnswerGenerator.stream`'s "Gemini never yielded any text" guard quietly substituted the canned
+"I don't have that" fallback for every single real question, including ones with a perfect context
+match. Because the WebMock fixtures shared the same wrong assumption as the code under test, the spec
+suite was self-consistently green throughout — this is exactly the failure mode this project's
+"verify against real infrastructure" standard exists to catch, and did. Fixed by normalizing `\r\n` to
+`\n` before splitting; the fixtures were also corrected to use `\r\n` so they now test the real wire
+format instead of re-testing the same wrong assumption.
+
+Verified: 75/75 specs green, Brakeman clean. Live-verified end to end after the fix: `curl -N` against
+the real streaming endpoint for "what desserts do you have?" (previously silently falling back)
+correctly streams three real SSE fragments naming actual real menu items, followed by a `done` event;
+a genuinely off-topic question still correctly streams the no-context fallback as a single fragment.
+
+M5 (guardrails) — `SpreeMenuChat::RateLimiter` (Postgres-backed fixed-window counter,
+`rate_limit_per_hour` requests per (store, IP) — no Redis anywhere in this stack, same rationale as
+Solid Queue running inside Postgres) and `SpreeMenuChat::TokenBudget` (Postgres-backed daily cap on
+Gemini generation tokens per store, using Gemini's own reported `usageMetadata.totalTokenCount`, not
+an estimate). `ChatController` checks the rate limit before opening the SSE stream (a real 429 JSON
+error, not a raw exception or a broken stream); `AnswerGenerator` checks the token budget before
+even retrieval, and skips straight to a distinct "we've reached today's limit" fallback once
+exhausted, same as the existing no-context fallback but honestly worded for this different reason.
+`LlmClient#generate_stream` now returns Gemini's final reported token total (each SSE frame's
+`usageMetadata` carries a running total; the last one seen is the true total for the turn) so
+`AnswerGenerator` can record real spend without estimating.
+
+Deliberately scoped to generation tokens only, not embedding tokens — see the class comment on
+`SpreeMenuChat::TokenBudget` for why folding in Voyage's query-embedding cost too was left as a
+follow-up rather than blocking this guardrail.
+
+Verified live against the real dev app, not just specs: a real chat question recorded its real
+Gemini-reported token count (393 tokens) against today's budget; simulating the rate limit already
+being at its configured cap made the next real request return a genuine `429` with a plain JSON
+error body (confirmed `Content-Type: application/json`, no SSE stream opened) instead of a raw
+error; simulating the daily token budget already being exhausted made the next real request stream
+the budget-exceeded fallback as a single SSE fragment with zero further Gemini spend (confirmed the
+stored token total was unchanged after). Also grepped the full `app/`/`lib/` tree to confirm neither
+a write-capable Spree model (`Spree::Order`, `Spree::LineItem`, `Spree::Cart`, ...) nor a
+`tools`/function-declarations argument is referenced anywhere outside this file's own comments —
+the read-only guardrail described since M3 is still structurally true, not just documented.
+
+M6 (admin visibility) — confirmed with the user before building: persist real conversation content
+(not just operational counters), since that's a data-retention decision the plan explicitly flagged
+rather than a default to build silently. `SpreeMenuChat::Conversation`/`SpreeMenuChat::Message`
+(anonymous, grouped by a 30-minute time-window heuristic on (store, IP) rather than an explicit
+client-sent session id — the widget has no session of its own, see `Conversation::SESSION_WINDOW`'s
+comment for the real tradeoff this makes), logged by `ChatController` after each SSE stream closes
+(best-effort — a logging failure is captured, never allowed to affect the response already sent).
+Admin nav position 72 (right after the M1 credential page at 71) and a read-only
+`Spree::Admin::MenuChatConversationsController` index — identifier, first question, message count,
+started/last-message timestamps — scoped to the current store via a `for_store` scope
+(`Admin::ResourceController#scope` picks this up automatically, no controller override needed).
+
+`new_resource: false` set on the table registration up front, not found the hard way a third time —
+both `spree_square` and `spree_doordash` hit and fixed the identical real bug (`new_admin_..._url`
+routing error on an empty read-only, index-only table) on their own first read-only admin pages.
+
+Verified against the real dev app, not the gem's own SQLite dummy-app suite (M6's own stated
+standard, and precisely where both sibling extensions' changelogs record real Postgres-only bugs
+invisible to specs): logged into the real admin, loaded the Conversations page **while genuinely
+empty** and confirmed the empty state renders cleanly (no routing error); sent a real chat question
+through the live endpoint, reloaded, and confirmed the real row appeared with the real question text,
+a correct message count of 2, and correct relative timestamps; confirmed clicking the row does
+nothing (no `:show` route exists, matching the index-only design) rather than erroring.

data/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing
+
+Thanks for considering a contribution to `spree_menu_chat`.
+
+## Getting set up
+
+```bash
+bundle install
+bundle exec rake test_app   # generates spec/dummy, the Rails app specs run against
+bundle exec rspec
+```
+
+## Making a change
+
+1. Open an issue first for anything beyond a small fix, so the approach can be discussed before
+   you put time into it.
+2. Add or update specs alongside any behavior change — `bundle exec rspec` should stay green.
+3. Keep decorators as a last resort (see the main README's customization pattern order); prefer
+   Spree's Events/Subscribers or Dependencies mechanisms where they fit.
+4. This extension is deliberately read-only — any change that would let it write to
+   `Spree::Order`, `Spree::LineItem`, `Spree::Cart`, or pass tool/function-calling definitions to
+   the generation call is out of scope for a pull request here.
+5. Open a pull request describing what changed and why.
+
+## Releasing (maintainers)
+
+```bash
+bundle exec gem bump --version [major|minor|patch] -t -m "Release v%s"
+bundle exec gem release
+```
+
+See the [gem-release README](https://github.com/svenfuchs/gem-release) for more options.

data/Gemfile

@@ -0,0 +1,27 @@
+source 'https://rubygems.org'
+
+gem 'rails-controller-testing'
+
+# Pinned to the released 5.6.x line (matching spree_host), same rationale as
+# spree_square's and spree_doordash's Gemfiles.
+spree_opts = if ENV['SPREE_PATH']
+                { 'path': ENV['SPREE_PATH'] }
+             else
+                '~> 5.6.0'
+             end
+gem 'spree', spree_opts
+gem 'spree_admin', spree_opts
+
+gem 'spree_dev_tools', '>= 0.6.0.rc1'
+
+if ENV['DB'] == 'mysql'
+  gem 'mysql2'
+elsif ENV['DB'] == 'postgres'
+  gem 'pg'
+else
+  gem 'sqlite3'
+end
+
+gem 'propshaft'
+
+gemspec

data/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Amit Solanki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,95 @@
+# Spree Menu Chat
+
+[![Gem Version](https://img.shields.io/gem/v/spree_menu_chat.svg)](https://rubygems.org/gems/spree_menu_chat)
+[![GitHub Release](https://img.shields.io/github/v/release/amitkssolanki/spree_menu_chat)](https://github.com/amitkssolanki/spree_menu_chat/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.md)
+
+A read-only, retrieval-grounded chat assistant for [Spree Commerce](https://spreecommerce.org) storefronts. Answers customer questions about the menu, ingredients, dietary info, hours, and store policies — grounded entirely in the store's own synced catalog and `Spree::Policy` content, nothing from the model's general knowledge. It's the companion to [`spree_square`](https://github.com/amitkssolanki/spree_square) (reused, softly, for modifier-list grounding when present) and [`spree_doordash`](https://github.com/amitkssolanki/spree_doordash).
+
+> ⚠️ **This extension is explicitly read-only.** It has no cart or order mutation capability at all — no `tools`/function-calling definitions are ever passed to the generation call, so there is no code path by which a response can add an item, place an order, or change any Spree state. That's a deliberately separate, higher-risk feature this extension does not attempt.
+
+## What this does
+
+- **Grounded Q&A over the real menu** — embeds every published product (name, description, category, modifier lists) and every store `Spree::Policy` (hours, delivery area, allergen info, etc.) into pgvector, and answers only from what's actually retrieved for a given question.
+- **Live-synced, not a snapshot** — re-embeds automatically whenever a product changes, whether from a Square sync or a manual admin edit.
+- **Graceful "I don't know"** — if nothing retrieved clears a similarity floor, it skips the generation call entirely and returns a real contact-us fallback rather than guessing.
+- **No official SDK dependency** — neither the [Gemini API](https://ai.google.dev) (generation) nor [Voyage AI](https://www.voyageai.com) (embeddings) has an official Ruby SDK, so both are called directly over their REST APIs — the same pattern `spree_doordash` already uses for DoorDash's Drive API.
+
+## Installation
+
+1. Add this extension to your Gemfile with this line:
+
+    ```ruby
+    bundle add spree_menu_chat
+    ```
+
+2. Run the install generator
+
+    ```ruby
+    bundle exec rails g spree_menu_chat:install
+    ```
+
+3. Restart your server
+
+  If your server was running, restart it so that it can find the assets properly.
+
+## Connecting Gemini and Voyage AI
+
+Neither service uses OAuth — both are plain static API keys, entered directly:
+
+1. Create a free API key at [Google AI Studio](https://aistudio.google.com) — no billing account
+   required. The free tier (as of writing: 1,000 requests/day on `gemini-flash-lite-latest`, no card
+   on file) comfortably covers a single restaurant's real traffic. One trade-off worth knowing:
+   Google's free-tier terms allow using your prompts/responses to improve their models (the paid
+   tier does not).
+2. Create a free API key at [Voyage AI](https://www.voyageai.com) — the first 200 million tokens
+   are free per account on the `voyage-4`/`voyage-4-lite` family, which is enormous headroom for
+   embedding a restaurant menu (a few thousand tokens, typically). **Separately, and easy to miss:**
+   without a payment method on file, Voyage also caps *request rate* at just 3 requests/minute,
+   10K tokens/minute (confirmed live — the free 200M-token allowance is real and unaffected, but
+   this rate cap is much tighter than that headroom suggests). `SpreeMenuChat::EmbeddingClient`
+   self-throttles to that limit so a full-catalog `reembed_all` run doesn't 429, but it does mean
+   that run takes real wall-clock time (roughly one record every ~20s once past the first 3) — add
+   a payment method in the Voyage dashboard once you're past initial development to raise the cap;
+   the free token grant still applies afterward.
+3. In your Spree admin, go to **Menu Chat Connection** in the sidebar and paste both keys in.
+   They're encrypted at rest ([ActiveRecord::Encryption](https://guides.rubyonrails.org/active_record_encryption.html))
+   — same mechanism `spree_square`/`spree_doordash` use for their own credentials, sharing the
+   same `ACTIVE_RECORD_ENCRYPTION_*` keys.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test_app   # generates spec/dummy
+bundle exec rspec
+```
+
+To manually verify a real Gemini key end to end (outside the spec suite):
+
+```bash
+cp .env.local.example .env.local   # fill in GEMINI_API_KEY
+bin/rails spree_menu_chat:verify_connection
+```
+
+When testing your application's integration with this extension you may use its factories.
+Simply add this require statement to your spec_helper:
+
+```ruby
+require 'spree_menu_chat/factories'
+```
+
+## Releasing a new version
+
+```shell
+bundle exec gem bump -p -t
+bundle exec gem release
+```
+
+For more options please see [gem-release README](https://github.com/svenfuchs/gem-release)
+
+## Contributing
+
+If you'd like to contribute, please take a look at the
+[instructions](CONTRIBUTING.md) for installing dependencies and crafting a good
+pull request.

data/Rakefile

@@ -0,0 +1,23 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+require 'spree/testing_support/extension_rake'
+
+RSpec::Core::RakeTask.new
+
+task :default do
+  if Dir['spec/dummy'].empty?
+    Rake::Task[:test_app].invoke
+    Dir.chdir('../../')
+  end
+  Rake::Task[:spec].invoke
+end
+
+desc 'Generates a dummy app for testing'
+task :test_app do
+  ENV['LIB_NAME'] = 'spree_menu_chat'
+  Rake::Task['extension:test_app'].execute(
+    install_admin: true
+  )
+end

data/app/controllers/spree/admin/menu_chat_conversations_controller.rb

@@ -0,0 +1,15 @@
+module Spree
+  module Admin
+    # Read-only QA view of every logged chat conversation for the current
+    # store — same shape as Spree::Admin::SquareWebhookEventsController.
+    # Scoped to current_store automatically: ResourceController#scope calls
+    # `model_class.for_store(current_store)` when the model responds to it
+    # (see SpreeMenuChat::Conversation's `for_store` scope) — no override
+    # needed here.
+    class MenuChatConversationsController < ResourceController
+      def model_class
+        SpreeMenuChat::Conversation
+      end
+    end
+  end
+end

data/app/controllers/spree/admin/menu_chat_credentials_controller.rb

@@ -0,0 +1,38 @@
+module Spree
+  module Admin
+    # Plain credential-entry form for the current store's Gemini + Voyage AI
+    # API keys — not an OAuth connect/disconnect flow (neither service has
+    # one). Same shape as Spree::Admin::DoordashCredentialsController: an
+    # admin pastes the two key values in here directly, encrypted at rest.
+    class MenuChatCredentialsController < Spree::Admin::BaseController
+      def show
+        @credential = SpreeMenuChat::Credential.find_or_initialize_by(store: current_store)
+      end
+
+      def update
+        @credential = SpreeMenuChat::Credential.find_or_initialize_by(store: current_store)
+
+        if @credential.update(credential_params)
+          flash[:success] = Spree.t(:menu_chat_credential_saved, default: 'Menu Chat credentials saved.')
+        else
+          flash[:error] = @credential.errors.full_messages.to_sentence
+        end
+
+        redirect_to admin_menu_chat_credential_path
+      end
+
+      private
+
+      # Blank fields mean "leave unchanged" — the form always renders these
+      # empty and never echoes the current value back (see
+      # SpreeDoordash::Credential's controller for the identical rationale).
+      def credential_params
+        permitted = params.require(:spree_menu_chat_credential).permit(:gemini_api_key, :voyage_api_key)
+        %i[gemini_api_key voyage_api_key].each do |field|
+          permitted.delete(field) if permitted[field].blank?
+        end
+        permitted
+      end
+    end
+  end
+end