solid_agent 0.0.0 → 0.1.1

data/lib/solid_agent/has_tools.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+# HasTools provides a DSL for defining and loading tool schemas in ActiveAgent agents.
+#
+# This concern enables declarative tool registration with automatic schema loading
+# from JSON view templates or inline definitions.
+#
+# @example Auto-discover tools from views
+#   class MyAgent < ApplicationAgent
+#     include SolidAgent::HasTools
+#     has_tools  # Discovers all tools from app/views/my_agent/tools/*.json.erb
+#   end
+#
+# @example Explicit tool list
+#   class MyAgent < ApplicationAgent
+#     include SolidAgent::HasTools
+#     has_tools :search, :fetch, :analyze
+#   end
+#
+# @example Inline tool definition
+#   class MyAgent < ApplicationAgent
+#     include SolidAgent::HasTools
+#     tool :get_weather do
+#       description "Get current weather for a location"
+#       parameter :location, type: :string, required: true, description: "City name"
+#       parameter :units, type: :string, enum: %w[celsius fahrenheit], default: "celsius"
+#     end
+#   end
+#
+# @example Mixed approach
+#   class MyAgent < ApplicationAgent
+#     include SolidAgent::HasTools
+#     has_tools :navigate, :click  # Load from templates
+#     tool :custom_action do       # Define inline
+#       description "A custom action"
+#       parameter :input, type: :string, required: true
+#     end
+#   end
+module SolidAgent
+  module HasTools
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_tool_names, default: []
+      class_attribute :_inline_tools, default: {}
+      class_attribute :_tools_auto_discover, default: false
+    end
+
+    class_methods do
+      # Declares which tools this agent uses.
+      #
+      # Without arguments, enables auto-discovery of tools from view templates.
+      # With arguments, explicitly lists tools to load from templates.
+      #
+      # @param tool_names [Array<Symbol, String>] explicit list of tools to load
+      # @return [void]
+      #
+      # @example Auto-discover
+      #   has_tools
+      #
+      # @example Explicit list
+      #   has_tools :navigate, :click, :fill_form
+      def has_tools(*tool_names)
+        if tool_names.empty?
+          self._tools_auto_discover = true
+        else
+          self._tool_names = tool_names.map(&:to_sym)
+        end
+      end
+
+      # Defines a tool inline using a DSL block.
+      #
+      # The tool name should match a method in the agent class that will be
+      # called when the LLM invokes this tool.
+      #
+      # @param name [Symbol, String] tool name (must match an instance method)
+      # @yield block for defining tool schema using ToolBuilder DSL
+      # @return [void]
+      #
+      # @example
+      #   tool :search do
+      #     description "Search for documents"
+      #     parameter :query, type: :string, required: true
+      #     parameter :limit, type: :integer, default: 10
+      #   end
+      def tool(name, &block)
+        builder = ToolBuilder.new(name)
+        builder.instance_eval(&block) if block_given?
+        self._inline_tools = _inline_tools.merge(name.to_sym => builder.to_schema)
+      end
+    end
+
+    # Returns all tool schemas for this agent.
+    #
+    # Combines tools from:
+    # 1. Auto-discovered JSON templates (if has_tools called without args)
+    # 2. Explicitly listed tools (if has_tools called with args)
+    # 3. Inline tool definitions (from tool blocks)
+    #
+    # @return [Array<Hash>] array of tool schemas in OpenAI format
+    def tools
+      @_tools_cache ||= begin
+        schemas = []
+
+        # Load from templates
+        if _tools_auto_discover
+          schemas.concat(discover_tool_templates)
+        elsif _tool_names.any?
+          schemas.concat(_tool_names.map { |name| load_tool_schema(name) })
+        end
+
+        # Add inline tools
+        schemas.concat(_inline_tools.values)
+
+        schemas
+      end
+    end
+
+    # Reloads tools, clearing any cached schemas.
+    #
+    # Useful when tool templates may have changed during development.
+    #
+    # @return [Array<Hash>] freshly loaded tool schemas
+    def reload_tools!
+      @_tools_cache = nil
+      tools
+    end
+
+    private
+
+    # Discovers tool templates from the agent's views directory.
+    #
+    # Looks for JSON templates in:
+    # - app/views/{agent_name}/tools/*.json.erb
+    # - app/views/agents/{agent_without_suffix}/tools/*.json.erb
+    #
+    # @return [Array<Hash>] discovered tool schemas
+    def discover_tool_templates
+      tool_schemas = []
+      tools_path = Rails.root.join("app", "views", agent_name, "tools")
+
+      if tools_path.exist?
+        tools_path.glob("*.json.erb").each do |template_path|
+          tool_name = template_path.basename(".json.erb").to_s
+          tool_schemas << load_tool_schema(tool_name)
+        end
+      end
+
+      # Also check nested structure: app/views/agents/{name}/tools/
+      nested_path = Rails.root.join("app", "views", "agents", agent_name.delete_suffix("_agent"), "tools")
+      if nested_path.exist?
+        nested_path.glob("*.json.erb").each do |template_path|
+          tool_name = template_path.basename(".json.erb").to_s
+          # Avoid duplicates
+          next if tool_schemas.any? { |t| t[:name] == tool_name }
+          tool_schemas << load_tool_schema(tool_name)
+        end
+      end
+
+      tool_schemas
+    end
+
+    # Loads a single tool schema from its JSON view template.
+    #
+    # @param tool_name [Symbol, String] name of the tool
+    # @return [Hash] tool schema with symbolized keys
+    # @raise [ActionView::MissingTemplate] if template not found
+    # @raise [JSON::ParserError] if template produces invalid JSON
+    def load_tool_schema(tool_name)
+      template_path = "tools/#{tool_name}"
+
+      json_content = render_to_string(
+        template: "#{agent_name}/#{template_path}",
+        formats: [:json],
+        layout: false
+      )
+
+      JSON.parse(json_content, symbolize_names: true)
+    rescue JSON::ParserError => e
+      Rails.logger.error "[#{self.class.name}] Invalid JSON in tool template: #{template_path}"
+      raise e
+    end
+
+    # DSL builder for inline tool definitions.
+    #
+    # Provides a clean API for defining tool schemas programmatically:
+    #
+    #   tool :my_tool do
+    #     description "Does something useful"
+    #     parameter :input, type: :string, required: true
+    #   end
+    class ToolBuilder
+      def initialize(name)
+        @name = name.to_s
+        @description = ""
+        @parameters = {}
+        @required = []
+      end
+
+      # Sets the tool description.
+      #
+      # @param text [String] human-readable description of what the tool does
+      # @return [void]
+      def description(text)
+        @description = text
+      end
+
+      # Defines a parameter for the tool.
+      #
+      # @param name [Symbol, String] parameter name
+      # @param type [Symbol, String] JSON Schema type (:string, :integer, :boolean, :array, :object)
+      # @param required [Boolean] whether this parameter is required (default: false)
+      # @param description [String] parameter description
+      # @param enum [Array] allowed values (for string type)
+      # @param items [Hash] item schema (for array type)
+      # @param properties [Hash] nested properties (for object type)
+      # @param default [Object] default value
+      # @return [void]
+      #
+      # @example Simple string parameter
+      #   parameter :query, type: :string, required: true
+      #
+      # @example Enum parameter
+      #   parameter :format, type: :string, enum: %w[json xml csv]
+      #
+      # @example Array parameter
+      #   parameter :tags, type: :array, items: { type: :string }
+      def parameter(name, type:, required: false, description: nil, enum: nil, items: nil, properties: nil, default: nil)
+        param_schema = { type: type.to_s }
+        param_schema[:description] = description if description
+        param_schema[:enum] = enum if enum
+        param_schema[:items] = items if items
+        param_schema[:properties] = properties if properties
+        param_schema[:default] = default if default
+
+        @parameters[name.to_s] = param_schema
+        @required << name.to_s if required
+      end
+
+      # Converts the builder state to an OpenAI-compatible tool schema.
+      #
+      # @return [Hash] tool schema
+      def to_schema
+        {
+          type: "function",
+          name: @name,
+          description: @description,
+          parameters: {
+            type: "object",
+            properties: @parameters,
+            required: @required
+          }.compact
+        }
+      end
+    end
+  end
+end

data/lib/solid_agent/streams_tool_updates.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+# StreamsToolUpdates provides real-time UI feedback during tool execution.
+#
+# When an agent is processing and calls tools (which may take time), this concern
+# broadcasts status updates to the client so users see what's happening rather than
+# a frozen UI. This is especially important for long-running tools like web browsing.
+#
+# @example Basic usage
+#   class MyAgent < ApplicationAgent
+#     include SolidAgent::HasTools
+#     include SolidAgent::StreamsToolUpdates
+#
+#     has_tools :search, :navigate
+#
+#     def research
+#       prompt(tools: tools)
+#     end
+#   end
+#
+# @example With custom descriptions
+#   class MyAgent < ApplicationAgent
+#     include SolidAgent::HasTools
+#     include SolidAgent::StreamsToolUpdates
+#
+#     tool_description :navigate, ->(args) { "Visiting #{args[:url]}..." }
+#     tool_description :search, ->(args) { "Searching for '#{args[:query]}'..." }
+#     tool_description :extract_text, "Reading page content..."
+#   end
+module SolidAgent
+  module StreamsToolUpdates
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_tool_descriptions, default: {}
+      class_attribute :_wrapped_tools, default: Set.new
+    end
+
+    class_methods do
+      # Defines a human-readable description for a tool that will be shown in the UI.
+      #
+      # @param tool_name [Symbol, String] the tool method name
+      # @param description [String, Proc] static string or proc that receives args
+      #
+      # @example Static description
+      #   tool_description :extract_text, "Reading page content..."
+      #
+      # @example Dynamic description with args
+      #   tool_description :navigate, ->(args) { "Visiting #{args[:url]}..." }
+      def tool_description(tool_name, description)
+        self._tool_descriptions = _tool_descriptions.merge(tool_name.to_sym => description)
+        wrap_tool_method(tool_name)
+      end
+
+      # Wraps a tool method to broadcast status before execution
+      #
+      # @param tool_name [Symbol, String] the tool method name
+      def wrap_tool_method(tool_name)
+        tool_sym = tool_name.to_sym
+        return if _wrapped_tools.include?(tool_sym)
+
+        self._wrapped_tools = _wrapped_tools.dup.add(tool_sym)
+
+        # Use prepend to wrap the method
+        wrapper_module = Module.new do
+          define_method(tool_sym) do |**kwargs|
+            broadcast_tool_status(tool_sym, kwargs) if should_broadcast_tools?
+            super(**kwargs)
+          end
+        end
+
+        prepend wrapper_module
+      end
+    end
+
+    private
+
+    def should_broadcast_tools?
+      params[:stream_id].present?
+    end
+
+    # Broadcasts a tool status update to the client
+    #
+    # @param tool_name [String, Symbol] the tool being executed
+    # @param args [Hash] the arguments passed to the tool
+    def broadcast_tool_status(tool_name, args = {})
+      return unless params[:stream_id]
+
+      description = tool_description_for(tool_name, args)
+
+      Rails.logger.info "[#{self.class.name}] Tool status: #{description}"
+
+      ActionCable.server.broadcast(
+        params[:stream_id],
+        {
+          tool_status: {
+            name: tool_name.to_s,
+            description: description,
+            timestamp: Time.current.iso8601
+          }
+        }
+      )
+    end
+
+    # Gets the human-readable description for a tool
+    #
+    # @param tool_name [String, Symbol] the tool name
+    # @param args [Hash] the arguments passed to the tool
+    # @return [String] description to show in UI
+    def tool_description_for(tool_name, args = {})
+      custom = _tool_descriptions[tool_name.to_sym]
+
+      if custom.is_a?(Proc)
+        custom.call(args)
+      elsif custom.is_a?(String)
+        custom
+      else
+        default_tool_description(tool_name, args)
+      end
+    end
+
+    # Generates a default description for common tool types
+    #
+    # @param tool_name [String, Symbol] the tool name
+    # @param args [Hash] the arguments passed to the tool
+    # @return [String] default description
+    def default_tool_description(tool_name, args = {})
+      case tool_name.to_s
+      when "navigate"
+        args[:url] ? "Visiting #{truncate_url(args[:url])}..." : "Navigating to page..."
+      when "click"
+        args[:text] ? "Clicking '#{args[:text]}'..." : "Clicking element..."
+      when "fill_form"
+        args[:field] ? "Filling in #{args[:field]}..." : "Filling form..."
+      when "extract_text", "extract_main_content"
+        "Reading page content..."
+      when "extract_links"
+        "Extracting links..."
+      when "page_info"
+        "Getting page info..."
+      when "go_back"
+        "Going back..."
+      when "search", "web_search"
+        args[:query] ? "Searching for '#{args[:query]}'..." : "Searching..."
+      when "read", "read_file"
+        args[:path] ? "Reading #{File.basename(args[:path])}..." : "Reading file..."
+      when "write", "write_file"
+        args[:path] ? "Writing #{File.basename(args[:path])}..." : "Writing file..."
+      else
+        "Performing #{tool_name.to_s.tr('_', ' ')}..."
+      end
+    end
+
+    # Truncates a URL for display
+    #
+    # @param url [String] the URL to truncate
+    # @param max_length [Integer] maximum length
+    # @return [String] truncated URL
+    def truncate_url(url, max_length: 50)
+      return url if url.length <= max_length
+
+      uri = URI.parse(url)
+      host = uri.host || url[0..max_length]
+      path = uri.path || ""
+
+      if host.length > max_length
+        "#{host[0..max_length]}..."
+      elsif (host.length + path.length) > max_length
+        remaining = max_length - host.length - 3
+        "#{host}#{path[0..remaining]}..."
+      else
+        "#{host}#{path}"
+      end
+    rescue URI::InvalidURIError
+      url.length > max_length ? "#{url[0..max_length]}..." : url
+    end
+  end
+end

data/lib/solid_agent/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SolidAgent
+  VERSION = "0.1.1"
+end

data/lib/solid_agent.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "solid_agent/version"
+require_relative "solid_agent/has_context"
+require_relative "solid_agent/has_tools"
+require_relative "solid_agent/streams_tool_updates"
+
+module SolidAgent
+  class Error < StandardError; end
+
+  class << self
+    attr_accessor :context_class, :message_class, :generation_class
+
+    def configure
+      yield self if block_given?
+    end
+  end
+
+  # Default configuration
+  self.context_class = "AgentContext"
+  self.message_class = "AgentMessage"
+  self.generation_class = "AgentGeneration"
+end
+
+# Load Rails integration if Rails is present
+if defined?(Rails::Engine)
+  require_relative "solid_agent/engine"
+end

data/sig/solid_agent.rbs

@@ -0,0 +1,4 @@
+module SolidAgent
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -1,27 +1,102 @@
 --- !ruby/object:Gem::Specification
 name: solid_agent
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Justin Bowen
-autorequire:
-bindir: bin
+bindir: exe
 cert_chain: []
-date: 2024-05-29 00:00:00.000000000 Z
-dependencies: []
-description: A simple way to make Ruby AI Agents
-email: jusbowen@gmail.com
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activeagent
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  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: activerecord
+  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'
+description: SolidAgent extends ActiveAgent with database-backed prompt context management,
+  declarative tool schemas, and real-time streaming updates. Provides has_context,
+  has_tools, and streams_tool_updates concerns for building robust AI agents.
+email:
+- JusBowen@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
+- Rakefile
+- lib/generators/solid_agent/agent/agent_generator.rb
+- lib/generators/solid_agent/agent/templates/action.text.erb
+- lib/generators/solid_agent/agent/templates/agent.rb.erb
+- lib/generators/solid_agent/context/context_generator.rb
+- lib/generators/solid_agent/context/templates/context_model.rb.erb
+- lib/generators/solid_agent/context/templates/create_context.rb.erb
+- lib/generators/solid_agent/context/templates/create_generations.rb.erb
+- lib/generators/solid_agent/context/templates/create_messages.rb.erb
+- lib/generators/solid_agent/context/templates/generation_model.rb.erb
+- lib/generators/solid_agent/context/templates/message_model.rb.erb
+- lib/generators/solid_agent/install/install_generator.rb
+- lib/generators/solid_agent/install/templates/agent_context.rb.erb
+- lib/generators/solid_agent/install/templates/agent_generation.rb.erb
+- lib/generators/solid_agent/install/templates/agent_message.rb.erb
+- lib/generators/solid_agent/install/templates/create_agent_contexts.rb.erb
+- lib/generators/solid_agent/install/templates/create_agent_generations.rb.erb
+- lib/generators/solid_agent/install/templates/create_agent_messages.rb.erb
+- lib/generators/solid_agent/install/templates/initializer.rb.erb
+- lib/generators/solid_agent/tool/templates/tool.json.erb
+- lib/generators/solid_agent/tool/tool_generator.rb
 - lib/solid_agent.rb
-homepage: https://rubygems.org/gems/solid_eagent
+- lib/solid_agent/engine.rb
+- lib/solid_agent/has_context.rb
+- lib/solid_agent/has_tools.rb
+- lib/solid_agent/streams_tool_updates.rb
+- lib/solid_agent/version.rb
+- sig/solid_agent.rbs
+homepage: https://docs.activeagents.ai/solid_agent
 licenses:
 - MIT
-metadata: {}
-post_install_message:
+metadata:
+  homepage_uri: https://docs.activeagents.ai/solid_agent
+  source_code_uri: https://github.com/activeagents/solid_agent
+  changelog_uri: https://github.com/activeagents/solid_agent/blob/main/CHANGELOG.md
+  documentation_uri: https://docs.activeagents.ai/solid_agent
 rdoc_options: []
 require_paths:
 - lib
@@ -29,15 +104,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
-signing_key:
+rubygems_version: 3.7.2
 specification_version: 4
-summary: A simple way to make Ruby AI Agents
+summary: Database-backed context, tools, and streaming for ActiveAgent
 test_files: []