solid_agent 0.0.0 → 0.2.0

data/lib/generators/solid_agent/install/templates/agent_context.rb.erb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+# AgentContext stores conversation context for AI agents.
+#
+# Each context represents a single conversation or task session,
+# tracking messages, generations, and metadata.
+#
+# @example Creating a context for a user
+#   context = AgentContext.create!(
+#     contextable: current_user,
+#     agent_name: "WritingAssistantAgent",
+#     action_name: "improve"
+#   )
+#
+# @example Finding contexts for a record
+#   user.agent_contexts.recent.each do |context|
+#     puts "#{context.agent_name}##{context.action_name}: #{context.messages.count} messages"
+#   end
+#
+class AgentContext < ApplicationRecord
+  # Associations
+  belongs_to :contextable, polymorphic: true, optional: true
+  has_many :messages, class_name: "AgentMessage", dependent: :destroy
+  has_many :generations, class_name: "AgentGeneration", 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) }
+  scope :with_trace, ->(trace_id) { where(trace_id: trace_id) }
+
+  # 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: ActiveAgent 1.x response
+  # objects don't expose #provider or #duration, and provider messages may
+  # not respond to #tool_calls — a hard read would raise inside
+  # SolidAgent's rescued persistence callback and silently drop the
+  # generation.
+  #
+  # @param response [ActiveAgent::GenerationResponse] the generation response
+  # @param extra_attributes [Hash] additional column values (e.g. trace_id, provenance)
+  # @return [AgentGeneration] the created generation record
+  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))
+
+    # Update cumulative token counts
+    increment!(:total_input_tokens, generation.input_tokens)
+    increment!(:total_output_tokens, generation.output_tokens)
+
+    # Also add assistant message to the conversation
+    add_assistant_message(response.message&.content, metadata: { "tool_calls" => generation.tool_calls })
+
+    generation
+  end
+
+  # Records a generation together with its provenance snapshot, correlating
+  # it with the distributed trace via provenance[:trace_id].
+  #
+  # Called automatically by SolidAgent::HasContext when this method exists.
+  #
+  # @param response [ActiveAgent::GenerationResponse] the generation response
+  # @param provenance [Hash] provenance hash from HasContext#current_provenance
+  # @return [AgentGeneration] the created generation record
+  def record_generation_with_provenance!(response, provenance)
+    provenance = (provenance || {}).deep_stringify_keys
+
+    record_generation!(
+      response,
+      trace_id: provenance["trace_id"],
+      provenance: provenance
+    )
+  end
+
+  # Adds a user message to the context
+  #
+  # @param content [String] the message content
+  # @param attributes [Hash] additional attributes
+  # @return [AgentMessage] the created message
+  def add_user_message(content, **attributes)
+    messages.create!(role: "user", content: content, **attributes)
+  end
+
+  # Adds an assistant message to the context
+  #
+  # @param content [String] the message content
+  # @param attributes [Hash] additional attributes
+  # @return [AgentMessage] the created message
+  def add_assistant_message(content, **attributes)
+    messages.create!(role: "assistant", content: content, **attributes)
+  end
+
+  # Adds a system message to the context
+  #
+  # @param content [String] the message content
+  # @return [AgentMessage] the created message
+  def add_system_message(content)
+    messages.create!(role: "system", content: content)
+  end
+
+  # Adds a tool result message to the context
+  #
+  # @param tool_call_id [String] the ID of the tool call
+  # @param tool_name [String] the name of the tool
+  # @param result [Hash, String] the tool result
+  # @return [AgentMessage] the created message
+  def add_tool_message(tool_call_id:, tool_name:, result:, arguments: nil, duration_ms: nil)
+    messages.create!(
+      role: "tool",
+      tool_call_id: tool_call_id,
+      tool_name: tool_name,
+      tool_result: result,
+      tool_arguments: arguments.presence || {},
+      metadata: duration_ms ? { "duration_ms" => duration_ms } : {},
+      content: result.is_a?(String) ? result : result.to_json
+    )
+  end
+
+  # Returns total token count
+  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/install/templates/agent_generation.rb.erb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# AgentGeneration stores the results of LLM generation calls.
+#
+# Each generation represents a single API call to the LLM provider,
+# tracking the response, token usage, and any tool calls made.
+#
+# @example Accessing generation data
+#   generation = context.generations.last
+#   puts "Model: #{generation.model}"
+#   puts "Tokens: #{generation.input_tokens} in, #{generation.output_tokens} out"
+#   puts "Duration: #{generation.duration_seconds}s"
+#
+class AgentGeneration < ApplicationRecord
+  # Associations
+  belongs_to :agent_context
+
+  # 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") }
+
+  # Returns total token count for this generation
+  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
+
+  # Check if this generation included tool calls
+  def has_tool_calls?
+    tool_calls.present? && tool_calls.any?
+  end
+
+  # Check if generation completed normally
+  def completed?
+    finish_reason == "stop"
+  end
+
+  # Check if generation was truncated due to length
+  def truncated?
+    finish_reason == "length"
+  end
+
+  # Check if generation ended with tool calls
+  def ended_with_tool_calls?
+    finish_reason == "tool_calls"
+  end
+
+  # Returns the cost estimate based on token usage (override with your pricing)
+  #
+  # @param input_price_per_million [Float] price per million input tokens
+  # @param output_price_per_million [Float, nil] price per million output tokens
+  # @return [Float, nil] estimated cost in dollars, nil when nothing to price
+  def estimated_cost(input_price_per_million: nil, output_price_per_million: nil)
+    if input_price_per_million && output_price_per_million
+      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
+    else
+      # Per-model rates from SolidAgent::ModelPricing (RubyLLM registry
+      # when available, static table otherwise)
+      SolidAgent::ModelPricing.estimate(model: model, input_tokens: input_tokens, output_tokens: output_tokens)
+    end
+  end
+end

data/lib/generators/solid_agent/install/templates/agent_memory.rb.erb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Agent-curated long-term memory for a subject record, written and read by
+# agents through SolidAgent::HasMemory's save_memory/recall_memory tools.
+#
+# Memory is scoped to (memorable, scope) — not to an agent class — so any
+# agent operating on the same subject shares it, making it a handoff
+# channel between agents. Entry source_agent records who wrote each note.
+class AgentMemory < ApplicationRecord
+  belongs_to :memorable, polymorphic: true, optional: true
+  has_many :entries, class_name: "AgentMemoryEntry", dependent: :destroy
+
+  validates :scope, presence: true
+
+  # Finds or creates the memory for a subject.
+  def self.for(memorable, scope: SolidAgent::HasMemory::DEFAULT_SCOPE)
+    find_or_create_by!(memorable: memorable, scope: scope.to_s)
+  end
+
+  # Appends a summary note.
+  def remember(content, source_agent: nil, category: nil)
+    entries.create!(content: content, source_agent: source_agent, category: category)
+  end
+
+  # Most recent notes first.
+  def recall(limit: 20, category: nil)
+    scope = entries.order(created_at: :desc)
+    scope = scope.where(category: category) if category.present?
+    scope.limit(limit || 20).to_a
+  end
+
+  def forget(entry_id)
+    entries.find(entry_id).destroy!
+  end
+
+  def summary_list
+    entries.order(:created_at).pluck(:content)
+  end
+
+  # Formatted block suitable for injecting into another agent's
+  # instructions when handing a subject off.
+  def to_prompt
+    notes = entries.order(:created_at).map do |entry|
+      source = entry.source_agent.present? ? " (#{entry.source_agent})" : ""
+      "- #{entry.content}#{source}"
+    end
+    return "" if notes.empty?
+
+    "Memory notes for this subject:\n#{notes.join("\n")}"
+  end
+end

data/lib/generators/solid_agent/install/templates/agent_memory_entry.rb.erb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# One agent-authored summary note in an AgentMemory.
+class AgentMemoryEntry < ApplicationRecord
+  belongs_to :agent_memory
+
+  validates :content, presence: true
+
+  scope :chronological, -> { order(:created_at) }
+  scope :by_category, ->(category) { where(category: category) }
+  scope :from_agent, ->(agent_name) { where(source_agent: agent_name) }
+end

data/lib/generators/solid_agent/install/templates/agent_message.rb.erb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# AgentMessage stores individual messages within an agent context.
+#
+# Messages can be from users, assistants, system prompts, or tool results.
+# This provides a full audit trail of the conversation.
+#
+# @example Adding messages to a context
+#   context.messages.create!(role: "user", content: "Hello!")
+#   context.messages.create!(role: "assistant", content: "Hi there!")
+#
+# @example Tool call message
+#   context.messages.create!(
+#     role: "assistant",
+#     content: nil,
+#     tool_calls: [{ id: "call_123", name: "search", arguments: { query: "Ruby" } }]
+#   )
+#
+# @example Tool result message
+#   context.messages.create!(
+#     role: "tool",
+#     tool_call_id: "call_123",
+#     tool_name: "search",
+#     tool_result: { results: [...] }
+#   )
+#
+class AgentMessage < ApplicationRecord
+  # Associations
+  belongs_to :agent_context
+
+  # 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
+  #
+  # @return [Hash] message in { role:, content: } format
+  def to_message_hash
+    hash = { role: role, content: content }
+
+    # Include tool call info for assistant messages with tool calls
+    if role == "assistant" && tool_calls_data.present?
+      hash[:tool_calls] = tool_calls_data
+    end
+
+    # Include tool result info for tool messages
+    if role == "tool"
+      hash[:tool_call_id] = tool_call_id
+      hash[:name] = tool_name
+    end
+
+    hash
+  end
+
+  # Returns parsed tool calls from metadata or dedicated columns
+  def tool_calls_data
+    metadata&.dig("tool_calls") || []
+  end
+
+  # Check if this is a tool call message
+  def tool_call?
+    role == "assistant" && tool_calls_data.present?
+  end
+
+  # Check if this is a tool result message
+  def tool_result?
+    role == "tool"
+  end
+end

data/lib/generators/solid_agent/install/templates/agent_run.rb.erb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+# A single agent execution: lifecycle status, inputs/outputs, usage, and
+# an append-only stream of progress events. Correlates with AgentContext/
+# AgentGeneration rows and telemetry traces via trace_id.
+class AgentRun < ApplicationRecord
+  belongs_to :runnable, polymorphic: true, optional: true
+
+  STATUSES = %w[pending running complete failed cancelled].freeze
+
+  validates :status, inclusion: { in: STATUSES }
+
+  scope :recent, -> { order(created_at: :desc) }
+  scope :for_agent, ->(agent_name) { where(agent_name: agent_name) }
+  scope :for_action, ->(action_name) { where(action_name: action_name) }
+  scope :with_trace, ->(trace_id) { where(trace_id: trace_id) }
+  scope :for_status, ->(status) { where(status: status) }
+
+  STATUSES.each do |status_name|
+    define_method("#{status_name}?") { status == status_name }
+  end
+
+  def in_progress?
+    pending? || running?
+  end
+
+  def finished?
+    complete? || failed? || cancelled?
+  end
+
+  # === Lifecycle ===
+
+  def start!
+    update!(status: "running", started_at: Time.current)
+  end
+
+  def complete!(output: nil, metadata: {}, input_tokens: nil, output_tokens: nil)
+    update!(
+      status: "complete",
+      output: output,
+      output_metadata: (output_metadata || {}).merge(metadata),
+      input_tokens: input_tokens || self.input_tokens,
+      output_tokens: output_tokens || self.output_tokens,
+      completed_at: Time.current,
+      duration_ms: calculated_duration_ms(fallback_end: Time.current)
+    )
+  end
+
+  def fail!(error)
+    update!(
+      status: "failed",
+      error_message: error.respond_to?(:message) ? error.message : error.to_s,
+      completed_at: Time.current,
+      duration_ms: calculated_duration_ms(fallback_end: Time.current)
+    )
+  end
+
+  def cancel!
+    return false if finished?
+
+    update!(status: "cancelled", completed_at: Time.current)
+    true
+  end
+
+  # === Progress events ===
+
+  # Appends a progress event mid-run so pollers can stream what the agent
+  # is doing (pending llm/tool/agent calls). Events pair up by eid: a
+  # "started" event is pending until a "done"/"error" with the same eid
+  # lands. update_column: no validations/callbacks, so this is safe to call
+  # from the run's own execution thread.
+  #
+  # Read-modify-write on a JSON column drops entries when two writers race,
+  # so the re-read and the write are serialized by a row lock.
+  def append_event(kind:, label:, eid: nil, status: "done", detail: nil, duration_ms: nil)
+    event = {
+      "at" => Time.current.iso8601(3),
+      "eid" => eid,
+      "kind" => kind.to_s,
+      "label" => label.to_s,
+      "status" => status.to_s
+    }.compact
+    event["detail"] = detail.to_s.byteslice(0, 1200).to_s.scrub if detail
+    event["duration_ms"] = duration_ms if duration_ms
+
+    with_lock do
+      current = self.class.where(id: id).pick(:events) || []
+      update_column(:events, current + [ event ])
+    end
+
+    event
+  end
+
+  # === Cohort fingerprinting ===
+
+  # Records the instructions this run executed under as a stable digest —
+  # the grouping key (with model) for configuration cohorts.
+  def record_instructions(instructions)
+    self.instructions_digest = SolidAgent::RunFingerprint.digest(instructions)
+  end
+
+  # Deterministic memorable name for the digest ("calm-heron") — reads far
+  # better than hex when comparing cohorts.
+  def instructions_codename
+    SolidAgent::RunFingerprint.codename(instructions_digest)
+  end
+
+  # === Usage ===
+
+  def total_tokens
+    input_tokens.to_i + output_tokens.to_i
+  end
+
+  def calculated_duration_ms(fallback_end: nil)
+    return duration_ms if duration_ms.present?
+
+    finish = completed_at || fallback_end
+    return nil unless started_at && finish
+
+    ((finish - started_at) * 1000).to_i
+  end
+end

data/lib/generators/solid_agent/install/templates/create_agent_contexts.rb.erb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+class CreateAgentContexts < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :agent_contexts do |t|
+      # Polymorphic association to any model (User, Document, 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 :agent_contexts, [:agent_name, :action_name]
+    add_index :agent_contexts, :created_at
+  end
+end

data/lib/generators/solid_agent/install/templates/create_agent_generations.rb.erb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+class CreateAgentGenerations < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :agent_generations do |t|
+      t.references :agent_context, 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 (for debugging)
+      t.jsonb :raw_response
+
+      # Timing
+      t.float :duration_seconds
+
+      # Telemetry correlation: the distributed trace this generation belongs
+      # to (e.g. ActiveAgent::Telemetry trace_id), threaded through
+      # prompt_options[:trace_id]
+      t.string :trace_id
+
+      # Provenance snapshot (agent/prompt/context checksums) captured at
+      # generation time — see SolidAgent::HasContext#current_provenance
+      t.jsonb :provenance, default: {}
+
+      t.timestamps
+    end
+
+    add_index :agent_generations, :model
+    add_index :agent_generations, :finish_reason
+    add_index :agent_generations, :trace_id
+    add_index :agent_generations, [:agent_context_id, :created_at]
+  end
+end

data/lib/generators/solid_agent/install/templates/create_agent_memories.rb.erb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class CreateAgentMemories < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :agent_memories do |t|
+      # The subject the memory is about (an Agent record, User, Project...).
+      # Any agent operating on the same subject + scope shares the memory,
+      # which is what makes it a handoff channel between agents.
+      t.references :memorable, polymorphic: true, index: true
+
+      # Namespace so a subject can carry independent memory streams.
+      t.string :scope, null: false, default: "default"
+
+      t.timestamps
+    end
+    add_index :agent_memories, [ :memorable_type, :memorable_id, :scope ], unique: true
+
+    create_table :agent_memory_entries do |t|
+      t.references :agent_memory, null: false, foreign_key: true
+
+      # The summary note the agent chose to persist.
+      t.text :content, null: false
+
+      # Which agent class wrote it (handoff provenance).
+      t.string :source_agent
+
+      # Optional label: fact, task, handoff, ...
+      t.string :category
+
+      t.timestamps
+    end
+    add_index :agent_memory_entries, [ :agent_memory_id, :created_at ]
+    add_index :agent_memory_entries, :category
+  end
+end

data/lib/generators/solid_agent/install/templates/create_agent_messages.rb.erb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+class CreateAgentMessages < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :agent_messages do |t|
+      t.references :agent_context, null: false, foreign_key: true, index: true
+
+      # Message role: user, assistant, system, tool
+      t.string :role, null: false
+
+      # Message content (text content for the message)
+      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 (images, files)
+      t.jsonb :attachments, default: []
+
+      # Metadata
+      t.jsonb :metadata, default: {}
+
+      # Provenance snapshot + content checksum, populated automatically by
+      # SolidAgent::HasContext when present
+      t.jsonb :provenance, default: {}
+      t.string :content_checksum
+
+      t.timestamps
+    end
+
+    add_index :agent_messages, :role
+    add_index :agent_messages, :tool_call_id
+    add_index :agent_messages, [:agent_context_id, :created_at]
+  end
+end