robot_lab-rails 0.2.1 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aea941ab401ce28705914a98694a577399c78cff4cbebb6513b6a3fba02a4525
-  data.tar.gz: aeb31e16dec1408a62bd4fb3424e2b09b7096f845084e6a7ed664ccc253cac29
+  metadata.gz: 363024a9b53fc93e6bee9f45d93ade96b62f8e2fcc86172eb1233baea141b525
+  data.tar.gz: 3ad6bf319772440866cb90ac41169e99eff28e9137143281685c48e46d652774
 SHA512:
-  metadata.gz: e5e0201b324dc571199341a6616a22ac18fe477b0c70ac2c86a25614360f8e87074c6142646baba92e9562442c03a42155f9368a5d9bea060e508182b9c4fb5f
-  data.tar.gz: 57b6d986ba10d5c08eee1ea4f0ef97dccfde83b5bccf558cbba62dde9389a899fc532f9890a0c0a65c5fc4d1e2adb5320383e44f58f11eccc699ebc2c757455e
+  metadata.gz: ec1fcbe29db8f114c0ce38a942a1582d1d018ac0a834412368763cb02d4bd5e3886cfa55da2d914d2408e7dca553bc1c86c63512f4f717bcb7e8a8dafa1b4ba2
+  data.tar.gz: 5332b0bd26088e36c01610ceae13b34ca3850c3a58a91a82a4fac264239f3dfae6b9625ace7c0f495e91e7d60d31c9b1ac98ce80aa561131d27021a35725d0fe

data/.envrc

@@ -1 +1,3 @@
+source_up
 export RR=`pwd`
+export BUNDLE_GEMFILE=Gemfile

data/.loki

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+# robot_lab-rails — ActiveJob, generators, Turbo broadcasts for Rails apps.
+
+import_up "repo_dev.loki"
+
+class Tasks
+  @@gem_name ||= "robot_lab-rails".freeze
+
+  header "robot_lab-rails v#{gem_version} — Rails integration for RobotLab"
+
+  desc "Run Rails-specific integration tests"
+  def integration
+    sh "bundle exec rake test"
+  end
+end

data/.quality/reek_baseline.txt

@@ -0,0 +1,3 @@
+2	lib/generators/robot_lab/install_generator.rb
+1	lib/robot_lab/rails_integration/engine.rb
+3	lib/robot_lab/rails_integration/job.rb

data/.rubocop.yml

@@ -1,173 +1 @@
-AllCops:
-  NewCops: enable
-  SuggestExtensions: false
-  TargetRubyVersion: 4.0
-  Exclude:
-    - 'examples/**/*'
-    - 'vendor/**/*'
-    - 'dead_code/**/*'
-
-# ── Style: disabled cops ───────────────────────────────────────────────────
-Style/StringLiterals:
-  Enabled: false
-
-Style/StringLiteralsInInterpolation:
-  Enabled: false
-
-Style/Documentation:
-  Enabled: false
-
-# Ruby 4.0 freezes string literals by default
-Style/FrozenStringLiteralComment:
-  Enabled: false
-
-Style/IfUnlessModifier:
-  Enabled: false
-
-Style/RescueModifier:
-  Enabled: false
-
-Style/TrivialAccessors:
-  Enabled: false
-
-Style/MultilineTernaryOperator:
-  Enabled: false
-
-Style/SafeNavigation:
-  Enabled: false
-
-Style/EmptyClassDefinition:
-  Enabled: false
-
-Style/ClassAndModuleChildren:
-  Enabled: false
-
-Style/RescueStandardError:
-  Enabled: false
-
-Style/OneClassPerFile:
-  Enabled: false
-
-# Both % and format/sprintf are acceptable
-Style/FormatString:
-  Enabled: false
-
-# String concatenation and interpolation are both acceptable
-Style/StringConcatenation:
-  Enabled: false
-
-# ── Layout ─────────────────────────────────────────────────────────────────
-Layout/LineLength:
-  Max: 140
-
-Layout/ExtraSpacing:
-  Enabled: false
-
-Layout/HashAlignment:
-  Enabled: false
-
-Layout/FirstHashElementIndentation:
-  Enabled: false
-
-Layout/EmptyLineAfterGuardClause:
-  Enabled: false
-
-# ── Naming ─────────────────────────────────────────────────────────────────
-# Single-char params (c, e, n) are acceptable throughout
-Naming/MethodParameterName:
-  Enabled: false
-
-Naming/VariableNumber:
-  Exclude:
-    - 'test/**/*'
-
-Naming/RescuedExceptionsVariableName:
-  Enabled: false
-
-# set_results and similar explicit setters are clear and conventional
-Naming/AccessorMethodName:
-  Enabled: false
-
-
-# has_tool_calls? and similar are clear and conventional
-Naming/PredicatePrefix:
-  Enabled: false
-
-# Test helper methods don't need to follow predicate naming rules
-Naming/PredicateMethod:
-  Exclude:
-    - 'test/**/*'
-
-# ── Lint: relax noisy cops on intentional patterns ─────────────────────────
-# Library and framework methods commonly accept args for API/documentation purposes
-Lint/UnusedMethodArgument:
-  Enabled: false
-
-
-Lint/EmptyBlock:
-  Exclude:
-    - 'test/**/*'
-
-Lint/ConstantDefinitionInBlock:
-  Exclude:
-    - 'Rakefile'
-    - 'test/**/*'
-
-# ── Gemspec ────────────────────────────────────────────────────────────────
-Gemspec/DevelopmentDependencies:
-  EnforcedStyle: Gemfile
-
-Gemspec/RequiredRubyVersion:
-  Enabled: false
-
-Gemspec/OrderedDependencies:
-  Enabled: false
-
-# ── Metrics ────────────────────────────────────────────────────────────────
-# Framework-level code (routers, parsers, orchestrators) is inherently complex.
-# Flog is the primary complexity gate — these RuboCop thresholds catch only
-# egregious outliers without false-positiving every dispatch method.
-
-Metrics/MethodLength:
-  Max: 35
-  CountAsOne:
-    - heredoc
-    - array
-    - hash
-  Exclude:
-    - 'test/**/*'
-
-Metrics/AbcSize:
-  Max: 40
-  Exclude:
-    - 'test/**/*'
-
-Metrics/ClassLength:
-  Max: 600
-  Exclude:
-    - 'test/**/*'
-
-Metrics/ModuleLength:
-  Max: 200
-  Exclude:
-    - 'test/**/*'
-
-Metrics/CyclomaticComplexity:
-  Max: 20
-  Exclude:
-    - 'test/**/*'
-
-Metrics/PerceivedComplexity:
-  Max: 20
-  Exclude:
-    - 'test/**/*'
-
-# Long method signatures with keyword args are a Ruby framework idiom
-Metrics/ParameterLists:
-  Enabled: false
-
-Metrics/BlockLength:
-  Exclude:
-    - 'Rakefile'
-    - '*.gemspec'
-    - 'test/**/*'
+inherit_from: ../.rubocop-base.yml

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+### Added
+- `.loki` Asgard task file: `test`, `rubocop`, `rubocop_fix`, `flog`, `flay`, `quality`, `build`, `install`, `release`, and `console` tasks via the Asgard task runner
+- `flay_check` Rake task: structural code duplication gate (mass threshold 50); integrated into the `quality` Rake task
+- `flay` and `minitest-reporters` gems added to development dependencies
+- `test_output.txt`, `flay_output.txt`, `flog_output.txt`, and `rubocop_output.txt` added to `.gitignore`
+
+### Changed
+- `test/test_helper.rb`: test output redirected to `test_output.txt` via `$stdout` reassignment; `TerminalSummaryReporter` prints a single PASS/FAIL summary line to the terminal
+- `Rakefile`: `rubocop` and `rubocop_fix` tasks removed (now owned by Asgard); `flay_check` integrated into the `quality` gate
+
 ## [0.2.1] - 2026-05-19
 
 ### Added

data/CLAUDE.md

@@ -0,0 +1,71 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Gem Does
+
+`robot_lab-rails` is a Rails Engine that integrates RobotLab into Rails applications. It provides a Railtie for configuration, an ActiveJob base class with optional Turbo Stream broadcasting, generators for scaffolding, and autoloading for `app/robots/` and `app/tools/`.
+
+## Commands
+
+```bash
+bundle exec rake test        # Run full test suite
+ruby -Ilib:test test/<file>  # Run a single test file
+
+# Inside a Rails app using this gem:
+rails g robot_lab:install            # migration, models, initializer, job
+rails g robot_lab:robot MyRobot      # app/robots/my_robot.rb + test
+rails g robot_lab:robot MyRouter --routing  # routing robot variant
+rails g robot_lab:job MyRobot        # app/jobs/my_robot_job.rb
+```
+
+## Architecture
+
+**`RailsIntegration::Engine`** (`rails_integration/engine.rb`) — Rails Engine with `isolate_namespace RobotLab`. Adds `app/robots/` and `app/tools/` to Rails autoload paths so robot and tool classes are autoloaded like models.
+
+**`RailsIntegration::Railtie`** (`rails_integration/railtie.rb`) — Reads `config.robot_lab.default_model` and `config.robot_lab.default_provider` from the Rails app config and applies them to `RobotLab.configure`. Sets `RobotLab.config.logger = Rails.logger` so all RobotLab log output goes through Rails logging.
+
+**`RailsIntegration::Job`** (`rails_integration/job.rb`) — `ActiveJob::Base` subclass. Subclass with `robot_class MyRobot` DSL, or pass `robot_class:` at enqueue time.
+
+```ruby
+class SupportRobotJob < RobotLab::Job
+  queue_as :default
+  robot_class SupportRobot
+end
+
+SupportRobotJob.perform_later(message: "Hello", thread_id: session_id)
+```
+
+When `thread_id` is provided and Turbo is available, the job streams content and tool-call badges live via `Turbo::StreamsChannel`, and persists the result to `RobotLabThread` / `RobotLabResult` ActiveRecord models. Built-in retry (3 attempts, 5 second wait) and discard on `DeserializationError`.
+
+**`RailsIntegration::TurboStreamCallbacks`** (`rails_integration/turbo_stream_callbacks.rb`) — Stateless module. Safe to require without turbo-rails installed (guards with `defined?(Turbo::StreamsChannel)` at call time).
+
+```ruby
+cb = TurboStreamCallbacks.build_content_callback(stream_name: "robot_lab_thread_42")
+# => Proc that broadcasts each content chunk as HTML-escaped text
+
+tool_cb = TurboStreamCallbacks.build_tool_call_callback(stream_name: "robot_lab_thread_42")
+# => Proc that broadcasts a tool-badge span per tool call
+```
+
+## Generator Templates
+
+Templates live in `lib/generators/robot_lab/templates/`. The install generator creates:
+- `config/initializers/robot_lab.rb`
+- `db/migrate/create_robot_lab_tables.rb` (RobotLabThread + RobotLabResult tables)
+- `app/models/robot_lab_thread.rb` / `app/models/robot_lab_result.rb`
+- `app/jobs/robot_run_job.rb`
+- Empty `app/robots/` and `app/tools/` directories
+
+## Key Constraints
+
+- `Engine` and `Railtie` are only loaded when `defined?(Rails)` — the gem is safe to require in non-Rails contexts (e.g. test helpers that stub Rails).
+- `Job#setup_thread` calls `"RobotLabThread".constantize` — this is a string reference to avoid a hard dependency; ensure the model is generated before using `thread_id`.
+- `TurboStreamCallbacks` HTML-escapes all content via `ERB::Util.html_escape` — do not bypass this.
+- The Railtie uses `ActiveSupport.on_load(:active_record)` for AR setup — place any ActiveRecord extensions there, not in the initializer.
+
+## Testing
+
+- Minitest with SimpleCov (branch coverage tracked, no minimum threshold enforced yet)
+- Tests stub Rails, ActiveJob, and Turbo — no Rails app is loaded
+- Coverage baseline: ~80% line / ~82% branch

data/README.md

@@ -78,6 +78,31 @@ SupportJob.perform_later(message: params[:message], thread_id: session_id)
 
 Omitting `thread_id` runs the robot in fire-and-forget mode — no persistence, no broadcasting.
 
+## Recurring Tasks (Solid Queue)
+
+When using [Solid Queue](https://github.com/rails/solid_queue), skip the wrapper job and call a class method directly via the `command:` key in `config/recurring.yml`:
+
+```ruby
+# app/services/daily_digest.rb
+class DailyDigest
+  def self.run
+    User.digest_subscribers.find_each do |user|
+      DailyDigestJob.perform_later(user_id: user.id)
+    end
+  end
+end
+```
+
+```yaml
+# config/recurring.yml
+daily_digest:
+  command: "DailyDigest.run"
+  schedule: "every day at 06:00"
+  queue: ai   # optional; defaults to solid_queue_recurring
+```
+
+The orchestrator class is independently testable. For overnight autonomous runs, `RobotLab::To.run` works as a recurring command directly. See the [Rails Integration Guide](https://madbomber.github.io/robot_lab-rails/guides/rails-integration#recurring-tasks-solid-queue) for queue configuration details and the `robot_lab-to` pattern.
+
 ## Turbo Stream Streaming
 
 When `thread_id` is provided and [turbo-rails](https://github.com/hotwired/turbo-rails) is installed, `RobotLab::Job` automatically:

data/Rakefile

@@ -24,16 +24,6 @@ task :test_file, [:file] do |_t, args|
   ruby "test/#{args[:file]}"
 end
 
-desc 'Check code style with RuboCop'
-task :rubocop do
-  sh 'bundle exec rubocop'
-end
-
-desc 'Auto-correct RuboCop offenses'
-task :rubocop_fix do
-  sh 'bundle exec rubocop -a'
-end
-
 desc 'Check code complexity with Flog (warn >=20, fail >=50)'
 task :flog_check do
   require 'flog'
@@ -71,36 +61,62 @@ task :flog_check do
   end
 end
 
-desc 'Run all quality checks: tests (with coverage), RuboCop, and Flog'
-task :quality do
-  results = {}
+desc 'Check for structural code duplication with Flay (mass >= 50)'
+task :flay_check do
+  require 'flay'
 
-  puts "\n#{'=' * 60}"
-  puts 'Quality Gate: Tests + Coverage'
-  puts '=' * 60
-  results[:tests] = system('bundle exec rake test') ? :pass : :fail
+  mass_threshold = 50
 
-  puts "\n#{'=' * 60}"
-  puts 'Quality Gate: RuboCop'
-  puts '=' * 60
-  results[:rubocop] = system('bundle exec rubocop') ? :pass : :fail
+  flay = Flay.new({ mass: mass_threshold, diff: false, verbose: false, summary: false, timeout: 60 })
+  flay.process(*Dir.glob('lib/**/*.rb'))
+  flay.analyze
 
-  puts "\n#{'=' * 60}"
-  puts 'Quality Gate: Flog Complexity'
-  puts '=' * 60
-  results[:flog] = system('bundle exec rake flog_check') ? :pass : :fail
+  if flay.hashes.empty?
+    puts "\nFlay: no structural duplication detected (mass >= #{mass_threshold})"
+  else
+    puts "\nFlay found structural duplication (mass >= #{mass_threshold}):"
+    flay.report
+    abort "\nFlay quality gate failed: #{flay.hashes.length} pattern(s) detected"
+  end
+end
+
+desc 'Run all quality checks: tests (with coverage), RuboCop, Flog, and Flay'
+task :quality do
+  gates = [
+    ['Tests + Coverage', 'bundle exec rake test'],
+    ['RuboCop',          'bundle exec rubocop'],
+    ['Flog Complexity',  'bundle exec rake flog_check'],
+    ['Flay Duplication', 'bundle exec rake flay_check']
+  ]
+
+  results = gates.map do |label, command|
+    puts "\n#{'=' * 60}"
+    puts "Quality Gate: #{label}"
+    puts '=' * 60
+    [label, system(command) ? :pass : :fail]
+  end
+
+  green = ->(s) { "\e[32m#{s}\e[0m" }
+  red   = ->(s) { "\e[31m#{s}\e[0m" }
+  width = results.map { |label, _| label.length }.max
 
   puts "\n#{'=' * 60}"
-  puts 'Quality Summary'
+  puts 'Quality Gate Summary'
   puts '=' * 60
-  results.each do |gate, status|
-    icon = status == :pass ? 'PASS' : 'FAIL'
-    puts "  [#{icon}] #{gate}"
+  results.each do |label, status|
+    badge = status == :pass ? green.call('PASS') : red.call('FAIL')
+    puts "  [#{badge}] #{label.ljust(width)}"
   end
+  puts '-' * 60
+
+  passed = results.count { |_, s| s == :pass }
+  failed = results.count { |_, s| s == :fail }
+  tally  = "#{passed} passed, #{failed} failed"
+  puts "  #{failed.zero? ? green.call(tally) : red.call(tally)}"
   puts '=' * 60
 
-  abort "\nQuality gate failed" if results.values.any?(:fail)
-  puts "\nAll quality gates passed."
+  abort "\n#{red.call('Quality gate failed.')}" unless failed.zero?
+  puts "\n#{green.call('All quality gates passed.')}"
 end
 
 namespace :docs do

data/docs/guides/rails-integration.md

@@ -121,8 +121,15 @@ RobotLab.config.streaming_enabled          #=> true
 rails generate robot_lab:robot Support
 rails generate robot_lab:robot Billing --description="Handles billing inquiries"
 rails generate robot_lab:robot Router --routing
+rails generate robot_lab:robot Support --tools=order_lookup,refund_processor
 ```
 
+Options:
+
+- `--description` — Robot description (defaults to `"A helpful <Name> robot"`)
+- `--routing` — Generate a routing robot (subclasses `RobotLab::Robot`, overrides `call`) instead of the plain factory-style robot
+- `--tools` — List of tool names; emitted as commented-out entries in the generated `tools` array for you to uncomment and wire up
+
 ### Robot Class
 
 Robots are plain Ruby classes with a `.build` factory method that calls `RobotLab.build` with keyword arguments:
@@ -503,6 +510,83 @@ class ProcessMessageJob < ApplicationJob
 end
 ```
 
+## Recurring Tasks (Solid Queue)
+
+When using [Solid Queue](https://github.com/rails/solid_queue), you can schedule robot runs without writing a thin wrapper job. Solid Queue's `command:` key in `config/recurring.yml` calls a class method directly, eliminating unnecessary glue code.
+
+### Orchestrator class
+
+Keep the scheduling logic in a plain Ruby class. The class method fans out per-item jobs — or runs a robot directly:
+
+```ruby title="app/services/daily_digest.rb"
+class DailyDigest
+  def self.run
+    User.digest_subscribers.find_each do |user|
+      DailyDigestJob.perform_later(user_id: user.id)
+    end
+  end
+end
+```
+
+### Wiring in recurring.yml
+
+Reference the method directly in `config/recurring.yml`:
+
+```yaml title="config/recurring.yml"
+daily_digest:
+  command: "DailyDigest.run"
+  schedule: "every day at 06:00"
+```
+
+No wrapper job needed. `DailyDigest.run` is a plain class method — independently testable without enqueuing anything.
+
+### Queue configuration
+
+Solid Queue sends recurring commands to the `solid_queue_recurring` queue by default. Add a dedicated worker in `config/queue.yml` so recurring runs don't compete with your main job queues:
+
+```yaml title="config/queue.yml"
+production:
+  workers:
+    - queues: [solid_queue_recurring]
+      threads: 1
+    - queues: [default, ai]
+      threads: 3
+```
+
+Override the queue per task with `queue:` to route recurring robot runs through a shared worker:
+
+```yaml title="config/recurring.yml"
+daily_digest:
+  command: "DailyDigest.run"
+  schedule: "every day at 06:00"
+  queue: ai
+```
+
+### Using robot_lab-to for overnight runs
+
+The `robot_lab-to` gem's `RobotLab::To.run` is designed for a single autonomous session, making it a natural fit for a Solid Queue recurring task:
+
+```ruby title="app/services/nightly_analysis.rb"
+class NightlyAnalysis
+  def self.run
+    RobotLab::To.run(
+      "Analyze yesterday's support tickets and generate a quality report",
+      max_iterations: 10,
+      stop_when: "Report is written to disk"
+    )
+  end
+end
+```
+
+```yaml title="config/recurring.yml"
+nightly_analysis:
+  command: "NightlyAnalysis.run"
+  schedule: "every day at 02:00"
+  queue: ai
+```
+
+> `RobotLab::To.run` is synchronous. Solid Queue runs it inside a worker process — this is intentional. Each nightly run blocks its worker for the duration of the autonomous loop.
+
 ## Testing
 
 ### Test Configuration
@@ -582,6 +666,10 @@ class RobotLabThread < ApplicationRecord
   def last_result
     results.order(sequence_number: :desc).first
   end
+
+  def message_count
+    results.count
+  end
 end
 ```
 
@@ -596,14 +684,24 @@ class RobotLabResult < ApplicationRecord
 
   validates :session_id, presence: true
   validates :robot_name, presence: true
+  validates :sequence_number, presence: true,
+                              numericality: { only_integer: true, greater_than_or_equal_to: 0 }
 
   default_scope { order(sequence_number: :asc) }
 
+  def output_messages
+    (output_data || []).map { |d| RobotLab::Message.from_hash(d.symbolize_keys) }
+  end
+
+  def tool_call_messages
+    (tool_calls_data || []).map { |d| RobotLab::Message.from_hash(d.symbolize_keys) }
+  end
+
   def to_robot_result
     RobotLab::RobotResult.new(
       robot_name: robot_name,
-      output: (output_data || []).map { |d| RobotLab::Message.from_hash(d.symbolize_keys) },
-      tool_calls: (tool_calls_data || []).map { |d| RobotLab::Message.from_hash(d.symbolize_keys) },
+      output: output_messages,
+      tool_calls: tool_call_messages,
       stop_reason: stop_reason
     )
   end

data/lib/robot_lab/rails/version.rb

@@ -2,6 +2,6 @@
 
 module RobotLab
   module Rails
-    VERSION = "0.2.1"
+    VERSION = "0.2.6"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: robot_lab-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.6
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -75,8 +75,11 @@ extra_rdoc_files: []
 files:
 - ".envrc"
 - ".github/workflows/deploy-github-pages.yml"
+- ".loki"
+- ".quality/reek_baseline.txt"
 - ".rubocop.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -153,7 +156,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.11
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Rails integration for the robot_lab LLM agent framework
 test_files: []