robot_lab 0.0.9 → 0.0.12

data/examples/21_learning_loop.rb

@@ -0,0 +1,164 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 21: Learning Accumulation Loop
+#
+# Demonstrates robot.learn() for building up observations between runs.
+# A code reviewer robot analyzes Ruby snippets. After each review, the
+# caller records a key insight as a learning. On the next run, those
+# learnings are automatically prepended to the user message so the robot
+# can incorporate prior observations without needing a persistent chat.
+#
+# Demonstrates:
+#   - robot.learn(text) — adds a learning, deduplicates automatically
+#   - robot.learnings — read the accumulated list
+#   - Learnings injected as "LEARNINGS FROM PREVIOUS RUNS:" prefix
+#   - Superset dedup: a broader learning replaces narrower earlier ones
+#   - Memory persistence: learnings survive rebuilding with the same Memory
+#
+# Usage:
+#   ANTHROPIC_API_KEY=your_key ruby examples/21_learning_loop.rb
+
+ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
+
+require_relative "../lib/robot_lab"
+
+SNIPPETS = [
+  {
+    code: <<~RUBY,
+      def process(items)
+        results = []
+        items.each do |item|
+          results << item * 2
+        end
+        results
+      end
+    RUBY
+    insight: "This codebase prefers map/collect over manual array accumulation"
+  },
+  {
+    code: <<~RUBY,
+      def find_user(id)
+        user = User.find(id)
+        if user != nil
+          return user
+        end
+        return nil
+      end
+    RUBY
+    insight: "Explicit nil comparisons and redundant returns appear frequently here"
+  },
+  {
+    code: <<~RUBY,
+      def calculate_total(cart)
+        total = 0
+        cart.items.each do |item|
+          if item.discount != nil
+            total = total + (item.price - item.discount)
+          else
+            total = total + item.price
+          end
+        end
+        return total
+      end
+    RUBY
+    insight: "Cart/pricing logic tends to have missing edge cases around nil discounts and zero values"
+  }
+].freeze
+
+puts "=" * 65
+puts "Example 21: Learning Accumulation Loop"
+puts "=" * 65
+puts
+
+robot = RobotLab.build(
+  name: "code_reviewer",
+  system_prompt: <<~PROMPT,
+    You are a concise Ruby code reviewer. For each snippet:
+    1. Identify the main issue (one sentence).
+    2. Show the improved version (code block).
+    Keep responses under 80 words total.
+  PROMPT
+  model: "claude-haiku-4-5-20251001"
+)
+
+SNIPPETS.each_with_index do |item, i|
+  run_number = i + 1
+
+  # ---------------------------------------------------------------
+  # Show what learnings are active going into this run
+  # ---------------------------------------------------------------
+  puts "--- Run #{run_number} ---"
+  if robot.learnings.empty?
+    puts "Learnings:  (none yet)"
+  else
+    puts "Learnings injected into this prompt:"
+    robot.learnings.each { |l| puts "  • #{l}" }
+  end
+  puts
+
+  # ---------------------------------------------------------------
+  # Run the robot — accumulated learnings are prepended automatically
+  # ---------------------------------------------------------------
+  result = robot.run("Review this Ruby snippet:\n\n#{item[:code]}")
+
+  puts "Review:"
+  puts result.reply&.strip&.gsub(/^/, "  ")
+  puts
+
+  # ---------------------------------------------------------------
+  # Record the insight from this run as a learning
+  # ---------------------------------------------------------------
+  robot.learn(item[:insight])
+  puts "Added learning: #{item[:insight].inspect}"
+  puts
+end
+
+# ---------------------------------------------------------------
+# Show the full accumulated learning list
+# ---------------------------------------------------------------
+puts "=" * 65
+puts "Accumulated learnings (#{robot.learnings.size} total):"
+robot.learnings.each_with_index { |l, i| puts "  #{i + 1}. #{l}" }
+puts
+
+# ---------------------------------------------------------------
+# Demonstrate superset dedup: a broader learning replaces narrower ones
+# ---------------------------------------------------------------
+puts "--- Deduplication demo ---"
+puts
+robot2 = RobotLab.build(name: "reviewer2", system_prompt: "You review code.")
+
+robot2.learn("avoid using puts")
+robot2.learn("avoid using puts and p in production code")  # covers the first
+
+puts "Learnings after adding broader statement (should be 1, not 2):"
+robot2.learnings.each_with_index { |l, i| puts "  #{i + 1}. #{l}" }
+puts
+
+# ---------------------------------------------------------------
+# Demonstrate persistence: learnings survive a robot rebuild using
+# the same Memory object
+# ---------------------------------------------------------------
+puts "--- Persistence across rebuild ---"
+puts
+
+shared_memory = robot.instance_variable_get(:@memory)
+rebuilt = RobotLab.build(
+  name: "code_reviewer",
+  system_prompt: "You review code.",
+  model: "claude-haiku-4-5-20251001"
+)
+rebuilt.instance_variable_set(:@memory, shared_memory)
+
+# Trigger the memory restore path
+persisted = shared_memory.get(:learnings)
+rebuilt.instance_variable_set(:@learnings, Array(persisted))
+
+puts "Learnings on rebuilt robot (#{rebuilt.learnings.size}):"
+rebuilt.learnings.each_with_index { |l, i| puts "  #{i + 1}. #{l}" }
+puts
+
+puts "=" * 65
+puts "Learning loop demo complete."
+puts "=" * 65

data/examples/22_context_compression.rb

@@ -0,0 +1,179 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 22: Context Window Compression
+#
+# Demonstrates robot.compress_history() for reducing token usage in long
+# conversations. Old turns are scored against the recent context using
+# stemmed term-frequency cosine similarity. High-relevance turns are kept
+# verbatim; irrelevant turns are dropped; medium-relevance turns can be
+# summarized by a second robot.
+#
+# Demonstrates:
+#   - robot.compress_history() — drop/keep/summarize old turns in-place
+#   - recent_turns: N — last N user+assistant pairs always protected
+#   - keep_threshold: / drop_threshold: — tunable relevance bands
+#   - summarizer: — optional lambda(text) -> String for medium-relevance
+#   - Token reduction reported before/after compression
+#
+# Requires:
+#   gem 'classifier', '~> 2.3'   # add to your Gemfile
+#
+# Usage:
+#   ANTHROPIC_API_KEY=your_key ruby examples/22_context_compression.rb
+
+ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
+
+require_relative "../lib/robot_lab"
+
+# ---------------------------------------------------------------------------
+# Check optional dependency
+# ---------------------------------------------------------------------------
+begin
+  require "classifier"
+rescue LoadError
+  puts "This example requires the classifier gem."
+  puts "Add to your Gemfile:  gem 'classifier', '~> 2.3'"
+  exit 1
+end
+
+# ---------------------------------------------------------------------------
+# Helper to count approximate tokens (rough: 4 chars per token)
+# ---------------------------------------------------------------------------
+def approx_tokens(messages)
+  messages.sum do |m|
+    content = m.respond_to?(:content) ? m.content.to_s : m.to_s
+    (content.length / 4.0).ceil
+  end
+end
+
+puts "=" * 60
+puts "Example 22: Context Window Compression"
+puts "=" * 60
+puts
+
+# ---------------------------------------------------------------------------
+# Build a robot and simulate a long conversation on two topics
+# ---------------------------------------------------------------------------
+bot = RobotLab.build(
+  name:          "assistant",
+  system_prompt: "You are a concise Ruby expert. Reply in 2-3 sentences."
+)
+
+puts "Simulating a long conversation (no real LLM calls)..."
+puts
+
+# Simulate a conversation history with two distinct topics:
+# older turns: Ruby metaprogramming (will become irrelevant)
+# recent turns: Rails routing (current topic)
+
+require "ostruct"
+
+FakeMsg = Struct.new(:role, :content, :tool_calls, :stop_reason) do
+  def text?      = true
+  def tool_use?  = false
+  def system?    = role == :system
+  def user?      = role == :user
+  def assistant? = role == :assistant
+end
+
+def fake(role, content)
+  FakeMsg.new(role.to_sym, content, nil, :stop)
+end
+
+history = [
+  fake(:system,    "You are a concise Ruby expert. Reply in 2-3 sentences."),
+
+  # --- OLD TOPIC: Ruby metaprogramming (5 turns back) ---
+  fake(:user,      "Explain Ruby's method_missing and when to use it."),
+  fake(:assistant, "method_missing is called when an object receives an undefined message. It's useful for DSLs and proxy objects, but add respond_to_missing? too. Use sparingly as it hurts performance."),
+  fake(:user,      "What's the difference between define_method and def?"),
+  fake(:assistant, "define_method creates methods dynamically from a block, capturing closure variables. def is the static keyword form. Use define_method when the method body depends on runtime values."),
+  fake(:user,      "How does BasicObject differ from Object in Ruby?"),
+  fake(:assistant, "BasicObject is the root class with minimal methods, useful for proxy and DSL objects that must not inherit standard methods. Object inherits from BasicObject and adds Kernel, making it the normal base class."),
+
+  # --- RECENT TOPIC: Rails routing (last 2 turns, always protected) ---
+  fake(:user,      "How does Rails routing work with resourceful controllers?"),
+  fake(:assistant, "resources :posts generates 7 RESTful routes mapping HTTP verbs to controller actions. You can nest resources and add member/collection routes. Run rails routes to see everything."),
+  fake(:user,      "What is the difference between member and collection routes in Rails?"),
+  fake(:assistant, "Member routes operate on a specific resource (needs :id), collection routes operate on the whole collection. Use member { get :preview } and collection { get :search } inside a resources block.")
+]
+
+before_count = history.size
+before_tokens = approx_tokens(history)
+
+puts "Before compression:"
+puts "  Messages : #{before_count}"
+puts "  ~Tokens  : #{before_tokens}"
+puts
+
+# ---------------------------------------------------------------------------
+# Option A: Drop medium-relevance turns (no summarizer)
+# ---------------------------------------------------------------------------
+compressor_a = RobotLab::HistoryCompressor.new(
+  messages:        history,
+  recent_turns:    2,
+  keep_threshold:  0.25,
+  drop_threshold:  0.05,
+  summarizer:      nil
+)
+
+result_a = compressor_a.call
+tokens_a = approx_tokens(result_a)
+
+puts "After compression (drop mode, recent_turns: 2, keep: 0.25, drop: 0.05):"
+puts "  Messages : #{result_a.size}  (removed #{before_count - result_a.size})"
+puts "  ~Tokens  : #{tokens_a}  (saved #{before_tokens - tokens_a})"
+puts "  Kept roles: #{result_a.map(&:role).join(', ')}"
+puts
+
+# ---------------------------------------------------------------------------
+# Option B: With a summarizer lambda for medium-relevance turns
+# ---------------------------------------------------------------------------
+puts "After compression (summarize mode, keep: 0.5, drop: 0.05):"
+
+summarizer = lambda do |text|
+  # In production this would call a small LLM robot.
+  # Here we fake it by taking the first sentence.
+  text.split(/[.!?]/).first.to_s.strip + "."
+end
+
+compressor_b = RobotLab::HistoryCompressor.new(
+  messages:        history,
+  recent_turns:    2,
+  keep_threshold:  0.5,
+  drop_threshold:  0.05,
+  summarizer:      summarizer
+)
+
+result_b = compressor_b.call
+tokens_b = approx_tokens(result_b)
+
+puts "  Messages : #{result_b.size}  (removed #{before_count - result_b.size})"
+puts "  ~Tokens  : #{tokens_b}  (saved #{before_tokens - tokens_b})"
+puts "  Kept roles: #{result_b.map(&:role).join(', ')}"
+puts
+
+# ---------------------------------------------------------------------------
+# Show the LLM summarizer pattern (not executed — requires API key)
+# ---------------------------------------------------------------------------
+puts "=" * 60
+puts "LLM summarizer pattern (requires API key):"
+puts "=" * 60
+puts <<~RUBY
+
+  summarizer_bot = RobotLab.build(
+    name:          "summarizer",
+    system_prompt: "Summarize the following text in one sentence."
+  )
+
+  robot.compress_history(
+    recent_turns:    3,
+    keep_threshold:  0.6,
+    drop_threshold:  0.2,
+    summarizer:      ->(text) { summarizer_bot.run("Summarize: \#{text}").reply }
+  )
+
+RUBY
+
+puts "Done."

data/examples/23_convergence.rb

@@ -0,0 +1,137 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 23: Debate Convergence Detection
+#
+# Demonstrates RobotLab::Convergence for detecting when two independent
+# agents have reached the same conclusion. This enables a fast-path that
+# skips an expensive reconciler LLM call when verifiers already agree.
+#
+# Demonstrates:
+#   - Convergence.similarity(a, b) — 0.0..1.0 cosine similarity score
+#   - Convergence.detected?(a, b) — boolean above default threshold (0.85)
+#   - Convergence.detected?(a, b, threshold: 0.6) — custom threshold
+#   - Router fast-path pattern: skip reconciler when verifiers agree
+#
+# Requires:
+#   gem 'classifier', '~> 2.3'   # add to your Gemfile
+#
+# Usage:
+#   ANTHROPIC_API_KEY=your_key ruby examples/23_convergence.rb
+
+ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
+
+require_relative "../lib/robot_lab"
+
+# ---------------------------------------------------------------------------
+# Check optional dependency
+# ---------------------------------------------------------------------------
+begin
+  require "classifier"
+rescue LoadError
+  puts "This example requires the classifier gem."
+  puts "Add to your Gemfile:  gem 'classifier', '~> 2.3'"
+  exit 1
+end
+
+puts "=" * 60
+puts "Example 23: Debate Convergence Detection"
+puts "=" * 60
+puts
+
+# ---------------------------------------------------------------------------
+# Similarity scoring
+# ---------------------------------------------------------------------------
+pairs = {
+  "Identical responses" => [
+    "The time complexity of quicksort is O(n log n) average case and O(n²) worst case. Use merge sort for guaranteed O(n log n).",
+    "The time complexity of quicksort is O(n log n) average case and O(n²) worst case. Use merge sort for guaranteed O(n log n)."
+  ],
+  "Semantically similar (same conclusion)" => [
+    "Quicksort has average O(n log n) time complexity but degrades to O(n²) in the worst case. Prefer merge sort when stability matters.",
+    "The average time complexity of quicksort is O(n log n). In the worst case it becomes O(n²), so merge sort is safer for sorted input."
+  ],
+  "Partially related (same topic, different focus)" => [
+    "Quicksort is O(n log n) average case. It is in-place and cache-friendly, making it fast in practice despite worst-case concerns.",
+    "Merge sort guarantees O(n log n) in all cases and is stable. It requires O(n) extra space unlike the in-place quicksort."
+  ],
+  "Unrelated responses" => [
+    "Quicksort has average O(n log n) time complexity but degrades to O(n²) in the worst case.",
+    "The Pacific Ocean is the largest and deepest ocean on Earth, covering more than thirty percent of the planet surface area."
+  ]
+}
+
+puts "Similarity scores:"
+puts "-" * 60
+pairs.each do |label, (a, b)|
+  score = RobotLab::Convergence.similarity(a, b)
+  converged = RobotLab::Convergence.detected?(a, b, threshold: 0.6)
+  puts "  #{label}"
+  puts "    Score: #{"%.3f" % score}  |  Converged at 0.60: #{converged ? "YES" : "no"}"
+  puts
+end
+
+# ---------------------------------------------------------------------------
+# Router fast-path pattern
+# ---------------------------------------------------------------------------
+puts "=" * 60
+puts "Router fast-path pattern"
+puts "=" * 60
+puts <<~RUBY
+
+  # Two verifier robots run in parallel and store their replies in shared memory.
+  # The router checks convergence before dispatching to the expensive reconciler.
+
+  router = ->(args) do
+    a = args.context[:verifier_a]&.reply.to_s
+    b = args.context[:verifier_b]&.reply.to_s
+
+    if RobotLab::Convergence.detected?(a, b)
+      nil   # Both agree — skip reconciler, network halts here
+    else
+      ["reconciler"]
+    end
+  end
+
+  network = RobotLab.create_network(
+    name:   "fact_check",
+    robots: [verifier_a, verifier_b, reconciler],
+    router: router
+  )
+
+  result = network.run(message: "Is this claim accurate?")
+
+RUBY
+
+# ---------------------------------------------------------------------------
+# Demonstrate with simulated verifier outputs
+# ---------------------------------------------------------------------------
+puts "Simulating verifier fast-path:"
+puts "-" * 60
+
+verifier_outputs = [
+  {
+    label:  "Verifiers agree (skip reconciler)",
+    a:      "The claim is accurate. Photosynthesis converts light energy into glucose using carbon dioxide and water, producing oxygen as a byproduct.",
+    b:      "This is correct. Photosynthesis uses sunlight, CO₂, and water to produce glucose and oxygen in plant cells.",
+    threshold: 0.5
+  },
+  {
+    label:  "Verifiers disagree (call reconciler)",
+    a:      "The claim is accurate. The Great Wall of China is visible from space with the naked eye at low Earth orbit.",
+    b:      "The claim is false. Astronauts confirm the Great Wall cannot be seen from space without magnification because it is far too narrow.",
+    threshold: 0.7
+  }
+]
+
+verifier_outputs.each do |scenario|
+  score     = RobotLab::Convergence.similarity(scenario[:a], scenario[:b])
+  converged = RobotLab::Convergence.detected?(scenario[:a], scenario[:b], threshold: scenario[:threshold])
+  action    = converged ? "SKIP reconciler (fast-path)" : "CALL reconciler"
+
+  puts "  #{scenario[:label]}"
+  puts "    Score: #{"%.3f" % score}  →  #{action}"
+  puts
+end
+
+puts "Done."

data/examples/24_structured_delegation.rb

@@ -0,0 +1,150 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 24: Structured Delegation
+#
+# Demonstrates robot.delegate(to:, task:) for structured inter-robot calls,
+# in both synchronous (blocking) and asynchronous (parallel fan-out) modes.
+#
+# Demonstrates:
+#   - robot.delegate(to:, task:)              — sync: blocks, returns RobotResult
+#   - robot.delegate(to:, task:, async: true) — async: returns DelegationFuture
+#   - future.value / future.value(timeout: N) — block until result ready
+#   - future.resolved?                        — non-blocking poll
+#   - result.delegated_by — which robot delegated
+#   - result.robot_name   — which robot did the work
+#   - result.duration     — wall-clock seconds for the delegated call
+#   - result.input_tokens / result.output_tokens — delegatee's token usage
+#   - Contrast with bus messaging (fire-and-forget) and pipelines (predefined)
+#
+# Usage:
+#   ANTHROPIC_API_KEY=your_key ruby examples/24_structured_delegation.rb
+
+ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
+
+require_relative "../lib/robot_lab"
+
+puts "=" * 60
+puts "Example 24: Structured Delegation"
+puts "=" * 60
+puts
+
+# ---------------------------------------------------------------------------
+# Build a manager and two specialist robots
+# ---------------------------------------------------------------------------
+manager = RobotLab.build(
+  name:          "manager",
+  system_prompt: "You are a project manager. Delegate tasks concisely."
+)
+
+summarizer = RobotLab.build(
+  name:          "summarizer",
+  system_prompt: "You are a concise summarizer. Produce a 1-2 sentence summary."
+)
+
+analyst = RobotLab.build(
+  name:          "analyst",
+  system_prompt: "You are a data analyst. Identify the key metric in one sentence."
+)
+
+# ---------------------------------------------------------------------------
+# Manager delegates to each specialist in turn
+# ---------------------------------------------------------------------------
+document = <<~TEXT
+  Q4 revenue came in at $4.2M, up 18% year-over-year. Customer acquisition
+  cost dropped to $120, the lowest in three years. Churn held steady at 2.1%.
+  Net promoter score improved from 42 to 58. The mobile app drove 34% of new
+  sign-ups, compared to 19% in Q3.
+TEXT
+
+puts "Document:"
+puts document
+puts "-" * 60
+
+# ---------------------------------------------------------------------------
+# Synchronous delegation — sequential, blocks until each result arrives
+# ---------------------------------------------------------------------------
+puts "── Synchronous (sequential) ──────────────────────────────"
+puts
+
+puts "Delegating to summarizer (blocking)..."
+summary_result = manager.delegate(to: summarizer, task: "Summarize this report:\n\n#{document}")
+
+puts "Summary (from #{summary_result.robot_name}, delegated by #{summary_result.delegated_by}):"
+puts "  #{summary_result.reply}"
+puts "  Duration: #{"%.2f" % summary_result.duration}s | " \
+     "Tokens: #{summary_result.input_tokens} in / #{summary_result.output_tokens} out"
+puts
+
+puts "Delegating to analyst (blocking)..."
+analysis_result = manager.delegate(to: analyst, task: "What is the single most important metric here?\n\n#{document}")
+
+puts "Analysis (from #{analysis_result.robot_name}, delegated by #{analysis_result.delegated_by}):"
+puts "  #{analysis_result.reply}"
+puts "  Duration: #{"%.2f" % analysis_result.duration}s | " \
+     "Tokens: #{analysis_result.input_tokens} in / #{analysis_result.output_tokens} out"
+puts
+
+# ---------------------------------------------------------------------------
+# Asynchronous delegation — parallel fan-out, results collected later
+# ---------------------------------------------------------------------------
+puts "── Asynchronous (parallel fan-out) ───────────────────────"
+puts
+
+# Fresh robots — each delegate call should start from a clean slate
+async_summarizer = RobotLab.build(
+  name:          "summarizer",
+  system_prompt: "You are a concise summarizer. Produce a 1-2 sentence summary."
+)
+async_analyst = RobotLab.build(
+  name:          "analyst",
+  system_prompt: "You are a data analyst. Identify the key metric in one sentence."
+)
+
+puts "Firing both delegations in parallel..."
+t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+f_summary  = manager.delegate(to: async_summarizer, task: "Summarize this report:\n\n#{document}",                     async: true)
+f_analysis = manager.delegate(to: async_analyst,    task: "What is the single most important metric?\n\n#{document}", async: true)
+
+puts "Both futures launched. Futures resolved? " \
+     "summary=#{f_summary.resolved?} analysis=#{f_analysis.resolved?}"
+puts "Collecting results..."
+
+summary  = f_summary.value(timeout: 60)
+analysis = f_analysis.value(timeout: 60)
+
+elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+
+puts
+puts "Summary  (#{summary.robot_name}):  #{summary.reply}"
+puts "Analysis (#{analysis.robot_name}): #{analysis.reply}"
+puts
+puts "Total wall time with parallelism: #{"%.2f" % elapsed}s " \
+     "(vs ~#{"%.2f" % (summary.duration + analysis.duration)}s sequential)"
+puts
+
+# ---------------------------------------------------------------------------
+# Contrast with the alternatives
+# ---------------------------------------------------------------------------
+puts "=" * 60
+puts "When to use delegate vs. the alternatives"
+puts "=" * 60
+puts <<~TEXT
+
+  bus messaging       — fire-and-forget; no return value; async
+                        use when: you want to notify without waiting
+
+  pipeline            — predefined sequence; robots share memory
+                        use when: you have a fixed workflow graph
+
+  delegate()          — synchronous; blocks; returns RobotResult with metadata
+                        use when: one robot needs the result of another's work
+
+  delegate(async:true) — returns DelegationFuture immediately
+                         use when: you want to run multiple delegates in
+                         parallel and collect results when ready
+
+TEXT
+
+puts "Done."

data/examples/25_history_search/conversation.jsonl

@@ -0,0 +1,30 @@
+{"role":"user","content":"We need to add a `status` column to the orders table. There are about 4 million rows in production. What's the safest migration approach?"}
+{"role":"assistant","content":"For a 4M-row table on Postgres, use strong_migrations: add the column with a default of null first, then backfill in batches of 1000 rows using a separate script, and finally add the NOT NULL constraint with a DEFAULT only after the backfill completes. This avoids a full table lock. Set lock_timeout to 5 seconds and statement_timeout to 10 seconds on the migration connection so a slow query can't block deploys."}
+{"role":"user","content":"Should we add an index on status at the same time?"}
+{"role":"assistant","content":"Create it concurrently: `add_index :orders, :status, algorithm: :concurrent`. This builds the index without holding an exclusive lock. Run it in a separate migration from the column addition, and monitor pg_stat_activity during the build. Expect it to take 2-5 minutes on a 4M-row table; plan a maintenance window if your DB is under heavy write load during that time."}
+{"role":"user","content":"What about the foreign key from order_items to orders? We have cascade deletes enabled."}
+{"role":"assistant","content":"Cascade deletes with a busy foreign key can cause unexpected lock chains. Before the migration, check pg_locks for any long-running transactions that hold row locks on orders. If you see contention, defer the cascade to application-level logic: remove the database-level ON DELETE CASCADE, handle the deletion in an after_destroy callback, and wrap it in a transaction with a retry on deadlock. Log any cascade failures to a dead_letter table so nothing silently disappears."}
+{"role":"user","content":"The GET /api/v2/orders endpoint is averaging 800ms in production. Our SLA is 200ms. Where do we start?"}
+{"role":"assistant","content":"Start with rack-mini-profiler in staging with the pp=flamegraph query parameter — it will show exactly where the time is going. My first guess is N+1 queries: every order record is probably triggering individual SELECTs on users, products, and shipments. Add includes(:user, :line_items => :product, :shipments) to your base scope. Run EXPLAIN (ANALYZE, BUFFERS) on the resulting query; you want to see index scans, not sequential scans."}
+{"role":"user","content":"We found 14 N+1 queries. After fixing those, we're down to 420ms. Still too slow."}
+{"role":"assistant","content":"Good progress. Next suspect is serialization. If you're using ActiveModelSerializers or JBuilder, move to Blueprinter or oj with a hand-rolled hash — serialization overhead on large collections is significant. Also check whether you're calling .count anywhere inside a loop; that's a hidden query. Beyond that, look at pagination: if the endpoint returns more than 50 records, add Kaminari or cursor-based pagination and cap the page size. A 50-record page should serialize in under 5ms."}
+{"role":"user","content":"Response is 210ms now. Can we cache this endpoint?"}
+{"role":"assistant","content":"Yes. Use Russian doll caching: cache the full collection response keyed on max(orders.updated_at) plus the user_id and page number. Set a 5-minute TTL and add a cache-control: public, max-age=60 header for CDN caching. Invalidate on order write using an after_commit hook. For authenticated endpoints, ensure Vary: Authorization is in the response headers so the CDN does not serve one user's data to another. Monitor hit rate with Rails.cache.stats — aim for > 80% before calling it done."}
+{"role":"user","content":"Our current deploy takes 22 minutes from merge to production. The team is frustrated. What's slowing it down?"}
+{"role":"assistant","content":"Pull the CI timing breakdown. Common culprits in that range: (1) test suite parallelism is low — if you're running 2000 tests on a single container, split across 4 and save 8-10 minutes; (2) Docker image builds are not caching gem layers — pin the Gemfile.lock COPY before the rest of the source so the bundle install layer is reused on unchanged deps; (3) you may be running integration tests that hit external APIs or spin up the full Rails app — stub those with WebMock or VCR in CI and save 3-4 minutes. Which CI platform are you on?"}
+{"role":"user","content":"GitHub Actions. We're already using matrix builds but our Docker layer caching is definitely off."}
+{"role":"assistant","content":"Add cache-from: type=gha and cache-to: type=gha,mode=max to your docker/build-push-action step. With GHA cache, the gem install layer will be a cache hit on most PRs and saves 5-7 minutes. Also enable --mount=type=cache,target=/usr/local/bundle in your Dockerfile RUN step for the bundle install — this caches gems inside the BuildKit layer cache. Together these typically cut Docker build time from 8 minutes to under 2."}
+{"role":"user","content":"What's the right rollback procedure if something goes wrong post-deploy?"}
+{"role":"assistant","content":"Maintain a three-step rollback playbook: (1) Feature flag off — if the broken feature is behind a flag, disable it in LaunchDarkly or Flipper without touching code; (2) ECS rollback to previous image — update the task definition to the previous image tag; this takes under 60 seconds. (3) Database rollback — only if a migration ran and is reversible. Run db:rollback on each app instance, then redeploy the old image. Keep an #incidents Slack channel with a pinned deploy log showing the last 5 image SHAs so the on-call engineer does not have to dig."}
+{"role":"user","content":"Should we do blue-green deploys?"}
+{"role":"assistant","content":"Blue-green makes sense if your rollback SLA is under 30 seconds. The overhead: you need to run double the app servers during deploy (cost), and any migrations must be backwards-compatible with both the old and new code simultaneously — no column renames, no dropping columns the old code reads. A simpler middle ground is a canary deploy: route 5% of traffic to the new version, watch error rate and p99 for 10 minutes, then promote. This requires a weighted target group split in the load balancer."}
+{"role":"user","content":"Our invoice generation Sidekiq jobs are failing intermittently with Stripe timeout errors. How should we handle retries?"}
+{"role":"assistant","content":"Use Sidekiq's built-in retry with exponential backoff, but add a custom retry delay for Stripe errors specifically. In the job class: sidekiq_retry_in { |count| (count ** 4) + 15 + rand(30) * count }. This gives you roughly 15s, 1m, 5m, 17m, 34m for retries 1-5. More importantly, make the job idempotent: before calling Stripe, check whether an invoice with your idempotency key already exists. Stripe accepts an Idempotency-Key header — set it to \"invoice-ORDER_ID-ATTEMPT\" so a duplicate call returns the already-created invoice rather than billing twice."}
+{"role":"user","content":"We're seeing jobs pile up in the dead queue when Stripe is degraded. 500+ dead jobs after a 20-minute outage."}
+{"role":"assistant","content":"That pile-up usually means max_retries is too low and jobs exhaust retries during the outage window. Raise it to 10 retries (covers ~6 hours of backoff). Add a Sidekiq job middleware that checks a circuit breaker flag in Redis before processing: if stripe:circuit_open is set, re-enqueue the job with a 5-minute delay instead of retrying immediately. Set the circuit breaker when you detect 3 consecutive Stripe failures, and auto-clear it after 10 minutes. This preserves the dead queue for genuine bugs rather than temporary outages."}
+{"role":"user","content":"How do we handle the dead queue cleanup after an outage?"}
+{"role":"assistant","content":"Build a Rake task that pulls jobs from the dead set, filters by error class and job age, and re-enqueues them in batches of 50 with a 1-second sleep between batches to avoid hammering the newly-recovered service. Log each re-enqueue with the original job args and failure reason. Run it manually after confirming Stripe is healthy. Never blindly drain the dead queue — inspect the error messages first; some failures may be data issues that need a code fix before retry."}
+{"role":"user","content":"We have two new engineers starting Monday. What should their first week look like?"}
+{"role":"assistant","content":"Day 1: environment setup (README-driven, should take under 2 hours), 1:1 with their manager, and a codebase walkthrough covering the main domain models. Days 2-3: pair on a small bug or chore ticket — something real but low-stakes. Day 4: own a small feature end-to-end, including writing the test. Day 5: retro on what was confusing in the onboarding docs and update the README. The goal by end of week one is that they've shipped something, however small, and feel unblocked asking questions."}
+{"role":"user","content":"Thanks"}
+{"role":"assistant","content":"Sure!"}