solid_agents 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5972db63aa2e5fb01908f0a70c788856b9812fce9961b21cf75c1d79b041406
-  data.tar.gz: 922aafdc00524dab9c490c56031af71c99ef539afbbf87acba80c53a9c1b73c3
+  metadata.gz: e4096d5a7518890d89a9ab5ef5583e1828f9457abe69f536c2e7042c05e9288a
+  data.tar.gz: f466a2d473053692596c5c70f43530df1e77e474c10622084ef6f3431d4b36b3
 SHA512:
-  metadata.gz: 1290f03a93a621b1bc78f94b8f7031134809b368c1e37c9542f5d22b58abd8d579b7774e93c6d0d6720838b3b5ea618a807c5fd6e2562737701ac7b0e5598c28
-  data.tar.gz: e6f7ceca7356d904fc0adf8187eea3ac4784e64cac04db5c3e944ceda661112c9e6729d9d1524f34ec2fb610925eafe10452fb79d2d611a088ca0e9835e145c5
+  metadata.gz: c1833f9334bf37f89c13d473154ef428240b87772fbedac727daa369f6cda15906ab93225fee8c3471f0d523794a5e9efa489d2e8c443f8e097518c12c23535d
+  data.tar.gz: 887265f38a7cdb95a05f15ab8a0919af5d1e9039de54a2f01e2507fecd75c6aa53cc5c52acf983f715c885950c2b158323a4969f4e3b9f962eea0245132301cd

data/CHANGELOG.md

@@ -2,14 +2,28 @@
 
 All notable changes to `solid_agents` will be documented in this file.
 
+## [v0.2.1] - 2026-03-23
+
+Follow-up release for RubyLLM runtime and path conventions.
+
+- Moved agent classes and prompt templates to `app/solid_agents/agents` and `app/solid_agents/prompts`.
+- Added VCR-backed live RubyLLM integration coverage with secret filtering and record-once behavior.
+- Standardized LLM credential loading to environment variables only and added `.env.sample`.
+- Updated installer and docs to reflect ENV-first configuration and current runtime defaults.
+
+Status notes:
+
+- This release is still WIP and not production-ready.
+- Breaking changes are expected before `1.0`.
+
 ## [v0.2.0] - 2026-03-23
 
 Major architecture reset delivered as a minor release for rapid iteration.
 
-- Replaced runtime adapters with a single pi-only execution path.
+- Replaced runtime adapters with a single RubyLLM-first execution path.
 - Rebuilt the run model into an event-driven staged workflow.
 - Added work-item board tracking and explicit inter-agent handoff records.
-- Introduced stage ownership with alphabetical agents: alex, betty, chad, david, emma.
+- Introduced stage ownership with alphabetical agents: alex, betty, chad, david, eddy.
 - Updated installer schema and initializer templates for the new workflow primitives.
 - Reworked run UI to expose stage, owner, events, and artifacts in clean columns.
 - Expanded Minitest coverage and moved to YAML fixtures for deterministic test data.
@@ -25,7 +39,7 @@ Initial public release (WIP).
 
 - Introduced `solid_agents` Rails engine for database-backed agent run orchestration.
 - Added run lifecycle models and persistence for runs, events, artifacts, agents, and config.
-- Added dispatch and execution flow with runtime adapters for OpenAI pi runtime and OpenAI pi runtime.
+- Added dispatch and execution flow with runtime adapters for OpenAI RubyLLM runtime and OpenAI RubyLLM runtime.
 - Added built-in UI/controllers for managing agents and inspecting runs.
 - Added installer generator, schema template, and base configuration defaults.
 

data/README.md

@@ -1,6 +1,6 @@
 # SolidAgents
 
-**Event-driven error fixing workflow for Rails apps, powered by the pi runtime.**
+**Event-driven error fixing workflow for Rails apps, powered by RubyLLM agents.**
 
 > [!WARNING]
 > `solid_agents` is an early release and still a work in progress.
@@ -18,9 +18,9 @@
 
 - Consume error-like events from source adapters (starting with `solid_errors` style payloads)
 - Track runs in an event-driven stage machine
-- Enforce non-overlapping stage ownership (`alex`, `betty`, `chad`, `david`, `emma`)
+- Enforce non-overlapping stage ownership (`alex`, `betty`, `chad`, `david`, `eddy`)
 - Persist handoffs, notes, and artifacts for each stage
-- Execute stage tasks through the pi runtime adapter
+- Execute stage tasks through the RubyLLM runtime adapter
 
 It does **not** own observability storage or incident detection as a source of truth.
 
@@ -52,7 +52,7 @@ Configure engine DB connection if desired:
 ```ruby
 # config/environments/production.rb
 config.solid_agents.connects_to = { database: { writing: :solid_agents } }
-config.solid_agents.default_runtime = :pi
+config.solid_agents.default_runtime = :ruby_llm
 ```
 
 Mount the UI:
@@ -69,11 +69,11 @@ end
 Create pipeline agents:
 
 ```ruby
-%w[alex betty chad david emma].each do |key|
+%w[alex betty chad david eddy].each do |key|
   SolidAgents::Agent.find_or_create_by!(key: key, environment: Rails.env) do |agent|
     agent.name = key.capitalize
     agent.role = key
-    agent.runtime = "pi"
+    agent.runtime = "ruby_llm"
     agent.working_directory = Rails.root.to_s
     agent.enabled = true
   end
@@ -86,10 +86,16 @@ Dispatch from a job:
 SolidAgents.dispatch_error(source: solid_error_record, agent_key: "alex")
 ```
 
+## RubyLLM Conventions
+
+- Agent classes live in `app/solid_agents/agents`.
+- Prompt instructions live in `app/solid_agents/prompts/.../instructions.txt.erb`.
+- Stage owners map directly to RubyLLM agent classes.
+
 ## Configuration
 
 ```ruby
-config.solid_agents.pi_command = "pi"
+config.solid_agents.default_model = "minimax/minimax-m2.7"
 config.solid_agents.default_test_command = "bin/rails test"
 config.solid_agents.max_iterations = 8
 ```
@@ -101,3 +107,17 @@ bundle install
 bundle exec rake test
 gem build solid_agents.gemspec
 ```
+
+## Secrets And Testing
+
+- Runtime credentials are loaded from environment variables only: `OPENROUTER_API_KEY` and optional `OPENROUTER_API_BASE`.
+- Keep real keys out of committed files and never commit `.env`.
+- Live LLM tests use VCR with `record: :once` and secret filtering.
+- Record cassettes intentionally with:
+
+```bash
+LIVE_LLM=1 OPENROUTER_API_KEY=... bundle exec rake test TEST=test/integration/solid_agents/ruby_llm_live_flow_test.rb
+```
+
+- To re-record a live interaction, delete the cassette file first and run the command again.
+- You can create a local `.env` from `.env.sample` and load it with `set -a; source .env; set +a`.

data/app/models/solid_agents/agent.rb

@@ -4,7 +4,7 @@ module SolidAgents
   class Agent < Record
     self.table_name = "solid_agents_agents"
 
-    ROLES = %w[alex betty chad david emma].freeze
+    ROLES = %w[alex betty chad david eddy].freeze
 
     has_many :runs, class_name: "SolidAgents::Run", dependent: :nullify
 

data/app/services/solid_agents/runs/prompt_builder.rb

@@ -7,8 +7,9 @@ module SolidAgents
     class PromptBuilder
       def self.call(run:, context:)
         <<~PROMPT
-          You are #{run.stage_owner} executing stage #{run.stage} for run #{run.id}.
-          Goal: move the workflow to the next stage with clear evidence.
+          Stage owner: #{run.stage_owner}
+          Stage: #{run.stage}
+          Run id: #{run.id}
 
           Constraints:
           - Repository path: #{run.repo_path}
@@ -17,11 +18,6 @@ module SolidAgents
           - Runtime: #{run.runtime}
           - Max iterations: #{run.max_iterations || SolidAgents.max_iterations}
 
-          Stage handoff contract:
-          - Produce concise notes for the next stage owner.
-          - Include reproducible evidence and command output.
-          - Respect repository rules from AGENTS.md.
-
           Context JSON:
           #{JSON.pretty_generate(context)}
         PROMPT

data/app/solid_agents/agents/alex.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SolidAgents
+  module Agents
+    class Alex < Base
+      def initialize(run:, context:)
+        super(run: run, context: context, owner: "alex")
+      end
+    end
+  end
+end

data/app/solid_agents/agents/base.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module SolidAgents
+  module Agents
+    class Base < RubyLLM::Agent
+      model SolidAgents.default_model, provider: SolidAgents.default_provider
+      tools SolidAgents::Tools::WorkflowGuideTool.new
+
+      attr_reader :run, :context, :owner
+
+      def initialize(run:, context:, owner:)
+        @run = run
+        @context = context
+        @owner = owner.to_s
+        super()
+      end
+
+      def call(prompt)
+        ask(prompt)
+      end
+
+      def instructions
+        template_path = File.expand_path("../prompts/#{owner}/instructions.txt.erb", __dir__)
+        ERB.new(File.read(template_path)).result(binding)
+      end
+    end
+  end
+end

data/app/solid_agents/agents/betty.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SolidAgents
+  module Agents
+    class Betty < Base
+      def initialize(run:, context:)
+        super(run: run, context: context, owner: "betty")
+      end
+    end
+  end
+end

data/app/solid_agents/agents/chad.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SolidAgents
+  module Agents
+    class Chad < Base
+      def initialize(run:, context:)
+        super(run: run, context: context, owner: "chad")
+      end
+    end
+  end
+end

data/app/solid_agents/agents/david.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SolidAgents
+  module Agents
+    class David < Base
+      def initialize(run:, context:)
+        super(run: run, context: context, owner: "david")
+      end
+    end
+  end
+end

data/app/solid_agents/agents/eddy.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SolidAgents
+  module Agents
+    class Eddy < Base
+      def initialize(run:, context:)
+        super(run: run, context: context, owner: "eddy")
+      end
+    end
+  end
+end

data/app/solid_agents/agents.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "agents/base"
+require_relative "agents/alex"
+require_relative "agents/betty"
+require_relative "agents/chad"
+require_relative "agents/david"
+require_relative "agents/eddy"
+
+module SolidAgents
+  module Agents
+    AGENT_CLASSES = {
+      "alex" => SolidAgents::Agents::Alex,
+      "betty" => SolidAgents::Agents::Betty,
+      "chad" => SolidAgents::Agents::Chad,
+      "david" => SolidAgents::Agents::David,
+      "eddy" => SolidAgents::Agents::Eddy
+    }.freeze
+
+    module_function
+
+    def for_owner(owner)
+      AGENT_CLASSES.fetch(owner.to_s, SolidAgents::Agents::Alex)
+    end
+  end
+end

data/app/solid_agents/prompts/alex/instructions.txt.erb

@@ -0,0 +1,3 @@
+You are Alex, the intake and triage agent for SolidAgents.
+Work stage: <%= run.stage %>
+Produce structured triage notes and a clean handoff summary for Betty.

data/app/solid_agents/prompts/betty/instructions.txt.erb

@@ -0,0 +1,3 @@
+You are Betty, the reproduction agent for SolidAgents.
+Work stage: <%= run.stage %>
+Prioritize failing automated reproduction and provide reproducible evidence.

data/app/solid_agents/prompts/chad/instructions.txt.erb

@@ -0,0 +1,3 @@
+You are Chad, the code fix implementation agent for SolidAgents.
+Work stage: <%= run.stage %>
+Apply minimal safe fixes and prepare concise rationale for David.

data/app/solid_agents/prompts/david/instructions.txt.erb

@@ -0,0 +1,3 @@
+You are David, the verification agent for SolidAgents.
+Work stage: <%= run.stage %>
+Validate automated and manual verification evidence before handoff.

data/app/solid_agents/prompts/eddy/instructions.txt.erb

@@ -0,0 +1,3 @@
+You are Eddy, the PR and CI shepherd agent for SolidAgents.
+Work stage: <%= run.stage %>
+Ensure PR quality, CI follow-through, and clear closure notes.

data/app/tools/solid_agents/tools/workflow_guide_tool.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SolidAgents
+  module Tools
+    class WorkflowGuideTool < RubyLLM::Tool
+      description "Returns workflow guidance for a given stage owner pair"
+
+      param :stage, type: "string", desc: "Current workflow stage"
+      param :owner, type: "string", desc: "Current stage owner"
+
+      def execute(stage:, owner:)
+        {
+          stage: stage,
+          owner: owner,
+          guidance: "Produce concise evidence, then hand off cleanly to the next stage owner.",
+          required_outputs: ["notes", "artifacts", "handoff_summary"]
+        }
+      end
+    end
+  end
+end

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

@@ -18,7 +18,8 @@ module SolidAgents
           "",
           '\\1# Configure Solid Agent',
           '\\1config.solid_agents.connects_to = { database: { writing: :solid_agents } }',
-          '\\1config.solid_agents.default_runtime = :pi'
+          '\\1config.solid_agents.default_runtime = :ruby_llm',
+          '\\1config.solid_agents.default_provider = :openrouter'
         ].join("\n")
       end
     end

data/lib/generators/solid_agents/install/templates/config/initializers/solid_agents.rb

@@ -4,7 +4,12 @@ Rails.application.configure do
   # Optional: override in specific environments.
   # config.solid_agents.connects_to = { database: { writing: :solid_agents } }
 
-  config.solid_agents.pi_command = ENV.fetch("SOLID_AGENTS_PI_COMMAND", "pi")
+  # Configure LLM access with environment variables:
+  # OPENROUTER_API_KEY="..."
+  # OPENROUTER_API_BASE="https://openrouter.ai/api/v1" # optional
+
+  config.solid_agents.default_model = ENV.fetch("SOLID_AGENTS_DEFAULT_MODEL", "minimax/minimax-m2.7")
+  config.solid_agents.default_provider = :openrouter
   config.solid_agents.default_test_command = ENV.fetch("SOLID_AGENTS_TEST_COMMAND", "bin/rails test")
   config.solid_agents.max_iterations = ENV.fetch("SOLID_AGENTS_MAX_ITERATIONS", 8).to_i
 end

data/lib/generators/solid_agents/install/templates/db/agent_schema.rb

@@ -5,7 +5,7 @@ ActiveRecord::Schema[6.1].define do
     t.string :key, null: false
     t.string :name, null: false
     t.string :role, null: false, default: "alex"
-    t.string :runtime, null: false, default: "pi"
+    t.string :runtime, null: false, default: "ruby_llm"
     t.boolean :enabled, null: false, default: true
     t.string :environment
     t.string :model
@@ -28,7 +28,7 @@ ActiveRecord::Schema[6.1].define do
     t.string :status, null: false, default: "queued"
     t.string :stage, null: false, default: "received"
     t.string :stage_owner, null: false, default: "alex"
-    t.string :runtime, null: false, default: "pi"
+    t.string :runtime, null: false, default: "ruby_llm"
     t.string :environment, null: false
     t.string :repo_path
     t.string :base_branch

data/lib/solid_agents/engine.rb

@@ -4,6 +4,7 @@ module SolidAgents
   class Engine < ::Rails::Engine
     config.root = File.expand_path("../..", __dir__)
     isolate_namespace SolidAgents
+    paths.add "app/solid_agents", eager_load: true
 
     config.solid_agents = ActiveSupport::OrderedOptions.new
 
@@ -12,5 +13,15 @@ module SolidAgents
         SolidAgents.public_send(:"#{name}=", value)
       end
     end
+
+    initializer "solid_agents.ruby_llm" do
+      SolidAgents.openrouter_api_key ||= ENV["OPENROUTER_API_KEY"]
+      SolidAgents.openrouter_api_base ||= ENV["OPENROUTER_API_BASE"]
+
+      RubyLLM.configure do |config|
+        config.openrouter_api_key = SolidAgents.openrouter_api_key if SolidAgents.openrouter_api_key.present?
+        config.openrouter_api_base = SolidAgents.openrouter_api_base if SolidAgents.openrouter_api_base.present?
+      end
+    end
   end
 end

data/lib/solid_agents/runtime/ruby_llm_adapter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module SolidAgents
+  module Runtime
+    class RubyLlmAdapter < Adapter
+      def execute(run:, prompt:)
+        agent_class = SolidAgents::Agents.for_owner(run.stage_owner)
+        agent = agent_class.new(run: run, context: run.prompt_payload || {})
+        response = agent.call(prompt)
+        output = response.respond_to?(:content) ? response.content.to_s : response.to_s
+
+        Result.new(ok: true, output: output, error: nil, metadata: {agent_class: agent_class.name, stage: run.stage, owner: run.stage_owner})
+      rescue StandardError => e
+        Result.new(ok: false, output: nil, error: e.message, metadata: {agent_class: agent_class&.name, stage: run.stage, owner: run.stage_owner, exception: e.class.name})
+      end
+    end
+  end
+end

data/lib/solid_agents/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SolidAgents
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/lib/solid_agents/workflow.rb

@@ -21,9 +21,9 @@ module SolidAgents
       "repro_manual" => "betty",
       "fixing" => "chad",
       "verifying" => "david",
-      "pr_opened" => "emma",
-      "ci_wait" => "emma",
-      "done" => "emma"
+      "pr_opened" => "eddy",
+      "ci_wait" => "eddy",
+      "done" => "eddy"
     }.freeze
 
     FINAL_STAGES = ["done", "failed"].freeze

data/lib/solid_agents.rb

@@ -3,21 +3,24 @@
 require_relative "solid_agents/version"
 require_relative "solid_agents/workflow"
 require_relative "solid_agents/runtime/adapter"
-require_relative "solid_agents/runtime/pi_adapter"
+require_relative "solid_agents/runtime/ruby_llm_adapter"
 require_relative "solid_agents/engine"
 
 module SolidAgents
   mattr_accessor :connects_to
   mattr_accessor :base_controller_class, default: "::ActionController::Base"
-  mattr_accessor :default_runtime, default: :pi
-  mattr_accessor :pi_command, default: "pi"
+  mattr_accessor :default_runtime, default: :ruby_llm
+  mattr_accessor :default_model, default: "minimax/minimax-m2.7"
+  mattr_accessor :default_provider, default: :openrouter
+  mattr_accessor :openrouter_api_key
+  mattr_accessor :openrouter_api_base
   mattr_accessor :default_test_command, default: "bin/rails test"
   mattr_accessor :max_iterations, default: 8
 
   class << self
     def runtime_adapter(runtime)
       case runtime.to_sym
-      when :pi then SolidAgents::Runtime::PiAdapter.new
+      when :ruby_llm then SolidAgents::Runtime::RubyLlmAdapter.new
       else
         raise ArgumentError, "Unsupported runtime: #{runtime.inspect}"
       end
@@ -28,3 +31,6 @@ module SolidAgents
     end
   end
 end
+
+require_relative "../app/tools/solid_agents/tools/workflow_guide_tool"
+require_relative "../app/solid_agents/agents"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_agents
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Kaka Ruto
@@ -93,6 +93,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -107,8 +121,36 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
 description: Solid Agent stores agent runs in its own database and dispatches staged
-  workflow tasks to the pi runtime with a built-in Rails UI.
+  workflow tasks to the RubyLLM runtime with a built-in Rails UI.
 email:
 - kr@kakaruto.com
 executables: []
@@ -136,6 +178,19 @@ files:
 - app/services/solid_agents/runs/dispatch.rb
 - app/services/solid_agents/runs/executor.rb
 - app/services/solid_agents/runs/prompt_builder.rb
+- app/solid_agents/agents.rb
+- app/solid_agents/agents/alex.rb
+- app/solid_agents/agents/base.rb
+- app/solid_agents/agents/betty.rb
+- app/solid_agents/agents/chad.rb
+- app/solid_agents/agents/david.rb
+- app/solid_agents/agents/eddy.rb
+- app/solid_agents/prompts/alex/instructions.txt.erb
+- app/solid_agents/prompts/betty/instructions.txt.erb
+- app/solid_agents/prompts/chad/instructions.txt.erb
+- app/solid_agents/prompts/david/instructions.txt.erb
+- app/solid_agents/prompts/eddy/instructions.txt.erb
+- app/tools/solid_agents/tools/workflow_guide_tool.rb
 - app/views/layouts/solid_agents/_style.html.erb
 - app/views/layouts/solid_agents/application.html.erb
 - app/views/solid_agents/agents/edit.html.erb
@@ -152,7 +207,7 @@ files:
 - lib/solid_agents.rb
 - lib/solid_agents/engine.rb
 - lib/solid_agents/runtime/adapter.rb
-- lib/solid_agents/runtime/pi_adapter.rb
+- lib/solid_agents/runtime/ruby_llm_adapter.rb
 - lib/solid_agents/version.rb
 - lib/solid_agents/workflow.rb
 homepage: https://github.com/kaka-ruto/solid_agents

data/lib/solid_agents/runtime/pi_adapter.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module SolidAgents
-  module Runtime
-    class PiAdapter < Adapter
-      def execute(run:, prompt:)
-        command = [SolidAgents.pi_command.to_s, "agent", "run", "--json", "--message", prompt]
-        run_command(*command).tap do |result|
-          result.metadata[:stage] = run.stage
-          result.metadata[:owner] = run.stage_owner
-        end
-      end
-    end
-  end
-end