console_agent 0.0.1 → 0.2.0

data/lib/console_agent/tools/memory_tools.rb

@@ -0,0 +1,136 @@
+require 'yaml'
+
+module ConsoleAgent
+  module Tools
+    class MemoryTools
+      MEMORIES_DIR = 'memories'
+
+      def initialize(storage = nil)
+        @storage = storage || ConsoleAgent.storage
+      end
+
+      def save_memory(name:, description:, tags: [])
+        key = memory_key(name)
+        existing = load_memory(key)
+
+        frontmatter = {
+          'name' => name,
+          'tags' => Array(tags).empty? && existing ? (existing['tags'] || []) : Array(tags),
+          'created_at' => existing ? existing['created_at'] : Time.now.utc.iso8601
+        }
+        frontmatter['updated_at'] = Time.now.utc.iso8601 if existing
+
+        content = "---\n#{YAML.dump(frontmatter).sub("---\n", '').strip}\n---\n\n#{description}\n"
+        @storage.write(key, content)
+
+        path = @storage.respond_to?(:root_path) ? File.join(@storage.root_path, key) : key
+        if existing
+          "Memory updated: \"#{name}\" (#{path})"
+        else
+          "Memory saved: \"#{name}\" (#{path})"
+        end
+      rescue Storage::StorageError => e
+        "FAILED to save (#{e.message}). Add this manually to .console_agent/#{key}:\n" \
+        "---\nname: #{name}\ntags: #{Array(tags).inspect}\n---\n\n#{description}"
+      end
+
+      def delete_memory(name:)
+        key = memory_key(name)
+        unless @storage.exists?(key)
+          # Try to find by name match across all memory files
+          found_key = find_memory_key_by_name(name)
+          return "No memory found: \"#{name}\"" unless found_key
+          key = found_key
+        end
+
+        memory = load_memory(key)
+        @storage.delete(key)
+        "Memory deleted: \"#{memory ? memory['name'] : name}\""
+      rescue Storage::StorageError => e
+        "FAILED to delete memory (#{e.message})."
+      end
+
+      def recall_memories(query: nil, tag: nil)
+        memories = load_all_memories
+        return "No memories stored yet." if memories.empty?
+
+        results = memories
+        if tag && !tag.empty?
+          results = results.select { |m|
+            Array(m['tags']).any? { |t| t.downcase.include?(tag.downcase) }
+          }
+        end
+        if query && !query.empty?
+          q = query.downcase
+          results = results.select { |m|
+            m['name'].to_s.downcase.include?(q) ||
+            m['description'].to_s.downcase.include?(q) ||
+            Array(m['tags']).any? { |t| t.downcase.include?(q) }
+          }
+        end
+
+        return "No memories matching your search." if results.empty?
+
+        results.map { |m|
+          line = "**#{m['name']}**\n#{m['description']}"
+          line += "\nTags: #{m['tags'].join(', ')}" if m['tags'] && !m['tags'].empty?
+          line
+        }.join("\n\n")
+      end
+
+      def memory_summaries
+        memories = load_all_memories
+        return nil if memories.empty?
+
+        memories.map { |m|
+          tags = Array(m['tags'])
+          tag_str = tags.empty? ? '' : " [#{tags.join(', ')}]"
+          "- #{m['name']}#{tag_str}"
+        }
+      end
+
+      private
+
+      def memory_key(name)
+        slug = name.downcase.strip
+          .gsub(/[^a-z0-9\s-]/, '')
+          .gsub(/[\s]+/, '-')
+          .gsub(/-+/, '-')
+          .sub(/^-/, '').sub(/-$/, '')
+        "#{MEMORIES_DIR}/#{slug}.md"
+      end
+
+      def load_memory(key)
+        content = @storage.read(key)
+        return nil if content.nil? || content.strip.empty?
+        parse_memory(content)
+      rescue => e
+        ConsoleAgent.logger.warn("ConsoleAgent: failed to load memory #{key}: #{e.message}")
+        nil
+      end
+
+      def load_all_memories
+        keys = @storage.list("#{MEMORIES_DIR}/*.md")
+        keys.map { |key| load_memory(key) }.compact
+      rescue => e
+        ConsoleAgent.logger.warn("ConsoleAgent: failed to load memories: #{e.message}")
+        []
+      end
+
+      def parse_memory(content)
+        return nil unless content =~ /\A---\s*\n(.*?\n)---\s*\n(.*)/m
+        frontmatter = YAML.safe_load($1, permitted_classes: [Time, Date]) || {}
+        description = $2.strip
+        frontmatter.merge('description' => description)
+      end
+
+      def find_memory_key_by_name(name)
+        keys = @storage.list("#{MEMORIES_DIR}/*.md")
+        keys.find do |key|
+          memory = load_memory(key)
+          memory && memory['name'].to_s.downcase == name.downcase
+        end
+      end
+    end
+  end
+end

data/lib/console_agent/tools/model_tools.rb

@@ -0,0 +1,95 @@
+module ConsoleAgent
+  module Tools
+    class ModelTools
+      def list_models
+        return "ActiveRecord is not available." unless defined?(ActiveRecord::Base)
+
+        eager_load_app!
+        models = find_models
+        return "No models found." if models.empty?
+
+        lines = models.map do |model|
+          assoc_names = model.reflect_on_all_associations.map { |a| a.name.to_s }
+          if assoc_names.empty?
+            model.name
+          else
+            "#{model.name} (#{assoc_names.join(', ')})"
+          end
+        end
+
+        lines.join("\n")
+      rescue => e
+        "Error listing models: #{e.message}"
+      end
+
+      def describe_model(model_name)
+        return "ActiveRecord is not available." unless defined?(ActiveRecord::Base)
+        return "Error: model_name is required." if model_name.nil? || model_name.strip.empty?
+
+        eager_load_app!
+        model_name = model_name.strip
+
+        model = find_models.detect { |m| m.name == model_name || m.name.underscore == model_name.underscore }
+        return "Model '#{model_name}' not found. Use list_models to see available models." unless model
+
+        result = "Model: #{model.name}\n"
+        result += "Table: #{model.table_name}\n"
+
+        assocs = model.reflect_on_all_associations.map { |a| "#{a.macro} :#{a.name}" }
+        unless assocs.empty?
+          result += "Associations:\n"
+          assocs.each { |a| result += "  #{a}\n" }
+        end
+
+        begin
+          validators = model.validators.map { |v|
+            attrs = v.attributes.join(', ')
+            kind = v.class.name.split('::').last.sub('Validator', '').downcase
+            "#{kind} on #{attrs}"
+          }.uniq
+          unless validators.empty?
+            result += "Validations:\n"
+            validators.each { |v| result += "  #{v}\n" }
+          end
+        rescue => e
+          # validations may not be accessible
+        end
+
+        # Scopes - detect via singleton methods that aren't inherited
+        begin
+          base = defined?(ApplicationRecord) ? ApplicationRecord : ActiveRecord::Base
+          scope_candidates = (model.singleton_methods - base.singleton_methods)
+            .reject { |m| m.to_s.start_with?('_') || m.to_s.start_with?('find') }
+            .sort
+            .first(20)
+          unless scope_candidates.empty?
+            result += "Possible scopes/class methods:\n"
+            scope_candidates.each { |s| result += "  #{s}\n" }
+          end
+        rescue => e
+          # ignore
+        end
+
+        result
+      rescue => e
+        "Error describing model '#{model_name}': #{e.message}"
+      end
+
+      private
+
+      def find_models
+        base_class = defined?(ApplicationRecord) ? ApplicationRecord : ActiveRecord::Base
+        ObjectSpace.each_object(Class).select { |c|
+          c < base_class && !c.abstract_class? && c.name && !c.name.start_with?('HABTM_')
+        }.sort_by(&:name)
+      end
+
+      def eager_load_app!
+        return unless defined?(Rails) && Rails.respond_to?(:application)
+        Rails.application.eager_load! if Rails.application.respond_to?(:eager_load!)
+      rescue => e
+        # ignore
+      end
+    end
+  end
+end

data/lib/console_agent/tools/registry.rb

@@ -0,0 +1,253 @@
+require 'json'
+
+module ConsoleAgent
+  module Tools
+    class Registry
+      attr_reader :definitions
+
+      # Tools that should never be cached (side effects or user interaction)
+      NO_CACHE = %w[ask_user save_memory delete_memory].freeze
+
+      def initialize
+        @definitions = []
+        @handlers = {}
+        @cache = {}
+        @last_cached = false
+        register_all
+      end
+
+      def last_cached?
+        @last_cached
+      end
+
+      def execute(tool_name, arguments = {})
+        handler = @handlers[tool_name]
+        unless handler
+          return "Error: unknown tool '#{tool_name}'"
+        end
+
+        args = if arguments.is_a?(String)
+                 begin
+                   JSON.parse(arguments)
+                 rescue
+                   {}
+                 end
+               else
+                 arguments || {}
+               end
+
+        unless NO_CACHE.include?(tool_name)
+          cache_key = [tool_name, args].hash
+          if @cache.key?(cache_key)
+            @last_cached = true
+            return @cache[cache_key]
+          end
+        end
+
+        @last_cached = false
+        result = handler.call(args)
+        @cache[[tool_name, args].hash] = result unless NO_CACHE.include?(tool_name)
+        result
+      rescue => e
+        "Error executing #{tool_name}: #{e.message}"
+      end
+
+      def to_anthropic_format
+        definitions.map do |d|
+          tool = {
+            'name' => d[:name],
+            'description' => d[:description],
+            'input_schema' => d[:parameters]
+          }
+          tool
+        end
+      end
+
+      def to_openai_format
+        definitions.map do |d|
+          {
+            'type' => 'function',
+            'function' => {
+              'name' => d[:name],
+              'description' => d[:description],
+              'parameters' => d[:parameters]
+            }
+          }
+        end
+      end
+
+      private
+
+      def register_all
+        require 'console_agent/tools/schema_tools'
+        require 'console_agent/tools/model_tools'
+        require 'console_agent/tools/code_tools'
+
+        schema = SchemaTools.new
+        models = ModelTools.new
+        code = CodeTools.new
+
+        register(
+          name: 'list_tables',
+          description: 'List all database table names in this Rails app.',
+          parameters: { 'type' => 'object', 'properties' => {} },
+          handler: ->(_args) { schema.list_tables }
+        )
+
+        register(
+          name: 'describe_table',
+          description: 'Get column names and types for a specific database table.',
+          parameters: {
+            'type' => 'object',
+            'properties' => {
+              'table_name' => { 'type' => 'string', 'description' => 'The database table name (e.g. "users")' }
+            },
+            'required' => ['table_name']
+          },
+          handler: ->(args) { schema.describe_table(args['table_name']) }
+        )
+
+        register(
+          name: 'list_models',
+          description: 'List all ActiveRecord model names with their association names.',
+          parameters: { 'type' => 'object', 'properties' => {} },
+          handler: ->(_args) { models.list_models }
+        )
+
+        register(
+          name: 'describe_model',
+          description: 'Get detailed info about a specific model: associations, validations, table name.',
+          parameters: {
+            'type' => 'object',
+            'properties' => {
+              'model_name' => { 'type' => 'string', 'description' => 'The model class name (e.g. "User")' }
+            },
+            'required' => ['model_name']
+          },
+          handler: ->(args) { models.describe_model(args['model_name']) }
+        )
+
+        register(
+          name: 'list_files',
+          description: 'List Ruby files in a directory of this Rails app. Defaults to app/ directory.',
+          parameters: {
+            'type' => 'object',
+            'properties' => {
+              'directory' => { 'type' => 'string', 'description' => 'Relative directory path (e.g. "app/models", "lib"). Defaults to "app".' }
+            }
+          },
+          handler: ->(args) { code.list_files(args['directory']) }
+        )
+
+        register(
+          name: 'read_file',
+          description: 'Read the contents of a file in this Rails app. Capped at 200 lines.',
+          parameters: {
+            'type' => 'object',
+            'properties' => {
+              'path' => { 'type' => 'string', 'description' => 'Relative file path (e.g. "app/models/user.rb")' }
+            },
+            'required' => ['path']
+          },
+          handler: ->(args) { code.read_file(args['path']) }
+        )
+
+        register(
+          name: 'search_code',
+          description: 'Search for a pattern in Ruby files. Returns matching lines with file paths.',
+          parameters: {
+            'type' => 'object',
+            'properties' => {
+              'query' => { 'type' => 'string', 'description' => 'Search pattern (substring match)' },
+              'directory' => { 'type' => 'string', 'description' => 'Relative directory to search in. Defaults to "app".' }
+            },
+            'required' => ['query']
+          },
+          handler: ->(args) { code.search_code(args['query'], args['directory']) }
+        )
+
+        register(
+          name: 'ask_user',
+          description: 'Ask the console user a clarifying question. Use this when you need specific information to write accurate code (e.g. which user they are, which record to target, what value to use). Do NOT generate placeholder values like YOUR_USER_ID — ask instead.',
+          parameters: {
+            'type' => 'object',
+            'properties' => {
+              'question' => { 'type' => 'string', 'description' => 'The question to ask the user' }
+            },
+            'required' => ['question']
+          },
+          handler: ->(args) { ask_user(args['question']) }
+        )
+
+        register_memory_tools
+      end
+
+      def register_memory_tools
+        return unless ConsoleAgent.configuration.memories_enabled
+
+        require 'console_agent/tools/memory_tools'
+        memory = MemoryTools.new
+
+        register(
+          name: 'save_memory',
+          description: 'Save a fact or pattern you learned about this codebase for future sessions. Use after discovering how something works (e.g. sharding, auth, custom business logic).',
+          parameters: {
+            'type' => 'object',
+            'properties' => {
+              'name' => { 'type' => 'string', 'description' => 'Short name for this memory (e.g. "Sharding architecture")' },
+              'description' => { 'type' => 'string', 'description' => 'Detailed description of what you learned' },
+              'tags' => { 'type' => 'array', 'items' => { 'type' => 'string' }, 'description' => 'Optional tags (e.g. ["database", "sharding"])' }
+            },
+            'required' => ['name', 'description']
+          },
+          handler: ->(args) {
+            memory.save_memory(name: args['name'], description: args['description'], tags: args['tags'] || [])
+          }
+        )
+
+        register(
+          name: 'delete_memory',
+          description: 'Delete a memory by name.',
+          parameters: {
+            'type' => 'object',
+            'properties' => {
+              'name' => { 'type' => 'string', 'description' => 'The memory name to delete (e.g. "Sharding architecture")' }
+            },
+            'required' => ['name']
+          },
+          handler: ->(args) { memory.delete_memory(name: args['name']) }
+        )
+
+        register(
+          name: 'recall_memories',
+          description: 'Search your saved memories about this codebase. Call with no args to list all, or pass a query/tag to filter.',
+          parameters: {
+            'type' => 'object',
+            'properties' => {
+              'query' => { 'type' => 'string', 'description' => 'Search term to filter by name, description, or tags' },
+              'tag' => { 'type' => 'string', 'description' => 'Filter by a specific tag' }
+            }
+          },
+          handler: ->(args) { memory.recall_memories(query: args['query'], tag: args['tag']) }
+        )
+      end
+
+      def ask_user(question)
+        $stdout.puts "\e[36m  ? #{question}\e[0m"
+        $stdout.print "\e[36m  > \e[0m"
+        answer = $stdin.gets
+        return '(no answer provided)' if answer.nil?
+        answer.strip.empty? ? '(no answer provided)' : answer.strip
+      end
+
+      def register(name:, description:, parameters:, handler:)
+        @definitions << {
+          name: name,
+          description: description,
+          parameters: parameters
+        }
+        @handlers[name] = handler
+      end
+    end
+  end
+end

data/lib/console_agent/tools/schema_tools.rb

@@ -0,0 +1,60 @@
+module ConsoleAgent
+  module Tools
+    class SchemaTools
+      def list_tables
+        return "ActiveRecord is not connected." unless ar_connected?
+
+        tables = connection.tables.sort
+        tables.reject! { |t| t == 'schema_migrations' || t == 'ar_internal_metadata' }
+        return "No tables found." if tables.empty?
+
+        tables.join(", ")
+      rescue => e
+        "Error listing tables: #{e.message}"
+      end
+
+      def describe_table(table_name)
+        return "ActiveRecord is not connected." unless ar_connected?
+        return "Error: table_name is required." if table_name.nil? || table_name.strip.empty?
+
+        table_name = table_name.strip
+        unless connection.tables.include?(table_name)
+          return "Table '#{table_name}' not found. Use list_tables to see available tables."
+        end
+
+        cols = connection.columns(table_name).map do |c|
+          parts = ["#{c.name}:#{c.type}"]
+          parts << "nullable" if c.null
+          parts << "default=#{c.default}" unless c.default.nil?
+          parts.join(" ")
+        end
+
+        indexes = connection.indexes(table_name).map do |idx|
+          unique = idx.unique ? "UNIQUE " : ""
+          "#{unique}INDEX on (#{idx.columns.join(', ')})"
+        end
+
+        result = "Table: #{table_name}\n"
+        result += "Columns:\n"
+        cols.each { |c| result += "  #{c}\n" }
+        unless indexes.empty?
+          result += "Indexes:\n"
+          indexes.each { |i| result += "  #{i}\n" }
+        end
+        result
+      rescue => e
+        "Error describing table '#{table_name}': #{e.message}"
+      end
+
+      private
+
+      def ar_connected?
+        defined?(ActiveRecord::Base) && ActiveRecord::Base.connected?
+      end
+
+      def connection
+        ActiveRecord::Base.connection
+      end
+    end
+  end
+end

data/lib/console_agent/version.rb

@@ -0,0 +1,3 @@
+module ConsoleAgent
+  VERSION = '0.2.0'.freeze
+end

data/lib/console_agent.rb

@@ -1 +1,76 @@
-module ConsoleAgent; VERSION = '0.0.1'; end
+require 'console_agent/version'
+require 'console_agent/configuration'
+
+module ConsoleAgent
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration) if block_given?
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+      reset_storage!
+    end
+
+    def storage
+      @storage ||= begin
+        adapter = configuration.storage_adapter
+        if adapter
+          adapter
+        else
+          require 'console_agent/storage/file_storage'
+          Storage::FileStorage.new
+        end
+      end
+    end
+
+    def reset_storage!
+      @storage = nil
+    end
+
+    def logger
+      @logger ||= if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+                    Rails.logger
+                  else
+                    require 'logger'
+                    Logger.new($stderr, progname: 'ConsoleAgent')
+                  end
+    end
+
+    def logger=(log)
+      @logger = log
+    end
+
+    def status
+      c = configuration
+      key = c.resolved_api_key
+      masked_key = if key.nil? || key.empty?
+                     "\e[31m(not set)\e[0m"
+                   else
+                     key[0..6] + '...' + key[-4..-1]
+                   end
+
+      lines = []
+      lines << "\e[36m[ConsoleAgent v#{VERSION}]\e[0m"
+      lines << "  Provider:       #{c.provider}"
+      lines << "  Model:          #{c.resolved_model}"
+      lines << "  API key:        #{masked_key}"
+      lines << "  Context mode:   #{c.context_mode}"
+      lines << "  Max tokens:     #{c.max_tokens}"
+      lines << "  Temperature:    #{c.temperature}"
+      lines << "  Timeout:        #{c.timeout}s"
+      lines << "  Max tool rounds:#{c.max_tool_rounds}" if c.context_mode == :smart
+      lines << "  Auto-execute:   #{c.auto_execute}"
+      lines << "  Memories:       #{c.memories_enabled}"
+      lines << "  Debug:          #{c.debug}"
+      $stdout.puts lines.join("\n")
+      nil
+    end
+  end
+end
+
+require 'console_agent/railtie' if defined?(Rails::Railtie)

data/lib/generators/console_agent/install_generator.rb

@@ -0,0 +1,26 @@
+require 'rails/generators'
+
+module ConsoleAgent
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+      desc 'Creates a ConsoleAgent initializer in config/initializers/'
+
+      def copy_initializer
+        template 'initializer.rb', 'config/initializers/console_agent.rb'
+      end
+
+      def show_readme
+        say ''
+        say 'ConsoleAgent installed!', :green
+        say ''
+        say 'Next steps:'
+        say '  1. Set your API key: export ANTHROPIC_API_KEY=sk-...'
+        say '  2. Edit config/initializers/console_agent.rb if needed'
+        say '  3. Run: rails console'
+        say '  4. Try: ai "show me all tables"'
+        say ''
+      end
+    end
+  end
+end

data/lib/generators/console_agent/templates/initializer.rb

@@ -0,0 +1,33 @@
+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'
+
+  # Max tokens for LLM response
+  config.max_tokens = 4096
+
+  # Temperature (0.0 - 1.0)
+  config.temperature = 0.2
+
+  # Auto-execute generated code without confirmation (use with caution!)
+  config.auto_execute = false
+
+  # Context mode:
+  #   :smart - (default) minimal system prompt, LLM uses tools to fetch schema/model/code details on demand
+  #   :full  - sends all schema, models, and routes in the system prompt every time
+  config.context_mode = :smart
+
+  # Max tool-use rounds per query in :smart mode (safety cap)
+  config.max_tool_rounds = 10
+
+  # HTTP timeout in seconds
+  config.timeout = 30
+
+  # Debug mode: prints full API requests/responses and tool calls to stderr
+  # config.debug = true
+end