rails_agent_console 0.1.0

data/lib/rails_agent_console/agent.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+module RailsAgentConsole
+  class Agent
+    attr_reader :config, :ui, :history
+
+    def initialize(config = RailsAgentConsole.configuration, ui: nil, history: nil)
+      @config = config
+      @ui = ui || UI.new(config)
+      @history = history || History.new
+    end
+
+    def run(prompt, write: config.write_mode?)
+      return usage if prompt.to_s.strip.empty?
+
+      ui.heading "Inspecting application..."
+      proposal = propose(prompt, write: write)
+      return decline(proposal, write: write) if proposal.empty?
+
+      present(proposal)
+
+      return refuse_or_repair(prompt, proposal, write: write) unless proposal.safe?
+      return unless confirmed?(proposal)
+
+      execute(prompt, proposal, write: write)
+    rescue ConfigurationError, ProviderError, InvalidResponseError => e
+      ui.failure e.message
+      nil
+    end
+
+    def ask(question)
+      return usage if question.to_s.strip.empty?
+
+      ensure_configured!
+      ui.heading "Thinking..."
+      answer = provider.chat(
+        system: Prompt.explain_system(question),
+        messages: [{ role: "user", content: Prompt::FollowUp.for_ask(question.to_s, history) }]
+      )
+      ui.blank
+      ui.say answer.strip
+      ui.blank
+      nil
+    rescue ConfigurationError, ProviderError, InvalidResponseError => e
+      ui.failure e.message
+      nil
+    end
+
+    def explain(code, question: nil)
+      source = code.is_a?(String) ? code : safe_inspect(code)
+      return usage if source.to_s.strip.empty?
+
+      ask(Prompt.explain_code_user(source, question))
+    end
+
+    def propose(prompt, write: config.write_mode?, focus: prompt)
+      ensure_configured!
+      request = Prompt::Dates.annotate(prompt.to_s)
+      request = Prompt::FollowUp.annotate(request, history.last&.code) if prompt.equal?(focus)
+      raw = provider.chat(
+        system: Prompt.query_system(focus, write_mode: write),
+        messages: history.messages + [{ role: "user", content: request }]
+      )
+      Proposal.parse(raw, write_mode: write)
+    end
+
+    def provider
+      @provider ||= Providers.build(config)
+    end
+
+    def reset_provider!
+      @provider = nil
+      self
+    end
+
+    def reset!
+      history.clear
+      Executor.reset!
+      @provider = nil
+      self
+    end
+
+    private
+
+    def ensure_configured!
+      return config.validate! if config.api_key?
+
+      Setup.run(ui: ui) if Setup.interactive?(config)
+      config.validate!
+    end
+
+    def present(proposal)
+      narrate(proposal.models.first(3))
+      ui.say ui.bold(proposal.writes? ? "Proposed command:" : "Proposed query:")
+      ui.blank
+      ui.code proposal.code
+      ui.blank
+      present_notes(proposal)
+    end
+
+    def present_notes(proposal)
+      ui.note proposal.explanation if proposal.explanation
+      proposal.assumptions.each { |assumption| ui.note "- #{assumption}" }
+      proposal.corrections.each { |correction| ui.note "Corrected: #{correction}" }
+    end
+
+    def narrate(models)
+      ui.tree(Schema.tree(models)) if models.any?
+      ui.blank
+    end
+
+    def decline(proposal, write:)
+      ui.blank
+      ui.warn "No query to run."
+      ui.note(proposal.explanation || retry_hint(proposal, write: write))
+      ui.blank
+      nil
+    end
+
+    def refuse(proposal, write:)
+      ui.blank
+      ui.warn "Refusing to run this code."
+      proposal.violations.each { |violation| ui.say "  - #{violation}" }
+      ui.blank
+      ui.note retry_hint(proposal, write: write)
+      nil
+    end
+
+    def retry_hint(proposal, write:)
+      if proposal.writes? && !write
+        "Read-only mode is on. Use `ai!` for a single write, or set " \
+          "RailsAgentConsole.config.write_mode = true."
+      else
+        "Rephrase the request, or allow the call with " \
+          "RailsAgentConsole.config.extra_allowed_methods << #{unknown_call(proposal).inspect}."
+      end
+    end
+
+    def unknown_call(proposal)
+      proposal.validation.unknown.first || "method_name"
+    end
+
+    def confirmed?(proposal)
+      return true if config.auto_confirm?
+      return destructive_confirmed?(proposal) if proposal.destructive?
+
+      report_preflight(proposal)
+      ui.blank
+      ui.yes?("Execute?")
+    end
+
+    def report_preflight(proposal)
+      count = Executor.preflight_count(proposal.code)
+      return if count.nil?
+
+      ui.blank
+      ui.say "Found #{count} #{count == 1 ? "record" : "records"}."
+    end
+
+    def destructive_confirmed?(proposal)
+      estimate = Executor.impact_estimate(proposal.code)
+      ui.blank
+      ui.warn "DESTRUCTIVE OPERATION"
+      ui.say "  This will change approximately #{estimate} records." if estimate
+      ui.say "  Affected calls: #{proposal.validation.writes.join(", ")}"
+      ui.blank
+      word = config.destructive_confirmation_word
+      answer = ui.ask("Type \"#{word}\" to continue:")
+      return true if answer.to_s.strip == word
+
+      ui.note "Cancelled."
+      false
+    end
+
+    def execute(prompt, proposal, write:, attempts_left: config.max_repair_attempts.to_i, attempted: [])
+      outcome = Executor.run(proposal.code)
+      ui.blank
+      summary = outcome.ok? ? report_success(outcome) : report_failure(outcome)
+      remember(prompt, proposal, summary)
+
+      if !outcome.ok? && attempts_left.positive?
+        tried = attempted + [attempt(proposal, failure_reason(outcome, proposal.code))]
+        repair(prompt, tried, write: write, attempts_left: attempts_left)
+      else
+        ui.blank
+        outcome.value
+      end
+    end
+
+    def attempt(proposal, reason)
+      { code: proposal.code, reason: reason }
+    end
+
+    def failure_reason(outcome, code)
+      error = outcome.error
+      message = "#{error.class}: #{error.message.to_s.lines.first.to_s.strip}"
+      hint = Diagnosis.hint(code, error.message)
+      hint ? "#{message}\n#{hint}" : message
+    end
+
+    def refuse_or_repair(prompt, proposal, write:, attempted: [], attempts_left: config.max_repair_attempts.to_i)
+      refuse(proposal, write: write)
+      return unless attempts_left.positive? && proposal.validation.repairable?
+
+      tried = attempted + [attempt(proposal, refusal_reason(proposal))]
+      repair(prompt, tried, write: write, attempts_left: attempts_left)
+    end
+
+    def refusal_reason(proposal)
+      "The code was refused before it ran: #{proposal.violations.join("; ")}"
+    end
+
+    def repair(prompt, attempted, write:, attempts_left:)
+      ui.blank
+      ui.heading "Fixing the query..."
+      fixed = propose(Prompt.repair_user(prompt, attempted), write: write, focus: prompt)
+      return unrepairable(fixed, attempted) if fixed.empty? || tried?(fixed, attempted)
+
+      present(fixed)
+
+      if fixed.safe?
+        return unless confirmed?(fixed)
+
+        execute(prompt, fixed, write: write, attempts_left: attempts_left - 1, attempted: attempted)
+      else
+        refuse_or_repair(prompt, fixed, write: write, attempted: attempted, attempts_left: attempts_left - 1)
+      end
+    end
+
+    def tried?(proposal, attempted)
+      attempted.any? { |earlier| earlier[:code] == proposal.code }
+    end
+
+    def unrepairable(fixed, attempted)
+      ui.blank
+      ui.note(if tried?(fixed, attempted)
+                "The model came back with a query it had already tried."
+              else
+                fixed.explanation || "No corrected query to run."
+              end)
+      ui.blank
+      nil
+    end
+
+    def report_success(outcome)
+      summary = Executor.describe(outcome.value)
+      ui.success "#{summary} in #{format("%.0f", outcome.duration * 1000)}ms"
+      ui.note outcome.note if outcome.note
+      summary
+    end
+
+    def report_failure(outcome)
+      ui.failure "#{outcome.error.class}: #{outcome.error.message.to_s.lines.first}"
+      "failed: #{outcome.error.class}"
+    end
+
+    def remember(prompt, proposal, summary)
+      history.add(prompt: prompt, code: proposal.code,
+                  explanation: proposal.explanation, outcome: summary)
+    end
+
+    def usage
+      ui.note 'Usage: ai "how many users signed up this month?"'
+      nil
+    end
+
+    def safe_inspect(value)
+      if Executor.relation?(value)
+        "An ActiveRecord::Relation on #{value.klass.name}, generating:\n#{value.to_sql}"
+      else
+        value.inspect
+      end
+    rescue StandardError
+      value.to_s
+    end
+  end
+end

data/lib/rails_agent_console/cli.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module RailsAgentConsole
+  class CLI
+    USAGE = <<~TEXT
+      Usage: rails-agent <command>
+
+        configure   Pick a provider and store an API key in ~/.rails_agent_console/config
+        schema      Print the schema context the agent sends to the model (needs a Rails app)
+        doctor      Show the resolved configuration and check connectivity
+        version     Print the gem version
+    TEXT
+
+    def initialize(argv, config: RailsAgentConsole.configuration, ui: nil)
+      @argv = argv
+      @config = config
+      @ui = ui || UI.new(config)
+    end
+
+    def run
+      case @argv.first
+      when "configure" then configure
+      when "schema" then schema
+      when "doctor" then doctor
+      when "version", "-v", "--version" then version
+      when nil, "help", "-h", "--help" then help
+      else
+        @ui.failure "Unknown command #{@argv.first.inspect}"
+        help
+        1
+      end
+    end
+
+    private
+
+    def configure
+      Setup.run(config: @config, ui: @ui) ? 0 : 1
+    end
+
+    def schema
+      return 1 unless load_rails_app
+
+      @ui.say Schema.context
+      0
+    end
+
+    def doctor
+      @ui.heading "Rails Agent Console #{VERSION}"
+      @ui.say "provider:    #{@config.provider}"
+      @ui.say "model:       #{@config.model}"
+      @ui.say "api key:     #{key_status}"
+      @ui.say "config file: #{Credentials.path}#{" (not created yet)" unless Credentials.exist?}"
+      @ui.say "mode:        #{@config.write_mode? ? "write" : "read-only"}"
+      @ui.blank
+      probe
+    end
+
+    def probe
+      unless @config.api_key?
+        @ui.failure "No API key. Run `rails-agent configure`."
+        return 1
+      end
+
+      answer = Providers.build(@config).chat(
+        system: "You are a health check. Answer with the single word: ok",
+        messages: [{ role: "user", content: "ping" }]
+      )
+      @ui.success "#{@config.provider} responded: #{answer.strip[0, 40]}"
+      0
+    rescue Error => e
+      @ui.failure e.message
+      1
+    end
+
+    def key_status
+      return "not set" unless @config.api_key
+
+      env_key = Configuration::ENV_KEYS[@config.provider]
+      source = ENV[env_key].to_s.empty? ? "config file" : env_key
+      "#{mask(@config.api_key)} (from #{source})"
+    end
+
+    def mask(key)
+      return "****" if key.to_s.length < 8
+
+      "#{key[0, 3]}#{"*" * 10}#{key[-4, 4]}"
+    end
+
+    def load_rails_app
+      path = File.expand_path("config/environment.rb", Dir.pwd)
+      unless File.exist?(path)
+        @ui.failure "No config/environment.rb here - run this from a Rails application root."
+        return false
+      end
+
+      ENV["RAILS_ENV"] ||= "development"
+      require path
+      true
+    rescue StandardError, LoadError => e
+      @ui.failure "Could not load the Rails application: #{e.message}"
+      false
+    end
+
+    def help
+      @ui.say USAGE
+      0
+    end
+
+    def version
+      @ui.say VERSION
+      0
+    end
+  end
+end

data/lib/rails_agent_console/configuration.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module RailsAgentConsole
+  class Configuration
+    PROVIDERS = %i[openai anthropic gemini ollama].freeze
+
+    DEFAULT_MODELS = {
+      openai: "gpt-4o-mini",
+      anthropic: "claude-3-5-sonnet-latest",
+      gemini: "gemini-2.0-flash",
+      ollama: "qwen2.5-coder:7b"
+    }.freeze
+
+    ENV_KEYS = {
+      openai: "OPENAI_API_KEY",
+      anthropic: "ANTHROPIC_API_KEY",
+      gemini: "GEMINI_API_KEY",
+      ollama: "OLLAMA_API_KEY"
+    }.freeze
+
+    MODEL_OWNERS = {
+      openai: /\A(gpt-(\d|4o)|chatgpt-|o\d+(-|\z))/i,
+      anthropic: /\Aclaude-/i,
+      gemini: /\Agemini-/i
+    }.freeze
+
+    def self.provider_for(model)
+      name = model.to_s.strip
+      return if name.include?(":")
+
+      MODEL_OWNERS.find { |_, pattern| pattern.match?(name) }&.first
+    end
+
+    attr_writer :model, :api_key, :api_base
+    attr_accessor :temperature, :request_timeout,
+                  :write_mode, :auto_confirm, :destructive_confirmation_word,
+                  :extra_allowed_methods, :extra_allowed_constants, :execution_timeout, :preflight_count,
+                  :max_models, :max_focused_models, :include_internal_models, :excluded_models, :extra_context,
+                  :max_history, :max_repair_attempts,
+                  :color, :banner, :setup_on_boot, :input, :output, :inspect_limit, :console_helpers,
+                  :client
+
+    def initialize
+      @api_base = nil
+      @temperature = 0.0
+      @request_timeout = 60
+
+      @write_mode = false
+      @auto_confirm = false
+      @destructive_confirmation_word = "execute"
+      @extra_allowed_methods = []
+      @extra_allowed_constants = []
+      @execution_timeout = 30
+      @preflight_count = true
+
+      @max_models = 60
+      @max_focused_models = 8
+      @include_internal_models = false
+      @excluded_models = []
+      @extra_context = nil
+
+      @max_history = 6
+      @max_repair_attempts = 3
+
+      @color = nil # nil means "decide from the output stream"
+      @banner = true
+      @setup_on_boot = true
+      @input = nil
+      @output = nil
+      @inspect_limit = 20
+      @console_helpers = %i[ai ai! ask explain run ai_history ai_reset ai_schema ai_model]
+
+      @client = nil
+    end
+
+    def provider
+      @provider ||= detected_provider
+    end
+
+    def provider=(name)
+      @provider = name&.to_sym
+      @api_key = nil
+      @model = nil
+    end
+
+    def model
+      @model ||= Credentials.read.dig(provider.to_s, "model") ||
+                 DEFAULT_MODELS[provider] ||
+                 DEFAULT_MODELS[:openai]
+    end
+
+    def api_key
+      @api_key ||= blank_to_nil(ENV.fetch(ENV_KEYS.fetch(provider, ""), nil)) ||
+                   blank_to_nil(Credentials.read.dig(provider.to_s, "api_key"))
+    end
+
+    def api_base
+      @api_base || blank_to_nil(Credentials.read.dig(provider.to_s, "base_url"))
+    end
+
+    def snapshot
+      { provider: provider, model: @model, api_key: @api_key, api_base: @api_base }
+    end
+
+    def restore(state)
+      @provider, @model, @api_key, @api_base = state.values_at(:provider, :model, :api_key, :api_base)
+      self
+    end
+
+    def api_key?
+      !api_key.nil? || provider == :ollama || !client.nil?
+    end
+
+    def key_for?(name)
+      return true if name.to_sym == :ollama
+
+      !blank_to_nil(ENV.fetch(ENV_KEYS.fetch(name.to_sym, ""), nil)).nil? ||
+        !blank_to_nil(Credentials.read.dig(name.to_s, "api_key")).nil?
+    end
+
+    def write_mode?
+      !!@write_mode
+    end
+
+    def auto_confirm?
+      !!@auto_confirm
+    end
+
+    def color?
+      return @color unless @color.nil?
+
+      out = output || $stdout
+      out.respond_to?(:tty?) && out.tty?
+    end
+
+    def in
+      @input || $stdin
+    end
+
+    def out
+      @output || $stdout
+    end
+
+    def validate!
+      unless PROVIDERS.include?(provider)
+        raise ConfigurationError, "Unknown provider #{provider.inspect}. Supported: #{PROVIDERS.join(", ")}."
+      end
+
+      return true if api_key?
+
+      raise ConfigurationError,
+            "No API key for #{provider}. Set #{ENV_KEYS[provider]}, run `rails-agent configure`, " \
+            "or set RailsAgentConsole.config.api_key."
+    end
+
+    private
+
+    def blank_to_nil(value)
+      value.to_s unless value.to_s.strip.empty?
+    end
+
+    def detected_provider
+      from_file = Credentials.read["default_provider"]
+      return from_file.to_sym if from_file && PROVIDERS.include?(from_file.to_sym)
+
+      detected = PROVIDERS.find { |name| !blank_to_nil(ENV.fetch(ENV_KEYS[name], nil)).nil? }
+      detected || :openai
+    end
+  end
+end

data/lib/rails_agent_console/console_installer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RailsAgentConsole
+  module ConsoleInstaller
+    class << self
+      def install!(names = RailsAgentConsole.configuration.console_helpers)
+        helpers = ConsoleMethods.installable(names)
+
+        if rails_console_methods?
+          ::Rails::ConsoleMethods.include(helpers)
+        elsif irb_helper_methods?
+          register_irb_helpers(helpers)
+        else
+          ::TOPLEVEL_BINDING.receiver.extend(helpers)
+        end
+
+        helpers
+      end
+
+      private
+
+      def rails_console_methods?
+        defined?(::Rails::ConsoleMethods)
+      end
+
+      def irb_helper_methods?
+        defined?(::IRB::HelperMethod) && ::IRB::HelperMethod.respond_to?(:register)
+      end
+
+      def register_irb_helpers(helpers)
+        receiver = Object.new.extend(helpers)
+
+        helpers.instance_methods(false).each do |name|
+          ::IRB::HelperMethod.register(name, helper_class_for(name, receiver))
+        end
+      end
+
+      def helper_class_for(name, receiver)
+        Class.new(::IRB::HelperMethod::Base) do
+          description "rails_agent_console: #{name}"
+
+          define_method(:execute) do |*args, **options, &block|
+            receiver.public_send(name, *args, **options, &block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails_agent_console/console_methods.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module RailsAgentConsole
+  module ConsoleMethods
+    def ai(prompt = nil)
+      RailsAgentConsole.agent.run(prompt)
+    end
+
+    def ai!(prompt = nil)
+      RailsAgentConsole.agent.run(prompt, write: true)
+    end
+
+    def run(prompt = nil)
+      ai(prompt)
+    end
+    alias run_ai run
+
+    def ask(question = nil)
+      RailsAgentConsole.agent.ask(question)
+    end
+
+    def explain(code = nil, question: nil)
+      RailsAgentConsole.agent.explain(code, question: question)
+    end
+
+    def ai_history
+      RailsAgentConsole.configuration.out.puts(RailsAgentConsole.agent.history.to_s)
+      nil
+    end
+
+    def ai_reset
+      RailsAgentConsole.agent.reset!
+      RailsAgentConsole.configuration.out.puts("Conversation cleared.")
+      nil
+    end
+
+    def ai_schema(prompt = nil)
+      Schema.print(prompt)
+    end
+
+    def ai_model(target = nil)
+      ModelPicker.run(target)
+    end
+
+    ALL = instance_methods(false).freeze
+
+    def self.installable(names = RailsAgentConsole.configuration.console_helpers)
+      wanted = Array(names).map(&:to_sym)
+      copy = dup
+      (ALL - wanted).each { |name| copy.send(:remove_method, name) }
+      copy
+    end
+  end
+end

data/lib/rails_agent_console/console_session.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RailsAgentConsole
+  module ConsoleSession
+    class << self
+      def start(config: RailsAgentConsole.configuration, ui: UI.new(config))
+        banner(ui, config) if config.banner
+        return unless config.setup_on_boot && Setup.needed?(config)
+
+        if Setup.interactive?(config)
+          Setup.run(config: config, ui: ui)
+        else
+          ui.note "rails_agent_console: no API key found. Run `rails-agent configure` to set one up."
+        end
+      rescue Interrupt
+        ui.blank
+        ui.note "Skipped. Run `rails-agent configure` later."
+      end
+
+      private
+
+      def banner(ui, config)
+        ui.blank
+        ui.heading "Rails Agent Console #{VERSION}"
+        details = ["#{config.provider}/#{config.model}"]
+        details << (config.write_mode? ? "WRITE MODE" : "read-only")
+        ui.note "  #{details.join("  |  ")}"
+        ui.note '  ai "how many users signed up this month?"   ask "..."   explain User.all'
+        ui.note "  ai_model  to switch model or provider#{elsewhere(config)}"
+        ui.blank
+      end
+
+      def elsewhere(config)
+        others = (Configuration::PROVIDERS - [config.provider]).select do |name|
+          name == :ollama || config.key_for?(name)
+        end
+        others.empty? ? "" : " (#{others.join(", ")} also on hand)"
+      end
+    end
+  end
+end