rails-llm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 39eedacae9a3c2f4d9a66b014aa94311596fff997382d8bfc82ef078e181abd0
+  data.tar.gz: 0dee69794bf8e1100ea3a708844e1563b366249f5d156f46a678abdb50a54124
+SHA512:
+  metadata.gz: 93d1d518fdb7fdb1ba226db963bf0c5bb818e35cdfff114e8a08312ccbf618e9f2e27bf5a29c16fb7a51114d25f75d9681e3b395d86819853d5165f1acaa3f2d
+  data.tar.gz: c4f18a1b658f776822558e135822f837f19a9977d6ac7a5e5e6db535dcf34cecc4952febc62222a04ad57019bd8335b38e733edf5771c3793d160fc99638b991

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+gemspec
+gem "llm.rb", github: "llmrb/llm.rb"

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright (C) 2026
+0x1eef <0x1eef@hardenedbsd.org>
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,127 @@
+<p align="center">
+  <a href="https://github.com/llmrb/rails-llm">
+    <img src="https://github.com/llmrb/llm.rb/raw/main/llm.png" width="200"
+         height="200" border="0" alt="rails-llm">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/llmrb/rails-llm">
+    <img src="https://img.shields.io/badge/version-0.1.0-green.svg"
+         alt="Version">
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/License-0BSD-orange.svg"
+         alt="License">
+  </a>
+  <a href="https://github.com/llmrb/llm.rb">
+    <img src="https://img.shields.io/badge/powered%20by-llm.rb-blue.svg"
+         alt="Powered by llm.rb">
+  </a>
+</p>
+
+## About
+
+This project integrates the [llm.rb](https://github.com/llmrb/llm.rb#readme)
+runtime and its features into Rails.
+
+The project extends the builtin ActiveRecord support available to the
+[llm.rb](https://github.com/llmrb/llm.rb#readme)
+runtime with a Rails integration that includes generators for getting
+set up quickly, and an engine for a stream-capable chat interface
+that can be extended with your own tools.
+
+The [llm.rb](https://github.com/llmrb/llm.rb#readme) runtime runs on Ruby's
+standard library by default. loads optional pieces only when needed, and
+offers a single runtime for providers, agents, tools, skills, MCP, A2A (Agent2Agent),
+RAG (vector stores & embeddings), streaming, files, and persisted state.
+
+## Quick start
+
+**1. Add to Gemfile**
+
+Add `rails-llm`:
+
+```bash
+bundle add rails-llm
+```
+
+**2. Run generator**
+
+Generate the model, migration, and routes:
+
+```bash
+rails generate rails_llm:install
+```
+
+**3. Run migrations**
+
+Migrate the database:
+
+```bash
+rails db:migrate
+```
+
+**4. Configure your API key**
+
+Set your API key. If you want to use a different provider,
+edit `set_provider` in `app/models/rails_llm/agent.rb`.
+
+```bash
+export DEEPSEEK_API_KEY=...
+```
+
+**5. Profit**
+
+Open your browser: 
+
+```bash
+open http://localhost:3000/ai/agents
+```
+
+## Example
+
+#### acts_as_agent
+
+```ruby
+class Agent < ApplicationRecord
+  acts_as_agent provider: :set_provider, context: :set_context
+
+  private
+
+  def set_provider
+    LLM.deepseek(key: ENV["DEEPSEEK_API_KEY"])
+  end
+
+  def set_context
+    {model: "deepseek-v4-flash"}
+  end
+end
+
+agent = Agent.create!
+agent.ask("What is the capital of France?").content       # => "Paris"
+agent.ask("Summarize this", with: "report.pdf").content   # with a file
+agent.ask("Tell me a story") { |chunk| print chunk }      # streaming
+```
+
+## Engine
+
+#### Generators
+
+| Generator | What it creates |
+|---|---|
+| `rails_llm:install` | `RailsLLM::Agent` model, `RailsLLM::KnowledgeTool`, migration (`rails_llm_agents`), initializer, engine routes |
+| `rails_llm:model` | `RailsLLM::Agent` model with `acts_as_agent` |
+
+#### Engine routes
+
+| Method | Path | Action |
+|---|---|---|
+| GET | `/ai/agents` | List agents |
+| GET | `/ai/agents/:id` | View an agent |
+| POST | `/ai/agents` | Create a new agent |
+| POST | `/ai/agents/:id/ask` | Send a message |)
+
+## License
+
+[BSD Zero Clause](LICENSE)

data/app/assets/javascripts/rails_llm/application.js

@@ -0,0 +1,188 @@
+;(function() {
+  const View = (messages) => {
+    const append = (role, content) => {
+      const node = document.createElement("div")
+      node.className = `message ${role}`
+      node.textContent = content
+      messages.appendChild(node)
+      messages.scrollTop = messages.scrollHeight
+      return node
+    }
+
+    const appendToolCall = (name) => {
+      const node = document.createElement("details")
+      const summary = document.createElement("summary")
+      const label = document.createElement("span")
+      node.className = "tool-call live"
+      node.open = true
+      label.className = "tool-name"
+      label.textContent = name
+      summary.append("Running ", label)
+      node.appendChild(summary)
+      messages.appendChild(node)
+      messages.scrollTop = messages.scrollHeight
+      return node
+    }
+
+    return {
+      messages,
+      appendToolCall,
+      appendAssistant() {
+        const node = append("assistant", "")
+        return node
+      },
+      appendUser(content) {
+        return append("user", content)
+      },
+      clearEmptyState() {
+        const emptyState = messages.querySelector(".empty-state")
+        if (emptyState) emptyState.remove()
+      },
+      focusBottom() {
+        messages.scrollTop = messages.scrollHeight
+      },
+      showCursor(node) {
+        node.classList.add("streaming-cursor")
+      },
+      hideCursor(node) {
+        node.classList.remove("streaming-cursor")
+      }
+    }
+  }
+
+  const JSONStream = (response, onEvent) => {
+    const reader = response.body.getReader()
+    const decoder = new TextDecoder()
+    let buffer = ""
+
+    return {
+      async read() {
+        while (true) {
+          const {value, done} = await reader.read()
+          buffer += decoder.decode(value || new Uint8Array(), {stream: !done})
+          const lines = buffer.split("\n")
+          buffer = lines.pop()
+          lines.filter(Boolean).forEach((line) => onEvent(JSON.parse(line)))
+          if (done) break
+        }
+        if (buffer.trim()) onEvent(JSON.parse(buffer))
+      }
+    }
+  }
+
+  const Turn = (form, prompt = null) => {
+    const view = View(document.getElementById("messages"))
+    const input = form.querySelector('input[name="prompt"]')
+    const submit = form.querySelector('input[type="submit"], button[type="submit"]')
+    const content = (prompt || input.value).trim()
+    const state = {
+      assistantNode: null,
+      done: false
+    }
+
+    const ensureAssistantNode = () => {
+      state.assistantNode ||= view.appendAssistant()
+      view.showCursor(state.assistantNode)
+      return state.assistantNode
+    }
+
+    const onEvent = (event) => {
+      if (event.type == "done") {
+        state.done = true
+        return
+      }
+      if (event.type == "content") {
+        ensureAssistantNode().innerHTML = event.content || ""
+        view.focusBottom()
+        return
+      }
+      if (event.type == "tool_call") {
+        view.appendToolCall(event.name || "tool")
+      }
+    }
+
+    return {
+      async submit() {
+        if (!content) return
+        const formData = new FormData(form)
+        view.clearEmptyState()
+        formData.set("prompt", content)
+        view.appendUser(content)
+        input.value = ""
+        input.disabled = true
+        submit.disabled = true
+        try {
+          const response = await fetch(form.action, {
+            method: form.method || "POST",
+            body: formData,
+            headers: {
+              "Accept": "application/x-ndjson",
+              "X-CSRF-Token": document.querySelector('meta[name="csrf-token"]').content
+            }
+          })
+          if (!response.ok || !response.body) throw new Error(`Request failed: ${response.status}`)
+          await JSONStream(response, onEvent).read()
+        } catch (error) {
+          ensureAssistantNode().textContent = "Streaming failed."
+          console.error(error)
+        } finally {
+          if (state.assistantNode) view.hideCursor(state.assistantNode)
+          input.disabled = false
+          submit.disabled = false
+          input.focus()
+        }
+      }
+    }
+  }
+
+  const App = () => {
+    const onCreate = async (event) => {
+      event.preventDefault()
+      const form = event.currentTarget
+      const input = form.querySelector('input[name="prompt"]')
+      const prompt = input.value.trim()
+      const response = await fetch(form.action, {
+        method: form.method || "POST",
+        body: new FormData(form),
+        headers: {
+          "Accept": "application/json",
+          "X-CSRF-Token": document.querySelector('meta[name="csrf-token"]').content
+        }
+      })
+      if (!response.ok) return
+      const data = await response.json()
+      const url = new URL(data.location, window.location.origin)
+      url.searchParams.set("prompt", prompt)
+      window.location.assign(url)
+    }
+
+    const onAsk = async (event) => {
+      event.preventDefault()
+      await Turn(event.currentTarget).submit()
+    }
+
+    return {
+      async onDOMContentLoaded() {
+        switch(window.location.pathname) {
+          case "/ai/agents": {
+            const form = document.getElementById("new-agent-form")
+            form.addEventListener("submit", onCreate)
+            break
+          }
+          default: {
+            const askForm = document.getElementById("ask-form")
+            const prompt = new URLSearchParams(window.location.search).get("prompt")
+            askForm.addEventListener("submit", onAsk)
+            if (!prompt) return
+            window.history.replaceState({}, "", window.location.pathname)
+            await Turn(askForm, prompt).submit()
+            break
+          }
+        }
+      }
+    }
+  }
+
+  const app = App()
+  document.addEventListener("DOMContentLoaded", app.onDOMContentLoaded)
+})();

data/app/controllers/rails_llm/agents_controller.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module RailsLLM
+  class AgentsController < ::ApplicationController
+    include ActionController::Live
+
+    layout "rails_llm/application"
+    before_action :set_agents
+    before_action :set_agent, only: %i[show ask]
+
+    def index
+      @agent = Agent.new
+    end
+
+    def show
+      @messages = messages
+    end
+
+    def create
+      @agent = Agent.create!(create_params)
+      respond_to do |format|
+        format.html { redirect_to agent_path(@agent) }
+        format.json { render json: {location: agent_path(@agent)} }
+      end
+    end
+
+    def ask
+      prompt = params[:prompt]
+      return head(:unprocessable_entity) if prompt.blank?
+      response.headers["Content-Type"] = "application/x-ndjson; charset=utf-8"
+      response.headers["Cache-Control"] = "no-cache"
+      response.headers["X-Accel-Buffering"] = "no"
+      stream = Stream.new(response.stream)
+      @agent.ask(prompt, stream:)
+      stream.finish
+    ensure
+      response.stream.close
+    end
+
+    private
+
+    def set_agent
+      @agent = Agent.find(params[:id])
+    end
+
+    def set_agents
+      @agents = Agent.ordered
+    end
+
+    def create_params
+      allowed = {}
+      prompt = params[:prompt].to_s.strip
+      allowed.merge!(title: prompt.tr("\n", " ")[0, 80])
+    end
+
+    def messages
+      @agent
+        .messages
+        .select { _1.user? || _1.assistant? }
+        .reject { _1.tool_call? || _1.tool_return? }
+    end
+  end
+end