console_agent 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 528fd68c058820f080d3b6d2aec7767ac48944e17ae6f2c117d279fbec4c8070
-  data.tar.gz: cf28f6caa721b229536bb591c1c5ecfbb51b1dbc55cee342bccfdaabbca0e804
+  metadata.gz: 53925e32cd4919e550bfdc081ede866613ce3ea18a585aca6cb81d1687ce3901
+  data.tar.gz: ae601be1b81ff2fcb89addda1c008c0646118f2af21c9009a1792556ffd9b4ed
 SHA512:
-  metadata.gz: 9127d4e6c9eea9cb56cd4484906fd80c97f07d2c276f8d65f5906338011d03c39a53e5c1a5bfc3e1cbd3ecb69a4b6ddd9716a1aa8416b091c056ad5f267f21b2
-  data.tar.gz: 567dea6f8c8f8213ad3ed4b5cafa9519f3ecbbaa5825355cbee1be8a56981565dd3ec4905285ad7bdae8c6c5ea312550396ce1dfd2fe1c98df3e29d7d43b5a3e
+  metadata.gz: 54ec67e116e4a05de7a5d915f93dc7babf2d64d2b008bc507718dce92d58ad032beeaa1d7710d8190943454f937f91780ff5614e44f5ef173ab5feff6dddb339
+  data.tar.gz: f12af224368e44b149d740f8d0b2dee4a38ce86564ee9337c5a8ed569a83bb387d3edcf2ae76142d4b510f507c5e6d64d82aab70c16eb94f66d83e3811eb0cd6

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,335 @@
+# ConsoleAgent
+
+An AI-powered assistant for your Rails console. Ask questions in plain English, get executable Ruby code.
+
+It's like Claude Code embedded in your Rails Console.
+
+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 (pick one):
+
+```bash
+# Option A: environment variable
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# Option B: in the initializer
+# config.api_key = 'sk-ant-...'
+```
+
+Open a console and go:
+
+```ruby
+rails console
+ai "show me all users who signed up this week"
+```
+
+You can also set or change your API key at runtime in the console:
+
+```ruby
+ConsoleAgent.configure { |c| c.api_key = 'sk-ant-...' }
+```
+
+## 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
+```
+
+All settings can be changed at runtime in the console:
+
+```ruby
+ConsoleAgent.configure { |c| c.api_key = 'sk-ant-...' }
+ConsoleAgent.configure { |c| c.debug = true }
+ConsoleAgent.configure { |c| c.provider = :openai; c.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 |
+| `ask_user` | Ask the console user a clarifying question |
+| `save_memory` | Persist a learned fact for future sessions |
+| `recall_memories` | Search saved memories |
+| `load_skill` | Load full instructions for a skill |
+
+The LLM decides which tools to call based on your question. You can see the tool calls happening in real time.
+
+## Memories & Skills
+
+ConsoleAgent can remember what it learns about your codebase across sessions and load reusable skill instructions on demand.
+
+### Memories
+
+When the AI investigates something complex (like how sharding works in your app), it can save what it learned for next time. Memories are stored in `.console_agent/memories.yml` in your Rails app.
+
+```
+ai> how many users are on this shard?
+  Thinking...
+  -> search_code("shard")
+     Found 50 matches
+  -> read_file("config/initializers/sharding.rb")
+     202 lines
+  -> save_memory("Sharding architecture")
+     Memory saved: "Sharding architecture"
+
+Each shard is a separate database. User.count returns the count for the current shard only.
+
+  User.count
+
+[tokens in: 2,340 | out: 120 | total: 2,460]
+```
+
+Next session, the AI already knows:
+
+```
+ai> count users on this shard
+  Thinking...
+
+  User.count
+
+[tokens in: 580 | out: 45 | total: 625]
+```
+
+The memory file is human-editable YAML:
+
+```yaml
+# .console_agent/memories.yml
+memories:
+  - id: mem_1709123456_42
+    name: Sharding architecture
+    description: "App uses database-per-shard. Each shard is a separate DB. User.count only counts the current shard."
+    tags: [database, sharding]
+    created_at: "2026-02-27T10:30:00Z"
+```
+
+You can commit this file to your repo so the whole team benefits, or gitignore it for personal use.
+
+### Skills
+
+Skills are reusable instruction files that teach the AI how to handle specific tasks. Store them in `.console_agent/skills/` as markdown files with YAML frontmatter:
+
+```markdown
+# .console_agent/skills/sharding.md
+---
+name: Sharded database queries
+description: How to query across database shards. Use when user asks about counting records across shards or shard-specific operations.
+---
+
+## Instructions
+
+This app uses Apartment with one database per shard.
+- `User.count` only counts the current shard
+- To count across all shards: `Shard.all.sum { |s| s.switch { User.count } }`
+- Current shard: `Apartment::Tenant.current`
+```
+
+Only the skill name and description are sent to the AI on every request (~100 tokens per skill). The full instructions are loaded on demand via the `load_skill` tool only when relevant.
+
+### Storage
+
+By default, memories and skills are stored on the filesystem at `Rails.root/.console_agent/`. This works for development and for production environments with a persistent filesystem.
+
+For containers or other environments where the filesystem is ephemeral, you have two options:
+
+**Option A: Commit to your repo.** Create `.console_agent/memories.yml` and `.console_agent/skills/*.md` in your codebase. They'll be baked into your Docker image.
+
+**Option B: Custom storage adapter.** Implement the storage interface and plug it in:
+
+```ruby
+ConsoleAgent.configure do |config|
+  config.storage_adapter = MyS3Storage.new(bucket: 'my-bucket', prefix: 'console_agent/')
+end
+```
+
+A storage adapter just needs four methods: `read(key)`, `write(key, content)`, `list(pattern)`, and `exists?(key)`.
+
+To disable memories or skills:
+
+```ruby
+ConsoleAgent.configure do |config|
+  config.memories_enabled = false
+  config.skills_enabled = false
+end
+```
+
+## 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
+```
+
+## Local Development
+
+To develop the gem locally against a Rails app, use a path reference in your Gemfile:
+
+```ruby
+gem 'console_agent', path: '/path/to/console_agent'
+```
+
+Switch back to the published gem when you're done:
+
+```ruby
+gem 'console_agent'
+```
+
+## Requirements
+
+- Ruby >= 2.5
+- Rails >= 5.0
+- Faraday >= 1.0
+
+## License
+
+MIT

data/lib/console_agent/configuration.rb

@@ -0,0 +1,61 @@
+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,
+                  :storage_adapter, :memories_enabled
+
+    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 = 100
+      @storage_adapter  = nil
+      @memories_enabled = true
+    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,131 @@
+module ConsoleAgent
+  module ConsoleMethods
+    def ai_status
+      ConsoleAgent.status
+    end
+
+    def ai_memories(n = nil)
+      require 'yaml'
+      require 'console_agent/tools/memory_tools'
+      storage = ConsoleAgent.storage
+      keys = storage.list('memories/*.md').sort
+
+      if keys.empty?
+        $stdout.puts "\e[2mNo memories stored yet.\e[0m"
+        return nil
+      end
+
+      memories = keys.filter_map do |key|
+        content = storage.read(key)
+        next if content.nil? || content.strip.empty?
+        next unless content =~ /\A---\s*\n(.*?\n)---\s*\n(.*)/m
+        fm = YAML.safe_load($1, permitted_classes: [Time, Date]) || {}
+        fm.merge('description' => $2.strip, 'file' => key)
+      end
+
+      if memories.empty?
+        $stdout.puts "\e[2mNo memories stored yet.\e[0m"
+        return nil
+      end
+
+      shown = n ? memories.last(n) : memories.last(5)
+      total = memories.length
+
+      $stdout.puts "\e[36m[Memories — showing last #{shown.length} of #{total}]\e[0m"
+      shown.each do |m|
+        $stdout.puts "\e[33m  #{m['name']}\e[0m"
+        $stdout.puts "\e[2m  #{m['description']}\e[0m"
+        tags = Array(m['tags'])
+        $stdout.puts "\e[2m  tags: #{tags.join(', ')}\e[0m" unless tags.empty?
+        $stdout.puts
+      end
+
+      path = storage.respond_to?(:root_path) ? File.join(storage.root_path, 'memories') : 'memories/'
+      $stdout.puts "\e[2mStored in: #{path}/\e[0m"
+      $stdout.puts "\e[2mUse ai_memories(n) to show last n.\e[0m"
+      nil
+    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"
+        $stderr.puts "\e[33m  ai_memories - show recent memories (ai_memories(n) for last n)\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