spree_menu_chat 0.1.0

data/app/services/spree_menu_chat/embedding_client.rb

@@ -0,0 +1,161 @@
+require 'faraday'
+
+module SpreeMenuChat
+  # Thin wrapper around Voyage AI's embeddings REST endpoint. All embedding
+  # calls in this extension go through here — same "no official Ruby SDK,
+  # call the REST API directly" situation as SpreeMenuChat::LlmClient (for
+  # Gemini) and SpreeDoordash::Client (for DoorDash's Drive API).
+  #
+  # Self-throttles to the real limit (see #throttle!) rather than firing
+  # requests as fast as the caller loops and letting a generic error bubble
+  # up to ReembedCatalogJob's job-level retry_on — found live, running
+  # reembed_all against the real synced catalog: Voyage accounts with no
+  # payment method on file (true even for accounts still fully covered by
+  # the 200M-token free grant — the reduced limit is separate from the
+  # free-token allowance) are throttled to a real 3 requests/minute, 10K
+  # tokens/minute.
+  #
+  # First attempt at this fix (reactive: catch a 429, sleep ~20s, retry)
+  # undershot in practice — confirmed live: after the initial 3-request
+  # burst, retries kept landing inside the *same* still-open rate window
+  # (a 3-req/60s window doesn't fully clear just because 20s passed since
+  # the failure), so most retries 429'd again and the run silently
+  # bottomed out at 21/43 records. Self-throttling — tracking this
+  # process's own last N request timestamps and sleeping proactively
+  # before the (N+1)th falls inside the window — avoids firing requests
+  # doomed to 429 in the first place, rather than reacting after the fact.
+  # The reactive 429-retry (#request's rescue) stays as a safety net for
+  # anything the proactive throttle doesn't account for (clock skew,
+  # another process/job sharing this store's key), not as the primary
+  # mechanism anymore.
+  #
+  # Class-level (not per-instance) because the rate limit is scoped to the
+  # Voyage account/API key, not to any one EmbeddingClient instance — and
+  # this client is deliberately non-memoized (see .for_store below), so
+  # per-instance state would track nothing real. In-process/in-memory is
+  # sufficient here, not a Redis-backed limiter: this stack runs a single
+  # Puma+Solid-Queue process (no Redis anywhere in this project, same
+  # rationale as SpreeMenuChat::RateLimiter), and the account-level limit
+  # is already generous enough (3 RPM) that cross-process undercounting
+  # in a multi-dyno deployment would need to be revisited before that kind
+  # of scale, not before this.
+  class EmbeddingClient
+    class MissingCredentialsError < StandardError; end
+
+    BASE_URL = 'https://api.voyageai.com'.freeze
+
+    # The real, live-confirmed no-payment-method limit (see class comment).
+    MAX_REQUESTS_PER_WINDOW = 3
+    WINDOW_SECONDS = 60
+    WINDOW_MARGIN_SECONDS = 2 # clears clock-precision/latency edge cases
+
+    # Reactive safety net for a 429 the proactive throttle didn't prevent.
+    RATE_LIMIT_RETRY_WAIT = WINDOW_SECONDS + WINDOW_MARGIN_SECONDS
+    RATE_LIMIT_MAX_ATTEMPTS = 3
+
+    @request_times = []
+    @request_times_mutex = Mutex.new
+
+    class << self
+      # Exposed for specs (reset between examples) — not meant to be read
+      # or written from application code.
+      attr_accessor :request_times
+
+      def request_times_mutex
+        @request_times_mutex
+      end
+    end
+
+    # Deliberately NOT memoized — same rationale as every other client in
+    # this project (SpreeSquare::Client, SpreeDoordash::Client,
+    # SpreeMenuChat::LlmClient): a store's credential can be created/edited
+    # by an admin mid-process, and a Faraday connection is cheap enough to
+    # not be worth caching against that risk.
+    def self.instance
+      for_store
+    end
+
+    def self.for_store(store = Spree::Store.default)
+      new(credential: SpreeMenuChat::Credential.find_by(store: store))
+    end
+
+    def initialize(credential: nil)
+      @credential = credential
+      raise MissingCredentialsError, 'No Menu Chat credential connected for this store' unless @credential
+      raise MissingCredentialsError, 'No Voyage AI API key set for this store' if @credential.voyage_api_key.blank?
+    end
+
+    # `input` is a single string or an array of strings — Voyage's own
+    # accepted shape supports batching several documents into one request,
+    # though every current caller (SpreeMenuChat::Embedder, one record at a
+    # time) passes a single string; batching multiple products per call
+    # would cut the request count for ReembedCatalogJob's full-catalog pass
+    # and is worth doing as a follow-up given the real 3 RPM limit
+    # documented above, but isn't required for correctness now that every
+    # call is self-throttled to that limit. `input_type` is Voyage's own asymmetric-embedding
+    # hint: "document" for content being indexed (what this extension
+    # always embeds), "query" for the customer's question at retrieval time
+    # (SpreeMenuChat::Retriever, M3) — using the right one measurably
+    # improves retrieval quality per Voyage's own docs, it's not optional
+    # boilerplate.
+    def embed(input, input_type:, model: SpreeMenuChat::Config.embedding_model)
+      body = { input: Array(input), model: model, input_type: input_type }
+      result = request(:post, '/v1/embeddings', body)
+      result.fetch('data', []).map { |row| row['embedding'] }
+    end
+
+    private
+
+    def request(method, path, body = nil)
+      attempt = 1
+      begin
+        throttle!
+        response = connection.send(method) do |req|
+          req.url path
+          req.headers['Authorization'] = "Bearer #{@credential.voyage_api_key}"
+          req.headers['Content-Type'] = 'application/json'
+          req.body = body.to_json if body
+        end
+        handle_response(response)
+      rescue RequestError => e
+        raise unless e.status == 429 && attempt < RATE_LIMIT_MAX_ATTEMPTS
+
+        attempt += 1
+        sleep(RATE_LIMIT_RETRY_WAIT)
+        retry
+      end
+    end
+
+    # Blocks the calling thread until issuing another request keeps this
+    # process within MAX_REQUESTS_PER_WINDOW calls per WINDOW_SECONDS. See
+    # the class comment for why this needs to be proactive, not just a
+    # reactive retry-after-429.
+    def throttle!
+      self.class.request_times_mutex.synchronize do
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        self.class.request_times.reject! { |t| now - t >= WINDOW_SECONDS }
+
+        if self.class.request_times.size >= MAX_REQUESTS_PER_WINDOW
+          oldest = self.class.request_times.min
+          wait = (WINDOW_SECONDS - (now - oldest)) + WINDOW_MARGIN_SECONDS
+          sleep(wait) if wait.positive?
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          self.class.request_times.reject! { |t| now - t >= WINDOW_SECONDS }
+        end
+
+        self.class.request_times << Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: BASE_URL)
+    end
+
+    def handle_response(response)
+      parsed = response.body.present? ? JSON.parse(response.body) : {}
+      return parsed if response.status.between?(200, 299)
+
+      raise RequestError.new("Voyage API error (#{response.status}): #{parsed.inspect}", status: response.status, body: parsed)
+    end
+  end
+end

data/app/services/spree_menu_chat/llm_client.rb

@@ -0,0 +1,186 @@
+require 'faraday'
+
+module SpreeMenuChat
+  # Thin wrapper around the Gemini API's generateContent/streamGenerateContent
+  # REST endpoints. All generation calls in this extension go through here.
+  #
+  # There is no official Google-maintained Ruby SDK for the Gemini API
+  # (confirmed — only unofficial community gems exist) — same "no SDK, call
+  # the REST API directly" situation as SpreeDoordash::Client. Auth is a
+  # plain API key on the query string (Gemini's own documented shape;
+  # unlike DoorDash there's no per-request signing).
+  #
+  # Model default is the gemini-flash-lite-latest ALIAS, not a pinned dated
+  # model (see SpreeMenuChat::Configuration for why — confirmed live that a
+  # pinned model can 404 for new API keys while still appearing in the
+  # models.list catalog). If this ever 404s anyway, check the current model
+  # catalog and free-tier limits at https://aistudio.google.com.
+  class LlmClient
+    class MissingCredentialsError < StandardError; end
+
+    BASE_URL = 'https://generativelanguage.googleapis.com'.freeze
+
+    # Deliberately NOT memoized, same rationale as SpreeSquare::Client and
+    # SpreeDoordash::Client: a store's credential can be created/edited by an
+    # admin mid-process, and a Faraday connection is cheap enough to not be
+    # worth caching against that risk.
+    def self.instance
+      for_store
+    end
+
+    def self.for_store(store = Spree::Store.default)
+      new(credential: SpreeMenuChat::Credential.find_by(store: store))
+    end
+
+    def initialize(credential: nil)
+      @credential = credential
+      raise MissingCredentialsError, 'No Menu Chat credential connected for this store' unless @credential
+      raise MissingCredentialsError, 'No Gemini API key set for this store' if @credential.gemini_api_key.blank?
+    end
+
+    # Single-shot, non-streaming generation — used by M1's verify_connection
+    # rake task and SpreeMenuChat::AnswerGenerator#call. ChatController
+    # itself uses #generate_stream (below) as of M4; #call/#generate stay
+    # around as the simpler synchronous API for callers that don't need
+    # streaming (rake tasks, tests, a future admin "test this question"
+    # action).
+    #
+    # system_instruction is Gemini's own top-level field for a system prompt
+    # (kept separate from `contents`, not concatenated into the user turn —
+    # this is the mechanism SpreeMenuChat::AnswerGenerator uses to scope the
+    # assistant to menu/FAQ-only, per the plan's read-only guardrail).
+    def generate(prompt, system_instruction: nil, model: SpreeMenuChat::Config.generation_model)
+      request(:post, "/v1beta/models/#{model}:generateContent", generate_body(prompt, system_instruction))
+    end
+
+    # Streaming counterpart of #generate (M4) — calls Gemini's own
+    # `:streamGenerateContent?alt=sse` endpoint and yields each text
+    # fragment to the block as it arrives, instead of waiting for the full
+    # response. Confirmed live (2026-08-16): Gemini's real SSE frames are
+    # `data: <json>` blocks separated by a blank line, using `\r\n` line
+    # endings (see #consume_sse_frames for why that specific detail is
+    # load-bearing), where each JSON object has the same
+    # candidates[0].content.parts[0].text shape #generate already parses —
+    # streaming just delivers it in more, smaller pieces, not a different
+    # shape. The very last frame typically carries an empty `text` plus a
+    # `finishReason`/`thoughtSignature` — skipped here since there's
+    # nothing to yield.
+    #
+    # Uses Faraday's `on_data` streaming callback (confirmed live to work
+    # with this project's plain net_http adapter — no extra gem needed)
+    # rather than buffering the whole response and chunking it ourselves,
+    # so a slow/long answer actually reaches the caller incrementally
+    # instead of only feeling instant right at the very end.
+    #
+    # Returns the final totalTokenCount Gemini reported (each SSE frame's
+    # usageMetadata carries a running total, so the last one seen is the
+    # true total for the whole turn) — SpreeMenuChat::AnswerGenerator feeds
+    # this straight into SpreeMenuChat::TokenBudget (M5) rather than
+    # estimating spend itself. Returns nil if the response never included
+    # usage data (shouldn't happen in practice, but callers must not
+    # assume a value).
+    def generate_stream(prompt, system_instruction: nil, model: SpreeMenuChat::Config.generation_model, &block)
+      raw = +''
+      sse_buffer = +''
+      total_tokens = nil
+
+      response = connection.post("/v1beta/models/#{model}:streamGenerateContent") do |req|
+        req.params['alt'] = 'sse'
+        req.params['key'] = @credential.gemini_api_key
+        req.headers['Content-Type'] = 'application/json'
+        req.body = generate_body(prompt, system_instruction).to_json
+        req.options.on_data = proc do |chunk, _bytes|
+          raw << chunk
+          sse_buffer << chunk
+          seen = consume_sse_frames(sse_buffer, &block)
+          total_tokens = seen if seen
+        end
+      end
+
+      return total_tokens if response.status.between?(200, 299)
+
+      # Confirmed live: an error response on this endpoint is plain JSON
+      # (Gemini's normal {"error": {...}} shape), not an SSE "data:" frame
+      # — it never matched the `data:` prefix above, so it's still sitting
+      # in `raw` untouched here, same as #handle_response would see it in
+      # response.body for the non-streaming endpoint.
+      parsed = raw.present? ? JSON.parse(raw) : {}
+      raise RequestError.new("Gemini API error (#{response.status}): #{parsed.inspect}", status: response.status, body: parsed)
+    end
+
+    private
+
+    def generate_body(prompt, system_instruction)
+      body = { contents: [{ parts: [{ text: prompt }] }] }
+      body[:systemInstruction] = { parts: [{ text: system_instruction }] } if system_instruction
+      body
+    end
+
+    # Pulls complete "data: {...}<blank line>" frames out of the buffer as
+    # they become available and yields each frame's real text fragment (if
+    # any) to the block — leaves any trailing partial frame in the buffer
+    # for the next chunk to complete.
+    #
+    # Normalizes CRLF to LF on the way in before splitting on a blank
+    # line. This isn't defensive over-engineering: confirmed live
+    # (2026-08-16) that Gemini's real streamGenerateContent responses use
+    # "\r\n" line endings, not bare "\n" — a version of this method that
+    # only ever searched for a literal "\n\n" (matching the SSE spec's
+    # most commonly *assumed* framing, and what every hand-written WebMock
+    # fixture in this gem's own spec suite naturally produces) silently
+    # yielded zero chunks against the real API every single time, with no
+    # exception and no error logged — `raw` never matched `data:` because
+    # it was never split into frames at all. The self-authored WebMock
+    # stubs couldn't catch this: they tested this method's logic against
+    # my own (wrong) assumption about the wire format, not Gemini's actual
+    # one.
+    #
+    # Returns the last usageMetadata.totalTokenCount seen among the frames
+    # consumed on *this* call (nil if none carried one) — #generate_stream
+    # keeps whichever value was most recently non-nil across every on_data
+    # invocation, since a single call here only ever sees the frames that
+    # arrived in one chunk.
+    def consume_sse_frames(buffer)
+      buffer.gsub!("\r\n", "\n")
+      last_total_tokens = nil
+
+      while (idx = buffer.index("\n\n"))
+        frame = buffer.slice!(0..idx + 1)
+        next unless frame.start_with?('data:')
+
+        json_str = frame.delete_prefix('data:').strip
+        next if json_str.empty?
+
+        parsed = JSON.parse(json_str)
+        text = parsed.dig('candidates', 0, 'content', 'parts', 0, 'text')
+        yield text if text.present?
+
+        tokens = parsed.dig('usageMetadata', 'totalTokenCount')
+        last_total_tokens = tokens if tokens
+      end
+
+      last_total_tokens
+    end
+
+    def request(method, path, body = nil)
+      response = connection.send(method) do |req|
+        req.url path
+        req.params['key'] = @credential.gemini_api_key
+        req.headers['Content-Type'] = 'application/json'
+        req.body = body.to_json if body
+      end
+      handle_response(response)
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: BASE_URL)
+    end
+
+    def handle_response(response)
+      parsed = response.body.present? ? JSON.parse(response.body) : {}
+      return parsed if response.status.between?(200, 299)
+
+      raise RequestError.new("Gemini API error (#{response.status}): #{parsed.inspect}", status: response.status, body: parsed)
+    end
+  end
+end

data/app/services/spree_menu_chat/rate_limiter.rb

@@ -0,0 +1,53 @@
+module SpreeMenuChat
+  # Fixed-window rate limiter — SpreeMenuChat::Config.rate_limit_per_hour
+  # requests per (store, identifier) per rolling hour, Postgres-backed
+  # (no Redis anywhere in this stack, same rationale as Solid Queue running
+  # inside Postgres rather than a separate broker).
+  #
+  # Called from SpreeMenuChat::ChatController with request.remote_ip as the
+  # identifier — the widget is anonymous (no session/customer model yet),
+  # so IP is what's actually available before any answer is generated.
+  class RateLimiter
+    class LimitExceededError < StandardError; end
+
+    def self.check!(identifier, store: Spree::Store.default)
+      new(identifier, store: store).check!
+    end
+
+    def initialize(identifier, store:)
+      @identifier = identifier
+      @store = store
+    end
+
+    # Raises LimitExceededError once the identifier has made
+    # rate_limit_per_hour requests within the current window; otherwise
+    # increments the counter and returns normally. Fixed window (resets a
+    # full hour after the first request in it), not a true sliding window
+    # — simpler, and standard practice for a limit this size.
+    def check!
+      ActiveRecord::Base.transaction do
+        record = SpreeMenuChat::RateLimit.lock.find_or_initialize_by(store: @store, identifier: @identifier)
+        reset_if_window_expired(record)
+
+        raise LimitExceededError if record.count >= SpreeMenuChat::Config.rate_limit_per_hour
+
+        record.count += 1
+        record.save!
+      end
+    rescue ActiveRecord::RecordNotUnique
+      # Lost a race with a concurrent first-request from the same
+      # identifier — the row exists now, retry against it. Same pattern as
+      # SpreeSquare::WebhooksController#find_or_log_event.
+      retry
+    end
+
+    private
+
+    def reset_if_window_expired(record)
+      return if record.window_started_at.present? && record.window_started_at > 1.hour.ago
+
+      record.window_started_at = Time.current
+      record.count = 0
+    end
+  end
+end

data/app/services/spree_menu_chat/request_error.rb

@@ -0,0 +1,26 @@
+module SpreeMenuChat
+  # Shared error class raised by both SpreeMenuChat::LlmClient (Gemini) and
+  # SpreeMenuChat::EmbeddingClient (Voyage) on a non-2xx response.
+  #
+  # This used to live inline at the bottom of llm_client.rb — that worked in
+  # every spec run (Zeitwerk's eager_load_all, which spec/zeitwerk_spec.rb
+  # exercises, loads every file up front regardless of order) but broke for
+  # real: `rails runner` autoloads lazily, so calling
+  # SpreeMenuChat::EmbeddingClient without anything having first touched
+  # SpreeMenuChat::LlmClient left RequestError genuinely undefined —
+  # `NameError: uninitialized constant SpreeMenuChat::EmbeddingClient::
+  # RequestError`, confirmed live while running SpreeMenuChat::ReembedCatalogJob
+  # against the real synced catalog. Zeitwerk expects one constant per file
+  # matching its path; a class defined as a second citizen of another file
+  # only resolves by the accident of load order. Given its own file here, it
+  # autoloads correctly regardless of which client references it first.
+  class RequestError < StandardError
+    attr_reader :status, :body
+
+    def initialize(message, status:, body:)
+      super(message)
+      @status = status
+      @body = body
+    end
+  end
+end

data/app/services/spree_menu_chat/retriever.rb

@@ -0,0 +1,64 @@
+module SpreeMenuChat
+  # Embeds a customer's question and returns the top-K most similar
+  # SpreeMenuChat::Embedding rows for the store, via pgvector cosine
+  # distance — the retrieval half of RAG. SpreeMenuChat::AnswerGenerator is
+  # the only caller; kept separate so retrieval and generation each have
+  # one job.
+  #
+  # Uses `input_type: 'query'` (not 'document') on the embedding call —
+  # Voyage's asymmetric-embedding hint for the search-query side of a
+  # document/query pair, per the same rationale already documented on
+  # SpreeMenuChat::EmbeddingClient#embed.
+  class Retriever
+    def self.call(question, store: Spree::Store.default)
+      new(question, store: store).call
+    end
+
+    def initialize(question, store:)
+      @question = question
+      @store = store
+    end
+
+    # Returns a plain Array of SpreeMenuChat::Embedding (each with a real
+    # #neighbor_distance, populated by the `nearest_neighbors` scope) —
+    # empty if the question is blank, embedding it fails, or nothing clears
+    # the similarity floor. Never raises SpreeMenuChat::RequestError itself;
+    # SpreeMenuChat::AnswerGenerator treats "nothing retrieved" as the
+    # trigger for its no-context fallback regardless of *why* nothing came
+    # back, so a Voyage outage degrades to the same honest "I don't have
+    # that" response as a genuinely unanswerable question, not a 500.
+    def call
+      return [] if @question.blank?
+
+      query_vector = embed_question
+      return [] if query_vector.nil?
+
+      # `nearest_neighbors` is chainable (a plain `scope`, see the neighbor
+      # gem) but its `neighbor_distance` is a SELECT-list alias — Postgres
+      # doesn't allow referencing that in a WHERE clause on the same query,
+      # so the similarity floor is applied in Ruby after fetching, not as
+      # SQL. `retrieval_top_k` keeps that fetch small regardless.
+      SpreeMenuChat::Embedding
+        .where(store: @store)
+        .nearest_neighbors(:embedding, query_vector, distance: 'cosine')
+        .limit(SpreeMenuChat::Config.retrieval_top_k)
+        .select { |record| record.neighbor_distance <= max_distance }
+    end
+
+    private
+
+    def embed_question
+      SpreeMenuChat::EmbeddingClient.for_store(@store).embed(@question, input_type: 'query').first
+    rescue SpreeMenuChat::RequestError, SpreeMenuChat::EmbeddingClient::MissingCredentialsError => e
+      SpreeMenuChat::Alerting.capture(e, context: { area: 'retriever', store_id: @store.id })
+      nil
+    end
+
+    # Cosine distance = 1 - cosine similarity, so a similarity floor of 0.35
+    # (the default — see SpreeMenuChat::Configuration for why) becomes
+    # "keep anything within 0.65 distance."
+    def max_distance
+      1.0 - SpreeMenuChat::Config.similarity_floor.to_f
+    end
+  end
+end

data/app/services/spree_menu_chat/token_budget.rb

@@ -0,0 +1,52 @@
+module SpreeMenuChat
+  # Per-store daily cap on Gemini generation token spend (see
+  # SpreeMenuChat::Configuration#daily_token_budget) — the other half of
+  # M5's guardrails alongside SpreeMenuChat::RateLimiter. Once a store's
+  # daily total is exhausted, SpreeMenuChat::AnswerGenerator stops calling
+  # Gemini for the rest of the day and falls back to a "come back tomorrow
+  # / contact us" response instead, rather than continuing to spend.
+  #
+  # Deliberately tracks *generation* tokens only, using Gemini's own
+  # reported usageMetadata.totalTokenCount (not embedding tokens, and not
+  # an estimate). Voyage's embedding call in the live chat path is just the
+  # query embedding (SpreeMenuChat::Retriever) — a few dozen tokens,
+  # dwarfed by a real generation call's typical few-hundred-token cost.
+  # Folding embedding spend in too would be more complete, but it would
+  # mean EmbeddingClient/Retriever both starting to return usage alongside
+  # vectors — real plumbing, not just a config tweak — so it's left as a
+  # follow-up rather than blocking this guardrail on it.
+  class TokenBudget
+    def self.exceeded?(store: Spree::Store.default)
+      new(store: store).exceeded?
+    end
+
+    def self.record!(tokens, store: Spree::Store.default)
+      new(store: store).record!(tokens)
+    end
+
+    def initialize(store:)
+      @store = store
+    end
+
+    def exceeded?
+      used = SpreeMenuChat::TokenUsage.find_by(store: @store, date: Date.current)&.tokens_used || 0
+      used >= SpreeMenuChat::Config.daily_token_budget
+    end
+
+    def record!(tokens)
+      tokens = tokens.to_i
+      return if tokens <= 0
+
+      ActiveRecord::Base.transaction do
+        usage = SpreeMenuChat::TokenUsage.lock.find_or_initialize_by(store: @store, date: Date.current)
+        usage.tokens_used = usage.tokens_used.to_i + tokens
+        usage.save!
+      end
+    rescue ActiveRecord::RecordNotUnique
+      # Lost a race with a concurrent first-request-of-the-day for this
+      # store — the row exists now, retry against it. Same pattern as
+      # SpreeMenuChat::RateLimiter#check!.
+      retry
+    end
+  end
+end

data/app/views/spree/admin/menu_chat_conversations/index.html.erb

@@ -0,0 +1,5 @@
+<% content_for :page_title do %>
+  Menu Chat Conversations
+<% end %>
+
+<%= render_table @collection, :menu_chat_conversations %>

data/app/views/spree/admin/menu_chat_conversations/show.html.erb

@@ -0,0 +1,27 @@
+<% content_for :page_title do %>
+  Conversation — <%= @object.identifier %>
+<% end %>
+
+<div class="max-w-3xl mx-auto space-y-4 py-6">
+  <div class="text-sm text-gray-500">
+    Started <%= l(@object.created_at, format: :long) %> ·
+    Last message <%= l(@object.updated_at, format: :long) %>
+  </div>
+
+  <ul class="space-y-3">
+    <% @object.messages.order(:created_at).each do |message| %>
+      <li class="flex <%= message.role == 'user' ? 'justify-end' : 'justify-start' %>">
+        <div class="max-w-[80%] rounded-lg px-4 py-2 <%= message.role == 'user' ? 'bg-gray-900 text-white' : 'bg-gray-100 text-gray-900' %>">
+          <div class="text-xs opacity-70 mb-1"><%= message.role.capitalize %> · <%= l(message.created_at, format: :short) %></div>
+          <% if message.role == 'user' %>
+            <div class="whitespace-pre-wrap text-sm"><%= message.rendered_content %></div>
+          <% else %>
+            <div class="prose prose-sm max-w-none prose-p:my-1 prose-ul:my-1 prose-ol:my-1 prose-li:my-0">
+              <%= message.rendered_content %>
+            </div>
+          <% end %>
+        </div>
+      </li>
+    <% end %>
+  </ul>
+</div>

data/app/views/spree/admin/menu_chat_credentials/show.html.erb

@@ -0,0 +1,44 @@
+<% content_for :page_title do %>
+  Menu Chat Connection
+<% end %>
+
+<div class="card w-full max-w-2xl">
+  <div class="card-header flex items-center justify-between <%= 'bg-green-50' if @credential.persisted? %>">
+    <span class="font-medium">Menu Chat Assistant</span>
+    <% if @credential.persisted? %>
+      <span class="inline-flex items-center text-xs font-medium text-green-700">
+        <span class="w-1.5 h-1.5 rounded-full bg-green-500 mr-1"></span>
+        Configured
+      </span>
+    <% else %>
+      <span class="inline-flex items-center text-xs font-medium text-gray-500">
+        <span class="w-1.5 h-1.5 rounded-full bg-gray-400 mr-1"></span>
+        Not configured
+      </span>
+    <% end %>
+  </div>
+
+  <%= form_for @credential, url: admin_menu_chat_credential_path, method: :patch,
+        as: :spree_menu_chat_credential, html: { class: 'card-body space-y-4' } do |f| %>
+    <p class="text-sm text-gray-600">
+      Create a free API key at
+      <a href="https://aistudio.google.com" target="_blank" rel="noopener" class="text-blue-600 underline">Google AI Studio</a>
+      (generation) and
+      <a href="https://www.voyageai.com" target="_blank" rel="noopener" class="text-blue-600 underline">Voyage AI</a>
+      (embeddings), then paste both below. Stored encrypted — neither service uses OAuth.
+    </p>
+
+    <div>
+      <%= f.label :gemini_api_key, 'Gemini API key', class: 'label' %>
+      <%= f.password_field :gemini_api_key, value: '', placeholder: (@credential.gemini_api_key.present? ? '••••••••  (leave blank to keep current)' : nil), class: 'form-control' %>
+    </div>
+    <div>
+      <%= f.label :voyage_api_key, 'Voyage AI API key', class: 'label' %>
+      <%= f.password_field :voyage_api_key, value: '', placeholder: (@credential.voyage_api_key.present? ? '••••••••  (leave blank to keep current)' : nil), class: 'form-control' %>
+    </div>
+
+    <div class="card-footer -mx-4 -mb-4">
+      <%= f.submit 'Save', class: 'btn btn-primary' %>
+    </div>
+  <% end %>
+</div>

data/config/brakeman.ignore

@@ -0,0 +1,28 @@
+{
+  "ignored_warnings": [
+    {
+      "warning_type": "Cross-Site Request Forgery",
+      "warning_code": 86,
+      "fingerprint": "d7d765af355e7f6488034527edd09cc2dc9a043630f9d8eb0e2d924a1c0665f1",
+      "check_name": "ForgerySetting",
+      "message": "`protect_from_forgery` should be configured with `with: :exception`",
+      "file": "app/controllers/spree_menu_chat/chat_controller.rb",
+      "line": 24,
+      "link": "https://brakemanscanner.org/docs/warning_types/cross-site_request_forgery/",
+      "code": "protect_from_forgery(:with => :null_session)",
+      "render_path": null,
+      "location": {
+        "type": "controller",
+        "controller": "SpreeMenuChat::ChatController"
+      },
+      "user_input": null,
+      "confidence": "Medium",
+      "cwe_id": [
+        352
+      ],
+      "note": "Intentional, not a false positive to fix: this is a customer-facing JSON endpoint authenticated by the store's publishable API key (X-Spree-Api-Key), not by a Rails session, so there's no session-based state for CSRF to protect in the first place. `:exception` (Brakeman's preferred default) would make every legitimate request raise ActionController::InvalidAuthenticityToken, since the Next.js proxy never sends a Rails CSRF token — that would break the endpoint entirely, not harden it. `:null_session` is the correct, standard Rails pattern here, same as spree_square's WebhooksController (see that gem's config/brakeman.ignore for the identical rationale)."
+    }
+  ],
+  "updated": "2026-08-16 00:00:00 +0530",
+  "brakeman_version": "8.0.6"
+}