robot_lab 0.3.0 → 0.3.1

data/examples/18_rails/app/models/robot_lab_result.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-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) }
-
-  def output_messages
-    (output_data || []).map do |data|
-      RobotLab::Message.from_hash(data.symbolize_keys)
-    end
-  end
-
-  def tool_call_messages
-    (tool_calls_data || []).map do |data|
-      RobotLab::Message.from_hash(data.symbolize_keys)
-    end
-  end
-
-  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/examples/18_rails/app/models/robot_lab_thread.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-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
-
-  def self.find_or_create_by_session_id(id)
-    find_or_create_by(session_id: id)
-  end
-
-  def last_result
-    results.order(sequence_number: :desc).first
-  end
-
-  def message_count
-    results.count
-  end
-end

data/examples/18_rails/app/robots/chat_robot.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-# Factory for the chat robot. RobotLab::RailsIntegration::Job calls
-# ChatRobot.build(on_content:, on_tool_call:) to wire Turbo streaming.
-#
-# The model is served locally by Ollama. Ollama models are absent from
-# RubyLLM's registry, so provider: must accompany model: — that is what makes
-# RubyLLM skip the registry lookup.
-class ChatRobot
-  SYSTEM_PROMPT = "You are a friendly assistant. Be concise."
-
-  PROVIDER = ENV.fetch("ROBOT_LAB_PROVIDER", "ollama")
-  MODEL    = ENV.fetch("ROBOT_LAB_MODEL", "qwen3.6:latest")
-
-  def self.build(**options)
-    RobotLab.build(
-      name: "chat",
-      provider: PROVIDER,
-      model: MODEL,
-      system_prompt: SYSTEM_PROMPT,
-      local_tools: [TimeTool],
-      **options
-    )
-  end
-end

data/examples/18_rails/app/tools/time_tool.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-class TimeTool < RobotLab::Tool
-  description "Get the current date and time"
-
-  def execute
-    Time.current.strftime("%Y-%m-%d %H:%M:%S %Z")
-  end
-end

data/examples/18_rails/app/views/chat/_user_message.html.erb

@@ -1 +0,0 @@
-<div class="message user"><%= message %></div>

data/examples/18_rails/app/views/chat/index.html.erb

@@ -1,67 +0,0 @@
-<h1>RobotLab Chat</h1>
-
-<%= turbo_stream_from "robot_lab_thread_#{@thread_id}" %>
-
-<%= form_with url: chat_path, method: :post, class: "chat-form" do |f| %>
-  <%= f.text_field :message, placeholder: "Type a message...", autofocus: true, autocomplete: "off" %>
-  <%= f.submit "Send" %>
-<% end %>
-
-<div id="chat-scroll">
-  <div id="messages">
-    <% @results.each do |result| %>
-      <% if result.robot_name == "user" %>
-        <% result.output_messages.each do |msg| %>
-          <div class="message user"><%= msg.content %></div>
-        <% end %>
-      <% else %>
-        <% result.output_messages.each do |msg| %>
-          <div class="message assistant"><%= msg.content %></div>
-        <% end %>
-        <% unless result.tool_call_messages.empty? %>
-          <div>
-            <% result.tool_call_messages.each do |tc| %>
-              <span class="tool-badge">Used: <%= tc.content %></span>
-            <% end %>
-          </div>
-        <% end %>
-      <% end %>
-    <% end %>
-  </div>
-
-  <div id="robot_tools"></div>
-  <div id="robot_response" class="message assistant" style="display:none;"></div>
-  <div id="robot_errors"></div>
-  <div id="robot_status"></div>
-</div>
-
-<script>
-  const scrollContainer = document.getElementById('chat-scroll');
-  const responseEl = document.getElementById('robot_response');
-
-  function scrollToBottom() {
-    scrollContainer.scrollTop = scrollContainer.scrollHeight;
-  }
-
-  // Auto-scroll on any mutation inside the scroll container
-  const observer = new MutationObserver(function() {
-    if (responseEl.textContent.trim().length > 0) {
-      responseEl.style.display = 'block';
-    }
-    scrollToBottom();
-  });
-
-  observer.observe(scrollContainer, { childList: true, characterData: true, subtree: true });
-
-  // Clear the input field after form submission
-  document.addEventListener('turbo:submit-end', function(event) {
-    const input = event.target.querySelector('input[name="message"]');
-    if (input) {
-      input.value = '';
-      input.focus();
-    }
-  });
-
-  // Scroll to bottom on initial load if there's history
-  scrollToBottom();
-</script>

data/examples/18_rails/app/views/layouts/application.html.erb

@@ -1,49 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-  <title>RobotLab Rails Demo</title>
-  <meta name="viewport" content="width=device-width,initial-scale=1">
-  <%= action_cable_meta_tag %>
-  <script type="importmap">
-  {
-    "imports": {
-      "@hotwired/turbo": "https://cdn.jsdelivr.net/npm/@hotwired/turbo@8.0.12/+esm",
-      "@hotwired/turbo-rails": "https://cdn.jsdelivr.net/npm/@hotwired/turbo-rails@8.0.12/+esm",
-      "@rails/actioncable": "https://cdn.jsdelivr.net/npm/@rails/actioncable@8.0.200/+esm"
-    }
-  }
-  </script>
-  <script type="module">
-    import "@hotwired/turbo-rails"
-  </script>
-  <style>
-    * { box-sizing: border-box; margin: 0; padding: 0; }
-    body { font-family: system-ui, -apple-system, sans-serif; background: #1a1a2e; color: #e0e0e0; height: 100vh; display: flex; flex-direction: column; align-items: center; overflow: hidden; }
-    .container { max-width: 720px; width: 100%; padding: 2rem 1rem; display: flex; flex-direction: column; height: 100%; overflow: hidden; }
-    #chat-scroll { flex: 1; overflow-y: auto; scroll-behavior: smooth; padding-right: 0.25rem; }
-    #chat-scroll::-webkit-scrollbar { width: 6px; }
-    #chat-scroll::-webkit-scrollbar-track { background: transparent; }
-    #chat-scroll::-webkit-scrollbar-thumb { background: #333; border-radius: 3px; }
-    h1 { color: #7c83ff; margin-bottom: 1.5rem; font-size: 1.5rem; }
-    .chat-form { display: flex; gap: 0.5rem; margin-bottom: 1.5rem; }
-    .chat-form input[type="text"] { flex: 1; padding: 0.75rem; border-radius: 8px; border: 1px solid #333; background: #16213e; color: #e0e0e0; font-size: 1rem; }
-    .chat-form input[type="text"]:focus { outline: none; border-color: #7c83ff; }
-    .chat-form button { padding: 0.75rem 1.5rem; border-radius: 8px; border: none; background: #7c83ff; color: #fff; font-size: 1rem; cursor: pointer; }
-    .chat-form button:hover { background: #6a70e0; }
-    .message { padding: 0.75rem 1rem; margin-bottom: 0.5rem; border-radius: 8px; line-height: 1.5; white-space: pre-wrap; }
-    .message.user { background: #1f4068; margin-left: 4rem; }
-    .message.assistant { background: #16213e; margin-right: 4rem; border: 1px solid #2a2a4a; }
-    .tool-badge { display: inline-block; background: #2d1b69; color: #b8b0ff; padding: 0.2rem 0.6rem; border-radius: 4px; font-size: 0.8rem; margin: 0.25rem 0.25rem 0.25rem 0; }
-    .thinking { color: #7c83ff; font-style: italic; }
-    .complete { color: #4ade80; font-size: 0.85rem; }
-    .error { color: #f87171; background: #2d1320; padding: 0.5rem 0.75rem; border-radius: 6px; margin-bottom: 0.5rem; }
-    #robot_response { white-space: pre-wrap; }
-    .history-label { color: #666; font-size: 0.75rem; text-transform: uppercase; margin-bottom: 0.75rem; letter-spacing: 0.05em; }
-  </style>
-</head>
-<body>
-  <div class="container">
-    <%= yield %>
-  </div>
-</body>
-</html>

data/examples/18_rails/bin/dev

@@ -1,7 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-cd "$(dirname "$0")/.."
-
-echo "Starting Puma on http://localhost:3000 ..."
-bundle exec rails server -p 3000

data/examples/18_rails/bin/rails

@@ -1,6 +0,0 @@
-#!/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

@@ -1,15 +0,0 @@
-#!/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

@@ -1,33 +0,0 @@
-# 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

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

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

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

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

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

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

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-RobotLab.config.logger = Rails.logger
-
-# Runs against a local Ollama server — no API keys required.
-#   ollama serve
-#   ollama pull qwen3.6
-RubyLLM.configure do |c|
-  c.logger          = Rails.logger
-  c.ollama_api_base = ENV.fetch("OLLAMA_API_BASE", "http://localhost:11434/v1")
-end

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

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

data/examples/18_rails/config.ru

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

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

@@ -1,32 +0,0 @@
-# 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/19_token_tracking.rb

@@ -1,138 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Example 19: Per-Robot Token / Cost Tracking
-#
-# Demonstrates per-run and cumulative token tracking:
-#   - result.input_tokens / result.output_tokens  — tokens used in that run
-#   - robot.total_input_tokens / total_output_tokens — running totals on the robot
-#   - robot.reset_token_totals  — reset the accounting counter (not the chat)
-#
-# Key distinction:
-#   reset_token_totals resets the robot's *accounting counter* only.
-#   The underlying chat history keeps growing, so input_tokens per run
-#   naturally increase as conversation context accumulates.
-#   Use a fresh robot.build when you need a genuinely fresh context.
-#
-# LM Studio reports usage counts like the hosted providers do, so the tracking
-# API behaves identically — only the price per token differs. Token counts are
-# zero for providers that don't report usage data.
-#
-# Usage:
-#   ruby examples/19_token_tracking.rb
-
-require_relative "common"
-
-# Cost model. A local LM Studio model bills nothing, so the interesting number is
-# what the same traffic WOULD have cost on a hosted model — set RATE_INPUT_CPM
-# and RATE_OUTPUT_CPM to your provider's $-per-1M-token rates to see it.
-# Defaults are zero: local inference is free.
-RATE_INPUT_CPM  = ENV.fetch("RATE_INPUT_CPM",  "0").to_f
-RATE_OUTPUT_CPM = ENV.fetch("RATE_OUTPUT_CPM", "0").to_f
-
-def token_summary(input, output)
-  "in=#{input}  out=#{output}  total=#{input + output}"
-end
-
-def run_cost(input, output)
-  return "$0.00000 (local)" if RATE_INPUT_CPM.zero? && RATE_OUTPUT_CPM.zero?
-
-  dollars = (input * RATE_INPUT_CPM + output * RATE_OUTPUT_CPM) / 1_000_000.0
-  "$#{"%.5f" % dollars}"
-end
-
-def first_line(text)
-  text&.strip&.lines&.first&.strip || ""
-end
-
-banner "Per-Robot Token & Cost Tracking"
-
-puts "Model: #{LLM[:default].provider}/#{LLM[:default].model}"
-if RATE_INPUT_CPM.zero? && RATE_OUTPUT_CPM.zero?
-  puts "Rates: none set — local inference is free."
-  puts "       Set RATE_INPUT_CPM / RATE_OUTPUT_CPM to price the same traffic"
-  puts "       against a hosted provider."
-else
-  puts "Rates: $#{RATE_INPUT_CPM}/1M in, $#{RATE_OUTPUT_CPM}/1M out"
-end
-puts
-
-robot = RobotLab.build(
-  **llm_opts,
-  name: "analyst",
-  system_prompt: "You are a concise technical analyst. Keep every reply under 40 words."
-)
-
-prompts = [
-  "What is the difference between a stack and a queue?",
-  "Name three Ruby gems that every Rails project should consider.",
-  "Why does database indexing improve query performance?"
-]
-
-puts "Running #{prompts.size} prompts...\n\n"
-
-prompts.each_with_index do |prompt, i|
-  result = robot.run(prompt)
-
-  puts "Run #{i + 1}: #{prompt}"
-  puts "  Reply:      #{first_line(result.reply)}"
-  puts "  This run:   #{token_summary(result.input_tokens, result.output_tokens)}"
-  puts "  Cost:       #{run_cost(result.input_tokens, result.output_tokens)}"
-  puts "  Cumulative: #{token_summary(robot.total_input_tokens, robot.total_output_tokens)}"
-  puts
-end
-
-hr
-puts "After #{prompts.size} runs:"
-puts "  Total tokens: #{token_summary(robot.total_input_tokens, robot.total_output_tokens)}"
-puts "  Total cost:   #{run_cost(robot.total_input_tokens, robot.total_output_tokens)}"
-puts
-
-# ---------------------------------------------------------------
-# reset_token_totals: resets the accounting counter only.
-# Useful when you want to measure cost for a specific task batch
-# while keeping the robot alive for the next batch.
-#
-# Note: input_tokens will still reflect the full chat history sent
-# to the API — that's the real cost, not an error.
-# ---------------------------------------------------------------
-
-puts "Resetting token totals (batch 1 complete, starting batch 2)..."
-robot.reset_token_totals
-puts "  Counter now:  #{token_summary(robot.total_input_tokens, robot.total_output_tokens)}"
-puts
-puts "  Note: the next run's input_tokens will be larger than run 1's"
-puts "  because the LLM receives the full accumulated chat context."
-puts "  The counter reset tracks *accounting* — it doesn't clear the chat."
-puts
-
-result = robot.run("What is memoization?")
-puts "Batch 2 — Run 1: What is memoization?"
-puts "  Reply:      #{first_line(result.reply)}"
-puts "  This run:   #{token_summary(result.input_tokens, result.output_tokens)}"
-puts "  Batch total: #{token_summary(robot.total_input_tokens, robot.total_output_tokens)}"
-puts
-
-# ---------------------------------------------------------------
-# To start truly fresh (new context, new counter), build a new robot.
-# ---------------------------------------------------------------
-
-hr
-puts "Fresh robot — genuinely zero context:"
-puts
-
-fresh = RobotLab.build(
-  **llm_opts,
-  name: "analyst2",
-  system_prompt: "You are a concise technical analyst. Keep every reply under 40 words."
-)
-
-result = fresh.run("What is memoization?")
-puts "Run 1 (fresh robot): What is memoization?"
-puts "  Reply:      #{first_line(result.reply)}"
-puts "  This run:   #{token_summary(result.input_tokens, result.output_tokens)}"
-puts "  Cumulative: #{token_summary(fresh.total_input_tokens, fresh.total_output_tokens)}"
-puts
-
-hr
-puts "Token tracking demo complete."

data/examples/20_circuit_breaker.rb

@@ -1,147 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Example 20: Tool Loop Circuit Breaker
-#
-# Demonstrates max_tool_rounds to prevent runaway tool call loops.
-#
-# A "process runner" robot is given a step tool whose return value always
-# instructs the LLM to call it again — it would loop forever without a guard.
-# The circuit breaker fires after max_tool_rounds tool calls and raises
-# RobotLab::ToolLoopError.
-#
-# Key behaviour when the breaker fires:
-#   The chat history contains a dangling tool_use with no tool_result.
-#   Most providers reject any subsequent request with that
-#   broken history.  You MUST call robot.clear_messages before reusing the
-#   same robot instance — or simply build a fresh robot.
-#
-# Demonstrates:
-#   - max_tool_rounds: N on RobotLab.build
-#   - ToolLoopError raised when the limit is exceeded
-#   - clear_messages to flush the corrupted chat and recover the robot
-#   - Contrast: robot without a circuit breaker on a task that terminates
-#
-# Usage:
-#   ruby examples/20_circuit_breaker.rb
-
-require_relative "common"
-
-# -------------------------------------------------------------------------
-# A tool that always says "more steps remain" — designed to induce looping
-# -------------------------------------------------------------------------
-
-class MultiStepProcessor < RubyLLM::Tool
-  description <<~DESC
-    Executes one step of a sequential batch process.
-    Returns the result of that step and whether more steps remain.
-    You MUST call this tool again for each remaining step until
-    the status is "complete".
-  DESC
-
-  parameter :step_number,
-        type: "integer",
-        description: "Which step to execute. Start at 1, increment by 1 each call."
-
-  TOTAL_STEPS = 50  # far more than any sensible max_tool_rounds
-
-  def execute(step_number:)
-    remaining = TOTAL_STEPS - step_number
-    if remaining <= 0
-      { status: "complete", step: step_number, message: "All steps finished." }
-    else
-      {
-        status: "in_progress",
-        step_completed: step_number,
-        remaining_steps: remaining,
-        instruction: "Call this tool again with step_number: #{step_number + 1}"
-      }
-    end
-  end
-end
-
-banner "Tool Loop Circuit Breaker"
-
-TASK = "Run the batch process from step 1 using the MultiStepProcessor tool. " \
-       "Execute every step sequentially until the process reports 'complete'."
-
-# -------------------------------------------------------------------------
-# Part 1: Circuit breaker fires — rescue ToolLoopError, then recover
-#
-# After ToolLoopError the chat contains a dangling tool_use block with no
-# matching tool_result. Providers reject any follow-up request with that
-# history. Call clear_messages to flush the broken context before reuse.
-# -------------------------------------------------------------------------
-
-section "Part 1: Circuit Breaker Fires (max_tool_rounds: 5)"
-
-robot = RobotLab.build(
-  **llm_opts,
-  name: "process_runner",
-  system_prompt: "You are a process runner. Execute tasks exactly as instructed.",
-  local_tools: [MultiStepProcessor],
-  max_tool_rounds: 5
-)
-
-begin
-  # tools: :inherit — run() defaults to :none, which sends the provider an
-  # empty tool list. With no tool to loop on there would be nothing for the
-  # breaker to trip.
-  robot.run(TASK, tools: :inherit)
-  puts "Process completed (unexpected for this demo)."
-rescue RobotLab::ToolLoopError => e
-  puts "Circuit breaker fired!"
-  puts "  #{e.message}"
-end
-
-puts
-
-# -------------------------------------------------------------------------
-# Part 2: Recover by flushing the corrupted chat with clear_messages
-#
-# The robot retains its config (system prompt, tools, max_tool_rounds).
-# Only the conversation history is cleared — the robot is then reusable.
-# -------------------------------------------------------------------------
-
-section "Part 2: Recover with clear_messages"
-
-robot.clear_messages
-puts "Chat flushed. Robot config (tools, max_tool_rounds) is unchanged."
-puts "  max_tool_rounds still: #{robot.config.max_tool_rounds}"
-puts
-
-result = robot.run("What is 3 + 4? Answer in one sentence.")
-puts "Follow-up after recovery: #{result.reply&.strip}"
-puts
-
-# -------------------------------------------------------------------------
-# Part 3: Robot without a circuit breaker on a task that terminates quickly
-#
-# Normal tool use works fine with no guard — the breaker is a safety net,
-# not a tax on well-behaved tool interactions.
-# -------------------------------------------------------------------------
-
-section "Part 3: No Circuit Breaker — Task Terminates Naturally"
-
-class SingleStep < RubyLLM::Tool
-  description "Doubles a number and returns the result immediately."
-  parameter :value, type: "integer", description: "The number to double"
-
-  def execute(value:)
-    { result: value * 2, status: "complete" }
-  end
-end
-
-unguarded = RobotLab.build(
-  **llm_opts,
-  name: "calculator",
-  system_prompt: "Use the provided tool to answer questions.",
-  local_tools: [SingleStep]
-)
-
-result = unguarded.run("Double the number 21 using the tool.", tools: :inherit)
-puts "Result: #{result.reply&.strip}"
-puts
-
-hr
-puts "Circuit breaker demo complete."