omni_agent 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3a96ab390eb98871a6b9133599479381dda9ccfeee7b859c5a6641a5fe027c17
+  data.tar.gz: b4928a418a02e6178e338a00694f03d75b24f854ee85d49eb52f6125b683f0c0
+SHA512:
+  metadata.gz: cf525ecac3cf4a76815a007560d49c6049440d377aad441cca96aaac7df962e5dffd58672def02511a34d7a851c0ff2611b4ce0912b6b56abaaac032e811eabf
+  data.tar.gz: c1d64f9b290de984171aae25a1fdb2912a9ed8b395dec7ad1a9fa66af4a5d7743ac2aff4f7caab6108293cb050036aa8791e55491043846177cce43ea4e29a34

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-09
+
+### Added
+- Initial release of OmniAgent as a Rails engine for building application-native AI agents.
+- Agent runtime with provider abstraction, tool-calling loop, callbacks, and prompt rendering.
+- OpenAI provider support via the `openai` gem.
+- Tool DSL with JSON schema generation.
+- Rails generators and tasks for agent scaffolding.
+- RSpec coverage for agent runtime, providers, tools, and integration flows.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright ACR1209
+
+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,123 @@
+# OmniAgent
+
+OmniAgent is a Rails engine gem for building application-native AI agents with tools.
+It provides a small DSL to define agents, model/provider settings, prompt templates,
+tool schemas, and generation lifecycle callbacks.
+
+## What It Includes
+
+- `OmniAgent::Agent` runtime with provider abstraction and tool-calling loop
+- `OmniAgent::Tool` DSL with JSON-schema-style input definitions
+- Prompt composition from ERB files in `app/agents/<agent_name>/`
+- Agent callbacks (`before_generation`, `after_generation`)
+- Agent and tool tags to support filtering strategies
+- OpenAI provider integration out of the box
+- Rake tasks and Rails generators for scaffolding
+
+## Installation
+
+Add these lines to your application's Gemfile:
+
+```ruby
+gem "omni_agent"
+```
+
+Add the provider you're using to the Gemfile as well:
+```ruby
+gem "openai"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+1. Install base directories:
+
+```bash
+bundle exec rails generate omni_agent:install
+```
+
+2. Generate an agent scaffold:
+
+```bash
+bundle exec rails generate omni_agent:agent ResearchAgent --model gpt-4.1-mini --with-tools WeatherLookup Summarize
+```
+
+3. Add your API key in `.env`:
+
+```dotenv
+OPENAI_ACCESS_TOKEN=your_api_key_here
+```
+
+4. Implement your agent prompt and optional tools under:
+
+```text
+app/agents/research_agent/
+	research_agent.rb
+	prompt.md.erb
+	tools/
+```
+
+## Agent Example
+
+```ruby
+class ResearchAgent < OmniAgent::Agent
+	use_model "gpt-4o-mini"
+
+	before_generation :set_current_user
+
+	def set_current_user
+		@user = "Test User"
+	end
+end
+```
+
+## Tool Example
+
+```ruby
+module ResearchAgent::Tools
+	class GetWeather < OmniAgent::Tool
+		description "Get current weather for a city"
+		tags :weather
+		metadata category: :utility
+
+		input do
+			string :city, description: "City name"
+		end
+
+		def execute(city:)
+			"Sunny in #{city}"
+		end
+	end
+end
+```
+
+## Configuration
+
+Global defaults can be configured through `OmniAgent.configure`:
+
+```ruby
+OmniAgent.configure do |config|
+	config.default_provider = :openai
+	config.default_model = "gpt-4o-mini"
+end
+```
+
+## Running Tests
+
+```bash
+bundle exec rspec
+```
+
+## Contributing
+
+Issues and pull requests are welcome.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/setup"
+require "rspec/core/rake_task"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/app/assets/stylesheets/omni_agent/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/omni_agent/application_controller.rb

@@ -0,0 +1,4 @@
+module OmniAgent
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/helpers/omni_agent/application_helper.rb

@@ -0,0 +1,4 @@
+module OmniAgent
+  module ApplicationHelper
+  end
+end

data/app/jobs/omni_agent/application_job.rb

@@ -0,0 +1,4 @@
+module OmniAgent
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/omni_agent/application_mailer.rb

@@ -0,0 +1,6 @@
+module OmniAgent
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/omni_agent/application_record.rb

@@ -0,0 +1,5 @@
+module OmniAgent
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/views/layouts/omni_agent/application.html.erb

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Omni agent</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= yield :head %>
+
+  <%= stylesheet_link_tag    "omni_agent/application", media: "all" %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,2 @@
+OmniAgent::Engine.routes.draw do
+end

data/lib/generators/omni_agent/agent/agent_generator.rb

@@ -0,0 +1,103 @@
+require "rails/generators/named_base"
+require "fileutils"
+
+module OmniAgent
+  module Generators
+    class AgentGenerator < Rails::Generators::NamedBase
+      class_option :with_tools,
+                   type: :array,
+                   default: nil,
+                   banner: "[Tool1 Tool2 ...]",
+                   desc: "Create tools folder and scaffold tools. Optionally pass tool names"
+      class_option :model,
+                   type: :string,
+                   default: nil,
+                   desc: "Override the model used in use_model for the generated agent"
+
+      def create_agent_structure
+        FileUtils.mkdir_p(agent_directory)
+
+        create_file(agent_file_path, <<~RUBY)
+          class #{class_name} < OmniAgent::Agent
+            use_model #{generated_model_expression}
+          end
+        RUBY
+
+        create_file(prompt_file_path, <<~ERB)
+          You are #{class_name}, a helpful assistant with access to local tools.
+        ERB
+      end
+
+      def create_tools_if_requested
+        return unless with_tools_requested?
+
+        FileUtils.mkdir_p(tools_directory)
+
+        scaffold_names = requested_tool_names
+        scaffold_names.each do |tool_name|
+          create_file(tool_file_path(tool_name), tool_template(tool_name))
+        end
+      end
+
+      private
+
+      def agent_directory
+        File.join(destination_root, "app", "agents", file_name)
+      end
+
+      def agent_file_path
+        File.join(agent_directory, "#{file_name}.rb")
+      end
+
+      def prompt_file_path
+        File.join(agent_directory, "prompt.md.erb")
+      end
+
+      def tools_directory
+        File.join(agent_directory, "tools")
+      end
+
+      def tool_file_path(tool_name)
+        File.join(tools_directory, "#{tool_name.to_s.underscore}.rb")
+      end
+
+      def tool_template(tool_name)
+        tool_class = tool_name.to_s.camelize
+
+        <<~RUBY
+          module #{class_name}::Tools
+            class #{tool_class} < OmniAgent::Tool
+              description "#{tool_class} generated by omni_agent:agent"
+              tags :example
+              metadata category: :demo
+
+              input do
+                string :input_text, description: "Text input"
+              end
+
+              def execute(input_text:)
+                "Echo: \#{input_text}"
+              end
+            end
+          end
+        RUBY
+      end
+
+      def with_tools_requested?
+        !options[:with_tools].nil?
+      end
+
+      def requested_tool_names
+        names = Array(options[:with_tools]).map(&:to_s).map(&:strip).reject(&:empty?)
+        names.empty? ? ["ExampleTool"] : names
+      end
+
+      def generated_model_expression
+        model = options[:model].to_s.strip
+        return "OmniAgent.configuration.default_model" if model.empty?
+
+        model.inspect
+      end
+    end
+  end
+end

data/lib/generators/omni_agent/install/install_generator.rb

@@ -0,0 +1,21 @@
+require "rails/generators"
+require "fileutils"
+
+module OmniAgent
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc "Creates OmniAgent base directories in app/agents"
+
+      def create_agents_root
+        agents_root = File.join(destination_root, "app", "agents")
+        FileUtils.mkdir_p(agents_root)
+        say_status :create, agents_root
+      end
+
+      def show_next_steps
+        say "OmniAgent install complete."
+        say "Next: rails generate omni_agent:agent SupportAgent --with-tools Tool1 Tool2"
+      end
+    end
+  end
+end

data/lib/omni_agent/agent.rb

@@ -0,0 +1,328 @@
+module OmniAgent
+  class Agent
+    attr_reader :provider
+
+    module ImplicitRunEntrypoints
+      def method_added(method_name)
+        super
+
+        return if @_omni_agent_wrapping_method
+        return if method_name.to_s.start_with?("__omni_agent_original_")
+        return unless instance_methods(false).include?(method_name)
+        return if OmniAgent::Agent.instance_methods(false).include?(method_name)
+
+        original_method = instance_method(method_name)
+        return unless original_method.arity == 0
+
+        alias_name = "__omni_agent_original_#{method_name}".to_sym
+        return if instance_methods(false).include?(alias_name)
+
+        @_omni_agent_wrapping_method = true
+        alias_method alias_name, method_name
+
+        define_method(method_name) do |input = nil, context: {}, **context_keywords|
+          if input.nil? && context == {} && context_keywords.empty?
+            run_alias_entrypoint_logic(alias_name)
+          else
+            merged_context = context.is_a?(Hash) ? context.dup : {}
+            merged_context.merge!(context_keywords)
+
+            run_input = run_alias_entrypoint_logic(alias_name, fallback_input: input)
+
+            run(run_input, context: merged_context, prompt_method: method_name)
+          end
+        end
+      ensure
+        @_omni_agent_wrapping_method = false
+      end
+    end
+
+    class << self
+      def provider(name, **options)
+        if configured_with_use_model?
+          raise OmniAgent::Error, "Cannot combine `provider` and `use_model` in the same agent. Use either `provider ..., model: ...` or `use_model ...`."
+        end
+
+        @provider_name = name
+        @provider_options = options
+      end
+
+      def options(**options)
+        @model_options = configured_model_options.merge(options)
+      end
+
+      def use_model(name)
+        if configured_provider_name || configured_provider_options.any?
+          raise OmniAgent::Error, "Cannot combine `provider` and `use_model` in the same agent. Use either `provider ..., model: ...` or `use_model ...`."
+        end
+
+        @configured_with_use_model = true
+        @provider_options = { model: name }
+      end
+
+      def before_generation(*callbacks)
+        @before_generation_callbacks = configured_before_generation_callbacks + normalize_callbacks(:before_generation, callbacks)
+      end
+
+      def after_generation(*callbacks)
+        @after_generation_callbacks = configured_after_generation_callbacks + normalize_callbacks(:after_generation, callbacks)
+      end
+
+      def tags(*tag_names)
+        return @configured_tags || [] if tag_names.empty?
+
+        @configured_tags = (tags + normalize_tags(tag_names)).uniq
+      end
+
+      def run_aliases(*method_names)
+        aliases = normalize_callbacks(:run_aliases, method_names)
+
+        aliases.each do |method_name|
+          define_method(method_name) do |input, context: {}|
+            run(input, context: context, prompt_method: method_name)
+          end
+        end
+      end
+
+      def with(context = nil, provider_override: nil, model_override: nil, options_override: {}, **context_keywords)
+        merged_context = {}
+        merged_context.merge!(context) if context.is_a?(Hash)
+        merged_context.merge!(context_keywords)
+
+        new(
+          provider_override: provider_override,
+          model_override: model_override,
+          options_override: options_override,
+          context_override: merged_context
+        )
+      end
+
+      def configured_provider_name; @provider_name; end
+      def configured_provider_options; @provider_options || {}; end
+      def configured_model_options; @model_options || {}; end
+      def configured_with_use_model?; @configured_with_use_model == true; end
+      def configured_before_generation_callbacks; @before_generation_callbacks || []; end
+      def configured_after_generation_callbacks; @after_generation_callbacks || []; end
+      def configured_tags; tags; end
+
+      def inherited(subclass)
+        super
+        subclass.extend(ImplicitRunEntrypoints)
+      end
+
+      private
+
+      def normalize_callbacks(callback_type, callbacks)
+        raise ArgumentError, "#{callback_type} requires at least one method name" if callbacks.empty?
+
+        callbacks.map do |callback|
+          unless callback.is_a?(String) || callback.is_a?(Symbol)
+            raise ArgumentError, "#{callback_type} callbacks must be method names"
+          end
+
+          callback.to_sym
+        end
+      end
+
+      def normalize_tags(tag_names)
+        raise ArgumentError, "tags requires at least one tag" if tag_names.empty?
+
+        tag_names.map do |tag_name|
+          unless tag_name.is_a?(String) || tag_name.is_a?(Symbol)
+            raise ArgumentError, "tags must be strings or symbols"
+          end
+
+          tag_name.to_sym
+        end
+      end
+    end
+
+    def initialize(provider_override: nil, model_override: nil, options_override: {}, context_override: {})
+      target_provider_name = provider_override || self.class.configured_provider_name || OmniAgent.configuration.default_provider
+      target_model = model_override || self.class.configured_provider_options[:model]
+      @chat_options = self.class.configured_model_options.merge(options_override)
+      @provider = resolve_provider(target_provider_name, target_model)
+      @default_context = context_override || {}
+    end
+
+    def run(input, context: {}, prompt_method: nil)
+      context = @default_context.merge(context || {})
+
+      messages = [
+        { role: "system", content: nil },
+        { role: "user", content: input }
+      ]
+
+      run_before_generation_callbacks(input: input, context: context, messages: messages)
+      messages[0][:content] = system_prompt(context: context, prompt_method: prompt_method)
+
+      filtered_tools = tool_filter(tools: available_tools, agent_tags: self.class.tags)
+
+      loop do
+        response = provider.chat(messages: messages, tools: filtered_tools, **@chat_options)
+
+        if response.content && !response.tool_calls?
+          messages << { role: "assistant", content: response.content }
+          run_after_generation_callbacks(input: input, context: context, messages: messages, response: response)
+          return response.content
+        end
+
+        messages << {
+          role: "assistant",
+          content: response.content,
+          tool_calls: response.raw_response.dig("choices", 0, "message", "tool_calls")
+        }
+
+        response.tool_calls.each do |tool_call|
+          tool_name = tool_call[:name]
+          tool_args = tool_call[:arguments]
+          tool_id   = tool_call[:id]
+
+          tool_class = filtered_tools.find { |t| t.name.demodulize == tool_name }
+
+          if tool_class
+            begin
+              result = tool_class.invoke(tool_args)
+
+              messages << {
+                role: "tool",
+                tool_call_id: tool_id,
+                name: tool_name,
+                content: result.to_s
+              }
+            rescue => e
+              messages << {
+                role: "tool",
+                tool_call_id: tool_id,
+                name: tool_name,
+                content: "Error executing tool: #{e.message}"
+              }
+            end
+          else
+            messages << {
+              role: "tool",
+              tool_call_id: tool_id,
+              name: tool_name,
+              content: "Error: Tool #{tool_name} is not registered to this agent."
+            }
+          end
+        end
+      end
+    end
+
+    def available_tools
+      tool_namespace = "#{self.class.name}::Tools".safe_constantize
+      return [] unless tool_namespace
+
+      tool_namespace.constants.filter_map do |const_name|
+        const = tool_namespace.const_get(const_name)
+        const if const.is_a?(Class) && const < OmniAgent::Tool
+      end
+    end
+
+    private
+
+    def tool_filter(tools:, agent_tags:)
+      tools
+    end
+
+    def run_alias_entrypoint_logic(alias_name, fallback_input: nil)
+      @message = nil
+      result = public_send(alias_name)
+      computed_message = result.nil? ? @message : result
+
+      return computed_message if fallback_input.nil?
+
+      fallback_input
+    end
+
+    def resolve_provider(name, model)
+      OmniAgent::Providers.registry[name.to_sym].new(model: model)
+    end
+
+    def run_before_generation_callbacks(input:, context:, messages:)
+      payload = { input: input, context: context, messages: messages }
+
+      self.class.configured_before_generation_callbacks.each do |callback_name|
+        invoke_generation_callback(callback_name, payload)
+      end
+    end
+
+    def run_after_generation_callbacks(input:, context:, messages:, response:)
+      payload = { input: input, context: context, messages: messages, response: response }
+
+      self.class.configured_after_generation_callbacks.each do |callback_name|
+        invoke_generation_callback(callback_name, payload)
+      end
+    end
+
+    def invoke_generation_callback(callback_name, payload)
+      original_callback_name = "__omni_agent_original_#{callback_name}".to_sym
+      callback_target = if respond_to?(original_callback_name, true)
+        original_callback_name
+      else
+        callback_name
+      end
+
+      callback_method = self.class.instance_method(callback_target)
+
+      if callback_method.arity == 0
+        __send__(callback_target)
+      else
+        __send__(callback_target, payload)
+      end
+    end
+
+    def system_prompt(context:, prompt_method: nil)
+      return "You are a helpful assistant with access to local tools." unless defined?(Rails)
+
+      class_name = self.class.name
+      return "You are a helpful assistant with access to local tools." if class_name.nil?
+
+      agent_dir = inflector_underscore(class_name)
+      base_file_path = Rails.root.join("app", "agents", agent_dir, "prompt.md.erb")
+      method_file_path = if prompt_method
+        prompt_method_name = inflector_underscore(prompt_method.to_s)
+        Rails.root.join("app", "agents", agent_dir, "#{prompt_method_name}.md.erb")
+      end
+
+      isolated_scope = Object.new
+
+      context.each do |key, value|
+        isolated_scope.instance_variable_set("@#{key}", value)
+      end
+
+      internal_vars = [:@provider, :@chat_options] # Blacklists internal instance variables
+
+      (instance_variables - internal_vars).each do |ivar|
+        isolated_scope.instance_variable_set(ivar, instance_variable_get(ivar))
+      end
+
+      base_prompt = render_prompt_template(base_file_path, isolated_scope)
+      method_prompt = render_prompt_template(method_file_path, isolated_scope)
+
+      prompts = [base_prompt, method_prompt].compact.reject(&:empty?)
+      return prompts.join("\n\n") if prompts.any?
+
+      "You are a helpful assistant with access to local tools."
+    end
+
+    def render_prompt_template(file_path, isolated_scope)
+      return nil unless file_path && File.exist?(file_path)
+
+      ERB.new(File.read(file_path)).result(isolated_scope.instance_eval { binding })
+    end
+
+    def inflector_underscore(text)
+      return text.underscore if text.respond_to?(:underscore)
+
+      text
+        .to_s
+        .gsub("::", "/")
+        .gsub(/([A-Z]+)([A-Z][a-z])/, "\\1_\\2")
+        .gsub(/([a-z\d])([A-Z])/, "\\1_\\2")
+        .tr("-", "_")
+        .downcase
+    end
+  end
+end

data/lib/omni_agent/configuration.rb

@@ -0,0 +1,10 @@
+module OmniAgent
+  class Configuration
+    attr_accessor :default_provider, :default_model
+
+    def initialize
+      @default_provider = :openai
+      @default_model = "gpt-4o-mini"
+    end
+  end
+end

data/lib/omni_agent/engine.rb

@@ -0,0 +1,5 @@
+module OmniAgent
+  class Engine < ::Rails::Engine
+    isolate_namespace OmniAgent
+  end
+end

data/lib/omni_agent/errors.rb

@@ -0,0 +1,4 @@
+module OmniAgent
+  class Error < StandardError; end
+  class MissingDependencyError < Error; end
+end

data/lib/omni_agent/providers/base.rb

@@ -0,0 +1,27 @@
+# lib/omni_agents/providers/base.rb
+module OmniAgent
+  module Providers
+    class Base
+      attr_reader :model
+
+      def initialize(api_key: nil, model: nil)
+        @api_key = api_key || default_api_key
+        @model = model || default_model
+      end
+
+      def chat(messages:, tools: [], **_options)
+        raise NotImplementedError, "Providers must implement #chat"
+      end
+
+      protected
+
+      def default_api_key
+        raise NotImplementedError, "Providers must define a default API key lookup"
+      end
+
+      def default_model
+        raise NotImplementedError, "Providers must define a default model"
+      end
+    end
+  end
+end

data/lib/omni_agent/providers/openai.rb

@@ -0,0 +1,109 @@
+# lib/omni_agent/providers/openai.rb
+require 'json'
+
+module OmniAgent
+  module Providers
+    class OpenAI < Base
+      begin
+        require 'openai'
+      rescue LoadError
+        raise OmniAgent::MissingDependencyError, 
+              "The 'openai' gem is required to use the OpenAI provider. " \
+              "Please add `gem 'openai'` to your Gemfile."
+      end
+        
+      def chat(messages:, tools: [], **options)
+        openai_tools = tools.map { |tool| format_tool(tool) }
+
+        payload = {
+          model: model,
+          messages: messages
+        }
+        payload[:tools] = openai_tools if openai_tools.any?
+        payload.merge!(options) if options.any?
+
+        response = client.chat.completions.create(**payload)
+
+        parse_response(response)
+      rescue => e 
+        puts "Error during OpenAI chat: #{e.message}"
+      end
+
+      protected
+
+      def client
+        @client ||= ::OpenAI::Client.new(api_key: @api_key)
+      end
+
+      def default_api_key
+        ENV.fetch('OPENAI_ACCESS_TOKEN', nil)
+      end
+
+      def default_model
+        "gpt-4o-mini"
+      end
+
+      private
+
+      def format_tool(tool_class)
+        {
+          type: "function",
+          function: {
+            name: tool_class.name.split("::").last,
+            description: tool_class.description,
+            parameters: tool_class.json_schema 
+          }
+        }
+      end
+
+      def parse_response(raw_response)
+        choices = raw_response.respond_to?(:choices) ? raw_response.choices : raw_response["choices"]
+        first_choice = choices&.first || {}
+        
+        message = first_choice.respond_to?(:message) ? first_choice.message : (first_choice["message"] || {})
+        content = message.respond_to?(:content) ? message.content : message["content"]
+
+        raw_tool_calls = message.respond_to?(:tool_calls) ? message.tool_calls : message["tool_calls"]
+        raw_tool_calls ||= []
+
+        tool_calls = raw_tool_calls.map do |tc|
+          fn = tc.respond_to?(:function) ? tc.function : tc["function"]
+          {
+            id: tc.respond_to?(:id) ? tc.id : tc["id"],
+            name: fn.respond_to?(:name) ? fn.name : fn["name"],
+            arguments: JSON.parse((fn.respond_to?(:arguments) ? fn.arguments : fn["arguments"]) || "{}")
+          }
+        end
+
+        compat_tool_calls = raw_tool_calls.map do |tc|
+          fn = tc.respond_to?(:function) ? tc.function : tc["function"]
+          {
+            "id" => tc.respond_to?(:id) ? tc.id : tc["id"],
+            "type" => "function",
+            "function" => {
+              "name" => fn.respond_to?(:name) ? fn.name : fn["name"],
+              "arguments" => fn.respond_to?(:arguments) ? fn.arguments : fn["arguments"]
+            }
+          }
+        end.compact
+
+        compat_raw_response = {
+          "choices" => [
+            {
+              "message" => {
+                "content" => content,
+                "tool_calls" => (compat_tool_calls.empty? ? nil : compat_tool_calls)
+              }.compact
+            }
+          ]
+        }
+
+        OmniAgent::Providers::Response.new(
+          content: content,
+          raw_response: compat_raw_response,
+          tool_calls: tool_calls
+        )
+      end
+    end
+  end
+end

data/lib/omni_agent/providers/response.rb

@@ -0,0 +1,17 @@
+module OmniAgent
+  module Providers
+    class Response
+      attr_reader :content, :tool_calls, :raw_response
+
+      def initialize(content:, tool_calls: [], raw_response: nil)
+        @content = content
+        @tool_calls = tool_calls || []
+        @raw_response = raw_response
+      end
+
+      def tool_calls?
+        @tool_calls.any?
+      end
+    end
+  end
+end

data/lib/omni_agent/providers.rb

@@ -0,0 +1,10 @@
+
+module OmniAgent
+  module Providers
+    def self.registry
+      {
+        openai: OmniAgent::Providers::OpenAI 
+      }
+    end
+  end
+end

data/lib/omni_agent/tasks/omni_agent_tasks.rake

@@ -0,0 +1,78 @@
+require "fileutils"
+
+namespace :omni_agent do
+	desc "Set up OmniAgent directories in your Rails app"
+	task install: :environment do
+		agents_root = Rails.root.join("app", "agents")
+		FileUtils.mkdir_p(agents_root)
+
+		puts "Created #{agents_root}"
+		puts "OmniAgent install complete."
+		puts "Next: bundle exec rake \"omni_agent:create_agent[ResearchAgent]\""
+	end
+
+	desc "Create an agent scaffold. Usage: rake \"omni_agent:create_agent[ResearchAgent]\" [-- --with-tools]"
+	task :create_agent, [:name] => :environment do |_task, args|
+		agent_name = args[:name].to_s.strip
+
+		if agent_name.empty?
+			abort "Please provide an agent name. Example: bundle exec rake \"omni_agent:create_agent[ResearchAgent]\""
+		end
+
+		with_tools = ARGV.include?("--with-tools")
+
+		agent_file_name = "#{agent_name.underscore}.rb"
+		agent_dir_name = agent_name.underscore
+		agent_dir = Rails.root.join("app", "agents", agent_dir_name)
+		tools_dir = agent_dir.join("tools")
+		prompt_file = agent_dir.join("prompt.md.erb")
+		agent_rb = agent_dir.join(agent_file_name)
+
+		FileUtils.mkdir_p(agent_dir)
+
+		if File.exist?(agent_rb)
+			abort "Agent file already exists: #{agent_rb}"
+		end
+
+		File.write(agent_rb, <<~RUBY)
+			class #{agent_name} < OmniAgent::Agent
+			end
+		RUBY
+
+		unless File.exist?(prompt_file)
+			File.write(prompt_file, <<~PROMPT)
+				You are #{agent_name}, a helpful assistant with access to local tools.
+			PROMPT
+		end
+
+		if with_tools
+			FileUtils.mkdir_p(tools_dir)
+
+			example_tool = tools_dir.join("example_tool.rb")
+			unless File.exist?(example_tool)
+				File.write(example_tool, <<~RUBY)
+					module #{agent_name}::Tools
+						class ExampleTool < OmniAgent::Tool
+							description "Example tool generated by omni_agent:create_agent"
+							tags :example
+							metadata category: :demo
+
+							input do
+								string :input_text, description: "Text to echo back"
+							end
+
+							def execute(input_text:)
+								"Echo: \#{input_text}"
+							end
+						end
+					end
+				RUBY
+			end
+		end
+
+		puts "Created #{agent_rb}"
+		puts "Created #{prompt_file}" if File.exist?(prompt_file)
+		puts "Created #{tools_dir}" if with_tools
+		puts "Created #{tools_dir.join("example_tool.rb")}" if with_tools && File.exist?(tools_dir.join("example_tool.rb"))
+	end
+end

data/lib/omni_agent/tool/schema_builder.rb

@@ -0,0 +1,61 @@
+module OmniAgent
+  class Tool
+    class SchemaBuilder
+      attr_reader :properties, :required_fields
+
+      def initialize
+        @properties = {}
+        @required_fields = []
+      end
+
+      def string(name, description: nil, required: true)
+        add_property(name, type: "string", description: description, required: required)
+      end
+
+      def integer(name, description: nil, required: true)
+        add_property(name, type: "integer", description: description, required: required)
+      end
+
+      def boolean(name, description: nil, required: true)
+        add_property(name, type: "boolean", description: description, required: required)
+      end
+
+      def array(name, items_type:, description: nil, required: true)
+        property = { type: "array", items: { type: items_type } }
+        property[:description] = description if description
+        
+        @properties[name] = property
+        @required_fields << name.to_s if required
+      end
+
+      def hash(name, description: nil, required: true, &block)
+        property = { type: "object" }
+        property[:description] = description if description
+
+        if block_given?
+          nested_builder = SchemaBuilder.new
+          nested_builder.instance_eval(&block)
+          
+          property[:properties] = nested_builder.properties
+          property[:required] = nested_builder.required_fields
+          property[:additionalProperties] = false
+        else
+          property[:additionalProperties] = true
+        end
+
+        @properties[name] = property
+        @required_fields << name.to_s if required
+      end
+
+      private
+
+      def add_property(name, type:, description:, required:)
+        property = { type: type }
+        property[:description] = description if description
+        
+        @properties[name] = property
+        @required_fields << name.to_s if required
+      end
+    end
+  end
+end

data/lib/omni_agent/tool.rb

@@ -0,0 +1,68 @@
+# lib/omni_agents/tool.rb
+module OmniAgent
+  class Tool
+    class << self
+      def description(text = nil)
+        @description = text if text
+        @description || "No description provided."
+      end
+
+      def metadata(options = nil)
+        @metadata = options if options
+        @metadata || {}
+      end
+
+      def tags(*tag_names)
+        return @tags || [] if tag_names.empty?
+
+        @tags = (tags + normalize_tags(tag_names)).uniq
+      end
+
+      def configured_tags
+        tags
+      end
+
+      def input(&block)
+        if block_given?
+          builder = SchemaBuilder.new
+          builder.instance_eval(&block)
+          
+          @properties = builder.properties
+          @required = builder.required_fields
+        end
+      end
+
+      def json_schema
+        {
+          type: "object",
+          properties: @properties || {},
+          required: @required || [],
+          additionalProperties: false 
+        }
+      end
+
+      def invoke(arguments_hash)
+        kwargs = arguments_hash.transform_keys(&:to_sym)
+        new.execute(**kwargs)
+      end
+
+      private
+
+      def normalize_tags(tag_names)
+        raise ArgumentError, "tags requires at least one tag" if tag_names.empty?
+
+        tag_names.map do |tag_name|
+          unless tag_name.is_a?(String) || tag_name.is_a?(Symbol)
+            raise ArgumentError, "tags must be strings or symbols"
+          end
+
+          tag_name.to_sym
+        end
+      end
+    end
+
+    def execute(**args)
+      raise NotImplementedError, "#{self.class.name} must implement #execute"
+    end
+  end
+end

data/lib/omni_agent/version.rb

@@ -0,0 +1,3 @@
+module OmniAgent
+  VERSION = "0.1.0"
+end

data/lib/omni_agent.rb

@@ -0,0 +1,21 @@
+require "omni_agent/version"
+require "omni_agent/engine" if defined?(Rails)
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect("openai" => "OpenAI")
+loader.ignore(File.expand_path("generators", __dir__))
+loader.setup
+
+
+module OmniAgent
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: omni_agent
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ACR1209
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.3
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: OmniAgent provides a Rails-native framework for defining AI agents, tool
+  schemas, prompt templates, callbacks, and provider-backed generation workflows.
+email:
+- andrescoronel1209@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/stylesheets/omni_agent/application.css
+- app/controllers/omni_agent/application_controller.rb
+- app/helpers/omni_agent/application_helper.rb
+- app/jobs/omni_agent/application_job.rb
+- app/mailers/omni_agent/application_mailer.rb
+- app/models/omni_agent/application_record.rb
+- app/views/layouts/omni_agent/application.html.erb
+- config/routes.rb
+- lib/generators/omni_agent/agent/agent_generator.rb
+- lib/generators/omni_agent/install/install_generator.rb
+- lib/omni_agent.rb
+- lib/omni_agent/agent.rb
+- lib/omni_agent/configuration.rb
+- lib/omni_agent/engine.rb
+- lib/omni_agent/errors.rb
+- lib/omni_agent/providers.rb
+- lib/omni_agent/providers/base.rb
+- lib/omni_agent/providers/openai.rb
+- lib/omni_agent/providers/response.rb
+- lib/omni_agent/tasks/omni_agent_tasks.rake
+- lib/omni_agent/tool.rb
+- lib/omni_agent/tool/schema_builder.rb
+- lib/omni_agent/version.rb
+homepage: https://github.com/ACR1209/omni_agent
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ACR1209/omni_agent
+  source_code_uri: https://github.com/ACR1209/omni_agent
+  changelog_uri: https://github.com/ACR1209/omni_agent/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Rails engine for building AI agents with tools.
+test_files: []