console_agent 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 528fd68c058820f080d3b6d2aec7767ac48944e17ae6f2c117d279fbec4c8070
-  data.tar.gz: cf28f6caa721b229536bb591c1c5ecfbb51b1dbc55cee342bccfdaabbca0e804
+  metadata.gz: '09b1eab5b0fd84fb27fe9af623c234da290779f84d5972d4a67bfe000d581ab2'
+  data.tar.gz: 344f3afbc67adc4d87c5c2fb4e11ccc902fca071776a4a3aa6cb160783e22998
 SHA512:
-  metadata.gz: 9127d4e6c9eea9cb56cd4484906fd80c97f07d2c276f8d65f5906338011d03c39a53e5c1a5bfc3e1cbd3ecb69a4b6ddd9716a1aa8416b091c056ad5f267f21b2
-  data.tar.gz: 567dea6f8c8f8213ad3ed4b5cafa9519f3ecbbaa5825355cbee1be8a56981565dd3ec4905285ad7bdae8c6c5ea312550396ce1dfd2fe1c98df3e29d7d43b5a3e
+  metadata.gz: 73a5c9bd000e30b3cfa63c06efbb0f9619849ec56ca8b4b8f1c71cd7eae29439f9b4ef8d10725950aa8fb813159674820706fa5883784060464f8c9959c914aa
+  data.tar.gz: 4498692aab0860b717b7d309e252cb1b2130b7946a55421f0edd76c3b3469da27c6f8426667e23cf0a2fcab66a356896573f19b819c8ba603f08f50a5e60647d

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frank Cort
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,235 @@
+# ConsoleAgent
+
+An AI-powered assistant for your Rails console. Ask questions in plain English, get executable Ruby code.
+
+ConsoleAgent connects your `rails console` to an LLM (Claude or GPT) and gives it tools to introspect your app's database schema, models, and source code. It figures out what it needs on its own, so you don't pay for 50K tokens of context on every query.
+
+## Quick Start
+
+Add to your Gemfile:
+
+```ruby
+gem 'console_agent', group: :development
+```
+
+Run the install generator:
+
+```bash
+bundle install
+rails generate console_agent:install
+```
+
+Set your API key and open a console:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+rails console
+```
+
+Then:
+
+```ruby
+ai "show me all users who signed up this week"
+```
+
+## Console Commands
+
+| Command | Description |
+|---------|-------------|
+| `ai "query"` | Ask a question, review generated code, confirm before executing |
+| `ai! "query"` | Ask a question and enter interactive mode for follow-ups |
+| `ai!` | Enter interactive mode (type `exit` to leave) |
+| `ai? "query"` | Explain only — shows code but never executes |
+| `ai_status` | Print current configuration summary |
+
+### Example Session
+
+```
+irb> ai "find the 5 most recent orders over $100"
+  Thinking...
+  -> list_tables
+     12 tables: users, orders, line_items, products...
+  -> describe_table("orders")
+     8 columns
+  -> describe_model("Order")
+     4 associations, 2 validations
+
+You can query recent high-value orders like this:
+
+  Order.where("total > ?", 100).order(created_at: :desc).limit(5)
+
+[tokens in: 1,240 | out: 85 | total: 1,325]
+Execute? [y/N/edit] y
+=> [#<Order id: 4821, ...>, ...]
+```
+
+### Interactive Mode
+
+```
+irb> ai!
+ConsoleAgent interactive mode. Type 'exit' or 'quit' to leave.
+ai> show me all tables
+  Thinking...
+  -> list_tables
+     12 tables: users, orders, line_items, products...
+  ...
+ai> now count orders by status
+  ...
+ai> exit
+[session totals — in: 3,200 | out: 410 | total: 3,610]
+Left ConsoleAgent interactive mode.
+```
+
+### Configuration Status
+
+```
+irb> ai_status
+[ConsoleAgent v0.1.0]
+  Provider:       anthropic
+  Model:          claude-opus-4-6
+  API key:        sk-ant-...a3b4
+  Context mode:   smart
+  Max tokens:     4096
+  Temperature:    0.2
+  Timeout:        30s
+  Max tool rounds:10
+  Auto-execute:   false
+  Debug:          false
+```
+
+## Configuration
+
+The install generator creates `config/initializers/console_agent.rb`:
+
+```ruby
+ConsoleAgent.configure do |config|
+  # LLM provider: :anthropic or :openai
+  config.provider = :anthropic
+
+  # API key (or set ANTHROPIC_API_KEY / OPENAI_API_KEY env var)
+  # config.api_key = 'sk-...'
+
+  # Model override (defaults: claude-opus-4-6 for Anthropic, gpt-5.3-codex for OpenAI)
+  # config.model = 'claude-opus-4-6'
+
+  # Context mode:
+  #   :smart - (default) LLM uses tools to fetch schema/model/code on demand
+  #   :full  - sends all schema, models, and routes every time
+  config.context_mode = :smart
+
+  # Max tokens for LLM response
+  config.max_tokens = 4096
+
+  # Temperature (0.0 - 1.0)
+  config.temperature = 0.2
+
+  # Auto-execute generated code without confirmation
+  config.auto_execute = false
+
+  # Max tool-use rounds per query in :smart mode
+  config.max_tool_rounds = 10
+
+  # HTTP timeout in seconds
+  config.timeout = 30
+
+  # Debug mode: prints full API requests/responses and tool calls
+  # config.debug = true
+end
+```
+
+You can also change settings at runtime in the console:
+
+```ruby
+ConsoleAgent.configure { |c| c.debug = true }
+ConsoleAgent.configure { |c| c.provider = :openai }
+ENV['OPENAI_API_KEY'] = 'sk-...'
+```
+
+## Context Modes
+
+### Smart Mode (default)
+
+The LLM gets a minimal system prompt and uses tools to look up what it needs:
+
+- **list_tables** / **describe_table** — database schema on demand
+- **list_models** / **describe_model** — ActiveRecord associations, validations
+- **list_files** / **read_file** / **search_code** — browse app source code
+
+This keeps token usage low (~1-3K per query) even for large apps with hundreds of tables.
+
+### Full Mode
+
+Sends the entire database schema, all model details, and a route summary in every request. Simple but expensive for large apps (~50K+ tokens). Useful if you want everything available without tool-call round trips.
+
+```ruby
+ConsoleAgent.configure { |c| c.context_mode = :full }
+```
+
+## Tools Available in Smart Mode
+
+| Tool | Description |
+|------|-------------|
+| `list_tables` | All database table names |
+| `describe_table` | Columns, types, and indexes for one table |
+| `list_models` | All model names with association names |
+| `describe_model` | Associations, validations, scopes for one model |
+| `list_files` | Ruby files in a directory |
+| `read_file` | Read a source file (capped at 200 lines) |
+| `search_code` | Grep for a pattern across Ruby files |
+
+The LLM decides which tools to call based on your question. You can see the tool calls happening in real time.
+
+## Providers
+
+### Anthropic (default)
+
+Uses the Claude Messages API. Set `ANTHROPIC_API_KEY` or `config.api_key`.
+
+### OpenAI
+
+Uses the Chat Completions API. Set `OPENAI_API_KEY` or `config.api_key`.
+
+```ruby
+ConsoleAgent.configure do |config|
+  config.provider = :openai
+  config.model = 'gpt-5.3-codex'  # optional, this is the default
+end
+```
+
+## Docker Setup
+
+If your Rails app runs in Docker, mount the gem source as a volume.
+
+In `docker-compose.yml`:
+
+```yaml
+volumes:
+  - /path/to/console_agent:/console_agent
+```
+
+In `Gemfile`:
+
+```ruby
+gem 'console_agent', path: '/console_agent', group: :development
+```
+
+For Docker builds (where the gem source isn't available yet), add a stub to your Dockerfile before `bundle install`:
+
+```dockerfile
+RUN mkdir -p /console_agent/lib/console_agent && \
+    echo "module ConsoleAgent; VERSION = '0.1.0'; end" > /console_agent/lib/console_agent/version.rb && \
+    echo "require 'console_agent/version'" > /console_agent/lib/console_agent.rb && \
+    printf "require_relative 'lib/console_agent/version'\nGem::Specification.new do |s|\n  s.name = 'console_agent'\n  s.version = ConsoleAgent::VERSION\n  s.summary = 'stub'\n  s.authors = ['x']\n  s.files = ['lib/console_agent.rb']\n  s.add_dependency 'rails', '>= 5.0'\n  s.add_dependency 'faraday', '>= 1.0'\nend\n" > /console_agent/console_agent.gemspec
+```
+
+The volume mount overwrites the stub at runtime with the real source.
+
+## Requirements
+
+- Ruby >= 2.5
+- Rails >= 5.0
+- Faraday >= 1.0
+
+## License
+
+MIT

data/lib/console_agent/configuration.rb

@@ -0,0 +1,58 @@
+module ConsoleAgent
+  class Configuration
+    PROVIDERS = %i[anthropic openai].freeze
+    CONTEXT_MODES = %i[full smart].freeze
+
+    attr_accessor :provider, :api_key, :model, :max_tokens,
+                  :auto_execute, :context_mode, :temperature,
+                  :timeout, :debug, :max_tool_rounds
+
+    def initialize
+      @provider     = :anthropic
+      @api_key      = nil
+      @model        = nil
+      @max_tokens   = 4096
+      @auto_execute = false
+      @context_mode = :smart
+      @temperature  = 0.2
+      @timeout      = 30
+      @debug        = false
+      @max_tool_rounds = 10
+    end
+
+    def resolved_api_key
+      return @api_key if @api_key && !@api_key.empty?
+
+      case @provider
+      when :anthropic
+        ENV['ANTHROPIC_API_KEY']
+      when :openai
+        ENV['OPENAI_API_KEY']
+      end
+    end
+
+    def resolved_model
+      return @model if @model && !@model.empty?
+
+      case @provider
+      when :anthropic
+        'claude-opus-4-6'
+      when :openai
+        'gpt-5.3-codex'
+      end
+    end
+
+    def validate!
+      unless PROVIDERS.include?(@provider)
+        raise ConfigurationError, "Unknown provider: #{@provider}. Valid: #{PROVIDERS.join(', ')}"
+      end
+
+      unless resolved_api_key
+        env_var = @provider == :anthropic ? 'ANTHROPIC_API_KEY' : 'OPENAI_API_KEY'
+        raise ConfigurationError, "No API key. Set config.api_key or #{env_var} env var."
+      end
+    end
+  end
+
+  class ConfigurationError < StandardError; end
+end

data/lib/console_agent/console_methods.rb

@@ -0,0 +1,88 @@
+module ConsoleAgent
+  module ConsoleMethods
+    def ai_status
+      ConsoleAgent.status
+    end
+
+    def ai(query = nil)
+      if query.nil?
+        $stderr.puts "\e[33mUsage: ai \"your question here\"\e[0m"
+        $stderr.puts "\e[33m  ai  \"query\" - ask + confirm execution\e[0m"
+        $stderr.puts "\e[33m  ai! \"query\" - enter interactive mode (or ai! with no args)\e[0m"
+        $stderr.puts "\e[33m  ai? \"query\" - explain only, no execution\e[0m"
+        $stderr.puts "\e[33m  ai_status   - show current configuration\e[0m"
+        return nil
+      end
+
+      require 'console_agent/context_builder'
+      require 'console_agent/providers/base'
+      require 'console_agent/executor'
+      require 'console_agent/repl'
+
+      repl = Repl.new(__console_agent_binding)
+      repl.one_shot(query.to_s)
+    rescue => e
+      $stderr.puts "\e[31mConsoleAgent error: #{e.message}\e[0m"
+      nil
+    end
+
+    def ai!(query = nil)
+      require 'console_agent/context_builder'
+      require 'console_agent/providers/base'
+      require 'console_agent/executor'
+      require 'console_agent/repl'
+
+      repl = Repl.new(__console_agent_binding)
+
+      if query
+        repl.one_shot(query.to_s)
+      else
+        repl.interactive
+      end
+    rescue => e
+      $stderr.puts "\e[31mConsoleAgent error: #{e.message}\e[0m"
+      nil
+    end
+
+    def ai?(query = nil)
+      unless query
+        $stderr.puts "\e[33mUsage: ai? \"your question here\" - explain without executing\e[0m"
+        return nil
+      end
+
+      require 'console_agent/context_builder'
+      require 'console_agent/providers/base'
+      require 'console_agent/executor'
+      require 'console_agent/repl'
+
+      repl = Repl.new(__console_agent_binding)
+      repl.explain(query.to_s)
+    rescue => e
+      $stderr.puts "\e[31mConsoleAgent error: #{e.message}\e[0m"
+      nil
+    end
+
+    private
+
+    def __console_agent_binding
+      # Try IRB workspace binding
+      if defined?(IRB) && IRB.respond_to?(:CurrentContext)
+        ctx = IRB.CurrentContext rescue nil
+        if ctx && ctx.respond_to?(:workspace) && ctx.workspace.respond_to?(:binding)
+          return ctx.workspace.binding
+        end
+      end
+
+      # Try Pry binding
+      if defined?(Pry) && respond_to?(:pry_instance, true)
+        pry_inst = pry_instance rescue nil
+        if pry_inst && pry_inst.respond_to?(:current_binding)
+          return pry_inst.current_binding
+        end
+      end
+
+      # Fallback
+      TOPLEVEL_BINDING
+    end
+  end
+end

data/lib/console_agent/context_builder.rb

@@ -0,0 +1,200 @@
+module ConsoleAgent
+  class ContextBuilder
+    def initialize(config = ConsoleAgent.configuration)
+      @config = config
+    end
+
+    def build
+      case @config.context_mode
+      when :smart
+        build_smart
+      else
+        build_full
+      end
+    rescue => e
+      ConsoleAgent.logger.warn("ConsoleAgent: context build error: #{e.message}")
+      system_instructions + "\n\n" + environment_context
+    end
+
+    def build_full
+      parts = []
+      parts << system_instructions
+      parts << environment_context
+      parts << schema_context
+      parts << models_context
+      parts << routes_context
+      parts.compact.join("\n\n")
+    end
+
+    def build_smart
+      parts = []
+      parts << smart_system_instructions
+      parts << environment_context
+      parts.compact.join("\n\n")
+    end
+
+    private
+
+    def smart_system_instructions
+      <<~PROMPT.strip
+        You are a Ruby on Rails console assistant. The user is in a `rails console` session.
+        You help them query data, debug issues, and understand their application.
+
+        You have tools available to introspect the app's database schema, models, and source code.
+        Use them as needed to write accurate queries. For example, call list_tables to see what
+        tables exist, then describe_table to get column details for the ones you need.
+
+        You also have an ask_user tool to ask the console user clarifying questions. Use it when
+        you need specific information to write accurate code — such as which user they are, which
+        record to target, or what value to use.
+
+        RULES:
+        - Give ONE concise answer. Do not offer multiple alternatives or variations.
+        - Respond with a single ```ruby code block that directly answers the question.
+        - Include a brief one-line explanation before the code block.
+        - Use the app's actual model names, associations, and schema.
+        - Prefer ActiveRecord query interface over raw SQL.
+        - For destructive operations, add a comment warning.
+        - NEVER use placeholder values like YOUR_USER_ID or YOUR_EMAIL in code. If you need
+          a specific value from the user, call the ask_user tool to get it first.
+        - Keep code concise and idiomatic.
+        - Use tools to look up schema/model details rather than guessing column names.
+      PROMPT
+    end
+
+    def system_instructions
+      <<~PROMPT.strip
+        You are a Ruby on Rails console assistant. The user is in a `rails console` session.
+        You help them query data, debug issues, and understand their application.
+
+        RULES:
+        - Give ONE concise answer. Do not offer multiple alternatives or variations.
+        - Respond with a single ```ruby code block that directly answers the question.
+        - Include a brief one-line explanation before the code block.
+        - Use the app's actual model names, associations, and schema.
+        - Prefer ActiveRecord query interface over raw SQL.
+        - For destructive operations, add a comment warning.
+        - If the request is ambiguous, ask a clarifying question instead of guessing.
+        - Keep code concise and idiomatic.
+      PROMPT
+    end
+
+    def environment_context
+      lines = ["## Environment"]
+      lines << "- Ruby #{RUBY_VERSION}"
+      lines << "- Rails #{Rails.version}" if defined?(Rails) && Rails.respond_to?(:version)
+
+      if defined?(ActiveRecord::Base) && ActiveRecord::Base.connected?
+        adapter = ActiveRecord::Base.connection.adapter_name rescue 'unknown'
+        lines << "- Database adapter: #{adapter}"
+      end
+
+      if defined?(Bundler)
+        key_gems = %w[devise cancancan pundit sidekiq delayed_job resque
+                      paperclip carrierwave activestorage shrine
+                      pg mysql2 sqlite3 mongoid]
+        loaded = key_gems.select { |g| Gem.loaded_specs.key?(g) }
+        lines << "- Key gems: #{loaded.join(', ')}" unless loaded.empty?
+      end
+
+      lines.join("\n")
+    end
+
+    def schema_context
+      return nil unless defined?(ActiveRecord::Base) && ActiveRecord::Base.connected?
+
+      conn = ActiveRecord::Base.connection
+      tables = conn.tables.sort
+      return nil if tables.empty?
+
+      lines = ["## Database Schema"]
+      tables.each do |table|
+        next if table == 'schema_migrations' || table == 'ar_internal_metadata'
+
+        cols = conn.columns(table).map { |c| "#{c.name}:#{c.type}" }
+        lines << "- #{table} (#{cols.join(', ')})"
+      end
+      lines.join("\n")
+    rescue => e
+      ConsoleAgent.logger.debug("ConsoleAgent: schema introspection failed: #{e.message}")
+      nil
+    end
+
+    def models_context
+      return nil unless defined?(ActiveRecord::Base)
+
+      eager_load_app!
+      base_class = defined?(ApplicationRecord) ? ApplicationRecord : ActiveRecord::Base
+      models = ObjectSpace.each_object(Class).select { |c|
+        c < base_class && !c.abstract_class? && c.name && !c.name.start_with?('HABTM_')
+      }.sort_by(&:name)
+
+      return nil if models.empty?
+
+      lines = ["## Models"]
+      models.each do |model|
+        parts = [model.name]
+
+        assocs = model.reflect_on_all_associations.map { |a| "#{a.macro} :#{a.name}" }
+        parts << "  associations: #{assocs.join(', ')}" unless assocs.empty?
+
+        scopes = model.methods.grep(/^_scope_/).map { |m| m.to_s.sub('_scope_', '') } rescue []
+        if scopes.empty?
+          # Alternative: check singleton methods that return ActiveRecord::Relation
+          scope_names = (model.singleton_methods - base_class.singleton_methods).select { |m|
+            m != :all && !m.to_s.start_with?('_') && !m.to_s.start_with?('find')
+          }.first(10)
+          # We won't list these to avoid noise — scopes are hard to detect reliably
+        end
+
+        validations = model.validators.map { |v|
+          attrs = v.attributes.join(', ')
+          "#{v.class.name.demodulize.underscore.sub('_validator', '')} on #{attrs}"
+        }.uniq.first(5) rescue []
+        parts << "  validations: #{validations.join('; ')}" unless validations.empty?
+
+        lines << "- #{parts.join("\n")}"
+      end
+      lines.join("\n")
+    rescue => e
+      ConsoleAgent.logger.debug("ConsoleAgent: model introspection failed: #{e.message}")
+      nil
+    end
+
+    def routes_context
+      return nil unless defined?(Rails) && Rails.respond_to?(:application)
+
+      routes = Rails.application.routes.routes
+      return nil if routes.empty?
+
+      lines = ["## Routes (summary)"]
+      count = 0
+      routes.each do |route|
+        next if route.internal?
+        path = route.path.spec.to_s.sub('(.:format)', '')
+        verb = route.verb.to_s
+        next if verb.empty?
+        action = route.defaults[:controller].to_s + '#' + route.defaults[:action].to_s
+        lines << "- #{verb} #{path} -> #{action}"
+        count += 1
+        break if count >= 50
+      end
+      lines << "- ... (#{routes.size - count} more routes)" if routes.size > count
+
+      lines.join("\n")
+    rescue => e
+      ConsoleAgent.logger.debug("ConsoleAgent: route introspection failed: #{e.message}")
+      nil
+    end
+
+    def eager_load_app!
+      return unless defined?(Rails) && Rails.respond_to?(:application)
+
+      if Rails.application.respond_to?(:eager_load!)
+        Rails.application.eager_load!
+      end
+    rescue => e
+      ConsoleAgent.logger.debug("ConsoleAgent: eager_load failed: #{e.message}")
+    end
+  end
+end