robot_lab-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 93f8a8d257c9dfe599fde397b4be1cc979df53eed8d38a3adca987e493852311
+  data.tar.gz: a41afb0b4132c1c245a10f44d3b5d9dd40ced45ad264e0a7e08c342cf9fb5711
+SHA512:
+  metadata.gz: d84d9c25a0379bca316619e0268c9f727228572c09048cb2717591acf145f1459c4292617f3ba836d756a9bd0f79b4922fdec43812cf3d111ab57d8dc591d945
+  data.tar.gz: e908c4bee35578e1ecd313b126ea87b7cc3719eba286cbe01ed11000fdd65dc09b41ba49fc069da64137d783d8c19076ae5dac4dd5418b8aac7b8b89c32b31ad

data/.envrc

@@ -0,0 +1 @@
+export RR=`pwd`

data/.github/workflows/deploy-github-pages.yml

@@ -0,0 +1,52 @@
+name: Deploy Documentation to GitHub Pages
+on:
+  push:
+    branches:
+      - main
+      - develop
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/deploy-github-pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs
+          pip install mkdocs-material
+          pip install mkdocs-macros-plugin
+          pip install mike
+
+      - name: Configure Git
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+
+      - name: Build MkDocs site
+        run: mkdocs build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          keep_files: true

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-05-07
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dewayne VanHoozer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,110 @@
+# robot_lab-rails
+
+Rails integration for the [RobotLab](https://github.com/MadBomber/robot_lab) LLM agent framework.
+
+> [!CAUTION]
+> This gem is under active development. APIs may change without notice.
+
+## What it provides
+
+- **Rails Engine** — autoloads `app/robots/` and `app/tools/` in your application
+- **Railtie** — wires `RobotLab.config` to `Rails.logger` and applies Rails-specific configuration
+- **`RobotLab::Job`** — ActiveJob base class with Turbo Stream streaming, thread persistence, and error broadcasting
+- **Generators** — `rails generate robot_lab:install`, `robot_lab:robot NAME`, `robot_lab:job NAME`
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "robot_lab"
+gem "robot_lab-rails"
+```
+
+Then run the installer:
+
+```bash
+rails generate robot_lab:install
+rails db:migrate
+```
+
+This creates:
+
+- `config/initializers/robot_lab.rb` — configuration
+- `app/robots/` — directory for your robots
+- Database tables for conversation history
+
+## Background Jobs
+
+`RobotLab::Job` is an `ActiveJob::Base` subclass that handles the full robot-run lifecycle: robot class resolution, Turbo Stream wiring, thread-record persistence, and completion/error broadcasting.
+
+**Generic job** (robot class supplied at enqueue time):
+
+```bash
+rails generate robot_lab:install   # creates app/jobs/robot_run_job.rb
+```
+
+```ruby
+# app/jobs/robot_run_job.rb  (generated)
+class RobotRunJob < RobotLab::Job
+  queue_as :default
+end
+
+# Enqueue from a controller:
+RobotRunJob.perform_later(
+  robot_class: "SupportRobot",
+  message:     params[:message],
+  thread_id:   session_id
+)
+```
+
+**Dedicated job** (robot class bound at the class level via DSL):
+
+```bash
+rails generate robot_lab:job Support            # binds to SupportRobot, queue: default
+rails generate robot_lab:job Support --queue ai # custom queue
+```
+
+```ruby
+# app/jobs/support_job.rb  (generated)
+class SupportJob < RobotLab::Job
+  queue_as :default
+  robot_class SupportRobot
+end
+
+# Enqueue (no robot_class: needed):
+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.
+
+## Turbo Stream Streaming
+
+When `thread_id` is provided and [turbo-rails](https://github.com/hotwired/turbo-rails) is installed, `RobotLab::Job` automatically:
+
+- Wires `on_content` / `on_tool_call` Turbo Stream callbacks so the UI updates in real time
+- Broadcasts a **completion** event to `"robot_lab_thread_#{thread_id}"` when the run finishes
+- Broadcasts an **error** event (HTML-escaped) if the job raises
+
+In your view:
+
+```erb
+<%= turbo_stream_from "robot_lab_thread_#{session[:id]}" %>
+<div id="robot_response"></div>
+<div id="robot_status"></div>
+```
+
+## Links
+
+- [Rails Integration Guide](https://madbomber.github.io/robot_lab-rails/guides/rails-integration)
+- [Rails Application Example](https://madbomber.github.io/robot_lab-rails/examples/rails-application)
+- [RobotLab Core](https://github.com/MadBomber/robot_lab)
+- [RubyGems](https://rubygems.org/gems/robot_lab-rails)
+
+## License
+
+MIT License - Copyright (c) 2025 Dewayne VanHoozer
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/MadBomber/robot_lab-rails.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/docs/examples/rails-application.md

@@ -0,0 +1,419 @@
+# Rails Application
+
+Full Rails integration with Action Cable and background jobs.
+
+## Overview
+
+This example demonstrates integrating RobotLab into a Rails application with real-time streaming via Action Cable, background job processing, and persistent conversation history.
+
+## Setup
+
+### 1. Add to Gemfile
+
+```ruby
+# Gemfile
+gem "robot_lab"
+```
+
+### 2. Run Generator
+
+```bash
+rails generate robot_lab:install
+```
+
+This creates:
+
+- `config/initializers/robot_lab.rb`
+- `app/robots/` directory
+- `app/tools/` directory
+- Database migrations for conversation history
+
+### 3. Run Migrations
+
+```bash
+rails db:migrate
+```
+
+## Configuration
+
+RobotLab uses MywayConfig for configuration. There is no `RobotLab.configure` block. Instead, configuration is loaded automatically from multiple sources in priority order:
+
+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)
+
+### Config File
+
+```yaml
+# config/robot_lab.yml
+defaults:
+  ruby_llm:
+    model: claude-sonnet-4
+    anthropic_api_key: <%= ENV['ANTHROPIC_API_KEY'] %>
+
+development:
+  ruby_llm:
+    log_level: :debug
+
+production:
+  ruby_llm:
+    request_timeout: 180
+    max_retries: 5
+```
+
+### Environment Variables
+
+```bash
+# Provider API keys
+ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY=sk-ant-...
+ROBOT_LAB_RUBY_LLM__OPENAI_API_KEY=sk-...
+
+# Model configuration
+ROBOT_LAB_RUBY_LLM__MODEL=claude-sonnet-4
+ROBOT_LAB_RUBY_LLM__REQUEST_TIMEOUT=120
+```
+
+### Accessing Configuration
+
+```ruby
+# Read configuration values at runtime
+RobotLab.config.ruby_llm.model            #=> "claude-sonnet-4"
+RobotLab.config.ruby_llm.request_timeout  #=> 120
+
+# The logger defaults to Rails.logger when running in Rails
+RobotLab.config.logger  #=> Rails.logger
+```
+
+### Rails Engine and Railtie
+
+RobotLab provides both a Rails Engine (`RobotLab::RailsIntegration::Engine`) and a Railtie (`RobotLab::RailsIntegration::Railtie`). These are loaded automatically when Rails is detected. The Engine isolates the RobotLab namespace and adds `app/robots` and `app/tools` to the autoload paths. The Railtie loads rake tasks and generators.
+
+## Models
+
+```ruby
+# app/models/conversation_thread.rb
+class ConversationThread < ApplicationRecord
+  belongs_to :user
+  has_many :messages, class_name: "ConversationMessage", dependent: :destroy
+
+  validates :external_id, presence: true, uniqueness: true
+
+  def self.find_or_create_for(user:, external_id: nil)
+    external_id ||= SecureRandom.uuid
+    find_or_create_by!(user: user, external_id: external_id)
+  end
+end
+
+# app/models/conversation_message.rb
+class ConversationMessage < ApplicationRecord
+  belongs_to :thread, class_name: "ConversationThread"
+
+  validates :role, presence: true
+  validates :content, presence: true
+
+  scope :ordered, -> { order(:position) }
+end
+```
+
+## Robot Definitions
+
+Robots are built using `RobotLab.build` with named parameters. Tools are Ruby classes that inherit from `RubyLLM::Tool`.
+
+```ruby
+# app/tools/get_user_info_tool.rb
+class GetUserInfoTool < RubyLLM::Tool
+  description "Get information about the current user"
+
+  param :user_id, type: :integer, desc: "The user ID to look up"
+
+  def execute(user_id:)
+    user = User.find(user_id)
+    {
+      name: user.name,
+      email: user.email,
+      plan: user.subscription&.plan || "free",
+      member_since: user.created_at.to_date.to_s
+    }
+  rescue ActiveRecord::RecordNotFound
+    { error: "User not found" }
+  end
+end
+
+# app/tools/get_orders_tool.rb
+class GetOrdersTool < RubyLLM::Tool
+  description "Get user's recent orders"
+
+  param :user_id, type: :integer, desc: "The user ID"
+  param :limit, type: :integer, desc: "Number of orders to return", default: 5
+
+  def execute(user_id:, limit: 5)
+    orders = Order.where(user_id: user_id)
+                  .order(created_at: :desc)
+                  .limit(limit)
+
+    orders.map do |order|
+      {
+        id: order.external_id,
+        status: order.status,
+        total: order.total.to_f,
+        created_at: order.created_at.iso8601
+      }
+    end
+  end
+end
+
+# app/tools/create_ticket_tool.rb
+class CreateTicketTool < RubyLLM::Tool
+  description "Create a support ticket"
+
+  param :user_id, type: :integer, desc: "The user ID"
+  param :subject, type: :string, desc: "Ticket subject"
+  param :description, type: :string, desc: "Ticket description"
+  param :priority, type: :string, desc: "Priority level", enum: %w[low medium high]
+
+  def execute(user_id:, subject:, description:, priority: "medium")
+    ticket = SupportTicket.create!(
+      user_id: user_id,
+      subject: subject,
+      description: description,
+      priority: priority
+    )
+
+    {
+      success: true,
+      ticket_id: ticket.external_id,
+      message: "Ticket created successfully"
+    }
+  rescue => e
+    { success: false, error: e.message }
+  end
+end
+```
+
+```ruby
+# app/robots/support_robot.rb
+class SupportRobot
+  def self.build(user_id:)
+    RobotLab.build(
+      name: "support",
+      system_prompt: <<~PROMPT,
+        You are a helpful customer support assistant for our company.
+        Be friendly, professional, and thorough in your responses.
+        If you need to look up information, use the available tools.
+        The current user ID is #{user_id}.
+      PROMPT
+      local_tools: [GetUserInfoTool, GetOrdersTool, CreateTicketTool]
+    )
+  end
+end
+```
+
+## Network Configuration
+
+Networks use `create_network` with a block DSL that defines tasks and their dependencies:
+
+```ruby
+# app/robots/support_network.rb
+class SupportNetwork
+  def self.build(user_id:)
+    support = SupportRobot.build(user_id: user_id)
+
+    RobotLab.create_network(name: "support_network") do
+      task :support, support, depends_on: :none
+    end
+  end
+end
+```
+
+## Service Object
+
+```ruby
+# app/services/chat_service.rb
+class ChatService
+  def initialize(user:, thread_id: nil)
+    @user = user
+    @thread_id = thread_id
+  end
+
+  def call(message:)
+    robot = SupportRobot.build(user_id: @user.id)
+    result = robot.run(message)
+
+    {
+      response: result.last_text_content,
+      has_tool_calls: result.has_tool_calls?
+    }
+  end
+end
+```
+
+## Controller
+
+```ruby
+# app/controllers/api/chats_controller.rb
+module Api
+  class ChatsController < ApplicationController
+    before_action :authenticate_user!
+
+    def create
+      service = ChatService.new(
+        user: current_user,
+        thread_id: params[:thread_id]
+      )
+
+      result = service.call(message: params[:message])
+
+      render json: {
+        response: result[:response]
+      }
+    end
+  end
+end
+```
+
+## Action Cable Integration
+
+```ruby
+# app/channels/chat_channel.rb
+class ChatChannel < ApplicationCable::Channel
+  def subscribed
+    stream_for current_user
+  end
+
+  def receive(data)
+    ChatJob.perform_later(
+      user_id: current_user.id,
+      thread_id: data["thread_id"],
+      message: data["message"]
+    )
+  end
+end
+
+# app/jobs/chat_job.rb
+class ChatJob < ApplicationJob
+  queue_as :default
+
+  def perform(user_id:, thread_id:, message:)
+    user = User.find(user_id)
+    robot = SupportRobot.build(user_id: user.id)
+
+    result = robot.run(message)
+
+    ChatChannel.broadcast_to(
+      user,
+      type: "complete",
+      content: result.last_text_content
+    )
+  end
+end
+```
+
+## Frontend (Stimulus)
+
+```javascript
+// app/javascript/controllers/chat_controller.js
+import { Controller } from "@hotwired/stimulus"
+import { createConsumer } from "@rails/actioncable"
+
+export default class extends Controller {
+  static targets = ["messages", "input", "response"]
+
+  connect() {
+    this.consumer = createConsumer()
+    this.channel = this.consumer.subscriptions.create("ChatChannel", {
+      received: (data) => this.handleMessage(data)
+    })
+  }
+
+  disconnect() {
+    this.channel?.unsubscribe()
+  }
+
+  send() {
+    const message = this.inputTarget.value.trim()
+    if (!message) return
+
+    this.appendMessage("user", message)
+    this.inputTarget.value = ""
+
+    // Create response container
+    this.currentResponse = document.createElement("div")
+    this.currentResponse.className = "message assistant"
+    this.messagesTarget.appendChild(this.currentResponse)
+
+    this.channel.send({
+      message: message,
+      thread_id: this.threadId
+    })
+  }
+
+  handleMessage(data) {
+    switch (data.type) {
+      case "complete":
+        this.currentResponse.textContent = data.content
+        break
+    }
+  }
+
+  appendMessage(role, content) {
+    const div = document.createElement("div")
+    div.className = `message ${role}`
+    div.textContent = content
+    this.messagesTarget.appendChild(div)
+  }
+}
+```
+
+## View
+
+```erb
+<!-- app/views/chats/show.html.erb -->
+<div data-controller="chat">
+  <div class="messages" data-chat-target="messages">
+    <!-- Messages appear here -->
+  </div>
+
+  <form data-action="submit->chat#send">
+    <input type="text"
+           data-chat-target="input"
+           placeholder="Type a message..."
+           autocomplete="off">
+    <button type="submit">Send</button>
+  </form>
+</div>
+```
+
+## Running
+
+```bash
+# Install dependencies
+bundle install
+yarn install
+
+# Setup database
+rails db:migrate
+
+# Set API key (or configure via config/robot_lab.yml)
+export ANTHROPIC_API_KEY="your-key"
+
+# Start server
+bin/dev
+```
+
+## Key Concepts
+
+1. **Robot Factory**: `RobotLab.build(name:, system_prompt:, local_tools:, ...)` creates robot instances
+2. **MywayConfig**: Configuration via YAML files and environment variables, not a configure block
+3. **`robot.run("message")`**: Send a message as a positional string argument
+4. **`result.last_text_content`**: Extract the response text from a `RobotResult`
+5. **Memory**: Robots have `robot.memory` for key-value storage; networks share memory
+6. **Tools**: Ruby classes inheriting from `RubyLLM::Tool`, passed via `local_tools:`
+7. **Action Cable**: Real-time streaming to browser
+8. **Background Jobs**: Non-blocking processing
+
+## See Also
+
+- [Rails Integration Guide](../guides/rails-integration.md)
+- [Streaming Guide](../guides/streaming.md)