solid_agent 0.0.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2538e4679d79c86ca07874c50eeff13dfa542019af76c9b9b247e68a6527281b
-  data.tar.gz: b883e74f4e2c870b451bc8fc206c21c3639681abb99877b09a702d717385742c
+  metadata.gz: 52f173d6c45fc416105fb4a93760dc7aacc81061b75bada9820fce835e9652dd
+  data.tar.gz: '07348df42b87220dea84691d61a11cac6e6576cebbcbe2272c702a0bed6f539c'
 SHA512:
-  metadata.gz: 41868b5e2dcbdd9b7ee9a50d0479e02cab65cab421097bf7608725eb430bc15b2d86c63434d12aa29d3dc85c447e2f9230e0bb50ecee788e9b7c0bf82a5db06f
-  data.tar.gz: '09b3bebf383a8a01617ad1b160bc4ca3362299b6f9e6c5e760790b5f669c4b4ac78cafce0bad4d1214914dc4e89d5ada45817c9c3a58c727c432a07ce7fde428'
+  metadata.gz: ffd6386b0d71a95df1ac198c9590bbf337bf7e1a37ccc19e17eb57afbbcf544260fe7e2e552ba8470d4091d636a5b7b074aa5e7745d9d17021af839704b81f46
+  data.tar.gz: bcb89c355432829006b38157c727c271b4b63c86aa09a67d14611b16896f515406dfbf5d84f45c1b2b53a9e4adae6d4cfa250397271f3bb0f8e029f15417d5b4

data/README.md

@@ -0,0 +1,130 @@
+# SolidAgent
+
+SolidAgent extends the [ActiveAgent](https://github.com/activeagents/activeagent) framework with enterprise-grade features for building robust AI agents in Rails applications. It provides three core concerns that add database-backed persistence, declarative tool schemas, and real-time streaming capabilities to your agents.
+
+## Features
+
+- **HasContext** - Database-backed prompt context management for maintaining conversation history and agent state
+- **HasTools** - Declarative, schema-based tool definitions compatible with LLM function-calling APIs
+- **StreamsToolUpdates** - Real-time UI feedback during tool execution via ActionCable
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "solid_agent"
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install solid_agent
+```
+
+## Usage
+
+### Quick Start
+
+Generate a new agent with context support:
+
+```bash
+$ rails generate solid_agent:agent WritingAssistant --context --context_name conversation --contextable user
+```
+
+### HasContext - Persistent Conversation History
+
+Add database-backed context management to your agents:
+
+```ruby
+class WritingAssistantAgent < ApplicationAgent
+  include SolidAgent::HasContext
+
+  has_context :conversation, contextable: :user
+
+  def improve
+    load_conversation(contextable: current_user)
+    add_conversation_user_message(params[:message])
+    prompt messages: conversation_messages
+  end
+end
+```
+
+This generates helper methods like:
+- `load_conversation(contextable:)` - Load or create a context
+- `conversation_messages` - Get formatted message history
+- `add_conversation_user_message(content)` - Add a user message
+- `add_conversation_assistant_message(content)` - Add an AI response
+- `conversation_result` - Get the last assistant message
+
+### HasTools - Declarative Tool Schemas
+
+Define tools inline with a clean DSL:
+
+```ruby
+class ResearchAgent < ApplicationAgent
+  include SolidAgent::HasTools
+
+  tool :search do
+    description "Search for information"
+    parameter :query, type: :string, required: true
+    parameter :limit, type: :integer, default: 10
+  end
+
+  def research
+    prompt tools: tools
+  end
+
+  def search(query:, limit: 10)
+    # Tool implementation
+  end
+end
+```
+
+Or use JSON templates in `app/views/research_agent/tools/search.json.erb`.
+
+### StreamsToolUpdates - Real-Time Feedback
+
+Broadcast tool execution status to your UI:
+
+```ruby
+class BrowserAgent < ApplicationAgent
+  include SolidAgent::HasTools
+  include SolidAgent::StreamsToolUpdates
+
+  has_tools :navigate, :click
+  tool_description :navigate, ->(args) { "Visiting #{args[:url]}..." }
+end
+```
+
+### Generators
+
+```bash
+# Generate a new agent
+$ rails generate solid_agent:agent MyAgent
+
+# Generate with context support
+$ rails generate solid_agent:agent MyAgent --context --context_name session
+
+# Generate a tool template
+$ rails generate solid_agent:tool search MyAgent --parameters query:string:required
+
+# Generate context models
+$ rails generate solid_agent:context conversation
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/solid_agent.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module SolidAgent
+  module Generators
+    class AgentGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generates a new ActiveAgent agent with SolidAgent concerns"
+
+      class_option :context, type: :boolean, default: true,
+        desc: "Include HasContext concern"
+
+      class_option :context_name, type: :string, default: nil,
+        desc: "Custom context name (e.g., 'conversation', 'research_session')"
+
+      class_option :contextable, type: :string, default: nil,
+        desc: "Param key for auto-context (e.g., 'user', 'document')"
+
+      class_option :tools, type: :boolean, default: false,
+        desc: "Include HasTools concern"
+
+      class_option :streaming, type: :boolean, default: false,
+        desc: "Include StreamsToolUpdates concern"
+
+      class_option :actions, type: :array, default: ["perform"],
+        desc: "Agent actions to generate"
+
+      class_option :parent, type: :string, default: "ApplicationAgent",
+        desc: "Parent class for the agent"
+
+      def create_agent_file
+        @parent_class = options[:parent]
+        @include_context = options[:context]
+        @context_name = options[:context_name]
+        @contextable = options[:contextable]
+        @include_tools = options[:tools]
+        @include_streaming = options[:streaming]
+        @actions = options[:actions]
+
+        template "agent.rb.erb", "app/agents/#{file_name}_agent.rb"
+      end
+
+      def create_view_directory
+        empty_directory "app/views/#{file_name}_agent"
+
+        @actions.each do |action|
+          template "action.text.erb", "app/views/#{file_name}_agent/#{action}.text.erb",
+            action_name: action
+        end
+      end
+
+      def create_tools_directory
+        return unless @include_tools
+
+        empty_directory "app/views/#{file_name}_agent/tools"
+      end
+
+      def show_next_steps
+        say ""
+        say "Agent created successfully!", :green
+        say ""
+        say "Files generated:"
+        say "  app/agents/#{file_name}_agent.rb"
+        say "  app/views/#{file_name}_agent/"
+        @actions.each do |action|
+          say "  app/views/#{file_name}_agent/#{action}.text.erb"
+        end
+        say "  app/views/#{file_name}_agent/tools/" if @include_tools
+        say ""
+
+        if @include_tools
+          say "To add tools, run:", :yellow
+          say "  rails g solid_agent:tool search #{class_name}Agent --parameters query:string:required --description \"Search for content\""
+          say ""
+        end
+
+        say "Example usage:", :yellow
+        say "  #{class_name}Agent.with(content: \"Hello\").#{@actions.first}.generate_now"
+        say ""
+      end
+
+      private
+
+      def file_name
+        name.underscore
+      end
+
+      def class_name
+        name.camelize
+      end
+    end
+  end
+end

data/lib/generators/solid_agent/agent/templates/action.text.erb

@@ -0,0 +1,10 @@
+<%% # Action: <%= config[:action_name] %> %>
+<%% # This template is rendered as the user message for the prompt %>
+
+<%% if @content.present? %>
+Please process the following content:
+
+<%%= @content %>
+<%% else %>
+Please help me with my request.
+<%% end %>

data/lib/generators/solid_agent/agent/templates/agent.rb.erb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+class <%= class_name %>Agent < <%= @parent_class %>
+<%- if @include_context || @include_tools || @include_streaming -%>
+  # SolidAgent concerns
+<%- end -%>
+<%- if @include_context -%>
+  include SolidAgent::HasContext
+<%- end -%>
+<%- if @include_tools -%>
+  include SolidAgent::HasTools
+<%- end -%>
+<%- if @include_streaming -%>
+  include SolidAgent::StreamsToolUpdates
+<%- end -%>
+
+  # Configure the generation provider and model
+  generate_with :openai, model: "gpt-4o"
+
+<%- if @include_context -%>
+  # Enable database-backed context persistence
+  # Context is auto-created from params[:<%= @contextable || 'contextable' %>]
+<%- if @context_name -%>
+  has_context :<%= @context_name %>, contextable: :<%= @contextable || 'contextable' %>
+<%- else -%>
+  has_context contextable: :<%= @contextable || 'contextable' %>
+<%- end -%>
+<%- end -%>
+
+<%- if @include_tools -%>
+  # Declare tools (auto-discover from app/views/<%= file_name %>_agent/tools/*.json.erb)
+  # has_tools
+  #
+  # Or declare specific tools:
+  # has_tools :search, :analyze
+  #
+  # Or define inline:
+  # tool :example do
+  #   description "An example tool"
+  #   parameter :input, type: :string, required: true
+  # end
+<%- end -%>
+
+<%- if @include_streaming -%>
+  # Streaming callbacks for real-time updates
+  on_stream :broadcast_chunk
+  on_stream_close :broadcast_complete
+
+  # Tool descriptions for UI feedback
+  # tool_description :search, ->(args) { "Searching for '#{args[:query]}'..." }
+<%- end -%>
+
+<%- @actions.each do |action| -%>
+  # Action: <%= action %>
+  def <%= action %>
+<%- if @include_tools -%>
+    # Include tools in the prompt (context auto-created)
+    prompt(tools: tools, tool_choice: "auto")
+<%- else -%>
+    # Render the action template (context auto-created)
+    prompt
+<%- end -%>
+  end
+
+<%- end -%>
+<%- if @include_streaming -%>
+  private
+
+  def broadcast_chunk(chunk)
+    return unless chunk.delta
+    return unless params[:stream_id]
+
+    ActionCable.server.broadcast(params[:stream_id], { content: chunk.delta })
+  end
+
+  def broadcast_complete(chunk)
+    return unless params[:stream_id]
+
+    ActionCable.server.broadcast(params[:stream_id], { done: true })
+  end
+<%- end -%>
+<%- if @include_tools && !@include_streaming -%>
+  private
+
+  # Tool implementations go here
+  # def search(query:)
+  #   Rails.logger.info "[<%= class_name %>Agent] Tool called: search(#{query})"
+  #   { success: true, results: [] }
+  # rescue => e
+  #   { success: false, error: e.message }
+  # end
+<%- end -%>
+end

data/lib/generators/solid_agent/context/context_generator.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module SolidAgent
+  module Generators
+    class ContextGenerator < Rails::Generators::NamedBase
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generates a custom context model with migrations for domain-specific agent contexts"
+
+      argument :agent_name, type: :string, required: false,
+        desc: "The agent class name that will use this context (optional)"
+
+      class_option :skip_migrations, type: :boolean, default: false,
+        desc: "Skip generating migrations"
+
+      def create_migrations
+        return if options[:skip_migrations]
+
+        migration_template "create_context.rb.erb",
+          "db/migrate/create_#{table_name}.rb"
+
+        migration_template "create_messages.rb.erb",
+          "db/migrate/create_#{message_table_name}.rb"
+
+        migration_template "create_generations.rb.erb",
+          "db/migrate/create_#{generation_table_name}.rb"
+      end
+
+      def create_models
+        template "context_model.rb.erb", "app/models/#{file_name}.rb"
+        template "message_model.rb.erb", "app/models/#{message_file_name}.rb"
+        template "generation_model.rb.erb", "app/models/#{generation_file_name}.rb"
+      end
+
+      def show_usage
+        say ""
+        say "Context models created!", :green
+        say ""
+        say "Files generated:"
+        say "  app/models/#{file_name}.rb"
+        say "  app/models/#{message_file_name}.rb"
+        say "  app/models/#{generation_file_name}.rb"
+        say "  db/migrate/*_create_#{table_name}.rb"
+        say "  db/migrate/*_create_#{message_table_name}.rb"
+        say "  db/migrate/*_create_#{generation_table_name}.rb"
+        say ""
+        say "Next steps:", :yellow
+        say "  1. Run migrations: rails db:migrate"
+        say ""
+        say "  2. Add to your agent:"
+        say "     class #{agent_class_name} < ApplicationAgent"
+        say "       include SolidAgent::HasContext"
+        say "       has_context :#{context_name}"
+        say ""
+        say "       def perform"
+        say "         create_#{context_name}(contextable: params[:user])"
+        say "         prompt"
+        say "       end"
+        say "     end"
+        say ""
+      end
+
+      private
+
+      def context_name
+        name.underscore.singularize
+      end
+
+      def class_name
+        name.camelize
+      end
+
+      def file_name
+        name.underscore
+      end
+
+      def table_name
+        name.underscore.pluralize
+      end
+
+      def message_class_name
+        "#{class_name}Message"
+      end
+
+      def message_file_name
+        "#{file_name}_message"
+      end
+
+      def message_table_name
+        "#{file_name}_messages"
+      end
+
+      def generation_class_name
+        "#{class_name}Generation"
+      end
+
+      def generation_file_name
+        "#{file_name}_generation"
+      end
+
+      def generation_table_name
+        "#{file_name}_generations"
+      end
+
+      def agent_class_name
+        agent_name&.camelize || "MyAgent"
+      end
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+    end
+  end
+end

data/lib/generators/solid_agent/context/templates/context_model.rb.erb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+# <%= class_name %> stores context for <%= context_name %>-based agent interactions.
+#
+# @example Creating a <%= context_name %> for a user
+#   <%= context_name %> = <%= class_name %>.create!(
+#     contextable: current_user,
+#     agent_name: "MyAgent",
+#     action_name: "perform"
+#   )
+#
+# @example Using with has_context
+#   class MyAgent < ApplicationAgent
+#     include SolidAgent::HasContext
+#     has_context :<%= context_name %>
+#
+#     def perform
+#       create_<%= context_name %>(contextable: params[:user])
+#       prompt
+#     end
+#   end
+#
+class <%= class_name %> < ApplicationRecord
+  # Associations
+  belongs_to :contextable, polymorphic: true, optional: true
+  has_many :messages, class_name: "<%= message_class_name %>", dependent: :destroy
+  has_many :generations, class_name: "<%= generation_class_name %>", dependent: :destroy
+
+  # Validations
+  validates :agent_name, presence: true
+  validates :action_name, presence: true
+
+  # Scopes
+  scope :recent, -> { order(created_at: :desc) }
+  scope :for_agent, ->(name) { where(agent_name: name) }
+  scope :for_action, ->(name) { where(action_name: name) }
+
+  # Convenience method to get input_params from options
+  def input_params
+    options&.dig("input_params") || options&.dig(:input_params) || {}
+  end
+
+  # Records a generation response and updates token counts
+  def record_generation!(response)
+    generation = generations.create!(
+      content: response.message&.content,
+      model: response.model,
+      provider: response.provider,
+      finish_reason: response.finish_reason,
+      input_tokens: response.usage&.input_tokens || 0,
+      output_tokens: response.usage&.output_tokens || 0,
+      tool_calls: extract_tool_calls(response),
+      raw_response: response.raw_response,
+      duration_seconds: response.duration
+    )
+
+    increment!(:total_input_tokens, generation.input_tokens)
+    increment!(:total_output_tokens, generation.output_tokens)
+
+    add_assistant_message(response.message&.content, tool_calls: generation.tool_calls)
+
+    generation
+  end
+
+  def add_user_message(content, **attributes)
+    messages.create!(role: "user", content: content, **attributes)
+  end
+
+  def add_assistant_message(content, **attributes)
+    messages.create!(role: "assistant", content: content, **attributes)
+  end
+
+  def add_system_message(content)
+    messages.create!(role: "system", content: content)
+  end
+
+  def add_tool_message(tool_call_id:, tool_name:, result:)
+    messages.create!(
+      role: "tool",
+      tool_call_id: tool_call_id,
+      tool_name: tool_name,
+      tool_result: result,
+      content: result.is_a?(String) ? result : result.to_json
+    )
+  end
+
+  def total_tokens
+    total_input_tokens + total_output_tokens
+  end
+
+  private
+
+  def extract_tool_calls(response)
+    return [] unless response.message&.tool_calls.present?
+
+    response.message.tool_calls.map do |tc|
+      { id: tc.id, name: tc.name, arguments: tc.arguments }
+    end
+  end
+end

data/lib/generators/solid_agent/context/templates/create_context.rb.erb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+class Create<%= class_name.pluralize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :<%= table_name %> do |t|
+      # Polymorphic association to any model (User, Document, Project, etc.)
+      t.references :contextable, polymorphic: true, index: true
+
+      # Agent identification
+      t.string :agent_name, null: false
+      t.string :action_name, null: false
+
+      # System instructions for the conversation
+      t.text :instructions
+
+      # Flexible options storage (input_params, model settings, etc.)
+      t.jsonb :options, default: {}
+
+      # Tracing/debugging
+      t.string :trace_id, index: true
+
+      # Token usage tracking
+      t.integer :total_input_tokens, default: 0
+      t.integer :total_output_tokens, default: 0
+
+      t.timestamps
+    end
+
+    add_index :<%= table_name %>, [:agent_name, :action_name]
+    add_index :<%= table_name %>, :created_at
+  end
+end

data/lib/generators/solid_agent/context/templates/create_generations.rb.erb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+class Create<%= generation_class_name.pluralize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :<%= generation_table_name %> do |t|
+      t.references :<%= file_name %>, null: false, foreign_key: true, index: true
+
+      # The assistant's response content
+      t.text :content
+
+      # Model information
+      t.string :model
+      t.string :provider
+
+      # Finish reason: stop, tool_calls, length, etc.
+      t.string :finish_reason
+
+      # Token usage for this generation
+      t.integer :input_tokens, default: 0
+      t.integer :output_tokens, default: 0
+
+      # Tool calls made in this generation
+      t.jsonb :tool_calls, default: []
+
+      # Raw response from the provider
+      t.jsonb :raw_response
+
+      # Timing
+      t.float :duration_seconds
+
+      t.timestamps
+    end
+
+    add_index :<%= generation_table_name %>, :model
+    add_index :<%= generation_table_name %>, :finish_reason
+    add_index :<%= generation_table_name %>, [:<%= file_name %>_id, :created_at]
+  end
+end

data/lib/generators/solid_agent/context/templates/create_messages.rb.erb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class Create<%= message_class_name.pluralize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :<%= message_table_name %> do |t|
+      t.references :<%= file_name %>, null: false, foreign_key: true, index: true
+
+      # Message role: user, assistant, system, tool
+      t.string :role, null: false
+
+      # Message content
+      t.text :content
+
+      # For tool calls and results
+      t.string :tool_call_id
+      t.string :tool_name
+      t.jsonb :tool_arguments, default: {}
+      t.jsonb :tool_result
+
+      # For multimodal content
+      t.jsonb :attachments, default: []
+
+      # Metadata
+      t.jsonb :metadata, default: {}
+
+      t.timestamps
+    end
+
+    add_index :<%= message_table_name %>, :role
+    add_index :<%= message_table_name %>, :tool_call_id
+    add_index :<%= message_table_name %>, [:<%= file_name %>_id, :created_at]
+  end
+end