solid_agent 0.0.0 → 0.2.0

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class CreateAgentRuns < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :agent_runs do |t|
+      # What the run executed against (an Agent record, a workflow, any
+      # AR subject) — optional, so bare executors can still record runs.
+      t.references :runnable, polymorphic: true, index: true
+
+      # Correlation keys shared with agent_contexts/agent_generations and
+      # telemetry traces.
+      t.string :agent_name
+      t.string :action_name
+      t.string :trace_id
+
+      t.string :status, null: false, default: "pending"
+
+      t.text :input_prompt
+      t.jsonb :input_params, default: {}
+      t.text :output
+      t.jsonb :output_metadata, default: {}
+      t.text :error_message
+
+      # Append-only progress events ({at, eid, kind, label, status,
+      # detail, duration_ms}) streamed to pollers mid-run.
+      t.jsonb :events, default: []
+
+      # 8-char fingerprint of the instructions the run executed under —
+      # the cohort grouping key for instruction/model comparisons.
+      t.string :instructions_digest
+
+      t.integer :input_tokens, default: 0
+      t.integer :output_tokens, default: 0
+      t.integer :duration_ms
+      t.datetime :started_at
+      t.datetime :completed_at
+
+      t.timestamps
+    end
+
+    add_index :agent_runs, :status
+    add_index :agent_runs, :trace_id
+    add_index :agent_runs, :instructions_digest
+    add_index :agent_runs, :created_at
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# SolidAgent Configuration
+#
+# This initializer configures SolidAgent for your application.
+# SolidAgent provides database-backed context management, tool schemas,
+# and real-time streaming updates for ActiveAgent agents.
+
+# You can customize the default model classes used by has_context:
+#
+# SolidAgent.configure do |config|
+#   config.context_class = "AgentContext"
+#   config.message_class = "AgentMessage"
+#   config.generation_class = "AgentGeneration"
+# end
+
+# Include SolidAgent concerns in your ApplicationAgent:
+#
+#   class ApplicationAgent < ActiveAgent::Base
+#     include SolidAgent::HasContext
+#     include SolidAgent::HasTools
+#     include SolidAgent::StreamsToolUpdates
+#   end
+#
+# Or include them selectively in specific agents:
+#
+#   class WritingAssistantAgent < ApplicationAgent
+#     include SolidAgent::HasContext
+#     has_context
+#
+#     def improve
+#       create_context(contextable: params[:document])
+#       prompt
+#     end
+#   end
+#
+#   class ResearchAgent < ApplicationAgent
+#     include SolidAgent::HasContext
+#     include SolidAgent::HasTools
+#     include SolidAgent::StreamsToolUpdates
+#
+#     has_context
+#     has_tools :navigate, :extract_text
+#
+#     tool_description :navigate, ->(args) { "Visiting #{args[:url]}..." }
+#
+#     def research
+#       create_context(contextable: params[:user])
+#       prompt(tools: tools)
+#     end
+#   end

data/lib/generators/solid_agent/manifest/manifest_generator.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module SolidAgent
+  module Generators
+    class ManifestGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generates a .agent.md manifest file for an agent"
+
+      class_option :model, type: :string, default: "anthropic/claude-sonnet-4-20250514",
+        desc: "Model identifier (provider/model format)"
+
+      class_option :tools, type: :array, default: [],
+        desc: "Tool names to include"
+
+      class_option :template, type: :string, default: nil,
+        desc: "Use a preset template (research, assistant, reviewer, chat)"
+
+      class_option :format, type: :string, default: "agent_md",
+        desc: "Output format (agent_md, dotprompt)"
+
+      class_option :context, type: :string, default: nil,
+        desc: "Contextual param key for HasContext (e.g., user, document)"
+
+      class_option :description, type: :string, default: nil,
+        desc: "Agent description"
+
+      def create_manifest_file
+        @model = options[:model]
+        @tools = options[:tools]
+        @preset = options[:template]
+        @format = options[:format].to_sym
+        @contextual = options[:context]
+        @description = options[:description] || default_description
+
+        # Apply preset template configuration
+        apply_preset if @preset
+
+        case @format
+        when :agent_md
+          template "agent.md.erb", manifest_path(".agent.md")
+        when :dotprompt
+          template "prompt.erb", manifest_path(".prompt")
+        else
+          template "agent.md.erb", manifest_path(".agent.md")
+        end
+      end
+
+      def show_next_steps
+        say ""
+        say "Manifest created successfully!", :green
+        say ""
+        say "File generated:"
+        say "  #{manifest_path(extension_for_format)}"
+        say ""
+        say "Usage:", :yellow
+        say "  # Parse the manifest"
+        say "  manifest = SolidAgent::AgentManifest.parse(\"#{manifest_path(extension_for_format)}\")"
+        say ""
+        say "  # Load as agent class"
+        say "  klass = SolidAgent::AgentManifest.load_agent(\"#{manifest_path(extension_for_format)}\")"
+        say ""
+        say "  # Validate the manifest"
+        say "  SolidAgent::AgentManifest.validate!(\"#{manifest_path(extension_for_format)}\")"
+        say ""
+
+        if @tools.any?
+          say "Tool stubs added. Implement the tool methods in your agent class:", :yellow
+          @tools.each do |tool|
+            say "  def #{tool}(args)"
+            say "    # Implement #{tool} logic"
+            say "  end"
+          end
+          say ""
+        end
+      end
+
+      private
+
+      def file_name
+        name.underscore
+      end
+
+      def class_name
+        name.camelize
+      end
+
+      def agent_class_name
+        "#{class_name}Agent"
+      end
+
+      def agent_title
+        class_name.gsub(/([A-Z])/, ' \1').strip
+      end
+
+      def manifest_path(extension)
+        "app/views/#{file_name}_agent/agent#{extension}"
+      end
+
+      def extension_for_format
+        case @format
+        when :agent_md then ".agent.md"
+        when :dotprompt then ".prompt"
+        else ".agent.md"
+        end
+      end
+
+      def default_description
+        "#{agent_title} agent"
+      end
+
+      def apply_preset
+        case @preset.to_s
+        when "research"
+          @description ||= "Research and analyze topics thoroughly, providing well-sourced information"
+          @tools = %w[search fetch analyze] if @tools.empty?
+          @preset_instructions = research_instructions
+        when "assistant"
+          @description ||= "General-purpose assistant for answering questions and helping with tasks"
+          @preset_instructions = assistant_instructions
+        when "reviewer"
+          @description ||= "Review and provide feedback on content, code, or documents"
+          @tools = %w[read_file analyze_diff] if @tools.empty?
+          @preset_instructions = reviewer_instructions
+        when "chat"
+          @description ||= "Conversational agent for multi-turn dialogue"
+          @contextual ||= "user"
+          @preset_instructions = chat_instructions
+        end
+      end
+
+      def research_instructions
+        <<~INSTRUCTIONS
+          You are a thorough research assistant. Your goal is to provide accurate,
+          well-sourced information on any topic.
+
+          ## Guidelines
+
+          - Always cite your sources when providing information
+          - Present multiple perspectives when topics are controversial
+          - Acknowledge uncertainty when information is incomplete
+          - Break down complex topics into understandable explanations
+          - Verify facts before presenting them
+        INSTRUCTIONS
+      end
+
+      def assistant_instructions
+        <<~INSTRUCTIONS
+          You are a helpful assistant. Your goal is to assist users with their
+          questions and tasks effectively.
+
+          ## Guidelines
+
+          - Be concise but thorough in your responses
+          - Ask clarifying questions when requests are ambiguous
+          - Provide step-by-step guidance for complex tasks
+          - Offer alternatives when appropriate
+        INSTRUCTIONS
+      end
+
+      def reviewer_instructions
+        <<~INSTRUCTIONS
+          You are a thorough reviewer. Your goal is to provide constructive feedback
+          that helps improve the quality of the work.
+
+          ## Guidelines
+
+          - Focus on both strengths and areas for improvement
+          - Be specific with your feedback
+          - Provide actionable suggestions
+          - Maintain a constructive and respectful tone
+          - Consider the context and goals of the work
+        INSTRUCTIONS
+      end
+
+      def chat_instructions
+        <<~INSTRUCTIONS
+          You are a conversational assistant. Engage in helpful, natural dialogue
+          while maintaining context from previous messages.
+
+          ## Guidelines
+
+          - Remember context from earlier in the conversation
+          - Ask follow-up questions to better understand the user's needs
+          - Be friendly and approachable
+          - Know when to be concise vs. detailed based on the question
+        INSTRUCTIONS
+      end
+
+      def default_instructions
+        @preset_instructions || <<~INSTRUCTIONS
+          You are the #{agent_title} agent.
+
+          ## Instructions
+
+          TODO - Add your agent's instructions here.
+
+          ## Guidelines
+
+          - Be helpful and accurate
+          - Follow the user's instructions carefully
+          - Ask for clarification when needed
+        INSTRUCTIONS
+      end
+    end
+  end
+end

data/lib/generators/solid_agent/manifest/templates/agent.md.erb

@@ -0,0 +1,39 @@
+---
+name: <%= file_name %>
+version: 1.0.0
+description: <%= @description %>
+model: <%= @model %>
+<% if @tools.any? -%>
+
+tools:
+<% @tools.each do |tool| -%>
+  - name: <%= tool %>
+    description: "TODO - Describe what <%= tool %> does"
+    inputSchema:
+      type: object
+      properties:
+        query:
+          type: string
+          description: "Input for <%= tool %>"
+      required:
+        - query
+<% end -%>
+<% end -%>
+
+activeagent:
+  class_name: <%= agent_class_name %>
+  concerns:
+<% if @contextual -%>
+    - has_context:
+        contextual: <%= @contextual %>
+<% end -%>
+<% if @tools.any? -%>
+    - has_tools: [<%= @tools.join(', ') %>]
+<% end -%>
+---
+
+# <%= agent_title %>
+
+<%= @description %>
+
+<%= default_instructions %>

data/lib/generators/solid_agent/manifest/templates/prompt.erb

@@ -0,0 +1,13 @@
+---
+name: <%= file_name %>
+model: <%= @model %>
+description: <%= @description %>
+<% if @tools.any? -%>
+tools:
+<% @tools.each do |tool| -%>
+  - <%= tool %>
+<% end -%>
+<% end -%>
+---
+
+<%= default_instructions %>

data/lib/generators/solid_agent/reasons/reasons_generator.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module SolidAgent
+  module Generators
+    class ReasonsGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Adds reasoning columns to an existing generation model for extended thinking support"
+
+      argument :model_name, type: :string, default: "AgentGeneration",
+        desc: "The model to add reasoning columns to"
+
+      class_option :content_column, type: :string, default: "reasoning_content",
+        desc: "Column name for storing reasoning content"
+
+      class_option :tokens_column, type: :string, default: "reasoning_tokens",
+        desc: "Column name for storing reasoning token count"
+
+      class_option :metadata_column, type: :string, default: "reasoning_metadata",
+        desc: "Column name for storing reasoning metadata (JSON)"
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_migration
+        @table_name = model_name.underscore.pluralize
+        @content_column = options[:content_column]
+        @tokens_column = options[:tokens_column]
+        @metadata_column = options[:metadata_column]
+
+        migration_template(
+          "add_reasoning_columns.rb.erb",
+          "db/migrate/add_reasoning_to_#{@table_name}.rb"
+        )
+      end
+
+      def add_concern_to_model
+        model_file = "app/models/#{model_name.underscore}.rb"
+
+        return unless File.exist?(model_file)
+
+        inject_into_class model_file, model_name do
+          "  include SolidAgent::Reasonable\n\n"
+        end
+
+        say "Added SolidAgent::Reasonable to #{model_name}", :green
+      end
+
+      def show_post_install_message
+        say ""
+        say "Reasoning support added to #{model_name}!", :green
+        say ""
+        say "Next steps:", :yellow
+        say "  1. Run migrations: rails db:migrate"
+        say "  2. Use reasoning in your agents:"
+        say ""
+        say "     class MyAgent < ApplicationAgent"
+        say "       include SolidAgent::HasReasons"
+        say "       include SolidAgent::HasContext"
+        say ""
+        say "       has_reasons auto_capture: true, persist: true"
+        say ""
+        say "       def analyze"
+        say "         result = prompt("
+        say "           messages: messages,"
+        say "           extended_thinking: true"
+        say "         )"
+        say ""
+        say "         # Access reasoning"
+        say "         last_reasoning.content"
+        say "         total_reasoning_tokens"
+        say "       end"
+        say "     end"
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/solid_agent/reasons/templates/add_reasoning_columns.rb.erb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class AddReasoningTo<%= @table_name.camelize %> < ActiveRecord::Migration[7.0]
+  def change
+    add_column :<%= @table_name %>, :<%= @content_column %>, :text
+    add_column :<%= @table_name %>, :<%= @tokens_column %>, :integer, default: 0
+    add_column :<%= @table_name %>, :<%= @metadata_column %>, :jsonb, default: {}
+
+    add_index :<%= @table_name %>, :<%= @tokens_column %>,
+      name: "index_<%= @table_name %>_on_<%= @tokens_column %>"
+  end
+end

data/lib/generators/solid_agent/tool/templates/tool.json.erb

@@ -0,0 +1,19 @@
+{
+  "type": "function",
+  "name": "<%= name %>",
+  "description": "<%= @tool_description %>",
+  "parameters": {
+    "type": "object",
+    "properties": {
+<%- @parameters.each_with_index do |param, index| -%>
+      "<%= param[:name] %>": {
+        "type": "<%= param[:type] %>",
+        "description": "<%= param[:description] %>"
+      }<%= index < @parameters.length - 1 ? ',' : '' %>
+<%- end -%>
+<%- if @parameters.empty? -%>
+<%- end -%>
+    },
+    "required": [<%= @parameters.select { |p| p[:required] }.map { |p| "\"#{p[:name]}\"" }.join(", ") %>]
+  }
+}

data/lib/generators/solid_agent/tool/tool_generator.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module SolidAgent
+  module Generators
+    class ToolGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generates a tool schema JSON template and optional tool method for an agent"
+
+      argument :agent_name, type: :string, required: true,
+        desc: "The agent class name (e.g., ResearchAgent)"
+
+      class_option :parameters, type: :array, default: [],
+        desc: "Tool parameters in name:type:required format (e.g., url:string:required query:string)"
+
+      class_option :description, type: :string, default: "",
+        desc: "Tool description"
+
+      class_option :inline, type: :boolean, default: false,
+        desc: "Generate inline tool definition instead of JSON template"
+
+      def create_tool_template
+        if options[:inline]
+          say "Inline tool definition for #{agent_name}:", :green
+          say ""
+          say inline_tool_definition
+          say ""
+        else
+          @tool_description = options[:description].presence || "#{name.humanize} tool"
+          @parameters = parse_parameters
+
+          template "tool.json.erb", tool_template_path
+          say "Created tool template: #{tool_template_path}", :green
+        end
+      end
+
+      def show_method_stub
+        say ""
+        say "Add this method to your #{agent_name}:", :yellow
+        say ""
+        say tool_method_stub
+        say ""
+
+        if options[:inline]
+          say "Add this to your agent class:", :yellow
+          say ""
+          say inline_tool_definition
+          say ""
+        else
+          say "Don't forget to register the tool in your agent:", :yellow
+          say ""
+          say "  has_tools :#{name}"
+          say ""
+        end
+      end
+
+      private
+
+      def tool_template_path
+        "app/views/#{agent_name.underscore}/tools/#{name}.json.erb"
+      end
+
+      def parse_parameters
+        options[:parameters].map do |param|
+          parts = param.split(":")
+          {
+            name: parts[0],
+            type: parts[1] || "string",
+            required: parts[2] == "required",
+            description: parts[3] || "The #{parts[0].humanize.downcase}"
+          }
+        end
+      end
+
+      def tool_method_stub
+        params_signature = @parameters.map do |p|
+          if p[:required]
+            "#{p[:name]}:"
+          else
+            "#{p[:name]}: nil"
+          end
+        end.join(", ")
+
+        params_log = @parameters.map { |p| "\#{#{p[:name]}}" }.join(", ")
+
+        <<~RUBY
+          # Tool method: #{name.humanize}
+          def #{name}(#{params_signature})
+            Rails.logger.info "[#{agent_name}] Tool called: #{name}(#{params_log})"
+
+            # TODO: Implement tool logic
+            { success: true }
+          rescue => e
+            Rails.logger.error "[#{agent_name}] #{name.humanize} error: \#{e.message}"
+            { success: false, error: e.message }
+          end
+        RUBY
+      end
+
+      def inline_tool_definition
+        params_block = @parameters.map do |p|
+          required_str = p[:required] ? ", required: true" : ""
+          "    parameter :#{p[:name]}, type: :#{p[:type]}#{required_str}, description: \"#{p[:description]}\""
+        end.join("\n")
+
+        <<~RUBY
+          tool :#{name} do
+            description "#{@tool_description}"
+          #{params_block}
+          end
+        RUBY
+      end
+    end
+  end
+end