solid_agent 0.0.0 → 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

@@ -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 :contextual, 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]
+        @contextual = options[:contextual]
+        @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[:<%= @contextual || 'contextual' %>]
+<%- if @context_name -%>
+  has_context :<%= @context_name %>, contextual: :<%= @contextual || 'contextual' %>
+<%- else -%>
+  has_context contextual: :<%= @contextual || 'contextual' %>
+<%- 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