robot_lab 0.0.7 → 0.0.9

data/examples/18_rails/bin/rails

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+APP_PATH = File.expand_path("../config/application", __dir__)
+require_relative "../config/application"
+require "rails/commands"

data/examples/18_rails/bin/setup

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+echo "==> Installing gems..."
+bundle install
+
+echo "==> Creating database..."
+bundle exec rails db:create
+
+echo "==> Running migrations..."
+bundle exec rails db:migrate
+
+echo "==> Done! Run bin/dev to start the server."

data/examples/18_rails/config/application.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+
+require "rails"
+require "active_record/railtie"
+require "active_job/railtie"
+require "action_controller/railtie"
+require "action_view/railtie"
+require "action_cable/engine"
+
+Bundler.require(*Rails.groups)
+
+module RobotLabDemo
+  class Application < Rails::Application
+    config.load_defaults 8.0
+
+    config.eager_load = false
+    config.consider_all_requests_local = true
+    config.secret_key_base = "demo-secret-key-for-development-only"
+
+    # Use async adapter for jobs — no external process needed
+    config.active_job.queue_adapter = :async
+
+    # Autoload app/robots and app/tools
+    config.autoload_paths << root.join("app", "robots")
+    config.autoload_paths << root.join("app", "tools")
+
+    # Disable unused middleware
+    config.api_only = false
+    config.hosts.clear
+  end
+end

data/examples/18_rails/config/cable.yml

@@ -0,0 +1,2 @@
+development:
+  adapter: async

data/examples/18_rails/config/database.yml

@@ -0,0 +1,5 @@
+development:
+  adapter: sqlite3
+  database: db/development.sqlite3
+  pool: 5
+  timeout: 5000

data/examples/18_rails/config/environment.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "application"
+Rails.application.initialize!

data/examples/18_rails/config/initializers/robot_lab.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+RobotLab.config.logger = Rails.logger

data/examples/18_rails/config/routes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+Rails.application.routes.draw do
+  root "chat#index"
+  post "chat", to: "chat#create"
+end

data/examples/18_rails/config.ru

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "config/environment"
+run Rails.application

data/examples/18_rails/db/migrate/001_create_robot_lab_tables.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+class CreateRobotLabTables < ActiveRecord::Migration[7.0]
+  def change
+    create_table :robot_lab_threads do |t|
+      t.string :session_id, null: false, index: { unique: true }
+      t.text :initial_input
+      t.json :input_metadata, default: {}
+      t.json :state_data, default: {}
+      t.text :last_user_message
+      t.datetime :last_user_message_at
+
+      t.timestamps
+    end
+
+    create_table :robot_lab_results do |t|
+      t.string :session_id, null: false, index: true
+      t.string :robot_name, null: false
+      t.integer :sequence_number, null: false, default: 0
+      t.json :output_data, default: []
+      t.json :tool_calls_data, default: []
+      t.string :stop_reason
+      t.string :checksum
+
+      t.timestamps
+    end
+
+    add_index :robot_lab_results, [:session_id, :sequence_number]
+    add_foreign_key :robot_lab_results, :robot_lab_threads,
+                    column: :session_id, primary_key: :session_id
+  end
+end

data/examples/README.md

@@ -45,6 +45,15 @@ examples/
     scout.rb                  #   Talent scout with analyst spawning
     display.rb                #   Terminal formatting (color, wrapping, file output)
     prompts/                  #   Templates for comic, heckler, and scout
+  18_rails/                   # Minimal Rails 8 demo app (full integration)
+    app/robots/chat_robot.rb  #   Robot factory with system prompt + TimeTool
+    app/tools/time_tool.rb    #   Custom RobotLab::Tool subclass
+    app/jobs/robot_run_job.rb #   Background job with Turbo Stream callbacks
+    app/controllers/          #   Chat controller (index + create)
+    app/views/                #   Layout with CDN importmap, chat view with streaming
+    app/models/               #   RobotLabThread, RobotLabResult
+    config/                   #   Minimal Rails 8 config (async adapters, no asset pipeline)
+    db/migrate/               #   Migration from generator template
   prompts/                    # Prompt templates (.md with YAML front matter)
 ```
 
@@ -152,6 +161,27 @@ Demonstrates: Robot subclasses, self-modification via tool side effects, dynamic
 
 **Requires:** LLM API key
 
+### 18 — Rails Integration Demo
+
+A minimal, hand-built Rails 8 app that exercises every piece of RobotLab's Rails integration end-to-end. No `rails new` — every file is hand-crafted for minimum size.
+
+**What it demonstrates:**
+- **ChatRobot** with a custom `TimeTool` (`app/robots/`, `app/tools/`)
+- **RobotRunJob** — background execution via `ActiveJob` async adapter
+- **Turbo Stream token streaming** — real-time content chunks broadcast to the browser over ActionCable
+- **Persistence** — `RobotLabThread` + `RobotLabResult` with conversation history
+- **Auto-scrolling chat** — MutationObserver keeps the view pinned to the latest streaming content
+
+**No Redis, no Solid Queue, no asset pipeline.** Uses `:async` adapters for both ActiveJob and ActionCable. Turbo JS loaded via importmap from CDN (`@hotwired/turbo-rails`).
+
+```bash
+cd examples/18_rails
+bin/setup              # bundle install + db:create + db:migrate
+bin/dev                # starts Puma on http://localhost:3000
+```
+
+**Requires:** LLM API key, Ruby 3.2+
+
 ## Prompt Templates
 
 Templates live in `examples/prompts/` as `.md` files with YAML front matter. Each template defines a robot's personality and behavior:

data/examples/prompts/audit_trail.md

@@ -0,0 +1,8 @@
+---
+description: Include audit metadata in every response
+---
+Include an "audit" field in every response with:
+- "timestamp": the current date/time you were asked (use ISO 8601)
+- "confidence": your confidence level from 0.0 to 1.0
+- "sources": list of data sources or signals you used for your assessment
+- "assumptions": any assumptions you made due to missing information

data/examples/prompts/incident_responder.md

@@ -0,0 +1,18 @@
+---
+description: Incident response analyst for production systems
+parameters:
+  team_name: null
+  services: null
+  on_call_runbook_url: null
+---
+You are the on-call incident response analyst for the <%= team_name %> team.
+
+Your team owns these services: <%= Array(services).join(", ") %>.
+
+When an incident is reported, analyze the provided alert data, logs, and metrics
+to help the on-call engineer understand what is happening and what to do next.
+
+Reference the team runbook at: <%= on_call_runbook_url %>
+
+Prioritize reducing customer impact over finding root cause.
+If you are uncertain, say so and recommend escalation.

data/examples/prompts/parameterized_main_test.md

@@ -0,0 +1,6 @@
+---
+description: Main template with same parameter as skill
+parameters:
+  company_name: null
+---
+Welcome to <%= company_name %> support.

data/examples/prompts/pii_redactor.md

@@ -0,0 +1,7 @@
+---
+description: Redact personally identifiable information from output
+---
+Never include real personally identifiable information (PII) in your responses.
+If log data contains email addresses, IP addresses, usernames, or account IDs,
+replace them with redacted placeholders like [EMAIL], [IP], [USER], [ACCOUNT_ID].
+This applies to all fields in your output including explanations.

data/examples/prompts/runbook_protocol.md

@@ -0,0 +1,12 @@
+---
+description: Follow structured runbook steps for incident response
+---
+When analyzing an incident, follow this protocol:
+
+1. ASSESS — Identify the affected service, severity, and blast radius.
+2. DIAGNOSE — Examine symptoms, recent changes, and correlated events.
+3. MITIGATE — Recommend immediate actions to reduce impact.
+4. RESOLVE — Propose a root-cause fix and verification steps.
+5. FOLLOW-UP — Suggest post-incident review items and preventive measures.
+
+Always label each section clearly. Never skip a step.

data/examples/prompts/skill_a_test.md

@@ -0,0 +1,4 @@
+---
+description: Skill A for testing
+---
+You have Skill A capabilities.

data/examples/prompts/skill_b_test.md

@@ -0,0 +1,4 @@
+---
+description: Skill B for testing
+---
+You have Skill B capabilities.

data/examples/prompts/skill_config_test.md

@@ -0,0 +1,5 @@
+---
+description: Skill with config overrides
+temperature: 0.9
+---
+You have config skill capabilities.

data/examples/prompts/skill_cycle_a_test.md

@@ -0,0 +1,6 @@
+---
+description: Cycle test A
+skills:
+  - skill_cycle_b_test
+---
+You have cycle A capabilities.

data/examples/prompts/skill_cycle_b_test.md

@@ -0,0 +1,6 @@
+---
+description: Cycle test B
+skills:
+  - skill_cycle_a_test
+---
+You have cycle B capabilities.

data/examples/prompts/skill_description_test.md

@@ -0,0 +1,4 @@
+---
+description: Skill description from frontmatter
+---
+You have description skill capabilities.

data/examples/prompts/skill_leaf_test.md

@@ -0,0 +1,4 @@
+---
+description: Leaf skill with no nested skills
+---
+You have leaf skill capabilities.

data/examples/prompts/skill_nested_test.md

@@ -0,0 +1,6 @@
+---
+description: Nested skill that depends on leaf
+skills:
+  - skill_leaf_test
+---
+You have nested skill capabilities.

data/examples/prompts/skill_refs_main_test.md

@@ -0,0 +1,6 @@
+---
+description: Skill that references the main template
+skills:
+  - assistant
+---
+You have a skill that references the main template.

data/examples/prompts/skill_self_ref_test.md

@@ -0,0 +1,6 @@
+---
+description: Self-referencing skill
+skills:
+  - skill_self_ref_test
+---
+You have self-referencing capabilities.

data/examples/prompts/skill_with_params_test.md

@@ -0,0 +1,6 @@
+---
+description: Skill with parameters
+parameters:
+  company_name: null
+---
+You work for <%= company_name %>.

data/examples/prompts/sre_compliance.md

@@ -0,0 +1,10 @@
+---
+description: SRE compliance bundle — PII redaction and audit trail
+skills:
+  - pii_redactor
+  - audit_trail
+---
+You operate under SRE compliance requirements.
+All responses must be safe for inclusion in incident tickets visible to external stakeholders.
+Do not speculate about blame or assign fault to individuals.
+Focus on systems, processes, and technical root causes.

data/examples/prompts/structured_output.md

@@ -0,0 +1,7 @@
+---
+description: Respond with structured JSON output
+temperature: 0.2
+---
+Always respond with valid JSON. Structure your response as a JSON object.
+Do not include any text outside the JSON block.
+If you need to explain something, include it in an "explanation" field.

data/examples/prompts/template_with_skills_test.md

@@ -0,0 +1,6 @@
+---
+description: Main template that uses skills via front matter
+skills:
+  - skill_a_test
+---
+You are the main template with skills from front matter.

data/lib/generators/robot_lab/install_generator.rb

@@ -17,6 +17,8 @@ module RobotLab
 
       class_option :skip_migration, type: :boolean, default: false,
                                     desc: "Skip database migration generation"
+      class_option :skip_job, type: :boolean, default: false,
+                              desc: "Skip background job generation"
 
       # Returns the next migration number for ActiveRecord migrations.
       #
@@ -52,6 +54,15 @@ module RobotLab
         template "result_model.rb.tt", "app/models/robot_lab_result.rb"
       end
 
+      # Creates the background job for robot execution.
+      #
+      # @return [void]
+      def create_job
+        return if options[:skip_job]
+
+        template "job.rb.tt", "app/jobs/robot_run_job.rb"
+      end
+
       # Creates the robots and tools directories.
       #
       # @return [void]
@@ -71,6 +82,7 @@ module RobotLab
         say "  1. Run migrations: rails db:migrate"
         say "  2. Configure your LLM API keys in config/initializers/robot_lab.rb"
         say "  3. Generate your first robot: rails g robot_lab:robot MyRobot"
+        say "  4. Enqueue robot runs via RobotRunJob (app/jobs/robot_run_job.rb)" unless options[:skip_job]
         say ""
       end
     end

data/lib/generators/robot_lab/templates/initializer.rb.tt

@@ -2,27 +2,41 @@
 
 # RobotLab Configuration
 #
-# Configure your AI robot framework settings here.
+# RobotLab uses MywayConfig for configuration. Settings are loaded from:
 #
-RobotLab.configure do |config|
-  # Default model for robots (optional)
-  # config.default_model = "claude-sonnet-4"
-  # config.default_provider = :anthropic
-
-  # Logger configuration
-  config.logger = Rails.logger
-
-  # Maximum iterations per robot run
-  # config.max_iterations = 10
-
-  # Enable debug mode in development
-  # config.debug = Rails.env.development?
-end
-
-# Configure Ruby LLM (required for LLM interactions)
+#   1. Bundled defaults (lib/robot_lab/config/defaults.yml)
+#   2. Environment-specific overrides (development, test, production)
+#   3. XDG user config (~/.config/robot_lab/config.yml)
+#   4. Project config (./config/robot_lab.yml)
+#   5. Environment variables (ROBOT_LAB_* prefix)
+#
+# Create config/robot_lab.yml for project-specific settings:
+#
+#   defaults:
+#     ruby_llm:
+#       anthropic_api_key: <%%= ENV['ANTHROPIC_API_KEY'] %>
+#       openai_api_key: <%%= ENV['OPENAI_API_KEY'] %>
+#       model: claude-sonnet-4
+#       request_timeout: 180
 #
-# RubyLLM.configure do |config|
-#   config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
-#   config.openai_api_key = ENV["OPENAI_API_KEY"]
-#   config.gemini_api_key = ENV["GEMINI_API_KEY"]
-# end
+#   development:
+#     ruby_llm:
+#       log_level: :debug
+#
+#   test:
+#     streaming_enabled: false
+#     ruby_llm:
+#       model: claude-3-haiku-20240307
+#       request_timeout: 30
+#
+# Or use environment variables with double underscores for nested keys:
+#
+#   ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY=sk-ant-...
+#   ROBOT_LAB_RUBY_LLM__MODEL=claude-sonnet-4
+#
+# RobotLab also falls back to standard provider env vars
+# (e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY) when the prefixed
+# versions are not set.
+
+# Set the RobotLab logger to use Rails.logger
+RobotLab.config.logger = Rails.logger

data/lib/generators/robot_lab/templates/job.rb.tt

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# Background job for executing robot runs asynchronously.
+#
+# Resolves a robot class, optionally wires Turbo Stream callbacks for
+# real-time token streaming, persists the result, and broadcasts
+# completion/error events.
+#
+# @example Enqueue from a controller
+#   RobotRunJob.perform_later(
+#     robot_class: "SupportRobot",
+#     message: params[:message],
+#     thread_id: session_id
+#   )
+#
+class RobotRunJob < ApplicationJob
+  queue_as :default
+
+  retry_on StandardError, wait: 5.seconds, attempts: 3
+  discard_on ActiveJob::DeserializationError
+
+  def perform(robot_class:, message:, thread_id:, **context)
+    thread = RobotLabThread.find_or_create_by_session_id(thread_id)
+    thread.update!(last_user_message: message, last_user_message_at: Time.current)
+
+    robot  = resolve_robot(robot_class, thread_id)
+    result = robot.run(message, **context)
+
+    persist_result(thread, result)
+    broadcast_completion(thread_id)
+  rescue StandardError => e
+    broadcast_error(thread_id, e)
+    raise
+  end
+
+  private
+
+  def resolve_robot(robot_class, thread_id)
+    klass       = robot_class.to_s.constantize
+    stream_name = "robot_lab_thread_#{thread_id}"
+
+    if turbo_available?
+      on_content = RobotLab::RailsIntegration::TurboStreamCallbacks.build_content_callback(
+        stream_name: stream_name
+      )
+      on_tool_call = RobotLab::RailsIntegration::TurboStreamCallbacks.build_tool_call_callback(
+        stream_name: stream_name
+      )
+      klass.build(on_content: on_content, on_tool_call: on_tool_call)
+    else
+      klass.build
+    end
+  end
+
+  def persist_result(thread, result)
+    sequence = thread.results.maximum(:sequence_number).to_i + 1
+    exported = result.export
+
+    thread.results.create!(
+      robot_name:      result.robot_name,
+      sequence_number: sequence,
+      output_data:     exported[:output],
+      tool_calls_data: exported[:tool_calls],
+      stop_reason:     result.stop_reason,
+      checksum:        result.checksum
+    )
+  end
+
+  def broadcast_completion(thread_id)
+    return unless turbo_available?
+
+    Turbo::StreamsChannel.broadcast_replace_to(
+      "robot_lab_thread_#{thread_id}",
+      target: "robot_status",
+      html: "<span class=\"robot-status-complete\">Complete</span>"
+    )
+  end
+
+  def broadcast_error(thread_id, error)
+    return unless turbo_available?
+
+    Turbo::StreamsChannel.broadcast_append_to(
+      "robot_lab_thread_#{thread_id}",
+      target: "robot_errors",
+      html: "<div class=\"robot-error\">#{ERB::Util.html_escape(error.message)}</div>"
+    )
+  end
+
+  def turbo_available?
+    defined?(Turbo::StreamsChannel)
+  end
+end

data/lib/generators/robot_lab/templates/robot.rb.tt

@@ -5,42 +5,27 @@
 # <%= robot_description %>
 #
 class <%= class_name %>Robot
-  include RobotLab::Lifecycle
-
   SYSTEM_PROMPT = <<~PROMPT
     You are a helpful <%= class_name.titleize %> assistant.
 
     Your role is to assist users with their requests in a friendly and efficient manner.
   PROMPT
 
-  def self.build
-    RobotLab.create_robot(
+  def self.build(**options)
+    RobotLab.build(
       name: "<%= file_name %>",
       description: "<%= robot_description %>",
-      system: SYSTEM_PROMPT,
-      tools: tools,
-      lifecycle: lifecycle_hooks
+      system_prompt: SYSTEM_PROMPT,
+      local_tools: tools,
+      **options
     )
   end
 
   def self.tools
     [
       <%- robot_tools.each do |tool| -%>
-      # <%= tool.camelize %>Tool.build,
+      # <%= tool.camelize %>,
       <%- end -%>
     ]
   end
-
-  def self.lifecycle_hooks
-    RobotLab::Lifecycle::Hooks.new(
-      on_start: ->(robot:, network:, prompt:, history:) {
-        # Called before robot execution
-        { prompt: prompt, history: history }
-      },
-      on_finish: ->(robot:, network:, result:) {
-        # Called after robot execution
-        result
-      }
-    )
-  end
 end

data/lib/generators/robot_lab/templates/robot_test.rb.tt

@@ -16,7 +16,7 @@ class <%= class_name %>RobotTest < ActiveSupport::TestCase
   end
 
   test "robot has system prompt" do
-    assert_not_nil @robot.instance_variable_get(:@system)
+    assert_not_nil @robot.system_prompt
   end
 
   # Add more tests as needed:
@@ -24,9 +24,11 @@ class <%= class_name %>RobotTest < ActiveSupport::TestCase
   # test "robot runs successfully" do
   #   result = @robot.run("Hello, I need help")
   #   assert result.is_a?(RobotLab::RobotResult)
+  #   assert_not_nil result.last_text_content
   # end
   #
-  # test "robot uses correct tools" do
-  #   # Test tool invocation
+  # test "robot has expected tools" do
+  #   tool_names = @robot.local_tools.map(&:name)
+  #   assert_includes tool_names, "expected_tool_name"
   # end
 end