solid_agent 0.1.1 → 0.2.0

data/examples/run_tracking/app/controllers/agent_runs_controller.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# The polling endpoint the progress stream exists for. Events are appended
+# with update_column from the run's own thread, so a request mid-run reads
+# whatever has landed so far.
+class AgentRunsController < ApplicationController
+  def create
+    document = Document.find(params[:document_id])
+
+    run = AgentRun.create!(
+      runnable: document,
+      agent_name: "ReportAgent",
+      action_name: "analyze",
+      input_prompt: params[:question]
+    )
+
+    DocumentAnalysisJob.perform_later(run.id)
+
+    render json: { id: run.id, status: run.status }, status: :accepted
+  end
+
+  def show
+    run = AgentRun.find(params[:id])
+
+    render json: {
+      status: run.status,
+      in_progress: run.in_progress?,
+      events: run.events,
+      output: run.output,
+      error: run.error_message,
+      tokens: run.total_tokens,
+      duration_ms: run.calculated_duration_ms(fallback_end: Time.current)
+    }
+  end
+
+  def destroy
+    run = AgentRun.find(params[:id])
+
+    # Returns false when the run already finished — cancellation is a
+    # request, not a guarantee.
+    render json: { cancelled: run.cancel! }
+  end
+end

data/examples/run_tracking/app/jobs/document_analysis_job.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Runs exist because the work happens somewhere the request can't watch.
+class DocumentAnalysisJob < ApplicationJob
+  queue_as :default
+
+  def perform(run_id)
+    run = AgentRun.find(run_id)
+    return if run.finished? # cancelled before a worker picked it up
+
+    DocumentAnalysisRun.new(run).call
+  rescue StandardError
+    # The service already recorded the failure on the run; re-raising lets
+    # Active Job apply its own retry policy.
+    raise
+  end
+end

data/examples/run_tracking/app/services/document_analysis_run.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# A durable record of one agent execution.
+#
+# AgentRun is the row a background job writes so a UI has something to
+# poll: lifecycle status, the input, the output, token and duration
+# accounting, an append-only progress stream, and an instructions
+# fingerprint that groups runs into cohorts when you change the prompt.
+#
+# Nothing in SolidAgent creates these for you — the executor does, which is
+# what this service is. It takes a run that already exists (the controller
+# creates it so the client has an id to poll immediately) and drives it
+# through its lifecycle.
+#
+# Docs: https://docs.activeagents.ai/solid_agent/runs
+class DocumentAnalysisRun
+  def initialize(run)
+    @run = run
+    @document = run.runnable
+    @question = run.input_prompt
+  end
+
+  def call
+    # Fingerprint the instructions this run executed under. Runs sharing a
+    # digest are one cohort — that is how "did the new prompt help?"
+    # becomes a comparable question.
+    @run.record_instructions(ReportAgent::INSTRUCTIONS)
+    @run.trace_id ||= SecureRandom.uuid
+    @run.save!
+    @run.start!
+
+    # Progress events pair up by eid: "started" stays pending in the UI
+    # until a "done" or "error" with the same eid lands.
+    @run.append_event(kind: "llm", label: "analyze", eid: "gen-1", status: "started")
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    response = ReportAgent.with(
+      document: @document,
+      question: @question,
+      trace_id: @run.trace_id
+    ).analyze.generate_now
+
+    @run.append_event(
+      kind: "llm", label: "analyze", eid: "gen-1", status: "done",
+      duration_ms: elapsed_ms(started)
+    )
+
+    @run.complete!(
+      output: response.message.content,
+      input_tokens: response.usage&.input_tokens,
+      output_tokens: response.usage&.output_tokens,
+      metadata: { model: "gpt-4o-mini" }
+    )
+
+    @run
+  rescue StandardError => e
+    # fail! records the message, stamps completed_at, computes duration.
+    @run.append_event(kind: "llm", label: "analyze", eid: "gen-1", status: "error", detail: e.message)
+    @run.fail!(e)
+    raise
+  end
+
+  private
+
+  def elapsed_ms(started)
+    ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+  end
+end

data/examples/run_tracking/usage.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# Runs, cohorts and cost — rails console walkthrough.
+#
+# Docs: https://docs.activeagents.ai/solid_agent/runs
+
+document = Document.find(1)
+
+# The controller creates the row so the client has an id to poll; here we
+# do both halves in one go.
+run = AgentRun.create!(
+  runnable: document,
+  agent_name: "ReportAgent",
+  action_name: "analyze",
+  input_prompt: "Who owns the IP?"
+)
+
+DocumentAnalysisRun.new(run).call
+
+run.status          # => "complete"
+run.finished?       # => true
+run.total_tokens
+run.duration_ms
+run.output
+
+# The progress stream, oldest first. Each event is
+# { at, eid, kind, label, status, detail, duration_ms }.
+run.events
+# => [{"at" => "2026-08-14T12:00:00.123Z", "eid" => "gen-1", "kind" => "llm",
+#      "label" => "analyze", "status" => "started"},
+#     {"at" => "...", "eid" => "gen-1", "kind" => "llm", "label" => "analyze",
+#      "status" => "done", "duration_ms" => 1840}]
+
+# --- Cohorts ------------------------------------------------------------
+
+# Runs are grouped by the instructions they executed under. The digest is
+# stable; the codename is the readable form of the same value.
+run.instructions_digest    # => "a1b2c3d4"
+run.instructions_codename  # => "calm-heron"
+
+AgentRun.where(instructions_digest: run.instructions_digest).count
+
+# "Did the new instructions help?" — one row per cohort.
+AgentRun.for_agent("ReportAgent").where(status: "complete")
+  .group(:instructions_digest)
+  .average(:duration_ms)
+  .transform_keys { |digest| SolidAgent::RunFingerprint.codename(digest) }
+# => { "calm-heron" => 2400.0, "misty-atoll" => 1810.0 }
+
+# Fingerprinting without a run record:
+SolidAgent::RunFingerprint.digest(ReportAgent::INSTRUCTIONS)
+SolidAgent::RunFingerprint.codename("a1b2c3d4")
+
+# --- Scopes and correlation --------------------------------------------
+
+AgentRun.recent.limit(20)
+AgentRun.for_agent("ReportAgent").for_status("failed")
+AgentRun.with_trace(run.trace_id)
+AgentContext.with_trace(run.trace_id)
+AgentGeneration.with_trace(run.trace_id)
+
+# --- Cost ---------------------------------------------------------------
+
+# Token counts are recorded; pricing is layered on top, so every figure is
+# an estimate. Rates come from RubyLLM's registry when that gem is loaded
+# and knows the model, and from a static pattern table otherwise.
+SolidAgent::ModelPricing.estimate(
+  model: "claude-sonnet-5", input_tokens: 12_000, output_tokens: 800
+)
+# => 0.048
+
+SolidAgent::ModelPricing.rate_for("gpt-4o-mini") # => [0.15, 0.6] per 1M tokens
+
+# The generated AgentGeneration#estimated_cost uses it automatically, and
+# takes explicit rates when you have negotiated your own.
+AgentGeneration.recent.first.estimated_cost
+AgentGeneration.recent.first.estimated_cost(
+  input_price_per_million: 0.10, output_price_per_million: 0.40
+)
+
+# Spend for a day, by model. Pricing is per-model, so total it in Ruby
+# rather than in SQL:
+AgentGeneration.where(created_at: 1.day.ago..)
+  .group_by(&:model)
+  .transform_values { |generations| generations.sum { |g| g.estimated_cost.to_f }.round(4) }

data/examples/tool_streaming/app/agents/browser_agent.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Rails does not guarantee net/http is loaded, and fetch_url below needs it.
+require "net/http"
+
+# Tools three ways, plus live progress and result caching.
+#
+# - `has_tools :fetch_url` loads a schema from a JSON view template, so the
+#   schema lives next to the rest of the agent's views and can use ERB.
+# - `tool :summarize_page do ... end` defines a schema inline.
+# - `tool_description` wraps the tool method so each call broadcasts a
+#   human-readable status over ActionCable before it runs.
+# - `SolidAgent::ToolCache.fetch` replays an identical call instead of
+#   paying for the side effect twice.
+#
+# Docs: https://docs.activeagents.ai/solid_agent/tools
+class BrowserAgent < ApplicationAgent
+  include SolidAgent::HasTools
+  include SolidAgent::StreamsToolUpdates
+
+  generate_with :openai, model: "gpt-4o-mini"
+
+  # Loaded from app/views/browser_agent/tools/fetch_url.json.erb.
+  # `has_tools` with no arguments discovers every template in that
+  # directory instead.
+  has_tools :fetch_url
+
+  tool :summarize_page do
+    description "Summarize text that was already fetched"
+    parameter :text, type: :string, required: true, description: "Page text to summarize"
+    parameter :sentences, type: :integer, default: 3
+  end
+
+  # Static or dynamic — a proc receives the tool's arguments. Declaring a
+  # description is what wraps the method for broadcasting; tools without
+  # one still run, they just stay quiet.
+  tool_description :fetch_url, ->(args) { "Fetching #{args[:url]}..." }
+  tool_description :summarize_page, "Summarizing the page..."
+
+  def browse
+    # `tools` is every schema this agent declares: templates first, then
+    # inline definitions.
+    prompt tools: tools
+  end
+
+  # Tool methods take keyword arguments and are named after the schema.
+  def fetch_url(url:)
+    # Identical (tool, args) pairs inside the TTL replay the stored result
+    # and come back tagged cached: true. Error-shaped results are never
+    # cached, so a transient failure doesn't stick for five minutes.
+    SolidAgent::ToolCache.fetch(tool: "fetch_url", args: { url: url }, ttl: 5.minutes) do
+      response = Net::HTTP.get_response(URI(url))
+
+      if response.is_a?(Net::HTTPSuccess)
+        { url: url, body: response.body.first(10_000) }
+      else
+        { error: "HTTP #{response.code}" }
+      end
+    end
+  end
+
+  def summarize_page(text:, sentences: 3)
+    { summary: text.split(/(?<=\.)\s+/).first(sentences).join(" ") }
+  end
+end

data/examples/tool_streaming/app/channels/tool_status_channel.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# The client half of StreamsToolUpdates. The agent broadcasts to whatever
+# string it was handed as params[:stream_id], so the channel just streams
+# from that name.
+#
+#   // app/javascript/channels/tool_status_channel.js
+#   consumer.subscriptions.create(
+#     { channel: "ToolStatusChannel", stream_id: streamId },
+#     { received({ tool_status }) {
+#         document.getElementById("status").textContent = tool_status.description
+#       } }
+#   )
+class ToolStatusChannel < ApplicationCable::Channel
+  def subscribed
+    stream_id = params[:stream_id].to_s
+
+    # Scope the id to the current user so one subscriber can't listen in on
+    # another's run.
+    reject unless stream_id.start_with?("tool_status:#{current_user.id}:")
+
+    stream_from stream_id
+  end
+end

data/examples/tool_streaming/app/views/browser_agent/tools/fetch_url.json.erb

@@ -0,0 +1,15 @@
+{
+  "type": "function",
+  "name": "fetch_url",
+  "description": "Fetch a web page and return its text",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "url": {
+        "type": "string",
+        "description": "Absolute http(s) URL to fetch"
+      }
+    },
+    "required": ["url"]
+  }
+}

data/examples/tool_streaming/usage.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Tools, live status and caching — rails console walkthrough.
+#
+# Docs: https://docs.activeagents.ai/solid_agent/tools
+
+# What the agent will send to the provider: the template-loaded schema
+# first, then the inline one.
+BrowserAgent.new.tools.map { |t| t[:name] }
+# => ["fetch_url", "summarize_page"]
+
+# Editing a JSON template while the server is running? Drop the cache:
+agent = BrowserAgent.new
+agent.reload_tools!
+
+# Without a stream_id nothing is broadcast — the same agent runs silently
+# from a job or a console.
+BrowserAgent.with(message: "Summarize https://rubyonrails.org").browse.generate_now
+
+# With one, every described tool announces itself before it runs:
+#   { tool_status: { name: "fetch_url",
+#                    description: "Fetching https://rubyonrails.org...",
+#                    timestamp: "2026-08-14T12:00:00Z" } }
+stream_id = "tool_status:#{current_user.id}:#{SecureRandom.uuid}"
+
+BrowserAgent.with(
+  stream_id: stream_id,
+  message: "Summarize https://rubyonrails.org"
+).browse.generate_now
+
+# --- Tool cache ---------------------------------------------------------
+
+# The cache is keyed by (tool, normalized args) — argument order and
+# symbol/string keys don't change the key.
+SolidAgent::ToolCache.cache_key("fetch_url", { url: "https://example.com" })
+# => "solid_agent:tool_cache:fetch_url:9f2c..."
+
+result = SolidAgent::ToolCache.fetch(tool: "fetch_url", args: { url: "https://example.com" }) do
+  { body: "expensive" }
+end
+result[:cached] # => nil on the first call, true on a replay
+
+# Backed by Rails.cache by default; swap the store (or switch it off) in
+# tests and non-Rails runtimes.
+SolidAgent::ToolCache.store = ActiveSupport::Cache::MemoryStore.new
+SolidAgent::ToolCache.default_ttl = 60
+SolidAgent::ToolCache.enabled = false

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

@@ -15,7 +15,7 @@ module SolidAgent
       class_option :context_name, type: :string, default: nil,
         desc: "Custom context name (e.g., 'conversation', 'research_session')"
 
-      class_option :contextable, type: :string, default: nil,
+      class_option :contextual, type: :string, default: nil,
         desc: "Param key for auto-context (e.g., 'user', 'document')"
 
       class_option :tools, type: :boolean, default: false,
@@ -34,7 +34,7 @@ module SolidAgent
         @parent_class = options[:parent]
         @include_context = options[:context]
         @context_name = options[:context_name]
-        @contextable = options[:contextable]
+        @contextual = options[:contextual]
         @include_tools = options[:tools]
         @include_streaming = options[:streaming]
         @actions = options[:actions]

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

@@ -19,11 +19,11 @@ class <%= class_name %>Agent < <%= @parent_class %>
 
 <%- if @include_context -%>
   # Enable database-backed context persistence
-  # Context is auto-created from params[:<%= @contextable || 'contextable' %>]
+  # Context is auto-created from params[:<%= @contextual || 'contextual' %>]
 <%- if @context_name -%>
-  has_context :<%= @context_name %>, contextable: :<%= @contextable || 'contextable' %>
+  has_context :<%= @context_name %>, contextual: :<%= @contextual || 'contextual' %>
 <%- else -%>
-  has_context contextable: :<%= @contextable || 'contextable' %>
+  has_context contextual: :<%= @contextual || 'contextual' %>
 <%- end -%>
 <%- end -%>
 

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

@@ -40,28 +40,46 @@ class <%= class_name %> < ApplicationRecord
     options&.dig("input_params") || options&.dig(:input_params) || {}
   end
 
-  # Records a generation response and updates token counts
-  def record_generation!(response)
-    generation = generations.create!(
+  # 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.model,
-      provider: response.provider,
-      finish_reason: response.finish_reason,
-      input_tokens: response.usage&.input_tokens || 0,
-      output_tokens: response.usage&.output_tokens || 0,
+      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.raw_response,
-      duration_seconds: response.duration
-    )
+      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, tool_calls: generation.tool_calls)
+    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
@@ -90,11 +108,27 @@ class <%= class_name %> < ApplicationRecord
 
   private
 
-  def extract_tool_calls(response)
-    return [] unless response.message&.tool_calls.present?
+  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
 
-    response.message.tool_calls.map do |tc|
-      { id: tc.id, name: tc.name, arguments: tc.arguments }
+    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_generations.rb.erb

@@ -18,6 +18,9 @@ class Create<%= generation_class_name.pluralize %> < ActiveRecord::Migration<%=
       # 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: []
@@ -28,11 +31,16 @@ class Create<%= generation_class_name.pluralize %> < ActiveRecord::Migration<%=
       # 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

@@ -23,6 +23,10 @@ class Create<%= message_class_name.pluralize %> < ActiveRecord::Migration<%= mig
       # Metadata
       t.jsonb :metadata, default: {}
 
+      # Provenance snapshot + content checksum (populated by HasContext)
+      t.jsonb :provenance, default: {}
+      t.string :content_checksum
+
       t.timestamps
     end
 

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

@@ -10,12 +10,23 @@ class <%= generation_class_name %> < ApplicationRecord
   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

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

@@ -29,6 +29,12 @@ module SolidAgent
 
         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
@@ -37,6 +43,9 @@ module SolidAgent
         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