asktive_record 0.1.7 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7892f64b41650512ee4e49b6b620453f9c89e99a9e9aa20f0c3c6437b63cf1e6
-  data.tar.gz: 657c6c0938f4179e02b76592093171b4917e0ed6cb105769139c940930ef18ec
+  metadata.gz: 459d4765079933a22356f0590b4921814565f2ced2dd40218bdfae032a1af89a
+  data.tar.gz: a75f994772cdb082159f6712a4b3f5ee6503ca3c58962f1a37743ed2531be45e
 SHA512:
-  metadata.gz: 73e84b0e0d7ef1dfe09391869a5c3ca8a026c02c28b85efa6c0720daf28ba235ce18d8609dc5b2e5d01a3f60670211a194e179024c53f01e2a8744ffd65011fc
-  data.tar.gz: 00db510181ccf36880333f83275e67557eec8f0e4d2f251e432e5c9f3f045ec5070eaaa480c25c45e986c6a24c7607173cb448c0d788cc783b93a0fd9ae59335
+  metadata.gz: d740d0ecc26e1164df04a138b535359ffd3a05604a311d329512fdf2297fc84f9e207302d3fba590a84e56721c0a8380127cfb2f84f29d61fb583aecc77778e6
+  data.tar.gz: 82c0fa432355cfb029c5f1656abd86e673231fe3d7bc9d7f1256a513f96ba22aed5f42a320c23a40f52691338b75a5c7fab7a9814579bf2ee7e193225c950548

data/.rubocop.yml

@@ -1,12 +1,30 @@
 AllCops:
-  TargetRubyVersion: 3.0
+  TargetRubyVersion: 3.1
+  NewCops: enable
   Exclude:
     - 'spec/**/*'
     - 'db/schema.rb'
     - 'vendor/**/*'
+    - 'bin/**/*'
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes
 
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120
+  AllowedPatterns: ['#']
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/AbcSize:
+  Max: 25
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false

data/CHANGELOG.md

@@ -1,4 +1,55 @@
-## [Unreleased]
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-03-26
+
+### Added
+- **Adapter Pattern**: Pluggable LLM provider architecture via `AsktiveRecord::Adapters::Base`
+  - Built-in `Adapters::OpenAI` adapter wrapping the ruby-openai gem
+  - Custom adapters can be passed via `config.adapter = MyAdapter.new(...)`
+- **SQL Sanitizer** (`AsktiveRecord::SqlSanitizer`): Defense-in-depth SQL injection prevention
+  - Dangerous keyword blocklist (INSERT, UPDATE, DELETE, DROP, ALTER, etc.)
+  - Injection pattern detection (UNION SELECT, semicolons, comments, SLEEP, etc.)
+- **Prompt Injection Prevention**: Input escaping and pattern filtering in `AsktiveRecord::Prompt`
+  - 2,000-character input limit
+  - Detects and rejects common prompt injection patterns
+- **Configurable Logger** (`AsktiveRecord::Log`): Structured logging with `[AsktiveRecord]` prefix
+  - Replaces all `puts` calls with proper log levels (info, debug, warn, error)
+  - Defaults to `Rails.logger` when available, falls back to `Logger.new($stdout)`
+- **Schema Loader Module** (`AsktiveRecord::SchemaLoader`): Shared schema loading logic
+- New configuration options: `temperature`, `max_tokens`, `cache_enabled`, `adapter`, `read_only`
+- Comprehensive test suite: **180 examples** (up from 87), **96.63% line / 84.88% branch coverage**
+  - Adapter specs (Base + OpenAI)
+  - SqlSanitizer spec (31 examples)
+  - Prompt spec (14 examples)
+  - Log spec (7 examples)
+  - SchemaLoader spec (10 examples)
+
+### Changed
+- **BREAKING**: Minimum Ruby version raised to 3.1.0 (was 3.0.0)
+- **BREAKING**: Minimum Rails version raised to 7.0 (was 6.1)
+- Default LLM model changed from `gpt-3.5-turbo` to `gpt-4o-mini` (3.5 is deprecated)
+- `LlmService` now delegates to adapter instead of directly using `OpenAI::Client`
+- `Query` class uses `SqlSanitizer` for robust validation
+- Initializer template uses `ENV["OPENAI_API_KEY"]` instead of hardcoded placeholder
+- Removed `zeitwerk` dependency (not needed for gem autoloading)
+- Added `rubygems_mfa_required` metadata for publish security
+
+### Fixed
+- SQL injection vulnerability: queries were not validated before execution
+- Prompt injection vulnerability: user input was passed directly to LLM prompts
+- Removed `system()` shell execution call in Model module
+- Fixed dead code paths in Query class (`extract_count_if_present`, no-op `exec_query`)
+- API key no longer leaked in hardcoded initializer template
+
+### Security
+- All 8 identified security vulnerabilities have been addressed
+- Defense-in-depth: SQL validation at LlmService, Query, and SqlSanitizer levels
+- Read-only mode enabled by default (only SELECT queries allowed)
 
 ## [0.1.0] - 2025-05-13
 

data/README.md

@@ -1,37 +1,15 @@
 # AsktiveRecord: A Ruby gem that lets your data answer like a human
 
-[![Gem Version](https://badge.fury.io/rb/asktive_record.svg)](https://badge.fury.io/rb/asktive_record) <!-- Placeholder: Update once published -->
-[![Build Status](https://github.com/rpossan/asktive_record/actions/workflows/main.yml/badge.svg)](https://github.com/rpossan/asktive_record/actions/workflows/main.yml) <!-- Placeholder: Update with correct repo path -->
+[![Gem Version](https://badge.fury.io/rb/asktive_record.svg)](https://badge.fury.io/rb/asktive_record)
+[![Build Status](https://github.com/rpossan/asktive_record/actions/workflows/main.yml/badge.svg)](https://github.com/rpossan/asktive_record/actions/workflows/main.yml)
 
-> **AsktiveRecord** is a Ruby gem designed to bridge the gap between human language and database queries. It lets you interact with your Rails database as if you were having a conversation with a knowledgeable assistant. Instead of writing SQL or chaining ActiveRecord methods, you simply ask questions in plain English—like (or any language) "Who are my newest users?" or "What products sold the most last month?"—and get clear, human-friendly answers. AsktiveRecord translates your questions into database queries using LLM behind the scenes, so you can focus on what you want to know, not how to write the query.
+> **AsktiveRecord** is a Ruby gem designed to bridge the gap between human language and database queries. It lets you interact with your Rails database as if you were having a conversation with a knowledgeable assistant. Instead of writing SQL or chaining ActiveRecord methods, you simply ask questions in plain English (or any language)—like "Who are my newest users?" or "What products sold the most last month?"—and get clear, human-friendly answers. AsktiveRecord translates your questions into database queries using LLMs behind the scenes, so you can focus on what you want to know, not how to write the query.
 
-## Features
-
-*   **Natural Language to SQL**: Convert human-readable questions into SQL queries.
-*   **LLM Integration**: Currently supports OpenAI's ChatGPT, with a design that allows for future expansion to other LLMs (e.g., Gemini).
-*   **Get Answers, Not Just Data**: Use the `.answer` method to get concise, human-readable responses to your queries, rather than raw data or SQL.
-*   **Avoid ActiveRecord Chaining and SQL**: No need to write complex ActiveRecord queries or SQL statements. Just ask your question in natural language.
-*   **Works with Multiple Languages**: While the gem is designed with English in mind, it can handle queries in other languages, depending on the LLM's capabilities.
-*   **Flexible Querying Options**:
-    *   Use with specific models (e.g., `User.ask("query")`)
-    *   Use with service classes to query any table (e.g., `AskService.ask("query")`)
-*   **Database Schema Awareness**: Uploads your database schema to the LLM for context-aware query generation.
-*   **Developer Control**: Provides a two-step query process: first, get the LLM-generated SQL, then sanitize and execute it, giving you full control over what runs against your database.
-*   **Smart Execution**: Automatically uses the appropriate execution method (`find_by_sql` for models, `ActiveRecord::Base.connection` for service classes).
-*   **Easy Setup**: Simple CLI commands to install and configure the gem in your Rails project.
-*   **Customizable Configuration**: Set your LLM provider, API keys, and model preferences through an initializer.
+## Requirements
 
-## How It Works
-
-1.  **Setup**: You install the gem and run a setup command. This command can read your `db/schema.rb` (or `db/structure.sql`) and make the LLM aware of your database structure.
-2.  **Configuration**: You configure your LLM API key and preferences in an initializer file.
-3.  **Querying**: You can query your database in two ways:
-    *   Model-specific: `User.ask("your natural language query")`
-    *   Service-based (any table): `AskService.ask("your natural language query")`
-4.  **LLM Magic**: AsktiveRecord sends your query and the relevant schema context to the configured LLM.
-5.  **SQL Generation**: The LLM returns a SQL query.
-6.  **Safety First**: The `ask` method returns a `AsktiveRecord::Query` object containing the raw SQL. You can then inspect this SQL, apply sanitization rules (e.g., ensure it's only a `SELECT` statement), and then explicitly execute it.
-7.  **Execution**: The `execute` method intelligently runs the sanitized SQL. If the query originated from a model (like `User.ask`), it uses `User.find_by_sql`. If it originated from a service class (like `AskService.ask`), it uses the general `ActiveRecord::Base.connection` to execute the query, returning an array of hashes for `SELECT` statements.
+- Ruby >= 3.1.0
+- Rails >= 7.0 (railties)
+- An OpenAI API key (or a custom LLM adapter)
 
 ## Installation
 
@@ -47,15 +25,90 @@ And then execute:
 $ bundle install
 ```
 
-Or install it yourself as:
+## Getting Started
+
+Create configuration file:
 
 ```bash
-$ gem install asktive_record
+$ bundle exec rails generate asktive_record:install
+# It will create a new Rails initializer file at `config/initializers/asktive_record.rb`
 ```
 
-## Getting Started
+Check the `config/initializers/asktive_record.rb` file to configure your LLM provider and API key. By default, setup will generate and read the `db/schema.rb` (or `db/structure.sql`) to make the LLM aware of your database structure.
+
+```bash
+$ bundle exec rails generate asktive_record:setup
+```
+
+This command will generate and read the `db/schema.rb` (or `db/structure.sql`) and make the LLM aware of your database structure. You can change the schema file path and skip the dump schema setting in the `config/initializers/asktive_record.rb` file if you are using a custom schema file or a non-standard schema location for legacy databases.
+
+See the [Configuration](#configuration) section for more details.
+
+```ruby
+# Include AsktiveRecord in your ApplicationRecord or specific models
+class User < ApplicationRecord
+  include AsktiveRecord
+end
+
+# Now you can query any table through this service
+query = User.ask("Show me the last five users who signed up")
+# => Returns a Query object with SQL targeting the users table based on your schema. Does not execute the SQL yet.
+
+# You can check the object with the generated SQL:
+query.raw_sql
+# => "SELECT * FROM users ORDER BY created_at DESC LIMIT 5"
+
+# Call the execute method to run the query on the database
+results = query.execute
+# => Returns an array of User objects (if the query is a SELECT) or raises an `AsktiveRecord::QueryExecutionError` if the query fails.
+
+# If you want to execute the query and get the response like human use the method answer
+results = query.answer
+# => Returns a string with the answer to the question, e.g., "The last five users who signed up are: [User1, User2, User3, User4, User5]"
+```
+
+For more detailed usage instructions, see the [Usage](#usage) section below.
+
+## Features
 
-After installing the gem, you need to run the installer to generate the configuration file:
+* **Natural Language to SQL**: Convert human-readable questions into SQL queries.
+* **LLM Adapter Pattern**: Pluggable architecture supporting OpenAI out of the box, with an extensible base for custom adapters (Anthropic, Gemini, local models, etc.).
+* **Security First**:
+  * SQL injection prevention via `SqlSanitizer` (keyword blocklist + injection pattern detection)
+  * Prompt injection prevention with input escaping and pattern filtering
+  * Read-only mode by default (only SELECT queries allowed)
+  * Defense-in-depth validation at multiple layers
+* **Get Answers, Not Just Data**: Use the `.answer` method to get concise, human-readable responses to your queries, rather than raw data or SQL.
+* **Avoid ActiveRecord Chaining and SQL**: No need to write complex ActiveRecord queries or SQL statements. Just ask your question in natural language.
+* **Works with Multiple Languages**: While the gem is designed with English in mind, it can handle queries in other languages, depending on the LLM's capabilities.
+* **Flexible Querying Options**:
+  * Use with specific models (e.g., `User.ask("query")`)
+  * Use with service classes to query any table (e.g., `AskService.ask("query")`)
+* **Database Schema Awareness**: Passes your database schema to the LLM for context-aware query generation.
+* **Developer Control**: Provides a two-step query process: first, get the LLM-generated SQL, then sanitize and execute it, giving you full control over what runs against your database.
+* **Smart Execution**: Automatically uses the appropriate execution method (`find_by_sql` for models, `ActiveRecord::Base.connection` for service classes).
+* **Structured Logging**: Configurable logging with `[AsktiveRecord]` prefix, defaults to `Rails.logger`.
+* **Easy Setup**: Simple CLI commands to install and configure the gem in your Rails project.
+* **Customizable Configuration**: Set your LLM provider, API keys, model preferences, temperature, and more through an initializer.
+
+## How It Works
+
+1. **Setup**: You install the gem and run a setup command. This command reads your `db/schema.rb` (or `db/structure.sql`) and makes the LLM aware of your database structure.
+2. **Configuration**: You configure your LLM API key and preferences in an initializer file.
+3. **Querying**: You can query your database in two ways:
+   * Model-specific: `User.ask("your natural language query")`
+   * Service-based (any table): `AskService.ask("your natural language query")`
+4. **LLM Processing**: AsktiveRecord sends your query and the relevant schema context to the configured LLM via the adapter.
+5. **SQL Generation**: The LLM returns a SQL query.
+6. **Safety First**: The generated SQL is validated through multiple layers:
+   * `SqlSanitizer` checks for dangerous keywords and injection patterns
+   * Read-only mode ensures only SELECT statements execute
+   * The `Query` object lets you inspect the SQL before execution
+7. **Execution**: The `execute` method runs the sanitized SQL. If the query originated from a model (like `User.ask`), it uses `User.find_by_sql`. If from a service class (like `AskService.ask`), it uses `ActiveRecord::Base.connection`.
+
+## Configuration
+
+After installing the gem, run the installer to generate the configuration file:
 
 ```bash
 $ bundle exec rails generate asktive_record:install
@@ -71,59 +124,95 @@ Open `config/initializers/asktive_record.rb` and configure your LLM provider and
 AsktiveRecord.configure do |config|
   # === LLM Provider ===
   # Specify the LLM provider to use. Default is :openai
-  # Supported providers: :openai (more can be added in the future)
   # config.llm_provider = :openai
 
   # === LLM API Key ===
   # Set your API key for the chosen LLM provider.
   # It is strongly recommended to use environment variables for sensitive data.
-  # For example, for OpenAI:
-  # config.llm_api_key = ENV["OPENAI_API_KEY"]
-  config.llm_api_key = "YOUR_OPENAI_API_KEY_HERE" # Replace with your actual key or ENV variable
+  config.llm_api_key = ENV["OPENAI_API_KEY"]
 
   # === LLM Model Name ===
-  # Specify the model name for the LLM provider if applicable.
-  # For OpenAI, default is "gpt-3.5-turbo". Other models like "gpt-4" can be used.
-  # config.llm_model_name = "gpt-3.5-turbo"
+  # Specify the model name. Default is "gpt-4o-mini".
+  # Other models like "gpt-4o" or "gpt-4-turbo" can be used.
+  # config.llm_model_name = "gpt-4o-mini"
 
   # === Database Schema Path ===
-  # Path to your Rails application's schema file (usually schema.rb or structure.sql).
-  # This is used by the `asktive_record:setup` command and the `.ask` method to provide context to the LLM.
+  # Path to your schema file (schema.rb or structure.sql).
   # Default is "db/schema.rb".
   # config.db_schema_path = "db/schema.rb"
 
   # === Skip dump schema ===
-  # If set to true, the schema will not be dumped when running the
-  # `asktive_record:setup` command.
-  # This is useful if you want to manage schema dumps manually
-  # or if you are using a different schema management strategy.
+  # If true, the schema will not be dumped during `asktive_record:setup`.
   # config.skip_dump_schema = false
+
+  # === Read-Only Mode ===
+  # When true (default), only SELECT queries are allowed.
+  # config.read_only = true
+
+  # === LLM Temperature ===
+  # Controls randomness. Lower = more deterministic. Default: 0.2
+  # config.temperature = 0.2
+
+  # === LLM Max Tokens ===
+  # Maximum tokens in the LLM response. Default: 250
+  # config.max_tokens = 250
+
+  # === Custom Adapter ===
+  # Provide a custom LLM adapter instead of using the built-in provider.
+  # The adapter must inherit from AsktiveRecord::Adapters::Base.
+  # config.adapter = MyCustomAdapter.new(api_key: ENV["MY_LLM_KEY"])
+
+  # === Custom Logger ===
+  # Set a custom logger. Defaults to Rails.logger when available.
+  # config.logger = Logger.new($stdout)
 end
 ```
 
-**Important**: Securely manage your API keys. Using environment variables (e.g., `ENV["OPENAI_API_KEY"]`) is highly recommended.
+**Important**: Securely manage your API keys. Using environment variables (e.g., `ENV["OPENAI_API_KEY"]`) is strongly recommended. Never commit API keys to source control.
+
+### Custom LLM Adapters
+
+AsktiveRecord uses an adapter pattern for LLM communication. You can create custom adapters for any LLM provider:
+
+```ruby
+class AnthropicAdapter < AsktiveRecord::Adapters::Base
+  def chat(prompt, options = {})
+    # Your Anthropic API call here
+    # Must return a string response (the SQL or answer text)
+  end
+
+  def default_model_name
+    "claude-sonnet-4-20250514"
+  end
+end
+
+# Use it in your configuration:
+AsktiveRecord.configure do |config|
+  config.adapter = AnthropicAdapter.new(
+    api_key: ENV["ANTHROPIC_API_KEY"],
+    model_name: "claude-sonnet-4-20250514"
+  )
+end
+```
 
 ### Prepare Schema for LLM
 
-Run the setup command to help AsktiveRecord understand your database structure. This command attempts to read your schema file (e.g., `db/schema.rb`).
+Run the setup command to help AsktiveRecord understand your database structure:
 
 ```bash
 $ bundle exec rails generate asktive_record:setup
 ```
 
-If your app uses a custom schema file or a non-standard schema location, you can specify the path in your configuration. For example, if your schema is located at `db/custom_schema.rb`, update your initializer:
+If your app uses a custom schema file or a non-standard schema location, you can specify the path in your configuration:
 
 ```ruby
 AsktiveRecord.configure do |config|
   config.db_schema_path = "db/custom_schema.rb"
-  config.skip_dump_schema = true # If your app uses a legacy schema or doesn't need to dump it using rails db:schema:dump (default is false)
+  config.skip_dump_schema = true
 end
 ```
 
-This ensures AsktiveRecord reads the correct schema file when providing context to the LLM. Make sure the specified file accurately reflects your database structure.
-
-
-This step ensures that the LLM has the necessary context about your tables and columns to generate accurate SQL queries. The schema content is passed with each query to the LLM in the current version.
+This ensures AsktiveRecord reads the correct schema file when providing context to the LLM.
 
 ## Usage
 
@@ -132,37 +221,35 @@ AsktiveRecord offers two ways to query your database using natural language:
 ### 1. Model-Specific Querying
 
 This approach ties queries to specific models, ideal when you know which table you want to query.
-If you want to apply AsktiveRecord for all your Rails models, add the `include AsktiveRecord` line in your `ApplicationRecord` or specific models. This allows you to use the `.ask` method directly on those models.
 
 ```ruby
-# First, include AsktiveRecord in your ApplicationRecord or specific models
+# Include AsktiveRecord in your ApplicationRecord or specific models
 class ApplicationRecord < ActiveRecord::Base
   primary_abstract_class
   include AsktiveRecord
 end
 
 # Or in a specific model
-# In this case, you can query the User model directly for the model table. All queries will be scoped to the users table.
 class User < ApplicationRecord
   include AsktiveRecord
 end
 
 # Now you can query the User model directly
 query = User.ask("Show me the last five users who signed up")
-# => Returns a Query object with SQL targeting the users table, not the sql executed yet
+# => Returns a Query object with SQL targeting the users table
 
 # Call the execute method to run the query on the database
 results = query.execute
-# => Returns an array of User objects (if the query is a SELECT) or raises an
+# => Returns an array of User objects
 
-# If you want to execute the query and get the response like human use the method answer
+# If you want a human-readable answer, use the answer method
 results = query.answer
-# => Returns a string with the answer to the question, e.g., "The last five users who signed up are: [User1, User2, User3, User4, User5]"
+# => "The last five users who signed up are: Alice, Bob, Charlie, Diana, Eve."
 ```
 
 ### 2. Service-Class Querying (Any Table)
 
-This approach allows querying any table or multiple tables with joins, ideal for more complex queries or when you want a central service to handle all natural language queries.
+This approach allows querying any table or multiple tables with joins:
 
 ```ruby
 # Create a service class that includes AsktiveRecord
@@ -171,23 +258,23 @@ class AskService
   # No additional code needed!
 end
 
-# Now you can query any table through this service
-asktive_record_query = AskService.ask("Which is the last user created?")
-# => Returns a Query object with SQL targeting the users table, not the sql executed yet
+# Query any table through this service
+query = AskService.ask("Which is the last user created?")
+# => Returns a Query object
 
-asktive_record_query = AskService.ask("Which is the cheapest product?").execute
-# => Returns an ActiveRecord::Result object (array of hashes) with the cheapest product details
+results = AskService.ask("Which is the cheapest product?").execute
+# => Returns an ActiveRecord::Result object (array of hashes)
 
-asktive_record_query = AskService.ask("Show me products with their categories").answer
-# => Returns a Query object with SQL that might include JOINs between products and categories
-# => Returns a string with the answer to the question, e.g., "The products with their categories are: [Product1, Product2, ...]"
+answer = AskService.ask("Show me products with their categories").answer
+# => "The products with their categories are: Widget (Electronics), Gadget (Electronics), ..."
 ```
 
 ### Working with Query Results
 
-Once you have executed a query, you can work with the results. The `execute` method returns different types of results based on the context:
-*   If the query is from a model (e.g., `User.ask(...)`), it returns an array of model instances (e.g., `User` objects).
-*   If the query is from a service class (e.g., `AskService.ask(...)`), it returns an `ActiveRecord::Result` object, which is an array of hashes representing the query results.
+The `execute` method returns different types of results based on the context:
+* **Model queries** (e.g., `User.ask(...)`): returns an array of model instances (e.g., `User` objects)
+* **Service queries** (e.g., `AskService.ask(...)`): returns an `ActiveRecord::Result` object (array of hashes)
+
 ```ruby
 # Example of working with results from a model query
 query = User.ask("Who are my newest users?")
@@ -195,21 +282,18 @@ results = query.execute
 # => results is an array of User objects
 ```
 
-### The `AsktiveRecord::Query` Object
-
 ### The `.answer` Method
 
-The `.answer` method provides a human-friendly, natural language response to your query, instead of returning raw data or SQL. When you call `.answer` on a query object, AsktiveRecord executes the query and uses the LLM to generate a concise, readable answer based on the results.
+The `.answer` method provides a human-friendly, natural language response to your query. When you call `.answer`, AsktiveRecord executes the query and uses the LLM to generate a concise, readable answer based on the results.
 
 ### Example Usage
 
-
 ```ruby
-# Using a service class to ask a question
+# Using a service class
 response = AskService.ask("Which is the cheapest product?").answer
 # => "The cheapest product is the Earphone."
 
-# Using a model to ask a question
+# Using a model
 response = User.ask("Who signed up most recently?").answer
 # => "The most recently signed up user is Alice Smith."
 
@@ -218,66 +302,69 @@ response = AskService.ask("How many orders were placed last week?").answer
 # => "There were 42 orders placed last week."
 ```
 
-Tip: You can get the query param and interpolates it into the ask method to get a more specific answer. For example, if you want to know the last user created, you can do:
+Tip: You can interpolate dynamic values into the question:
 
 ```ruby
 customer = Customer.find(params[:id])
-query = "Which is my most sold product?"
-response = AskService.ask("For the customer #{customer.id}, #{query}").answer
+response = AskService.ask("For customer #{customer.id}, which is the most sold product?").answer
 # => "The most sold product for customer ABC is the Premium Widget."
 ```
 
-The `.answer` method is ideal when you want a direct, human-readable summary, rather than an array of records or a SQL query.
+### Query Object API
 
-The `ask()` method returns an instance of `AsktiveRecord::Query`. This object has a few useful methods:
+The `ask()` method returns an instance of `AsktiveRecord::Query`. Key methods:
 
-*   `raw_sql`: The raw SQL string generated by the LLM.
-*   `sanitized_sql`: The SQL string after `sanitize!` has been called. Initially, it's the same as `raw_sql`.
-*   `sanitize!(allow_only_select: true)`: Performs sanitization. By default, it ensures the query is a `SELECT` statement. Raises `AsktiveRecord::SanitizationError` on failure. Returns `self` for chaining.
-*   `execute`: Executes the `sanitized_sql` against the database.
-    *   If the query originated from a model (e.g., `User.ask(...)`), it uses `YourModel.find_by_sql` and returns model instances.
-    *   If the query originated from a service class (e.g., `AskService.ask(...)`), it uses `ActiveRecord::Base.connection.select_all` (for SELECT) or `execute` and returns an `ActiveRecord::Result` object (array of hashes) or connection-specific results.
-*   `to_s`: Returns the `sanitized_sql` (or `raw_sql` if `sanitized_sql` hasn't been modified from raw).
+* `raw_sql` — The raw SQL string generated by the LLM.
+* `sanitized_sql` — The SQL string after `sanitize!` has been called.
+* `sanitize!(allow_only_select: true)` — Validates the query through `SqlSanitizer`. Raises `AsktiveRecord::SanitizationError` on failure.
+* `execute` — Executes the sanitized SQL against the database.
+* `answer` — Executes the query and returns a human-readable LLM-generated answer.
+* `to_s` — Returns the sanitized SQL (or raw SQL if not yet sanitized).
 
 ## Logging
-AsktiveRecord provides logging to help you debug and monitor natural language queries, generated SQL, and results. By default, logs are sent to the Rails logger at the `:info` level.
 
-### Example Log Output
+AsktiveRecord provides structured logging to help you debug and monitor queries. By default, logs are sent to `Rails.logger` with the `[AsktiveRecord]` prefix.
 
-When you run a query, you might see logs like:
+### Example Log Output
 
 ```
 [AsktiveRecord] Received question: "Who are my newest users?"
-[AsktiveRecord] Generated SQL: SELECT * FROM users ORDER BY created_at DESC LIMIT 5;
-[AsktiveRecord] Sanitized SQL: SELECT * FROM users ORDER BY created_at DESC LIMIT 5;
-[AsktiveRecord] Executing SQL via User.find_by_sql
-[AsktiveRecord] Query results: [#<User id: 1, name: "Alice", ...>, ...]
+[AsktiveRecord] Generated SQL: SELECT * FROM users ORDER BY created_at DESC LIMIT 5
+[AsktiveRecord] Sanitized SQL: SELECT * FROM users ORDER BY created_at DESC LIMIT 5
 ```
 
-When using the `.answer` method:
+When using `.answer`:
 
 ```
 [AsktiveRecord] Received question: "How many orders were placed last week?"
-[AsktiveRecord] Generated SQL: SELECT COUNT(*) FROM orders WHERE created_at >= '2024-06-01' AND created_at < '2024-06-08';
-[AsktiveRecord] Query results: [{"count"=>42}]
-[AsktiveRecord] LLM answer: "There were 42 orders placed last week."
+[AsktiveRecord] Generated SQL: SELECT COUNT(*) FROM orders WHERE created_at >= '2024-06-01'
+[AsktiveRecord] Answering question: How many orders were placed last week?
 ```
 
+## Security
+
+AsktiveRecord implements defense-in-depth security:
+
+* **SQL Sanitization**: All generated SQL passes through `SqlSanitizer` which blocks dangerous keywords (INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, etc.) and injection patterns (UNION SELECT, semicolons, comments, SLEEP, etc.)
+* **Read-Only Mode**: Enabled by default — only SELECT queries are allowed to execute
+* **Prompt Injection Prevention**: User input is escaped and filtered before being sent to the LLM, with a 2,000-character limit
+* **No Hardcoded Secrets**: Initializer template uses `ENV["OPENAI_API_KEY"]` by default
+* **Multi-Layer Validation**: SQL is validated at the LLM response level, the Query level, and the SqlSanitizer level
 
 ## Supported LLMs
 
-*   **Currently**: OpenAI (ChatGPT models like `gpt-3.5-turbo`, `gpt-4`).
-*   **Future**: The gem is designed to be extensible. Support for other LLMs (like Google's Gemini) can be added by creating new LLM service adapters.
+* **Built-in**: OpenAI (models like `gpt-4o-mini`, `gpt-4o`, `gpt-4-turbo`)
+* **Custom Adapters**: Any LLM can be supported by creating an adapter that inherits from `AsktiveRecord::Adapters::Base` and implements the `#chat` method
 
 ## Contributing
 
 Contributions are welcome! Whether it's bug reports, feature requests, documentation improvements, or code contributions, please feel free to open an issue or submit a pull request on GitHub.
 
-1.  Fork the repository ([https://github.com/rpossan/asktive_record/fork](https://github.com/rpossan/asktive_record/fork)).
-2.  Create your feature branch (`git checkout -b my-new-feature`).
-3.  Commit your changes (`git commit -am 'Add some feature'`).
-4.  Push to the branch (`git push origin my-new-feature`).
-5.  Create a new Pull Request.
+1. Fork the repository ([https://github.com/rpossan/asktive_record/fork](https://github.com/rpossan/asktive_record/fork)).
+2. Create your feature branch (`git checkout -b my-new-feature`).
+3. Commit your changes (`git commit -am 'Add some feature'`).
+4. Push to the branch (`git push origin my-new-feature`).
+5. Create a new Pull Request.
 
 Please make sure to add tests for your changes and ensure all tests pass (`bundle exec rspec`). Also, adhere to the existing code style (you can use RuboCop: `bundle exec rubocop`).
 
@@ -294,8 +381,3 @@ The gem is available as open source under the terms of the [MIT License](https:/
 ## Code of Conduct
 
 Everyone interacting in the AsktiveRecord project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
-
----
-
-*This gem was proudly developed with the assistance of an AI agent.* Author: [rpossan](https://github.com/rpossan)
-

data/lib/asktive_record/adapters/base.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module AsktiveRecord
+  module Adapters
+    # Base adapter class that defines the interface all LLM adapters must implement.
+    # To create a custom adapter, inherit from this class and implement the required methods.
+    #
+    # @example Creating a custom adapter
+    #   class MyAdapter < AsktiveRecord::Adapters::Base
+    #     def chat(prompt, options = {})
+    #       # Your LLM API call here
+    #       # Must return a string response
+    #     end
+    #   end
+    #
+    #   AsktiveRecord.configure do |config|
+    #     config.adapter = MyAdapter.new(api_key: ENV["MY_LLM_KEY"])
+    #   end
+    class Base
+      attr_reader :api_key, :model_name
+
+      def initialize(api_key:, model_name: nil)
+        @api_key = api_key
+        @model_name = model_name
+
+        return if @api_key
+
+        raise ConfigurationError,
+              "LLM API key is required for adapter initialization."
+      end
+
+      # Send a prompt to the LLM and return the text response.
+      #
+      # @param prompt [String] the prompt to send
+      # @param options [Hash] additional options (temperature, max_tokens, etc.)
+      # @return [String, nil] the text response from the LLM
+      def chat(prompt, options = {})
+        raise NotImplementedError, "#{self.class.name} must implement #chat"
+      end
+
+      # Returns the default model name for this adapter.
+      #
+      # @return [String] the default model name
+      def default_model_name
+        raise NotImplementedError, "#{self.class.name} must implement #default_model_name"
+      end
+
+      # Returns the resolved model name (configured or default).
+      #
+      # @return [String]
+      def resolved_model_name
+        model_name || default_model_name
+      end
+    end
+  end
+end