robot_lab 0.0.1

data/examples/prompts/triage/system.txt.erb

@@ -0,0 +1,16 @@
+You are an intelligent customer support triage specialist for <%= company_name %>.
+
+Your job is to analyze incoming customer requests and classify them into the appropriate category so they can be routed to the right specialist.
+
+## Available Categories
+<% categories.each do |category| %>
+- **<%= category[:name] %>**: <%= category[:description] %>
+<% end %>
+
+## Classification Rules
+1. Analyze the customer's message carefully
+2. Consider their account history and status
+3. Choose the SINGLE most appropriate category
+4. If unclear, default to "escalation" for human review
+
+Respond with ONLY the category name in lowercase, nothing else.

data/examples/prompts/triage/user.txt.erb

@@ -0,0 +1,17 @@
+Customer Message: <%= message %>
+
+<% if customer && customer[:recent_orders]&.any? %>
+Recent Order Activity:
+<% customer[:recent_orders].each do |order| %>
+- Order #<%= order[:id] %> (<%= order[:date] %>): <%= order[:status] %> - $<%= order[:total] %>
+<% end %>
+<% end %>
+
+<% if customer && customer[:open_tickets]&.any? %>
+Open Support Tickets:
+<% customer[:open_tickets].each do |ticket| %>
+- Ticket #<%= ticket[:id] %>: <%= ticket[:subject] %> (<%= ticket[:status] %>)
+<% end %>
+<% end %>
+
+Please classify this request.

data/lib/generators/robot_lab/install_generator.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module RobotLab
+  module Generators
+    # Installs RobotLab into a Rails application
+    #
+    # Usage:
+    #   rails generate robot_lab:install
+    #
+    class InstallGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :skip_migration, type: :boolean, default: false,
+                                    desc: "Skip database migration generation"
+
+      # Returns the next migration number for ActiveRecord migrations.
+      #
+      # @param dirname [String] the migrations directory
+      # @return [String] the next migration number
+      def self.next_migration_number(dirname)
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      # Creates the RobotLab initializer file.
+      #
+      # @return [void]
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/robot_lab.rb"
+      end
+
+      # Creates the database migration for RobotLab tables.
+      #
+      # @return [void]
+      def create_migration
+        return if options[:skip_migration]
+
+        migration_template "migration.rb.tt", "db/migrate/create_robot_lab_tables.rb"
+      end
+
+      # Creates the ActiveRecord model files.
+      #
+      # @return [void]
+      def create_models
+        return if options[:skip_migration]
+
+        template "thread_model.rb.tt", "app/models/robot_lab_thread.rb"
+        template "result_model.rb.tt", "app/models/robot_lab_result.rb"
+      end
+
+      # Creates the robots and tools directories.
+      #
+      # @return [void]
+      def create_directories
+        empty_directory "app/robots"
+        empty_directory "app/tools"
+      end
+
+      # Displays post-installation instructions.
+      #
+      # @return [void]
+      def display_post_install
+        say ""
+        say "RobotLab installed successfully!", :green
+        say ""
+        say "Next steps:"
+        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 ""
+      end
+    end
+  end
+end

data/lib/generators/robot_lab/robot_generator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module RobotLab
+  module Generators
+    # Generates a new RobotLab robot
+    #
+    # Usage:
+    #   rails generate robot_lab:robot NAME [options]
+    #
+    # Examples:
+    #   rails generate robot_lab:robot Support
+    #   rails generate robot_lab:robot Billing --description="Handles billing queries"
+    #
+    class RobotGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :description, type: :string, default: nil,
+                                 desc: "Robot description"
+      class_option :routing, type: :boolean, default: false,
+                             desc: "Generate a routing robot"
+      class_option :tools, type: :array, default: [],
+                           desc: "List of tools to include"
+
+      # Creates the robot class file.
+      #
+      # @return [void]
+      def create_robot_file
+        if options[:routing]
+          template "routing_robot.rb.tt", "app/robots/#{file_name}_robot.rb"
+        else
+          template "robot.rb.tt", "app/robots/#{file_name}_robot.rb"
+        end
+      end
+
+      # Creates the robot test file.
+      #
+      # @return [void]
+      def create_test_file
+        template "robot_test.rb.tt", "test/robots/#{file_name}_robot_test.rb"
+      end
+
+      private
+
+      def robot_description
+        options[:description] || "A helpful #{class_name.titleize} robot"
+      end
+
+      def robot_tools
+        options[:tools]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# RobotLab Configuration
+#
+# Configure your AI robot framework settings here.
+#
+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)
+#
+# 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
+
+# History Persistence (optional)
+#
+# Uncomment to enable conversation history storage:
+#
+# Rails.application.config.after_initialize do
+#   adapter = RobotLab::History::ActiveRecordAdapter.new(
+#     thread_model: RobotLabThread,
+#     result_model: RobotLabResult
+#   )
+#
+#   RobotLab.configuration.history = adapter.to_config
+# end

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

@@ -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/lib/generators/robot_lab/templates/result_model.rb.tt

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# RobotLab Result Model
+#
+# Stores robot execution results for history persistence.
+#
+class RobotLabResult < ApplicationRecord
+  belongs_to :thread,
+             class_name: "RobotLabThread",
+             foreign_key: :session_id,
+             primary_key: :session_id
+
+  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) }
+
+  # Get output messages as RobotLab::Message objects
+  #
+  # @return [Array<RobotLab::Message>]
+  #
+  def output_messages
+    (output_data || []).map do |data|
+      RobotLab::Message.from_hash(data.symbolize_keys)
+    end
+  end
+
+  # Get tool calls as RobotLab::Message objects
+  #
+  # @return [Array<RobotLab::Message>]
+  #
+  def tool_call_messages
+    (tool_calls_data || []).map do |data|
+      RobotLab::Message.from_hash(data.symbolize_keys)
+    end
+  end
+
+  # Convert to RobotLab::RobotResult
+  #
+  # @return [RobotLab::RobotResult]
+  #
+  def to_robot_result
+    RobotLab::RobotResult.new(
+      robot_name: robot_name,
+      output: output_messages,
+      tool_calls: tool_call_messages,
+      stop_reason: stop_reason
+    )
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# <%= class_name %> Robot
+#
+# <%= 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(
+      name: "<%= file_name %>",
+      description: "<%= robot_description %>",
+      system: SYSTEM_PROMPT,
+      tools: tools,
+      lifecycle: lifecycle_hooks
+    )
+  end
+
+  def self.tools
+    [
+      <%- robot_tools.each do |tool| -%>
+      # <%= tool.camelize %>Tool.build,
+      <%- 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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class <%= class_name %>RobotTest < ActiveSupport::TestCase
+  def setup
+    @robot = <%= class_name %>Robot.build
+  end
+
+  test "robot has correct name" do
+    assert_equal "<%= file_name %>", @robot.name
+  end
+
+  test "robot has description" do
+    assert_not_nil @robot.description
+  end
+
+  test "robot has system prompt" do
+    assert_not_nil @robot.instance_variable_get(:@system)
+  end
+
+  # Add more tests as needed:
+  #
+  # test "robot runs successfully" do
+  #   result = @robot.run("Hello, I need help")
+  #   assert result.is_a?(RobotLab::RobotResult)
+  # end
+  #
+  # test "robot uses correct tools" do
+  #   # Test tool invocation
+  # end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# <%= class_name %> Routing Robot
+#
+# <%= robot_description %>
+#
+# This robot routes requests to other robots based on classification.
+#
+class <%= class_name %>Robot
+  include RobotLab::Lifecycle
+
+  SYSTEM_PROMPT = <<~PROMPT
+    You are a routing robot that classifies user requests and directs them
+    to the appropriate specialist robot.
+
+    Analyze the user's request and determine which robot should handle it.
+    Respond with your classification decision.
+  PROMPT
+
+  def self.build
+    RobotLab.create_routing_robot(
+      name: "<%= file_name %>",
+      description: "<%= robot_description %>",
+      system: SYSTEM_PROMPT,
+      on_route: method(:route_decision)
+    )
+  end
+
+  # Determine which robot should handle the request
+  #
+  # @param result [RobotLab::RobotResult] Classification result
+  # @param robot [RobotLab::Robot] This robot
+  # @param network [RobotLab::Network] Parent network
+  # @return [Array<String>, nil] Robot names to route to
+  #
+  def self.route_decision(result:, robot:, network:)
+    # Extract classification from the result
+    output = result.output.last&.content.to_s.downcase
+
+    # Route based on classification
+    # Example routing logic:
+    # case output
+    # when /billing|payment|invoice/
+    #   ["billing_robot"]
+    # when /technical|bug|error/
+    #   ["technical_robot"]
+    # else
+    #   ["general_robot"]
+    # end
+
+    nil # Return nil to end the network run
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# RobotLab Thread Model
+#
+# Stores conversation threads for history persistence.
+#
+class RobotLabThread < ApplicationRecord
+  has_many :results,
+           class_name: "RobotLabResult",
+           foreign_key: :session_id,
+           primary_key: :session_id,
+           dependent: :destroy
+
+  validates :session_id, presence: true, uniqueness: true
+
+  # Find or create a thread by ID
+  #
+  # @param id [String] Thread ID
+  # @return [RobotLabThread]
+  #
+  def self.find_or_create_by_session_id(id)
+    find_or_create_by(session_id: id)
+  end
+
+  # Get the last result for this thread
+  #
+  # @return [RobotLabResult, nil]
+  #
+  def last_result
+    results.order(sequence_number: :desc).first
+  end
+
+  # Get message count for this thread
+  #
+  # @return [Integer]
+  #
+  def message_count
+    results.count
+  end
+end

data/lib/robot_lab/adapters/anthropic.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Adapters
+    # Adapter for Anthropic Claude models
+    #
+    # Handles Anthropic-specific API conventions:
+    # - System message as top-level parameter (not in messages array)
+    # - Tool use/result format differences
+    # - Content block structure
+    #
+    class Anthropic < Base
+      # Creates a new Anthropic adapter instance.
+      def initialize
+        super(:anthropic)
+      end
+
+      # Format messages for Anthropic API
+      #
+      # Anthropic requires system message at top level, not in messages array.
+      # Also handles tool_use and tool_result message formats.
+      #
+      # @param messages [Array<Message>]
+      # @return [Array<Hash>]
+      #
+      def format_messages(messages)
+        conversation_messages(messages).map do |msg|
+          format_single_message(msg)
+        end
+      end
+
+      # Parse Anthropic response into internal messages
+      #
+      # @param response [RubyLLM::Response] ruby_llm response object
+      # @return [Array<Message>]
+      #
+      def parse_response(response)
+        messages = []
+
+        # Handle text content
+        if response.content && !response.content.empty?
+          messages << TextMessage.new(
+            role: "assistant",
+            content: response.content,
+            stop_reason: response.tool_calls&.any? ? "tool" : "stop"
+          )
+        end
+
+        # Handle tool calls
+        if response.tool_calls&.any?
+          tool_messages = response.tool_calls.map do |id, tool_call|
+            ToolMessage.new(
+              id: id,
+              name: tool_call.name,
+              input: parse_tool_arguments(tool_call.arguments)
+            )
+          end
+
+          messages << ToolCallMessage.new(
+            role: "assistant",
+            tools: tool_messages,
+            stop_reason: "tool"
+          )
+        end
+
+        messages
+      end
+
+      # Format tools for Anthropic
+      #
+      # @param tools [Array<Tool>]
+      # @return [Array<Hash>]
+      #
+      def format_tools(tools)
+        tools.map do |tool|
+          schema = tool.to_json_schema
+          {
+            name: schema[:name],
+            description: schema[:description],
+            input_schema: schema[:parameters] || { type: "object", properties: {} }
+          }
+        end
+      end
+
+      # Anthropic tool choice format
+      #
+      # @param choice [String, Symbol]
+      # @return [Hash]
+      #
+      def format_tool_choice(choice)
+        case choice.to_s
+        when "auto" then { type: "auto" }
+        when "any" then { type: "any" }
+        else { type: "tool", name: choice.to_s }
+        end
+      end
+
+      private
+
+      def format_single_message(msg)
+        case msg
+        when TextMessage
+          { role: msg.role, content: msg.content }
+        when ToolCallMessage
+          {
+            role: "assistant",
+            content: msg.tools.map do |tool|
+              {
+                type: "tool_use",
+                id: tool.id,
+                name: tool.name,
+                input: tool.input
+              }
+            end
+          }
+        when ToolResultMessage
+          {
+            role: "user",
+            content: [
+              {
+                type: "tool_result",
+                tool_use_id: msg.tool.id,
+                content: format_tool_result_content(msg.content)
+              }
+            ]
+          }
+        else
+          { role: msg.role, content: msg.content.to_s }
+        end
+      end
+
+      def format_tool_result_content(content)
+        case content
+        when Hash
+          if content[:error]
+            JSON.generate(content)
+          elsif content[:data]
+            content[:data].is_a?(String) ? content[:data] : JSON.generate(content[:data])
+          else
+            JSON.generate(content)
+          end
+        else
+          content.to_s
+        end
+      end
+
+      def parse_tool_arguments(arguments)
+        case arguments
+        when String
+          begin
+            JSON.parse(arguments, symbolize_names: true)
+          rescue JSON::ParserError
+            { raw: arguments }
+          end
+        when Hash
+          arguments.transform_keys(&:to_sym)
+        else
+          arguments || {}
+        end
+      end
+    end
+  end
+end