ask-rails 0.2.5 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6e0eb7fb3f6797eb16e096b2f2e5b0c79eb002d697be20df6ac0b2bbe5abf3a
-  data.tar.gz: 4c6ffe88deca00e9e43472e286fb37630ba30953a5488d577a37ee805ccd7b73
+  metadata.gz: 87296c9e940bcd34d48e640c3a13c3e3d634b57abf253c434d0919b1dc3388bc
+  data.tar.gz: b8edd3def1dfa96b41d6af0dd842bebb724ac9909c8728d5c8a193a3956e83be
 SHA512:
-  metadata.gz: 3aafbab19ef97841a392242282f19886624412ec92602dfc525dcfd2743f05adc523f2604c139e847a9078ec307f596c85005796d8dab484ca32bb84bcd36e3e
-  data.tar.gz: 0f13102f41d739aa2215684508a8d705df6ef2ad842b2404d4232bf4b689840ec0eca0153ea71f503ce114eadb11bd0396bee6d3d30202e9376caf04ebd506bc
+  metadata.gz: 4533e9675014317d48c973bcfa23dd30a996d24f9f5e734060c37250735cdf0569df6b38ed2bb60c3a6c6d0dfdb8cf814869d5b628a9f0e37a8f5f91616f8347
+  data.tar.gz: 13fc4f80420ad209ab5e531d254883858acb6e8ac28d7806bac514afcc58c278df79a3c7026dfa69a49f20fbd70fa7ef0ac5ecada3255afedb3d23c338dcff2d

data/CHANGELOG.md

@@ -1,35 +1,45 @@
-## [0.2.5] - 2026-06-25
+## [0.6.0] — 2026-07-29
+
+### Added
+
+- **`ask_state` migration in install generator** — `rails generate ask:install` now creates `db/migrate/create_ask_state.rb` with a shared key-value table for agent sessions and graph checkpoints.
+
+- **Standard Rails generator path** — Generator moved to `lib/generators/ask/install_generator.rb` for automatic Rails discovery. Run `rails generate ask:install` with no additional configuration.
 
 ### Changed
-- Expanded tests: Persistence(7t), Configuration(7t), ServiceDiscovery(5t), Engine(7t), InstallGenerator(7t), Tools(24t with live DB). Infrastructure: rubocop, overcommit, CI matrix, Appraisals, gemspec.
-## 0.2.4 (2026-06-21)
+
+- Generator creates two migrations with unique timestamps: `ask_state` first, then `ask_audit_logs`.
+
+### Tested
+
+- `rails generate ask:install` tested in production Rails app (kawibot) — creates initializer and both migrations.
+- Migrations run successfully against PostgreSQL.
+
+## [0.5.0] — 2026-07-26
 
 ### Added
-- `Ask::Rails::Engine` — Rails engine for autoloading and generator discovery
-- Skills directory with methodology skills (rails.db_debug, rails.deploy_pipeline, rails.route_trouble)
-- Gemspec metadata for Rubygems discovery
 
-# Changelog
+- **Audit log migration in install generator** — `rails generate ask_rails:install` now creates `db/migrate/create_ask_audit_logs.rb` with `if_not_exists: true`.
+  Table schema: `session_id`, `event_type`, `jsonb data`, `timestamp`, `created_at`, `updated_at`. Indexed on `[session_id, event_type]` and `timestamp`.
 
-## 0.2.0 (2026-06-10)
+### Changed
+
+- Install generator now includes `::Rails::Generators::Migration` for `migration_template` support.
+
+## [0.4.0] — 2026-07-26
 
 ### Added
-- `Ask::Rails::QueryDatabase` — read-only SQL queries via ActiveRecord with auto-LIMIT, 
-  binary column handling, and production write guards
-- `Ask::Rails::ReadModel` — structured model introspection returning columns, associations,
-  validators, and primary keys; supports detail filtering
-- `Ask::Rails::ReadLog` — filtered log reading that tail-reads from end of file, supports
-  level filtering (ERROR/WARN/INFO/DEBUG), case-insensitive search, and automatically
-  detects log rotation files
 
-## 0.1.0 (2026-06-10)
+- **ask-rails-harness** — new `Ask::Rails::Harness` module for configuring the Rails-facing agent harness. Separates ask-rb ecosystem configuration from Rails-specific agent harness settings.
+
+### Changed
+
+- `config/initializers/ask_rails.rb` now configures `Ask::Rails::Harness` instead of `Ask::Rails`.
+
+## [0.1.0] — 2026-07-26
 
 ### Added
-- Railtie — `Ask::Rails::Railtie` configures and discovers tools/services on boot
-- Configuration — `Ask::Rails::Configuration` with `default_model`, `max_turns`, `system_prompt`, `tool_concurrency`
-- Session Factory — `Ask::Rails.agent_session` creates pre-configured `Ask::Agent::Session`
-- Service Discovery — auto-discovers installed `ask-*` service gems, injects context into system prompt
-- AR Persistence — `Ask::Rails::Persistence` saves/loads session state to database
-- Rails Tools — `ReadFile`, `RunCommand`, `SearchCodebase`, `ReadRoutes` (Rails.root-aware)
-- Generators — `rails generate ask_rails:install` creates migration, initializer, `app/tools/`
-- Dependencies: rails >= 7.1, ask-tools, ask-tools-shell, ask-agent, ask-auth
+
+- Initial release of `ask-rails` — Rails integration for the ask-rb ecosystem.
+- **Install generator** — `rails generate ask:install` creates `config/initializers/ask.rb`, `app/agents/application_agent.rb`, and `app/agents/` directory.
+- **Railtie** — Wires `Ask::Agent.logger` to `Rails.logger`, discovers agent definitions in `app/agents/`.

data/README.md

@@ -1,34 +1,59 @@
 # ask-rails
 
-Rails integration for the ask-rb ecosystem. The only gem a Rails app needs to join
-the ask-rb stack — provides a Railtie, AR session persistence, a session factory,
-automatic service gem discovery, and generators.
+Rails integration for the [ask-rb](https://github.com/ask-rb) ecosystem. Provides generators, file conventions, and railtie for using AI agents in your Rails app.
 
 ## Installation
 
 ```bash
 bundle add ask-rails
-rails generate ask_rails:install
+rails generate ask:install
 ```
 
+This creates:
+- `config/initializers/ask.rb` — agent configuration
+- `app/agents/application_agent.rb` — base class for your agents
+- `app/agents/` — directory for agent definitions
+
 ## Usage
 
+Define an agent:
+
 ```ruby
-# In any Rails context
-session = Ask::Rails.agent_session
-session.run("Find all open issues labeled 'bug' in our repo")
+# app/agents/support_bot.rb
+class Agents::SupportBot < ApplicationAgent
+  model "gpt-4o"
+  system_prompt "You help users with support questions."
+
+  tool :bash
+  tool :read
+  tool :grep
+end
 ```
 
-Service gems like `ask-github`, `ask-slack` are auto-discovered — the agent gets their
-context (auth info, quick-start snippets, error guides) in the system prompt automatically.
+Run it:
+
+```ruby
+agent = Ask::Agent.new("support_bot")
+response = agent.run("Find all open issues in the codebase")
+puts response
+```
 
-## Development
+Or use `Ask.chat` for one-off conversations:
 
-```bash
-bin/setup
-bundle exec rake test
+```ruby
+Ask.chat("Summarize this article: #{text}")
 ```
 
+## Configuration
+
+API keys are resolved automatically by `Ask::Auth`:
+
+- **Environment variables:** `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.
+- **Rails credentials:** `rails credentials:edit` → add `ask.openai`, `ask.anthropic`
+- **File:** `~/.ask/credentials.yml`
+
+No manual credential setup is required.
+
 ## License
 
 MIT

data/lib/ask/rails/generators/install/install_generator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Ask
+  module Rails
+    module Generators
+      class InstallGenerator < ::Rails::Generators::Base
+        include ::Rails::Generators::Migration
+
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Sets up ask-rb for Rails — creates initializer, agents directory, state and audit log migrations"
+
+        def create_initializer
+          template "initializer.rb", "config/initializers/ask.rb"
+        end
+
+        def create_application_agent
+          template "application_agent.rb", "app/agents/application_agent.rb"
+        end
+
+        def create_agents_directory
+          empty_directory "app/agents"
+          create_file "app/agents/.keep", "" unless options[:skip_keep]
+        end
+
+        def create_state_migration
+          migration_template "state_migration.rb", "db/migrate/create_ask_state.rb"
+        end
+
+        def create_audit_log_migration
+          migration_template "audit_log_migration.rb", "db/migrate/create_ask_audit_logs.rb"
+        end
+
+        private
+
+        def migration_version
+          "[#{ActiveRecord::Migration.current_version}]"
+        end
+      end
+    end
+  end
+end

data/lib/ask/rails/generators/install/templates/application_agent.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Base class for your application's AI agents.
+#
+# Subclass this to define agents:
+#
+#   class Agents::SupportBot < ApplicationAgent
+#     model "gpt-4o"
+#     system_prompt "You help users with support questions."
+#
+#     tool :search_knowledge_base
+#   end
+#
+# Then run:
+#   agent = Ask::Agent.new("support_bot")
+#   agent.run("How do I reset my password?")
+#
+class ApplicationAgent < Ask::Agent::Definition
+  # Default instructions — override in subclasses
+  system_prompt "You are a helpful assistant."
+
+  # Uncomment to add built-in tools:
+  # tool :bash
+  # tool :read
+  # tool :grep
+end

data/lib/ask/rails/generators/install/templates/audit_log_migration.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Migration for ask-agent's audit log table.
+# This table records session events (tool calls, errors, token usage, etc.)
+# from every agent that has audit_log configured.
+class CreateAskAuditLogs < ActiveRecord::Migration[<%= migration_version %>]
+  def change
+    create_table :ask_audit_logs, if_not_exists: true do |t|
+      t.string :session_id, null: false
+      t.string :event_type, null: false
+      t.jsonb :data, default: {}
+      t.datetime :timestamp, null: false
+      t.timestamps
+
+      t.index [:session_id, :event_type]
+      t.index :timestamp
+    end
+  end
+end

data/lib/ask/rails/generators/install/templates/initializer.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Ask Agent Configuration
+# ========================
+#
+# API keys are resolved automatically by Ask::Auth:
+#   - Environment variables: OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.
+#   - Rails credentials: rails credentials:edit → ask.openai, ask.anthropic
+#   - ~/.ask/credentials.yml
+#
+# See https://github.com/ask-rb/ask-auth for details.
+
+# Shared key-value state store for agent sessions and graph checkpoints.
+# Uses the ask_state table created by the migration.
+ASK_STATE = Ask::State::PostgreSQL.new(
+  table_name: :ask_state
+)
+
+Ask::Agent.configure do |config|
+  # State persistence for agent sessions
+  config.state = ASK_STATE
+
+  # Audit log for session events
+  config.audit_log = { adapter: :active_record }
+
+  # config.default_model = "gpt-4o"
+end

data/lib/ask/rails/generators/install/templates/state_migration.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Migration for ask-rb's shared key-value state table.
+# Used by ask-agent (session persistence) and ask-graph (workflow checkpoints).
+# This single table serves both components — keys are namespaced by convention.
+class CreateAskState < ActiveRecord::Migration[<%= migration_version %>]
+  def change
+    create_table :ask_state do |t|
+      t.string :key, null: false
+      t.jsonb :value, null: false, default: {}
+      t.datetime :expires_at
+      t.timestamps
+
+      t.index :key, unique: true
+      t.index :expires_at
+    end
+  end
+end

data/lib/ask/rails/railtie.rb

@@ -3,25 +3,8 @@
 module Ask
   module Rails
     class Railtie < ::Rails::Railtie
-      rake_tasks do
-        # Load rake tasks if any
-      end
-
       generators do
-        require_relative "../../generators/ask/rails/install/install_generator"
-      end
-
-      initializer "ask_rails.configure" do |app|
-        Ask::Rails.configuration.default_model ||= ENV["ASK_DEFAULT_MODEL"] || "gpt-4o"
-        Ask::Rails.configuration.max_turns ||= (ENV["ASK_MAX_TURNS"] || 25).to_i
-      end
-
-      initializer "ask_rails.discover_tools", after: :eager_load_most do
-        Ask::Rails.discover_tools!
-      end
-
-      initializer "ask_rails.discover_services", after: :eager_load_most do
-        Ask::Rails::ServiceDiscovery.discover!
+        require_relative "generators/install/install_generator"
       end
     end
   end

data/lib/ask/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Rails
-    VERSION = "0.2.5"
+    VERSION = "0.6.0"
   end
 end

data/lib/ask/rails.rb

@@ -1,80 +1,11 @@
 # frozen_string_literal: true
 
-require "rails"
 require "ask/agent"
-require "ask/auth"
 
 module Ask
   module Rails
-    class << self
-      def configure
-        yield configuration
-      end
-
-      def configuration
-        @configuration ||= Configuration.new
-      end
-
-      def agent_session(**extra)
-        tools = configuration.tools.map { |t| t.is_a?(Class) ? t.new : t }
-        prompt = extra.delete(:system_prompt) || configuration.system_prompt || default_system_prompt
-
-        Ask::Agent::Session.new(
-          model: configuration.default_model,
-          max_turns: configuration.max_turns,
-          system_prompt: prompt,
-          tools: tools,
-          persistence: configuration.persistence_adapter,
-          **extra
-        )
-      end
-
-      def discover_tools!
-        self.configuration.tools = Ask::Tools::Shell::TOOLS.map(&:new) + discovered_rails_tools
-      end
-
-      def root
-        @root ||= Pathname.new(File.expand_path("..", __dir__))
-      end
-
-      private
-
-      def discovered_rails_tools
-        tools = []
-        files = Dir[::Rails.root.join("app", "tools", "*.rb")]
-        files.each do |f|
-          require f
-          klass = File.basename(f, ".rb").camelize.constantize rescue next
-          tools << klass if klass < Ask::Rails::Tool
-        end
-        tools
-      rescue
-        tools
-      end
-
-      def default_system_prompt
-        <<~PROMPT
-          You are a Ruby on Rails software engineer.
-          You have direct access to the application's code, database, and runtime.
-          Use your tools to inspect and modify the codebase.
-          Once you have enough information, stop calling tools and give your answer.
-        PROMPT
-      end
-    end
   end
 end
 
 require_relative "rails/version"
-require_relative "rails/engine"
-require_relative "rails/configuration"
-require_relative "rails/railtie"
-require_relative "rails/persistence"
-require_relative "rails/service_discovery"
-require_relative "rails/tool"
-require_relative "rails/tools/read_file"
-require_relative "rails/tools/run_command"
-require_relative "rails/tools/search_codebase"
-require_relative "rails/tools/read_routes"
-require_relative "rails/tools/query_database"
-require_relative "rails/tools/read_model"
-require_relative "rails/tools/read_log"
+require_relative "rails/railtie" if defined?(::Rails::Railtie)

data/lib/generators/ask/install/templates/audit_log_migration.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class CreateAskAuditLogs < ActiveRecord::Migration[8.1]
+  def change
+    create_table :ask_audit_logs, if_not_exists: true do |t|
+      t.string :session_id, null: false
+      t.string :event_type, null: false
+      t.jsonb :data, default: {}
+      t.datetime :timestamp, null: false
+      t.timestamps
+
+      t.index [:session_id, :event_type]
+      t.index :timestamp
+    end
+  end
+end

data/lib/generators/ask/install/templates/initializer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Ask Agent Configuration
+# ========================
+#
+# API keys are resolved automatically by Ask::Auth:
+#   - Environment variables: OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.
+#   - Rails credentials: rails credentials:edit → ask.openai, ask.anthropic
+#   - ~/.ask/credentials.yml
+#
+# See https://github.com/ask-rb/ask-auth for details.
+
+Ask::Agent.configure do |config|
+  # Enable audit logging to the ask_audit_logs table
+  # config.audit_log = { adapter: :active_record }
+
+  # Optional: set a default model
+  # config.default_model = "gpt-4o"
+end

data/lib/generators/ask/install/templates/state_migration.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class CreateAskState < ActiveRecord::Migration[8.1]
+  def change
+    create_table :ask_state do |t|
+      t.string :key, null: false
+      t.jsonb :value, null: false, default: {}
+      t.datetime :expires_at
+      t.timestamps
+
+      t.index :key, unique: true
+      t.index :expires_at
+    end
+  end
+end

data/lib/generators/ask/install_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Ask
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path("install/templates", __dir__)
+
+      desc "Sets up ask-rb for Rails — creates initializer, state and audit log migrations"
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/ask.rb"
+      end
+
+      def create_state_migration
+        template "state_migration.rb", "db/migrate/#{next_migration_number}_create_ask_state.rb"
+      end
+
+      def create_audit_log_migration
+        template "audit_log_migration.rb", "db/migrate/#{next_migration_number}_create_ask_audit_logs.rb"
+      end
+
+      private
+
+      def next_migration_number
+        # Rails requires exactly YYYYMMDDHHMMSS format
+        @migration_suffix ||= 0
+        now = Time.now.utc.strftime("%Y%m%d%H%M")
+        "#{now}#{format('%02d', @migration_suffix)}"
+      ensure
+        @migration_suffix = (@migration_suffix || 0) + 1
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.6.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -23,34 +23,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
-- !ruby/object:Gem::Dependency
-  name: ask-tools
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.1'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.1'
-- !ruby/object:Gem::Dependency
-  name: ask-tools-shell
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.1'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: ask-agent
   requirement: !ruby/object:Gem::Requirement
@@ -65,34 +37,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.1'
-- !ruby/object:Gem::Dependency
-  name: ask-auth
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.1'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.1'
-- !ruby/object:Gem::Dependency
-  name: sqlite3
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -135,8 +79,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-description: Railtie, AR session persistence, session factory, service gem discovery,
-  and generators.
+description: Rails generators, file conventions, and railtie for using ask-agent in
+  Rails apps.
 email:
 - kaka@myrrlabs.com
 executables: []
@@ -148,33 +92,24 @@ files:
 - README.md
 - lib/ask-rails.rb
 - lib/ask/rails.rb
-- lib/ask/rails/configuration.rb
-- lib/ask/rails/engine.rb
-- lib/ask/rails/persistence.rb
+- lib/ask/rails/generators/install/install_generator.rb
+- lib/ask/rails/generators/install/templates/application_agent.rb
+- lib/ask/rails/generators/install/templates/audit_log_migration.rb
+- lib/ask/rails/generators/install/templates/initializer.rb
+- lib/ask/rails/generators/install/templates/state_migration.rb
 - lib/ask/rails/railtie.rb
-- lib/ask/rails/service_discovery.rb
-- lib/ask/rails/tool.rb
-- lib/ask/rails/tools/query_database.rb
-- lib/ask/rails/tools/read_file.rb
-- lib/ask/rails/tools/read_log.rb
-- lib/ask/rails/tools/read_model.rb
-- lib/ask/rails/tools/read_routes.rb
-- lib/ask/rails/tools/run_command.rb
-- lib/ask/rails/tools/search_codebase.rb
 - lib/ask/rails/version.rb
-- lib/ask/skills/rails.db_debug/SKILL.md
-- lib/ask/skills/rails.deploy_pipeline/SKILL.md
-- lib/ask/skills/rails.route_trouble/SKILL.md
-- lib/generators/ask/rails/install/install_generator.rb
-- lib/generators/ask/rails/install/templates/initializer.rb
-- lib/generators/ask/rails/install/templates/migration.rb
+- lib/generators/ask/install/templates/audit_log_migration.rb
+- lib/generators/ask/install/templates/initializer.rb
+- lib/generators/ask/install/templates/state_migration.rb
+- lib/generators/ask/install_generator.rb
 homepage: https://github.com/ask-rb/ask-rails
 licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/ask-rb/ask-rails
   source_code_uri: https://github.com/ask-rb/ask-rails
-  changelog_uri: https://github.com/ask-rb/ask-rails/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/ask-rb/ask-rails/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib

data/lib/ask/rails/configuration.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module Ask
-  module Rails
-    class Configuration
-      attr_accessor :default_model, :max_turns, :system_prompt,
-                    :tool_concurrency, :persistence_adapter, :tools
-
-      def initialize
-        @default_model = "gpt-4o"
-        @max_turns = 25
-        @system_prompt = nil
-        @tool_concurrency = 5
-        @persistence_adapter = nil
-        @tools = []
-      end
-    end
-  end
-end

data/lib/ask/rails/engine.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "railtie"
-
-module Ask
-  module Rails
-    class Engine < ::Rails::Engine
-      isolate_namespace Ask::Rails
-    end
-  end
-end