support_desk 0.2.0 → 0.3.0

data/lib/generators/support_desk/templates/add_assistants_to_support_desk.rb.erb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+# support_desk 0.3.0 — ASSISTANTS.
+#
+# Two new tables (the assistant herself, and the replies she proposes) and
+# nine columns on the tickets table: the turn, the pointer the turn reads,
+# her budget, and the three independent human-side flags (a person was
+# asked for, she was paused here, this case caps her).
+#
+# Every statement is guarded, so this is safe to run against a schema that
+# already has some of it — a half-finished migration, an upgrade run twice,
+# a host who added a column by hand.
+#
+# Column types are read from the columns they POINT AT, never from today's
+# generator setting: `ticket_id` follows support_desk_tickets.id, message
+# ids follow chats_messages.id, and the polymorphic ids follow the ones
+# support_desk_assignments already uses for an agent. An app that changed
+# `primary_key_type` after installing would otherwise be handed bigint
+# columns for uuid ids.
+class AddAssistantsToSupportDesk < ActiveRecord::Migration<%= migration_version %>
+  TICKET_INDEX = "index_support_desk_tickets_on_needs_human"
+
+  def up
+    create_assistants_table
+    create_drafts_table
+    add_ticket_columns
+    backfill_requester_pointer
+  end
+
+  # Exactly what `up` added. Only meaningful BEFORE an assistant has
+  # answered anything: dropping these tables throws away every proposal a
+  # human reviewed and every reason a case was handed over. A code rollback
+  # to 0.2 does NOT need this — the columns are nullable and the tables are
+  # simply ignored.
+  def down
+    remove_index :support_desk_tickets, name: TICKET_INDEX if
+      index_exists?(:support_desk_tickets, [ :desk_id, :human_required_at ], name: TICKET_INDEX)
+
+    ticket_columns.each_key do |name|
+      remove_column :support_desk_tickets, name if column_exists?(:support_desk_tickets, name)
+    end
+
+    drop_table :support_desk_drafts if table_exists?(:support_desk_drafts)
+    drop_table :support_desk_assistants if table_exists?(:support_desk_assistants)
+  end
+
+  private
+
+  # ---------------------------------------------------------------------------
+  # support_desk_assistants
+  #
+  # Who she is, and whether she is on. Everything she MAY DO lives in the
+  # initializer, in code — so a policy change is a deploy and a diff, not a
+  # row somebody edited. `active` is the exception on purpose: it is the
+  # cross-process kill switch, read fresh before every write she makes.
+  # ---------------------------------------------------------------------------
+  def create_assistants_table
+    unless table_exists?(:support_desk_assistants)
+      create_table :support_desk_assistants, id: primary_key_type do |t|
+        t.string :key, null: false
+        t.boolean :active, null: false, default: true
+        t.send(json_column_type, :settings, default: json_column_default)
+
+        t.timestamps
+      end
+    end
+
+    return if index_exists?(:support_desk_assistants, :key, name: "index_support_desk_assistants_on_key")
+
+    add_index :support_desk_assistants, :key, unique: true, name: "index_support_desk_assistants_on_key"
+  end
+
+  # ---------------------------------------------------------------------------
+  # support_desk_drafts
+  #
+  # A reply she proposed and a human sent, edited or threw away. `body` is
+  # what she wrote and `sent_body` what went out when they differ, so the
+  # verbatim/edited/rejected split a host reads before raising her level is
+  # a query and not a guess. `proposed_turn` is the case's turn when she
+  # wrote it — what makes `stale?` mean "the conversation moved on".
+  # ---------------------------------------------------------------------------
+  def create_drafts_table
+    unless table_exists?(:support_desk_drafts)
+      create_table :support_desk_drafts, id: primary_key_type do |t|
+        t.column :ticket_id, sql_type_of(:support_desk_tickets, "id"), null: false
+        t.string :author_type, null: false
+        t.column :author_id, sql_type_of(:support_desk_assignments, "agent_id"), null: false
+        t.string :reviewed_by_type
+        t.column :reviewed_by_id, sql_type_of(:support_desk_assignments, "agent_id")
+        t.column :sent_message_id, sql_type_of(:chats_messages, "id")
+
+        t.string :proposed_turn, null: false
+        # Null for an attachment-only proposal — a screenshot with nothing
+        # to add is a whole answer.
+        t.text :body
+        t.text :sent_body
+        t.string :status, null: false, default: "pending"
+        # 0.000 to 1.000: what the model declared, never what it was worth.
+        t.decimal :confidence, precision: 4, scale: 3
+        t.send(json_column_type, :sources, default: json_column_default)
+        t.send(json_column_type, :metadata, default: json_column_default)
+        t.string :rejection_reason
+        t.datetime :reviewed_at
+
+        t.timestamps
+      end
+
+      add_foreign_key :support_desk_drafts, :support_desk_tickets, column: :ticket_id
+    end
+
+    unless index_exists?(:support_desk_drafts, [ :ticket_id, :created_at ],
+                         name: "index_support_desk_drafts_on_ticket")
+      add_index :support_desk_drafts, [ :ticket_id, :created_at ], name: "index_support_desk_drafts_on_ticket"
+    end
+
+    unless index_exists?(:support_desk_drafts, [ :author_type, :author_id, :status ],
+                         name: "index_support_desk_drafts_on_author")
+      add_index :support_desk_drafts, [ :author_type, :author_id, :status ],
+                name: "index_support_desk_drafts_on_author"
+    end
+
+    # ONE pending proposal per case — the belt under the row lock that
+    # serialises them. Enforced on every adapter that has partial indexes
+    # (all but MySQL, Trilogy included); elsewhere the model's
+    # supersede-then-create is the whole story and `doctor` checks it.
+    return unless partial_indexes?
+    return if index_exists?(:support_desk_drafts, :ticket_id, name: "index_support_desk_drafts_on_pending")
+
+    add_index :support_desk_drafts, :ticket_id, unique: true, where: "status = 'pending'",
+              name: "index_support_desk_drafts_on_pending"
+  end
+
+  # ---------------------------------------------------------------------------
+  # support_desk_tickets (+)
+  #
+  # `assistant_revision` is the turn: one integer, bumped by every
+  # registered message and every transition, which is what makes a late or
+  # redelivered answer a no-op instead of a second reply.
+  #
+  # The three human-side flags are THREE columns and not one status, because
+  # they are three different decisions made by three different people:
+  # somebody asked for a person, a human paused her here, and this case caps
+  # her (what a reopen after she closed it writes). Resuming her lifts one
+  # of them, and only an explicit hand-back lifts all three.
+  # ---------------------------------------------------------------------------
+  def add_ticket_columns
+    ticket_columns.each do |name, options|
+      next if column_exists?(:support_desk_tickets, name)
+
+      add_column :support_desk_tickets, name, options[:type], **options.except(:type)
+    end
+
+    return if index_exists?(:support_desk_tickets, [ :desk_id, :human_required_at ], name: TICKET_INDEX)
+
+    add_index :support_desk_tickets, [ :desk_id, :human_required_at ], name: TICKET_INDEX
+  end
+
+  def ticket_columns
+    {
+      assistant_revision: { type: :bigint, null: false, default: 0 },
+      last_requester_message_id: { type: sql_type_of(:chats_messages, "id") },
+      assistant_turns_count: { type: :integer, null: false, default: 0 },
+      assistant_acted_at: { type: :datetime },
+      assistant_paused_at: { type: :datetime },
+      assistant_paused_reason: { type: :string },
+      assistant_cap: { type: :string },
+      human_required_at: { type: :datetime },
+      human_required_reason: { type: :string }
+    }
+  end
+
+  # The pointer the turn's reconciliation reads: which requester message the
+  # clocks are standing on, by id and not only by time.
+  #
+  # SQL, and deliberately not the model: a backfill that loaded today's
+  # Ticket would run this release's validations, callbacks and events over
+  # last release's rows. ORDER BY rather than MAX(id), because ids can be
+  # uuids and "the biggest uuid" is not "the newest message".
+  def backfill_requester_pointer
+    execute(<<~SQL.squish)
+      UPDATE support_desk_tickets SET last_requester_message_id = (
+        SELECT m.id FROM chats_messages m
+         WHERE m.conversation_id = support_desk_tickets.conversation_id
+           AND m.sender_type = support_desk_tickets.requester_type
+           AND m.sender_id = support_desk_tickets.requester_id
+           AND m.kind = 'text'
+         ORDER BY m.created_at DESC, m.id DESC LIMIT 1)
+       WHERE last_requester_message_id IS NULL AND conversation_id IS NOT NULL
+    SQL
+  end
+
+  # The storage this schema already uses for that column — uuid, bigint,
+  # integer. A new column that points at those records has to be stored the
+  # same way, whatever the generator is configured with today.
+  def sql_type_of(table, column)
+    found = connection.columns(table).find { |candidate| candidate.name == column }
+    unless found
+      raise ActiveRecord::MigrationError,
+            "#{table} has no #{column} column — run support_desk's and chats' install migrations first."
+    end
+
+    found.sql_type
+  end
+
+  # Honor the host's configured primary key type (uuid vs bigint) for the
+  # tables this migration CREATES. Everything it points at is derived above.
+  def primary_key_type
+    config = Rails.configuration.generators
+    config.options[config.orm][:primary_key_type] || :primary_key
+  end
+
+  # Whether this adapter can enforce a rule over SOME rows ("one pending
+  # draft per case"). Everything but MySQL can — and Trilogy is MySQL under
+  # a different ADAPTER_NAME, so a /mysql/ pattern alone would hand such a
+  # host an index it cannot create.
+  def partial_indexes?
+    !connection.adapter_name.match?(/mysql|trilogy/i)
+  end
+
+  # jsonb on every PostgreSQL adapter — matched by prefix because PostGIS
+  # answers "PostGIS", not "PostgreSQL".
+  def json_column_type
+    return :jsonb if connection.adapter_name.match?(/\Apostg/i)
+
+    :json
+  end
+
+  # MySQL 8+ doesn't allow default values on JSON columns. `sources`
+  # defaults to [] in Ruby (see SupportDesk::Draft) for the same reason it
+  # can't default here.
+  def json_column_default
+    return nil if connection.adapter_name.match?(/mysql|trilogy/i)
+
+    {}
+  end
+end

data/lib/generators/support_desk/templates/assistant/service.rb.erb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Support
+  # <%= assistant_name %>'s mind. Everything the gem knows how to do stops at the
+  # door of this file: which provider you call, what you put in the prompt,
+  # how you cache, what you spend, and what you refuse to answer are yours.
+  #
+  # What comes in:
+  #
+  # * `brief` — a SupportDesk::Brief. `brief.to_h` is versioned data;
+  #   `brief.to_text` is the same facts as plain text. It carries the desk,
+  #   the case, the requester, and `may` / `may_not` — the authorization,
+  #   so you never have to re-derive the rules this case is under.
+  # * `transcript` — a SupportDesk::Transcript. `to_text` is the readable
+  #   rendering; `to_a` is Turns (`role`, `name`, `body`, `at`,
+  #   `attachments`, `assisted`).
+  #
+  # ⚠️ Both of these go to whatever you call. `support_context` (the
+  # subject's and the requester's) is host data, chosen by you, and it
+  # leaves your building the moment this method does. Decide what belongs in
+  # a prompt before you fill those in, not after.
+  #
+  # What goes out: an Answer. Nothing else — this method never touches the
+  # ticket. The job owns the writes, so the turn, the policy and the lock
+  # are checked in exactly one place.
+  class <%= key.camelize %>
+    # `kind` is the whole decision:
+    #
+    #   :answer   — say this. `text` required; `confidence` (0..1) and
+    #               `sources` ([{ title:, url: }]) are shown to the agent
+    #               reviewing the proposal, so fill them in honestly.
+    #   :hand_off — a person should take this. `reason` required, `summary`
+    #               is the paragraph the next human reads first.
+    #   :note     — leave a staff note and stop. Never reaches the customer.
+    #   :nothing  — do nothing. The case stays in the humans' queue.
+    Answer = Struct.new(:kind, :text, :confidence, :sources, :reason, :summary, :metadata,
+                        keyword_init: true) do
+      def initialize(**attributes)
+        super
+        self.kind ||= :nothing
+        self.sources ||= []
+        self.metadata ||= {}
+      end
+    end
+
+    # Answer one case.
+    #
+    #   def self.answer(brief, transcript)
+    #     reply = MyModel.complete(system: PROMPT, user: brief.to_text)
+    #     return Answer.new(kind: :hand_off, reason: "unsure") if reply.confidence < 0.6
+    #
+    #     Answer.new(kind: :answer, text: reply.text, confidence: reply.confidence)
+    #   end
+    def self.answer(brief, transcript)
+      raise NotImplementedError,
+            "#{self} has no answer yet. Write one — the contract is the Assistants " \
+            "section of the support_desk README (brief in, Answer out, no ticket writes)."
+    end
+  end
+end

data/lib/generators/support_desk/templates/assistant/turn_job.rb.erb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Support
+  # <%= assistant_name %>'s turn.
+  #
+  # The gem emits `:assistant_turn` when there is something to answer; this
+  # job is the only thing that runs between that event and a word reaching a
+  # customer.
+  #
+  # Four rules, and they are the whole contract (README → Assistants):
+  #
+  # 1. **Arguments are ids, never records and never a prompt.** A serialized
+  #    ticket is a ticket as it was when the job was enqueued, and by the
+  #    time a worker picks it up that is a guess.
+  # 2. **Check the turn before spending money.** `assistant_turn` moves on
+  #    every message and every transition, so a mismatch means the case
+  #    changed while this job waited — and the newer turn's job already
+  #    exists. Returning here costs nothing; calling a model costs money to
+  #    produce an answer that would be refused anyway.
+  # 3. **Hand the answer to exactly one verb**, all of them `by:` her and
+  #    `turn:` this turn. Each consumes the turn and returns the successor
+  #    (`Outcome#turn` / `ticket.assistant_turn`); a second action in the
+  #    same run uses that one.
+  # 4. **`SupportDesk::StaleTurn` and `Locked` are normal outcomes**, not
+  #    failures — hence `discard_on` below. `SupportDesk::AssistantNotAllowed`
+  #    is NOT: the brief said `may_not`, so reaching it is a bug in here.
+  class <%= key.camelize %>TurnJob < ApplicationJob
+    queue_as :support
+
+    # A late job, a redelivered one and a case that moved on all land as
+    # StaleTurn, and all three mean the same thing: somebody else has this.
+    # Locked means there is nobody to write to any more. RecordNotFound
+    # means the case is gone. None of them is worth a retry.
+    #
+    # Provider timeouts ARE worth one — put `retry_on` for those here. Note
+    # that a retry AFTER a committed action raises StaleTurn and is
+    # discarded, which is exactly right: the work was done.
+    discard_on SupportDesk::StaleTurn, SupportDesk::Locked, ActiveRecord::RecordNotFound
+
+    def perform(ticket_id, assistant_key, turn)
+      ticket = SupportDesk::Ticket.find(ticket_id)
+      return unless ticket.assistant_turn == turn          # the case moved on while we waited
+
+      <%= key %> = SupportDesk.assistant(assistant_key)
+      return unless ticket.assistant_policy(<%= key %>).may_observe?
+
+      answer = <%= service_class %>.answer(ticket.brief, ticket.transcript)
+
+      case answer.kind
+      when :answer
+        # `respond!` lets POLICY decide what this becomes: sent, proposed as
+        # a draft for a person to send, or withheld with a reason on the
+        # record. Never encode the level in here — it changes per case.
+        ticket.respond!(answer.text, by: <%= key %>, turn: turn, confidence: answer.confidence,
+                                     sources: answer.sources, metadata: answer.metadata)
+      when :hand_off
+        ticket.escalate!(by: <%= key %>, turn: turn, reason: answer.reason, summary: answer.summary)
+      when :note
+        # Staff only. Never reaches the conversation.
+        ticket.note!(answer.text, by: <%= key %>, turn: turn)
+      when :nothing
+        # She decided not to act. The turn is NOT consumed and the case
+        # stays in the humans' queue — which is why `SupportDesk.doctor`
+        # counts idle turns: a harness that always answers :nothing looks
+        # exactly like one that is down.
+        nil
+      else
+        raise ArgumentError, "unsupported answer kind #{answer.kind.inspect}"
+      end
+    end
+  end
+end

data/lib/generators/support_desk/templates/assistant/turn_job_test.rb.erb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+# The three things about a harness that are worth a test, and the only three
+# that are the same in every app: the level decides what her answer BECOMES,
+# raising the level changes that and nothing else, and a turn that is no
+# longer the case's writes nothing at all.
+#
+# <%= service_class %>.answer is stubbed throughout — this is a test of the
+# wiring, not of a model. Point `requester` and `agent` at your own fixtures
+# and it runs.
+class <%= key.camelize %>TurnJobTest < ActiveSupport::TestCase
+  include SupportDesk::TestHelpers
+
+  setup do
+    @<%= key %> = SupportDesk.assistant(:<%= key %>)
+    @ticket = open_support_ticket(for: requester, message: "No me han pagado")
+  end
+
+  test "at :draft her answer waits for a person" do
+    answering("Lo estamos revisando") do
+      <%= job_class %>.perform_now(@ticket.id, "<%= key %>", @ticket.assistant_turn)
+    end
+
+    draft = assert_pending_draft @ticket, body: "revisando"
+    assert_equal @<%= key %>, draft.author
+    # Nothing reached the customer: a proposal is not a message.
+    refute_assistant_spoke @ticket
+  end
+
+  test "at :reply she answers the customer herself" do
+    with_assistant_config(:<%= key %>, autonomy: :reply) do
+      answering("Lo estamos revisando") do
+        <%= job_class %>.perform_now(@ticket.id, "<%= key %>", @ticket.assistant_turn)
+      end
+    end
+
+    assert_awaiting_requester @ticket
+    refute_pending_draft @ticket
+  end
+
+  test "a stale turn writes nothing and costs nothing" do
+    stale = @ticket.assistant_turn
+    ask_again(@ticket, "¿hola?")   # the customer wrote again: the turn moved
+
+    called = false
+    <%= service_class %>.stub(:answer, ->(*) { called = true; answer_for("…") }) do
+      <%= job_class %>.perform_now(@ticket.id, "<%= key %>", stale)
+    end
+
+    assert_not called, "the job called the model on a turn that was no longer the case's"
+    refute_pending_draft @ticket
+    refute_assistant_spoke @ticket
+  end
+
+  private
+
+  # The person asking. Point this at your own fixture or factory.
+  def requester = users(:one)
+
+  def answer_for(text)
+    <%= service_class %>::Answer.new(kind: :answer, text: text, confidence: 0.9)
+  end
+
+  def answering(text, &block)
+    <%= service_class %>.stub(:answer, ->(*) { answer_for(text) }, &block)
+  end
+end

data/lib/generators/support_desk/templates/initializer.rb

@@ -175,6 +175,39 @@ SupportDesk.configure do |config|
   # config.mirror_replies_by_email = :when_away   # :always | :when_away | :never
   # config.auto_close_after = nil                 # e.g. 7.days
 
+  # ==========================================================================
+  # AN ASSISTANT (0.3)
+  # ==========================================================================
+  #
+  # An AI agent, with the guardrails in code. `autonomy` is the most she may
+  # ever produce; topics only cap it DOWN. `disclosure` is REQUIRED — whether
+  # a customer is told they are talking to a machine is your decision, and
+  # `:none` is how you say "nothing", on purpose.
+  #
+  # config.assistant :rose do |rose|
+  #   rose.name            = "Rose"
+  #   rose.autonomy        = :draft                # :off :observe :draft :reply :resolve
+  #   rose.disclosure      = :signature_and_notice # :signature | :notice | :none
+  #   rose.max_turns       = 6
+  #   rose.responds_within = 3.minutes
+  #   rose.hand_off_when { |_ticket, message| message.body.to_s.match?(/\bpersona\b/i) }
+  #   rose.cap { |ticket| :draft if ticket.requester.try(:vip?) }
+  # end
+  # config.default_assistant = :rose
+  #
+  # The desk-level binding, for installations with more than one desk. An
+  # explicit nil means "no assistant HERE", which is not the same as
+  # inheriting the default one.
+  #
+  # config.desk(:billing) { |desk| desk.assistant = nil }
+  #
+  # Then subscribe your harness to the one event it needs — see the README's
+  # assistants section for the whole contract.
+  #
+  # SupportDesk.on(:assistant_turn, key: "support.rose.turn") do |ticket, assistant, _message, turn:|
+  #   Support::RoseTurnJob.set(wait: 20.seconds).perform_later(ticket.id, assistant.key, turn)
+  # end
+
   # ==========================================================================
   # MORE THAN ONE DESK
   # ==========================================================================

data/lib/generators/support_desk/upgrade_generator.rb

@@ -18,7 +18,7 @@ module SupportDesk
       include ActiveRecord::Generators::Migration
 
       source_root File.expand_path("templates", __dir__)
-      desc "Add the migrations a support_desk version bump needs (0.2.0: opened_by)"
+      desc "Add the migrations a support_desk version bump needs (0.2.0: opened_by, 0.3.0: assistants)"
 
       # Rails' migration numbering, borrowed from ActiveRecord's generators.
       def self.next_migration_number(dir)
@@ -30,6 +30,11 @@ module SupportDesk
                            File.join(db_migrate_path, "add_opened_by_to_support_desk_tickets.rb")
       end
 
+      def create_assistants_migration
+        migration_template "add_assistants_to_support_desk.rb.erb",
+                           File.join(db_migrate_path, "add_assistants_to_support_desk.rb")
+      end
+
       def display_post_upgrade_message
         say "\n🎫 support_desk upgrade migrations copied.", :green
         say "\n  1. Run 'rails db:migrate'. It adds `opened_by` and points every existing"
@@ -43,7 +48,12 @@ module SupportDesk
         say "     ALL old web requests and workers. This is NOT a rolling deployment."
         say "     Keep traffic paused, run 'rake support_desk:backfill_opened_by' under 0.2,"
         say "     verify no NULL openers remain, then start only 0.2 and resume traffic."
-        say "  4. See the CHANGELOG for the full list.\n", :green
+        say "  4. New in 0.3.0 — assistants. The migration is ADDITIVE and rolling-safe:"
+        say "     add `config.assistant` only once every process is on 0.3.0. Then"
+        say "       rails g support_desk:assistant Rose --disclosure signature"
+        say "     writes the harness and prints the stanza, the subscription and the two"
+        say "     scheduled tasks. It never edits your initializer."
+        say "  5. See the CHANGELOG for the full list.\n", :green
       end
 
       private