ruby_llm-ai_sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 83d6d8d1f54099cf62f2f8514780f8df54b185e7ad9e0fe7dbd5bb6e57be4a45
+  data.tar.gz: 49069ade3a6b4ff8fe19a417680651740331df524b1126ebe7fec854cd9882ed
+SHA512:
+  metadata.gz: 53f1644c79f531dd9d89fc655e900b6a27b50c0d55a41b7dec1d8d81b12991a2cca82d9bec777bd1cc685071f321e904f73f7efa55c30abd7379ff025ab910df
+  data.tar.gz: 21219200c9740960c39bab1d1b8ae88c663009a0b6b2de0e8977e23cc45f6229470144e2ca336d27529388b70159a0ac7cc68c6b98010ac4cc199500ca6f79f3

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- `RubyLLM::AiSdk::Stream` writes a chat turn as AI SDK UI message stream events: text, reasoning, tool calls, tool results, and approval requests.
+- `RubyLLM::AiSdk::Request` reads the last user message and approval decisions from the body `useChat` posts.
+- `RubyLLM::AiSdk::Controller` streams a turn from a Rails action with `stream_chat`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruno Costanzo
+
+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,103 @@
+# ruby_llm-ai_sdk
+
+Stream [RubyLLM](https://rubyllm.com) chats to the [AI SDK](https://ai-sdk.dev) `useChat` hook.
+
+The AI SDK's React hooks speak the [UI message stream protocol](https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol): Server-Sent Events that carry text deltas, reasoning, tool calls, tool results and approval requests. This gem emits that protocol from a RubyLLM chat, so a React or Next.js front end talks to a Ruby backend the same way it talks to a Node one, tool calls and human approvals included.
+
+```ruby
+RubyLLM::AiSdk::Stream.new(chat, response.stream).ask "Refund order 42"
+```
+
+## Installation
+
+```ruby
+gem "ruby_llm-ai_sdk"
+```
+
+Requires RubyLLM 1.16 or later. Approval requests need RubyLLM's `requires_approval`, unreleased at the time of writing, so point the `ruby_llm` gem at its `main` branch to use them.
+
+## Usage in Rails
+
+Include the controller module and hand `stream_chat` a chat. It sets the headers the AI SDK expects, streams the turn over `ActionController::Live`, and closes the stream when the turn ends.
+
+```ruby
+class MessagesController < ApplicationController
+  include RubyLLM::AiSdk::Controller
+
+  def create
+    stream_chat SupportAgent.find(params[:chat_id])
+  end
+end
+```
+
+On the front end, point `useChat` at that action. Nothing else changes.
+
+```tsx
+const { messages, sendMessage, addToolApprovalResponse } = useChat({
+  transport: new DefaultChatTransport({ api: `/chats/${chatId}/messages` }),
+  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
+});
+```
+
+`stream_chat` reads the body `useChat` posts. When the last message is from the user, it asks it. When the last assistant message carries approval decisions, it records them with `chat.approve` or `chat.deny` and continues the parked turn.
+
+## Usage anywhere else
+
+`Stream` writes to anything that responds to `write`, so it works with Rack hijacking, Sinatra streaming, or a file.
+
+```ruby
+stream = RubyLLM::AiSdk::Stream.new(chat, io)
+stream.ask "What is the weather in Paris?"   # one turn, streamed
+stream.serve request_body                     # a full useChat body, as JSON or a Hash
+```
+
+`RubyLLM::AiSdk::HEADERS` holds the response headers to set.
+
+## What the stream contains
+
+| RubyLLM event | AI SDK chunks |
+| --- | --- |
+| Turn begins | `start` |
+| First chunk of a model response | `start-step` |
+| Text chunks | `text-start`, `text-delta`, `text-end` |
+| Reasoning chunks | `reasoning-start`, `reasoning-delta`, `reasoning-end` |
+| Assistant message with tool calls | `tool-input-available` per call, then `finish-step` |
+| Tool result message | `tool-output-available`, or `tool-output-denied` after a denial |
+| Turn parked on `requires_approval` | `tool-approval-request` per pending call |
+| Turn ends | `finish`, then `[DONE]` |
+| Exception | `error`, then `[DONE]`, and the exception is re-raised |
+
+Tool outputs that are valid JSON arrive parsed, so `part.output` on the client is the object your tool returned.
+
+## Human in the loop
+
+Declare a tool with `requires_approval` and the turn stops before it runs. The client receives `tool-approval-request`, renders it with the tool's input, and the person decides:
+
+```tsx
+{part.state === "approval-requested" && (
+  <button onClick={() => addToolApprovalResponse({ id: part.approval.id, approved: true })}>
+    Approve
+  </button>
+)}
+```
+
+`useChat` posts the decision back, the gem records it, and the same stream format carries the tool's output and the model's reply. With `acts_as_chat`, the decision persists on the tool call record, so the parked turn can be resumed from another process.
+
+## Design notes
+
+- **A Stream is one turn.** It registers a callback on the chat it wraps and only writes while its own turn runs, so a chat can be streamed turn after turn, with one Stream per request.
+- **Tool results come from the transcript, not the callback.** RubyLLM's `after_tool_result` does not carry the tool call id, so results are read from the tool messages appended to the chat. That also keeps concurrent tool execution correct.
+- **Steps follow model responses.** Each assistant message closes a step; a text or reasoning chunk that arrives with no step open opens one.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake   # specs and RuboCop
+```
+
+The specs stub the provider and drive real `RubyLLM::Chat` objects through every path, including approvals. No API keys are needed.
+
+## License
+
+MIT.

data/lib/ruby_llm/ai_sdk/controller.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+require 'action_controller'
+
+module RubyLLM
+  module AiSdk
+    # Streams a chat turn from a Rails controller action in the format
+    # +useChat+ expects. Including it also includes ActionController::Live.
+    #
+    #   class MessagesController < ApplicationController
+    #     include RubyLLM::AiSdk::Controller
+    #
+    #     def create
+    #       stream_chat SupportAgent.find(params[:chat_id])
+    #     end
+    #   end
+    #
+    module Controller
+      extend ActiveSupport::Concern
+
+      included { include ActionController::Live }
+
+      # Streams one turn of +chat+ driven by +body+, the JSON +useChat+
+      # posted, and closes the response stream when the turn ends.
+      def stream_chat(chat, body = request.raw_post)
+        HEADERS.each { |name, value| response.headers[name] = value }
+        Stream.new(chat, response.stream).serve(body)
+      ensure
+        response.stream.close
+      end
+    end
+  end
+end

data/lib/ruby_llm/ai_sdk/request.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module AiSdk
+    # The body +useChat+ posts on every turn: the chat id and the full list
+    # of UI messages. A Request reads the two things the server acts on,
+    # the last user message and the approval decisions on the last
+    # assistant message.
+    #
+    #   request = RubyLLM::AiSdk::Request.parse(request.raw_post)
+    #   request.text      # => "Refund order 42"
+    #   request.approvals # => []
+    #
+    class Request
+      # One decision on a tool call that required approval.
+      Approval = Struct.new(:tool_call_id, :approved, keyword_init: true) do
+        # Returns whether the person approved the tool call.
+        def approved?
+          approved == true
+        end
+      end
+
+      # The chat id +useChat+ was created with.
+      attr_reader :id
+
+      # The UI messages as posted, an array of Hashes.
+      attr_reader :messages
+
+      # Returns a Request parsed from a JSON +body+.
+      def self.parse(body)
+        new(JSON.parse(body))
+      end
+
+      def initialize(body)
+        @id = body['id']
+        @messages = body.fetch('messages', [])
+      end
+
+      # Returns the id of the last message, or +nil+ when there is none.
+      def message_id
+        last_message&.fetch('id', nil)
+      end
+
+      # Returns the text of the last message when it comes from the user,
+      # with its text parts joined by newlines, or +nil+ otherwise.
+      def text
+        return unless last_message&.fetch('role', nil) == 'user'
+
+        parts_of_type('text').map { |part| part['text'] }.join("\n")
+      end
+
+      # Returns the Approval decisions recorded on the last assistant
+      # message, an empty array when there are none.
+      def approvals
+        return [] unless last_message&.fetch('role', nil) == 'assistant'
+
+        parts_where('state' => 'approval-responded').map do |part|
+          Approval.new(tool_call_id: part['toolCallId'], approved: part.dig('approval', 'approved'))
+        end
+      end
+
+      private
+
+      def last_message
+        messages.last
+      end
+
+      def parts_of_type(type)
+        parts_where('type' => type)
+      end
+
+      def parts_where(attributes)
+        last_message.fetch('parts', []).select { |part| attributes.all? { |key, value| part[key] == value } }
+      end
+    end
+  end
+end

data/lib/ruby_llm/ai_sdk/stream.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module AiSdk
+    # Writes one assistant turn of a Chat to an IO as AI SDK UI message
+    # stream events. Text and reasoning stream as they arrive, tool calls
+    # and their results follow each step, and tool calls parked on an
+    # approval end the turn with an approval request.
+    #
+    #   stream = RubyLLM::AiSdk::Stream.new(chat, response.stream)
+    #   stream.ask "Refund order 42"
+    #
+    # A Stream only writes during its own turn, so several streams can be
+    # built on the same chat over its lifetime, one per request.
+    class Stream
+      # The Chat this stream writes.
+      attr_reader :chat
+
+      # The IO the events go to. Anything that responds to +write+.
+      attr_reader :io
+
+      def initialize(chat, io)
+        @chat = chat
+        @io = io
+        @denied = []
+        @step = false
+        @active = false
+        chat.after_message { |message| append(message) if @active }
+      end
+
+      # Handles one +useChat+ request end to end. Records the approval
+      # decisions when the request carries them and continues the parked
+      # turn, otherwise asks the last user message. Returns the final
+      # Message.
+      def serve(request)
+        request = Request.parse(request) if request.is_a?(String)
+        request = Request.new(request) if request.is_a?(Hash)
+        return ask(request.text) if request.approvals.empty?
+
+        request.approvals.each { |approval| decide(approval) }
+        complete(message_id: request.message_id)
+      end
+
+      # Asks +text+ and streams the response. Accepts the same keyword
+      # arguments as Chat#ask. Returns the final Message.
+      def ask(text, **options)
+        turn { chat.ask(text, **options, &method(:receive)) }
+      end
+
+      # Continues a turn the chat already staged, such as one parked on an
+      # approval, and streams the response. Pass the id of the assistant
+      # message the client is showing as +message_id+ so it continues that
+      # message instead of starting a new one. Returns the final Message.
+      def complete(message_id: nil)
+        turn(message_id) { chat.complete(&method(:receive)) }
+      end
+
+      private
+
+      def turn(message_id = nil)
+        @active = true
+        emit type: 'start', messageId: message_id || "msg_#{SecureRandom.hex(12)}"
+        response = yield
+        request_approvals
+        emit type: 'finish'
+        response
+      rescue StandardError => e
+        emit type: 'error', errorText: e.message
+        raise
+      ensure
+        io.write "data: [DONE]\n\n"
+        @active = false
+      end
+
+      def append(message)
+        message.tool_result? ? tool_output(message) : finish_step(message)
+      end
+
+      def receive(chunk)
+        start_step unless @step
+        reasoning(thinking_text(chunk)) if thinking_text(chunk)
+        text(chunk.content.to_s) unless chunk.content.to_s.empty?
+      end
+
+      def start_step
+        @step = true
+        emit type: 'start-step'
+      end
+
+      def finish_step(message)
+        start_step unless @step
+        close_text
+        close_reasoning
+        message.tool_calls&.each_value do |tool_call|
+          emit type: 'tool-input-available', toolCallId: tool_call.id, toolName: tool_call.name,
+               input: tool_call.arguments
+        end
+        emit type: 'finish-step'
+        @step = false
+      end
+
+      def text(delta)
+        close_reasoning
+        @text_id ||= open_part('text')
+        emit type: 'text-delta', id: @text_id, delta: delta
+      end
+
+      def reasoning(delta)
+        close_text
+        @reasoning_id ||= open_part('reasoning')
+        emit type: 'reasoning-delta', id: @reasoning_id, delta: delta
+      end
+
+      def open_part(kind)
+        id = "#{kind}_#{SecureRandom.hex(8)}"
+        emit type: "#{kind}-start", id: id
+        id
+      end
+
+      def close_text
+        emit type: 'text-end', id: @text_id if @text_id
+        @text_id = nil
+      end
+
+      def close_reasoning
+        emit type: 'reasoning-end', id: @reasoning_id if @reasoning_id
+        @reasoning_id = nil
+      end
+
+      def tool_output(message)
+        if @denied.include?(message.tool_call_id)
+          emit type: 'tool-output-denied', toolCallId: message.tool_call_id
+        else
+          emit type: 'tool-output-available', toolCallId: message.tool_call_id, output: output_of(message)
+        end
+      end
+
+      def output_of(message)
+        JSON.parse(message.content.to_s)
+      rescue JSON::ParserError
+        message.content.to_s
+      end
+
+      def request_approvals
+        return unless chat.respond_to?(:pending_approvals)
+
+        chat.pending_approvals.each do |tool_call|
+          id = tool_call_id(tool_call)
+          emit type: 'tool-approval-request', toolCallId: id, approvalId: id
+        end
+      end
+
+      def decide(approval)
+        if approval.approved?
+          chat.approve(approval.tool_call_id)
+        else
+          chat.deny(approval.tool_call_id)
+          @denied << approval.tool_call_id
+        end
+      end
+
+      def tool_call_id(tool_call)
+        tool_call.respond_to?(:tool_call_id) ? tool_call.tool_call_id : tool_call.id
+      end
+
+      def thinking_text(chunk)
+        thinking = chunk.thinking
+        text = thinking.respond_to?(:text) ? thinking.text : thinking
+        text.to_s.empty? ? nil : text.to_s
+      end
+
+      def emit(event)
+        io.write "data: #{JSON.generate(event)}\n\n"
+      end
+    end
+  end
+end

data/lib/ruby_llm/ai_sdk/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module AiSdk
+    # The version of the ruby_llm-ai_sdk gem, as a string.
+    VERSION = '0.1.0'
+  end
+end

data/lib/ruby_llm/ai_sdk.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'securerandom'
+require 'ruby_llm'
+require_relative 'ai_sdk/version'
+require_relative 'ai_sdk/request'
+require_relative 'ai_sdk/stream'
+
+module RubyLLM
+  # Streams RubyLLM chats in the AI SDK UI message stream protocol, so a
+  # front end built on the AI SDK's +useChat+ hook can talk to a Ruby
+  # backend: text, reasoning, tool calls, tool results, and approvals.
+  #
+  #   RubyLLM::AiSdk::Stream.new(chat, io).ask "What is the weather in Paris?"
+  #
+  module AiSdk
+    autoload :Controller, 'ruby_llm/ai_sdk/controller'
+
+    # The response headers the AI SDK expects on a UI message stream.
+    HEADERS = {
+      'content-type' => 'text/event-stream',
+      'cache-control' => 'no-cache',
+      'connection' => 'keep-alive',
+      'x-vercel-ai-ui-message-stream' => 'v1',
+      'x-accel-buffering' => 'no'
+    }.freeze
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: ruby_llm-ai_sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Bruno Costanzo
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.16'
+description: 'Emits the AI SDK UI message stream protocol from RubyLLM chats, so React
+  front ends built with useChat talk to a Ruby backend: text, reasoning, tool calls
+  and approvals.'
+email:
+- dev.bcostanzo@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ruby_llm/ai_sdk.rb
+- lib/ruby_llm/ai_sdk/controller.rb
+- lib/ruby_llm/ai_sdk/request.rb
+- lib/ruby_llm/ai_sdk/stream.rb
+- lib/ruby_llm/ai_sdk/version.rb
+homepage: https://github.com/bruno-costanzo/ruby_llm-ai_sdk
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/bruno-costanzo/ruby_llm-ai_sdk
+  source_code_uri: https://github.com/bruno-costanzo/ruby_llm-ai_sdk
+  changelog_uri: https://github.com/bruno-costanzo/ruby_llm-ai_sdk/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Stream RubyLLM chats to the AI SDK useChat hook.
+test_files: []