llm-agent-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9d1e3f9099b547fc6fa0e3373f0975cb6b3f8204d3684b9adac7d4c66610c265
+  data.tar.gz: a323962c8263652345699fd1ecdf7355e307328cbb196c2918206d0747a41fda
+SHA512:
+  metadata.gz: 6c623acb99a898b831280cb7fc02eaaa91382e752516e2763b6acf0ffad5c7dfc4dc5e7ac492798c13f21c830662ffb4cf6ab02350cf20ada2cfc237cdacdaad
+  data.tar.gz: 33acd6c6f4b1c1e717b24fe8fb768844679145991c6fcbde5f7543cd0f52c94f8963de99943591b1b4665647d5c2f35dcd3cd930f2227c83cca19fe83d9faf72

data/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) ...

data/README.md

@@ -0,0 +1,111 @@
+# llm-agent-rails
+
+Rails engine for **Llm-powered slot filling and tool orchestration**.  
+Mount an endpoint, register tools (JSON Schema + handler), and let an Llm collect missing fields and call your Ruby code safely.
+
+## Install
+
+Add to your Gemfile:
+```ruby
+gem "llm-agent-rails", github: "yourname/llm-agent-rails" # until published
+```
+
+Bundle:
+```bash
+bundle install
+```
+
+Run the installer:
+```bash
+rails g llm:agent:install
+```
+This will:
+- Create `config/initializers/llm_agent.rb`
+- Mount the engine at `/llm/agent`
+
+## Quick test (cURL)
+
+```bash
+curl -X POST http://localhost:3000/llm/agent/step   -H "Content-Type: application/json"   -d '{
+    "thread_id":"demo-thread",
+    "messages":[{"role":"user","content":"Open a ticket: Apple Pay checkout keeps failing on mobile."}]
+  }'
+```
+
+## Register a tool (example)
+
+Create `app/llm_tools/tickets.rb`:
+```ruby
+module LlmTools
+  CREATE_TICKET_V1 = {
+    type: "object", additionalProperties: false,
+    properties: {
+      title:       { type: "string" },
+      description: { type: "string" },
+      priority:    { type: "string", enum: %w[low medium high] },
+      assignee_id: { type: "string" }
+    },
+    required: %w[title description priority]
+  }
+
+  def self.register!(registry)
+    registry.register!(
+      name: "create_ticket", version: "v1",
+      schema: CREATE_TICKET_V1,
+      description: "Create a support ticket.",
+      handler: ->(args, ctx) {
+        key = Llm::Agent::Rails::Idempotency.generate(thread_id: ctx[:thread_id])
+        ticket = Ticket.create!(
+          org_id: ctx[:tenant_id],
+          user_id: ctx[:actor_id],
+          idempotency_key: key,
+          title: args["title"],
+          description: args["description"],
+          priority: args["priority"],
+          assignee_id: args["assignee_id"]
+        )
+        { id: ticket.id, title: ticket.title, priority: ticket.priority, key: key }
+      }
+    )
+  end
+end
+```
+
+Register it in `config/initializers/llm_agent.rb`:
+```ruby
+# After Llm::Agent::Rails.configure block
+require Rails.root.join("app/llm_tools/tickets")
+LlmTools.register!(Llm::Agent::Rails.config[:registry])
+```
+
+## How it works
+
+- **Registry**: Define tools (name/version/schema/description/handler).
+- **Validators**: JSON Schema validation (`json_schemer`) before calling handlers.
+- **Idempotency**: Generate a per-thread key to prevent duplicate creates.
+- **Orchestrator**: Coordinates conversation, asks for missing fields, executes tools.
+- **Adapter**: OpenAI adapter (supports `openai ~> 0.21`, `chat.completions.create`).
+- **Store**: Memory store for tool-result messages (swap for Redis in prod).
+
+## Routes
+
+The engine exposes:
+```
+POST /llm/agent/step
+```
+(If you change the mount point, this path changes accordingly.)
+
+## Config
+
+Edit `config/initializers/llm_agent.rb`:
+```ruby
+Llm::Agent::Rails.configure do |c|
+  c[:model]       = "gpt-4o-mini"
+  c[:temperature] = 0
+  c[:store]       = Llm::Agent::Rails::Store::Memory.new
+  c[:registry]    = Llm::Agent::Rails::Registry.new
+end
+```
+
+## License
+MIT

data/Rakefile

@@ -0,0 +1,2 @@
+# frozen_string_literal: true
+require "bundler/gem_tasks"

data/app/controllers/llm/agent/chat_controller.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+module Llm
+  module Agent
+    class ChatController < ActionController::Base
+      protect_from_forgery with: :null_session
+
+      def step
+        raw = params[:messages]
+        if raw.nil?
+          return render json: { error: "BadRequest", message: "messages is required (array of {role, content})" }, status: :bad_request
+        end
+
+        # Coerce into an array of message hashes Rails/OpenAI will accept.
+        messages =
+          Array.wrap(raw).map do |m|
+            # If the client sent a JSON string, parse it.
+            m = JSON.parse(m) rescue m
+
+            # If it's ActionController::Parameters, unfurl to a plain hash.
+            m = m.to_unsafe_h if m.respond_to?(:to_unsafe_h)
+            m = m.to_h        if m.respond_to?(:to_h) && !m.is_a?(Hash)
+
+            # Keep only role/content, as OpenAI expects
+            {
+              "role"    => m["role"] || m[:role],
+              "content" => m["content"] || m[:content]
+            }
+          end
+
+        thread_id = params[:thread_id] || "http-#{request.request_id}"
+        ctx = {
+          tenant_id: params[:tenant_id] || "demo-org",
+          actor_id:  params[:actor_id]  || "demo-user",
+          thread_id: thread_id
+        }
+
+        adapter = ::Llm::Agent::Rails::Adapters::OpenAIAdapter.new(
+          api_key: ENV.fetch("OPENAI_API_KEY"),
+          model:    ::Llm::Agent::Rails.config[:model],
+          temperature: ::Llm::Agent::Rails.config[:temperature]
+        )
+
+        orch = ::Llm::Agent::Rails::Orchestrator.new(
+          adapter:  adapter,
+          registry: ::Llm::Agent::Rails.config[:registry],
+          store:    ::Llm::Agent::Rails.config[:store]
+        )
+
+        outcome = orch.step(
+          thread_id: ctx[:thread_id],
+          tenant_id: ctx[:tenant_id],
+          actor_id:  ctx[:actor_id],
+          messages:  messages
+        )
+
+        render json: outcome
+      rescue ActionController::ParameterMissing => e
+        render json: { error: e.message }, status: :bad_request
+      rescue => e
+        render json: { error: e.class.name, message: e.message }, status: :internal_server_error
+      end
+
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+Llm::Agent::Rails::Engine.routes.draw do
+  post "step", to: "chat#step"
+end

data/lib/generators/llm/agent/install_generator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+require "rails/generators"
+
+module Llm
+  module Agent
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        template "llm_agent.rb", "config/initializers/llm_agent.rb"
+      end
+
+      def mount_routes
+        route %(mount Llm::Agent::Rails::Engine => "/llm/agent")
+      end
+    end
+  end
+end

data/lib/generators/llm/agent/templates/llm_agent.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+# Configure the Llm agent runtime.
+Llm::Agent::Rails.configure do |c|
+  c[:model]       = "gpt-4o-mini"
+  c[:temperature] = 0
+  c[:store]       = Llm::Agent::Rails::Store::Memory.new
+  c[:registry]    = Llm::Agent::Rails::Registry.new
+end
+
+# Example: register tools here or in separate files.
+# require Rails.root.join("app/llm_tools/tickets")
+# LlmTools.register!(Llm::Agent::Rails.config[:registry])

data/lib/llm/agent/rails/adapters/openai_adapter.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+module Llm
+  module Agent
+    module Rails
+      module Adapters
+        class OpenAIAdapter
+          def initialize(api_key:, model:, temperature: 0)
+            @client = ::OpenAI::Client.new(api_key: api_key)
+            @model = model
+            @temperature = temperature
+          end
+
+          def step(system_prompt:, messages:, tools:, tool_results: [])
+            response = @client.chat.completions.create(
+              model: @model,
+              temperature: @temperature,
+              messages: [{ role: "system", content: system_prompt }] + messages + tool_results,
+              tools: tools,
+              tool_choice: "auto"
+            )
+
+            choice = response.choices.first
+            msg    = choice.message
+
+            tool_calls    = msg.respond_to?(:tool_calls)    ? msg.tool_calls    : nil
+            function_call = msg.respond_to?(:function_call) ? msg.function_call : nil
+            content       = msg.respond_to?(:content)       ? msg.content       : nil
+
+            { tool_calls: tool_calls, function_call: function_call, content: content }
+          end
+
+          def tool_result_message(tool_call_id:, name:, content:)
+            { role: "tool", tool_call_id: tool_call_id, name: name, content: content.to_json }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llm/agent/rails/engine.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+module Llm
+  module Agent
+    module Rails
+      class Engine < ::Rails::Engine
+        isolate_namespace ::Llm::Agent
+      end
+    end
+  end
+end

data/lib/llm/agent/rails/idempotency.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+require "securerandom"
+module Llm
+  module Agent
+    module Rails
+      module Idempotency
+        def self.generate(thread_id:)
+          "chat-#{thread_id}-#{SecureRandom.hex(6)}"
+        end
+      end
+    end
+  end
+end

data/lib/llm/agent/rails/orchestrator.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+require "json"
+
+module Llm
+  module Agent
+    module Rails
+      class Orchestrator
+        POLICY = <<~SYS
+          You are a task-oriented assistant that turns chat into structured tool calls.
+
+          Rules:
+          - First, extract as many required fields as possible from the user's latest message and prior context.
+          - Only ask for fields that are truly missing or ambiguous (one concise question at a time).
+          - Derive a short, descriptive title if not supplied (e.g., "Apple Pay checkout failure on mobile").
+          - Prefer sensible defaults when the schema allows (e.g., priority=medium).
+          - When you have all required fields, call exactly one function.
+
+          Reply briefly and clearly.
+        SYS
+
+        def initialize(adapter:, registry:, store:)
+          @adapter, @registry, @store = adapter, registry, store
+        end
+
+        def step(thread_id:, tenant_id:, actor_id:, messages:)
+          prior_tool_msgs = @store.fetch_tool_messages(thread_id)
+
+          res = @adapter.step(
+            system_prompt: POLICY,
+            messages: messages,
+            tools: @registry.tools_for_llm,
+            tool_results: prior_tool_msgs
+          )
+
+          if (calls = res[:tool_calls]).is_a?(Array) && calls.any?
+            call = calls.first
+            fn   = call.respond_to?(:function) ? call.function : nil
+            name = fn&.respond_to?(:name) ? fn.name : nil
+            args_json = fn&.respond_to?(:arguments) ? fn.arguments.to_s : "{}"
+            args = args_json.empty? ? {} : JSON.parse(args_json)
+
+            tool_name, version = (name or "").split(/_v/i)
+            version ||= "v1"
+
+            tool = @registry.tool(tool_name, version: "v1")
+            Validators.validate!(tool.schema, args)
+
+            ctx = { tenant_id: tenant_id, actor_id: actor_id, thread_id: thread_id }
+            result = tool.handler.call(args, ctx)
+
+            tool_msg = @adapter.tool_result_message(
+              tool_call_id: call.respond_to?(:id) ? call.id : nil,
+              name: "#{tool_name}_v1",
+              content: result
+            )
+            @store.push_tool_message(thread_id, tool_msg)
+
+            return { type: :tool_ran, tool_name: tool_name, result: result }
+          end
+
+          if (fc = res[:function_call])
+            name_with_version = fc["name"]
+            args_json = fc["arguments"].to_s
+            args = args_json.empty? ? {} : JSON.parse(args_json)
+
+            tool_name, version = name_with_version.split(/_v/i)
+            version ||= "v1"
+
+            tool = @registry.tool(tool_name, version: "v1")
+            Validators.validate!(tool.schema, args)
+
+            ctx = { tenant_id: tenant_id, actor_id: actor_id, thread_id: thread_id }
+            result = tool.handler.call(args, ctx)
+
+            return { type: :tool_ran, tool_name: tool_name, result: result }
+          end
+
+          { type: :assistant, text: res[:content].to_s }
+        end
+      end
+    end
+  end
+end

data/lib/llm/agent/rails/registry.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+module Llm
+  module Agent
+    module Rails
+      Tool = Struct.new(:name, :version, :schema, :description, :handler, keyword_init: true)
+
+      class Registry
+        def initialize
+          @tools = {}
+        end
+
+        def register!(name:, version:, schema:, description:, handler:)
+          @tools[key_for(name, version)] = Tool.new(name:, version:, schema:, description:, handler:)
+        end
+
+        def tool(name, version: "v1")
+          @tools.fetch(key_for(name, version))
+        end
+
+        def tools_for_llm
+          @tools.values.map do |t|
+            {
+              type: "function",
+              function: {
+                name: "#{t.name}_#{t.version}",
+                description: t.description,
+                parameters: t.schema
+              }
+            }
+          end
+        end
+
+        private
+
+        def key_for(name, version) = "#{name}:#{version}"
+      end
+    end
+  end
+end

data/lib/llm/agent/rails/store/memory.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+module Llm
+  module Agent
+    module Rails
+      module Store
+        class Memory
+          def initialize
+            @tool_msgs_by_thread = Hash.new { |h,k| h[k] = [] }
+          end
+          def fetch_tool_messages(thread_id) = @tool_msgs_by_thread[thread_id]
+          def push_tool_message(thread_id, msg) = @tool_msgs_by_thread[thread_id] << msg
+        end
+      end
+    end
+  end
+end

data/lib/llm/agent/rails/validators.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+module Llm
+  module Agent
+    module Rails
+      class Validators
+        def self.validate!(schema, args)
+          schemer = JSONSchemer.schema(schema)
+          errors = schemer.validate(args).to_a
+          raise ArgumentError, "Schema validation failed: #{errors}" if errors.any?
+        end
+      end
+    end
+  end
+end

data/lib/llm/agent/rails/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+module Llm
+  module Agent
+    module Rails
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/llm/agent/rails.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+require "rails"
+require "json"
+require "json_schemer"
+require "openai"
+
+require_relative "rails/version"
+require_relative "rails/engine"
+
+require_relative "rails/registry"
+require_relative "rails/validators"
+require_relative "rails/idempotency"
+require_relative "rails/orchestrator"
+require_relative "rails/adapters/openai_adapter"
+require_relative "rails/store/memory"
+
+module Llm
+  module Agent
+    module Rails
+      class << self
+        def config
+          @config ||= {
+            model: "gpt-4o-mini",
+            temperature: 0,
+            store: Llm::Agent::Rails::Store::Memory.new,
+            registry: Llm::Agent::Rails::Registry.new
+          }
+        end
+
+        def configure
+          yield config
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: llm-agent-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Phia Vang
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-09-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: openai
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+description: Drop-in Rails engine to register JSON-schema tools, let an Llm fill missing
+  fields, validate input, and execute handlers safely.
+email:
+- pnvang@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- app/controllers/llm/agent/chat_controller.rb
+- config/routes.rb
+- lib/generators/llm/agent/install_generator.rb
+- lib/generators/llm/agent/templates/llm_agent.rb
+- lib/llm/agent/rails.rb
+- lib/llm/agent/rails/adapters/openai_adapter.rb
+- lib/llm/agent/rails/engine.rb
+- lib/llm/agent/rails/idempotency.rb
+- lib/llm/agent/rails/orchestrator.rb
+- lib/llm/agent/rails/registry.rb
+- lib/llm/agent/rails/store/memory.rb
+- lib/llm/agent/rails/validators.rb
+- lib/llm/agent/rails/version.rb
+homepage: https://github.com/pnvang/llm-agent-rails
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/yourname/llm-agent-rails
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Rails engine for Llm-powered slot filling and tool orchestration.
+test_files: []