solid_agent 0.0.0 → 0.2.0

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,134 @@
+# 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.
+  # Response attributes are read defensively — see the install generator's
+  # AgentContext template for details.
+  def record_generation!(response, extra_attributes = {})
+    usage = response.respond_to?(:usage) ? response.usage : nil
+
+    generation = generations.create!({
+      content: response.message&.content,
+      model: response_value(response, :model),
+      provider: response_value(response, :provider),
+      finish_reason: response_value(response, :finish_reason),
+      input_tokens: usage&.input_tokens || 0,
+      output_tokens: usage&.output_tokens || 0,
+      cached_tokens: response_value(usage, :cached_tokens) || 0,
+      reasoning_tokens: response_value(usage, :reasoning_tokens) || 0,
+      tool_calls: extract_tool_calls(response),
+      raw_response: response_value(response, :raw_response),
+      duration_seconds: extract_duration_seconds(response, usage)
+    }.merge(extra_attributes))
+
+    increment!(:total_input_tokens, generation.input_tokens)
+    increment!(:total_output_tokens, generation.output_tokens)
+
+    add_assistant_message(response.message&.content, metadata: { "tool_calls" => generation.tool_calls })
+
+    generation
+  end
+
+  # Records a generation together with its provenance snapshot (called
+  # automatically by SolidAgent::HasContext when this method exists).
+  def record_generation_with_provenance!(response, provenance)
+    provenance = (provenance || {}).deep_stringify_keys
+
+    record_generation!(
+      response,
+      trace_id: provenance["trace_id"],
+      provenance: provenance
+    )
+  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 response_value(response, method)
+    response.respond_to?(method) ? response.public_send(method) : nil
+  end
+
+  def extract_duration_seconds(response, usage)
+    return response.duration if response.respond_to?(:duration) && response.duration
+
+    duration_ms = usage.respond_to?(:duration_ms) ? usage.duration_ms : nil
+    duration_ms ? duration_ms / 1000.0 : nil
+  end
+
+  def extract_tool_calls(response)
+    message = response.message
+    return [] unless message.respond_to?(:tool_calls) && message.tool_calls.present?
+
+    message.tool_calls.map do |tc|
+      {
+        id: tc.respond_to?(:id) ? tc.id : nil,
+        name: tc.respond_to?(:name) ? tc.name : nil,
+        arguments: tc.respond_to?(:arguments) ? tc.arguments : nil
+      }
+    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,46 @@
+# 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
+      # Provider prompt-cache hits and extended-thinking usage
+      t.integer :cached_tokens, default: 0
+      t.integer :reasoning_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
+
+      # Telemetry correlation + provenance snapshot
+      t.string :trace_id
+      t.jsonb :provenance, default: {}
+
+      t.timestamps
+    end
+
+    add_index :<%= generation_table_name %>, :model
+    add_index :<%= generation_table_name %>, :finish_reason
+    add_index :<%= generation_table_name %>, :trace_id
+    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,37 @@
+# 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: {}
+
+      # Provenance snapshot + content checksum (populated by HasContext)
+      t.jsonb :provenance, default: {}
+      t.string :content_checksum
+
+      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

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# <%= generation_class_name %> stores LLM generation results for a <%= context_name %>.
+#
+class <%= generation_class_name %> < ApplicationRecord
+  # Associations
+  belongs_to :<%= file_name %>
+
+  # Scopes
+  scope :recent, -> { order(created_at: :desc) }
+  scope :by_model, ->(model) { where(model: model) }
+  scope :with_tool_calls, -> { where.not(tool_calls: []) }
+  scope :with_trace, ->(trace_id) { where(trace_id: trace_id) }
+  scope :completed, -> { where(finish_reason: "stop") }
+
+  def total_tokens
+    input_tokens + output_tokens
+  end
+
+  # Provider prompt-cache hit on this generation?
+  def cache_hit?
+    cached_tokens.to_i.positive?
+  end
+
+  # Extended thinking captured?
+  def thinking?
+    reasoning_tokens.to_i.positive?
+  end
+
+  def has_tool_calls?
+    tool_calls.present? && tool_calls.any?
+  end
+
+  def completed?
+    finish_reason == "stop"
+  end
+
+  def truncated?
+    finish_reason == "length"
+  end
+
+  def ended_with_tool_calls?
+    finish_reason == "tool_calls"
+  end
+
+  def estimated_cost(input_price_per_million: 3.0, output_price_per_million: 15.0)
+    input_cost = (input_tokens / 1_000_000.0) * input_price_per_million
+    output_cost = (output_tokens / 1_000_000.0) * output_price_per_million
+    input_cost + output_cost
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# <%= message_class_name %> stores individual messages within a <%= context_name %>.
+#
+class <%= message_class_name %> < ApplicationRecord
+  # Associations
+  belongs_to :<%= file_name %>
+
+  # Validations
+  validates :role, presence: true, inclusion: { in: %w[user assistant system tool] }
+
+  # Scopes
+  scope :by_role, ->(role) { where(role: role) }
+  scope :user_messages, -> { by_role("user") }
+  scope :assistant_messages, -> { by_role("assistant") }
+  scope :system_messages, -> { by_role("system") }
+  scope :tool_messages, -> { by_role("tool") }
+  scope :chronological, -> { order(created_at: :asc) }
+
+  # Converts the message to a hash format for ActiveAgent prompts
+  def to_message_hash
+    hash = { role: role, content: content }
+
+    if role == "assistant" && tool_calls_data.present?
+      hash[:tool_calls] = tool_calls_data
+    end
+
+    if role == "tool"
+      hash[:tool_call_id] = tool_call_id
+      hash[:name] = tool_name
+    end
+
+    hash
+  end
+
+  def tool_calls_data
+    metadata&.dig("tool_calls") || []
+  end
+
+  def tool_call?
+    role == "assistant" && tool_calls_data.present?
+  end
+
+  def tool_result?
+    role == "tool"
+  end
+end

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module SolidAgent
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Installs SolidAgent: creates migrations for context persistence and initializer"
+
+      class_option :skip_migrations, type: :boolean, default: false,
+        desc: "Skip generating migrations"
+
+      class_option :skip_initializer, type: :boolean, default: false,
+        desc: "Skip generating initializer"
+
+      def create_migrations
+        return if options[:skip_migrations]
+
+        migration_template "create_agent_contexts.rb.erb",
+          "db/migrate/create_agent_contexts.rb"
+
+        migration_template "create_agent_messages.rb.erb",
+          "db/migrate/create_agent_messages.rb"
+
+        migration_template "create_agent_generations.rb.erb",
+          "db/migrate/create_agent_generations.rb"
+
+        migration_template "create_agent_memories.rb.erb",
+          "db/migrate/create_agent_memories.rb"
+
+        migration_template "create_agent_runs.rb.erb",
+          "db/migrate/create_agent_runs.rb"
+      end
+
+      def create_models
+        return if options[:skip_migrations]
+
+        template "agent_context.rb.erb", "app/models/agent_context.rb"
+        template "agent_message.rb.erb", "app/models/agent_message.rb"
+        template "agent_generation.rb.erb", "app/models/agent_generation.rb"
+        template "agent_memory.rb.erb", "app/models/agent_memory.rb"
+        template "agent_memory_entry.rb.erb", "app/models/agent_memory_entry.rb"
+        template "agent_run.rb.erb", "app/models/agent_run.rb"
+      end
+
+      def create_initializer
+        return if options[:skip_initializer]
+
+        template "initializer.rb.erb", "config/initializers/solid_agent.rb"
+      end
+
+      def show_post_install_message
+        say ""
+        say "SolidAgent installed successfully!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Run migrations: rails db:migrate"
+        say "  2. Include SolidAgent::HasContext in your ApplicationAgent"
+        say "  3. Use has_context in agents that need persistence"
+        say ""
+        say "Example:"
+        say "  class WritingAssistantAgent < ApplicationAgent"
+        say "    include SolidAgent::HasContext"
+        say "    has_context"
+        say ""
+        say "    def improve"
+        say "      create_context(contextable: params[:document])"
+        say "      prompt"
+        say "    end"
+        say "  end"
+        say ""
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+
+      # Ensure unique timestamps for multiple migrations
+      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