ai_record_finder 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: da4695452d3dbf655e818a95f773afca2b366086983122b4b2d75abfe9cc6894
+  data.tar.gz: d3d628ed44b129d95a41d3a99057e0c6a78ddae844e6f5752b3c2a3998af6565
+SHA512:
+  metadata.gz: dba189e5c9cdee52306e027ca8c506b264441b18cc8c4e7a9ccc95a5004f8f4a61ed9541c834b110b745a0750ba9ce9fea8de43cd3ead69fcc5105f1f762afed
+  data.tar.gz: 67e99f16ed5e8280aa0af1543a5bb9141884ec96e4a1768659c794fd3f4f84e47d9b14f02480af63a136e3535a21498dbd40cec7c92f464e8e9bc766f340f487

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--format documentation

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-02-19
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"ai_record_finder" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["bosejijo@gmail.com"](mailto:"bosejijo@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Jijo Bose
+
+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,115 @@
+# AIRecordFinder
+
+`ai_record_finder` converts natural language prompts into safe `ActiveRecord::Relation` objects.
+
+It is designed for B2B Rails applications that need strict query safety, tenant boundaries, and model-level authorization.
+
+Documentation homepage: `docs/HOME.md`
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "ai_record_finder"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Configuration
+
+Add an initializer at `config/initializers/ai_record_finder.rb`:
+
+```ruby
+AIRecordFinder.configure do |config|
+  config.api_key = ENV.fetch("OPENAI_API_KEY")
+  config.model_name = "gpt-4o-mini"
+  config.max_limit = 100
+  config.allowed_models = [Invoice, User]
+
+  # Optional: allow controlled joins by model.
+  config.allowed_associations = {
+    "Invoice" => ["user"]
+  }
+end
+```
+
+## Usage
+
+```ruby
+relation = AIRecordFinder.query(
+  prompt: "Unpaid invoices above 50000 from last quarter",
+  model: Invoice
+)
+
+# Always ActiveRecord::Relation
+relation.limit(10).pluck(:id)
+```
+
+For associated-table constraints, reference fields as `association.column` in natural language intent (for example: "invoices where `user.email` contains `@acme.com`"). The gem will auto-join needed associations, but they must still be whitelisted in `allowed_associations`.
+
+## Security Model
+
+`ai_record_finder` is fail-closed and built to avoid LLM-to-SQL injection:
+
+- AI is forced to return JSON DSL only (no SQL allowed).
+- AI output is sanitized (markdown/code fences stripped) and JSON-parsed safely.
+- Unknown keys/operators/fields are rejected.
+- Fields are validated against model schema introspection.
+- `limit` is strictly validated and hard-capped by configuration.
+- Models must be explicitly whitelisted in `allowed_models`.
+- Optional joins are blocked unless explicitly whitelisted in `allowed_associations`.
+- If model defines `current_tenant_scope`, it is always merged.
+- No `eval`, no destructive operations, no raw SQL execution from AI output.
+
+## Architecture Overview
+
+Core components:
+
+- `AIRecordFinder::Configuration`: runtime safety and API settings.
+- `AIRecordFinder::SchemaIntrospector`: model table/column/association/enum summary.
+- `AIRecordFinder::PromptBuilder`: strict system prompt with schema and DSL contract.
+- `AIRecordFinder::Client`: OpenAI-compatible HTTP transport (Faraday).
+- `AIRecordFinder::AIAdapter`: AI response extraction and JSON parsing.
+- `AIRecordFinder::DSLParser`: validates DSL structure and values.
+- `AIRecordFinder::SafetyGuard`: model authorization, limit policies, join policies, tenant scope.
+- `AIRecordFinder::QueryBuilder`: converts validated DSL into `ActiveRecord::Relation`.
+- `AIRecordFinder::Railtie`: auto-load support in Rails.
+
+## Error Types
+
+- `AIRecordFinder::InvalidModelError`
+- `AIRecordFinder::InvalidDSL`
+- `AIRecordFinder::AIResponseError`
+- `AIRecordFinder::UnauthorizedModel`
+
+## Testing
+
+Run:
+
+```bash
+bundle exec rspec
+```
+
+Included tests cover:
+
+- Valid query generation
+- Invalid field rejection
+- Limit overflow
+- Unknown operator
+- Unauthorized model
+- JSON injection attempt
+
+## Pro Roadmap
+
+Potential Pro features:
+
+- Query explain/preview before execution
+- Auditable prompt and DSL logs with redaction controls
+- Policy packs (SOC2/HIPAA presets)
+- Per-tenant usage quotas and rate-limits
+- Multi-model query planning with approval workflows

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: :rubocop

data/docs/DEVELOPER_GUIDE.md

@@ -0,0 +1,144 @@
+# Developer Guide (Basic)
+
+This guide explains how to use `ai_record_finder` in a Rails app.
+
+## 1. Install
+
+Add the gem:
+
+```ruby
+# Gemfile
+gem "ai_record_finder"
+```
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+## 2. Configure
+
+Create an initializer:
+
+```ruby
+# config/initializers/ai_record_finder.rb
+AIRecordFinder.configure do |config|
+  config.api_key = ENV.fetch("OPENAI_API_KEY")
+  config.model_name = "gpt-4o-mini"
+  config.max_limit = 100
+
+  # Only models in this list can be queried.
+  config.allowed_models = [Invoice, User]
+
+  # Optional: allow specific joins per model.
+  config.allowed_associations = {
+    "Invoice" => ["user"]
+  }
+end
+```
+
+## 3. Run a Query
+
+Use natural language + model:
+
+```ruby
+relation = AIRecordFinder.query(
+  prompt: "Unpaid invoices above 50000 from last quarter",
+  model: Invoice
+)
+```
+
+For associated-table constraints, use `association.column` semantics in the request intent, such as: "unpaid invoices where `user.email` contains `@acme.com`". The gem will auto-join associations used by these fields, but they must still be whitelisted in `allowed_associations`.
+
+The return value is always an `ActiveRecord::Relation`, so you can chain it:
+
+```ruby
+relation.limit(20).pluck(:id)
+```
+
+## 4. What Happens Internally
+
+1. The model is checked against `allowed_models`.
+2. The model schema (columns, associations, enums) is introspected.
+3. A strict AI prompt is built that allows only JSON DSL.
+4. AI output is cleaned and JSON-parsed.
+5. DSL is validated (fields, operators, sort, limit, keys).
+6. A safe ActiveRecord relation is built and returned.
+
+## 5. DSL Constraints (Important)
+
+The AI can only use these operators:
+
+- `eq`
+- `gt`
+- `lt`
+- `gte`
+- `lte`
+- `between`
+- `in`
+- `like`
+
+Safety rules:
+
+- Unknown fields are rejected.
+- Unknown operators are rejected.
+- Unknown JSON keys are rejected.
+- `limit` must be `<= config.max_limit`.
+- Joins are blocked unless explicitly allowed.
+
+## 6. Tenant Safety Hook
+
+If your model defines `current_tenant_scope`, it is automatically merged:
+
+```ruby
+class Invoice < ApplicationRecord
+  def self.current_tenant_scope
+    where(account_id: Current.account_id)
+  end
+end
+```
+
+This helps enforce tenant boundaries by default.
+
+## 7. Common Errors
+
+- `AIRecordFinder::UnauthorizedModel`
+: model is not in `allowed_models`.
+- `AIRecordFinder::InvalidModelError`
+: model is not an ActiveRecord model.
+- `AIRecordFinder::InvalidDSL`
+: AI returned unsupported fields/operators/keys/limit.
+- `AIRecordFinder::AIResponseError`
+: AI response was invalid or API call failed.
+
+## 8. Basic Controller Example
+
+```ruby
+class InvoicesController < ApplicationController
+  def search
+    relation = AIRecordFinder.query(
+      prompt: params[:q],
+      model: Invoice
+    )
+
+    @invoices = relation.limit(50)
+  rescue AIRecordFinder::Error => e
+    render json: { error: e.message }, status: :unprocessable_entity
+  end
+end
+```
+
+## 9. Testing Your Integration
+
+Run library tests:
+
+```bash
+bundle exec rspec
+```
+
+For app-level tests, mock `AIRecordFinder.query` in controller/service specs and assert:
+
+- It returns a relation.
+- Unauthorized models are rejected.
+- Tenant constraints remain applied.

data/lib/ai_record_finder/ai_adapter.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "json"
+
+module AIRecordFinder
+  # Converts natural language + schema prompt into parsed DSL JSON.
+  class AIAdapter
+    def initialize(client:)
+      @client = client
+    end
+
+    def call(system_prompt:, user_prompt:)
+      raw_content = @client.chat_completion(system_prompt: system_prompt, user_prompt: user_prompt)
+      parse_json(extract_json(raw_content))
+    rescue AIResponseError
+      raise
+    rescue StandardError => e
+      raise AIResponseError, "Failed to parse AI response: #{e.message}"
+    end
+
+    private
+
+    def extract_json(raw_content)
+      content = raw_content.to_s.strip
+
+      if content.start_with?("```")
+        content = content.gsub(/\A```(?:json)?\s*/i, "").gsub(/\s*```\z/, "")
+      end
+
+      first_brace = content.index("{")
+      last_brace = content.rindex("}")
+      raise AIResponseError, "No JSON object found in AI response" unless first_brace && last_brace
+
+      content[first_brace..last_brace]
+    end
+
+    def parse_json(json_string)
+      parsed = JSON.parse(json_string)
+      raise AIResponseError, "AI response must be a JSON object" unless parsed.is_a?(Hash)
+
+      parsed
+    rescue JSON::ParserError
+      raise AIResponseError, "AI returned invalid JSON"
+    end
+  end
+end

data/lib/ai_record_finder/client.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module AIRecordFinder
+  # HTTP client for OpenAI-compatible chat completion APIs.
+  class Client
+    CHAT_COMPLETIONS_PATH = "/chat/completions"
+
+    def initialize(configuration:)
+      @configuration = configuration
+      validate_configuration!
+    end
+
+    def chat_completion(system_prompt:, user_prompt:)
+      response = connection.post(CHAT_COMPLETIONS_PATH) do |req|
+        req.headers["Authorization"] = "Bearer #{@configuration.api_key}"
+        req.headers["Content-Type"] = "application/json"
+        req.body = JSON.generate(payload(system_prompt, user_prompt))
+      end
+
+      parsed = parse_body(response.body)
+      extract_content(parsed)
+    rescue Faraday::Error => e
+      raise AIResponseError, "AI request failed: #{e.message}"
+    end
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(url: @configuration.api_base_url) do |f|
+        f.options.timeout = @configuration.request_timeout
+        f.options.open_timeout = @configuration.request_timeout
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def payload(system_prompt, user_prompt)
+      {
+        model: @configuration.model_name,
+        temperature: @configuration.temperature,
+        messages: [
+          { role: "system", content: system_prompt },
+          { role: "user", content: user_prompt }
+        ]
+      }
+    end
+
+    def parse_body(body)
+      JSON.parse(body)
+    rescue JSON::ParserError
+      raise AIResponseError, "AI response body is not valid JSON"
+    end
+
+    def extract_content(parsed)
+      choices = parsed["choices"]
+      return choices.first.dig("message", "content") if choices.is_a?(Array) && choices.first
+
+      raise AIResponseError, "AI response missing choices.message.content"
+    end
+
+    def validate_configuration!
+      if @configuration.api_key.to_s.strip.empty?
+        raise AIResponseError, "Missing API key. Set AIRecordFinder.configure { |c| c.api_key = ... }"
+      end
+    end
+  end
+end

data/lib/ai_record_finder/configuration.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module AIRecordFinder
+  # Runtime configuration for AIRecordFinder.
+  class Configuration
+    DEFAULT_MODEL_NAME = "gpt-4o-mini"
+    DEFAULT_API_BASE_URL = "https://api.openai.com/v1"
+    DEFAULT_MAX_LIMIT = 100
+    DEFAULT_TIMEOUT = 15
+
+    attr_accessor :api_key, :model_name, :max_limit, :allowed_models,
+                  :api_base_url, :request_timeout, :temperature,
+                  :allowed_associations
+
+    def initialize
+      @api_key = nil
+      @model_name = DEFAULT_MODEL_NAME
+      @max_limit = DEFAULT_MAX_LIMIT
+      @allowed_models = []
+      @api_base_url = DEFAULT_API_BASE_URL
+      @request_timeout = DEFAULT_TIMEOUT
+      @temperature = 0.0
+      @allowed_associations = {}
+    end
+  end
+end

data/lib/ai_record_finder/dsl_parser.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module AIRecordFinder
+  # Validates and normalizes the AI-generated query DSL.
+  class DSLParser
+    ALLOWED_TOP_LEVEL_KEYS = %w[filters limit sort joins].freeze
+    ALLOWED_OPERATORS = %w[eq gt lt gte lte between in like].freeze
+    ALLOWED_SORT_DIRECTIONS = %w[asc desc].freeze
+
+    def initialize(model:, schema:, dsl:, max_limit:)
+      @model = model
+      @schema = schema
+      @dsl = dsl
+      @max_limit = max_limit
+      @columns = @schema.fetch(:columns).keys
+      @associations = @schema.fetch(:associations).keys
+      @association_columns = @schema.fetch(:association_columns, {})
+    end
+
+    def call
+      raise InvalidDSL, "DSL must be a JSON object" unless @dsl.is_a?(Hash)
+
+      dsl = deep_stringify_keys(@dsl)
+      validate_top_level_keys!(dsl)
+
+      filters = validate_filters!(dsl.fetch("filters", []))
+      limit = validate_limit!(dsl.fetch("limit", @max_limit))
+      sort = validate_sort!(dsl["sort"])
+      joins = validate_joins!(dsl.fetch("joins", []))
+
+      {
+        "filters" => filters,
+        "limit" => limit,
+        "sort" => sort,
+        "joins" => joins
+      }
+    end
+
+    private
+
+    def deep_stringify_keys(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, val), memo|
+          memo[key.to_s] = deep_stringify_keys(val)
+        end
+      when Array
+        value.map { |val| deep_stringify_keys(val) }
+      else
+        value
+      end
+    end
+
+    def validate_top_level_keys!(dsl)
+      unknown = dsl.keys - ALLOWED_TOP_LEVEL_KEYS
+      raise InvalidDSL, "Unknown DSL keys: #{unknown.join(', ')}" if unknown.any?
+    end
+
+    def validate_filters!(filters)
+      raise InvalidDSL, "filters must be an array" unless filters.is_a?(Array)
+
+      filters.map do |filter|
+        raise InvalidDSL, "each filter must be an object" unless filter.is_a?(Hash)
+
+        keys = filter.keys
+        unknown = keys - %w[field operator value]
+        raise InvalidDSL, "Unknown filter keys: #{unknown.join(', ')}" if unknown.any?
+
+        field = filter["field"].to_s
+        operator = filter["operator"].to_s
+        value = filter["value"]
+
+        validate_field!(field)
+        validate_operator!(operator)
+        validate_operator_value!(operator, value)
+
+        { "field" => field, "operator" => operator, "value" => value }
+      end
+    end
+
+    def validate_limit!(limit)
+      raise InvalidDSL, "limit must be an integer" unless limit.is_a?(Integer)
+
+      SafetyGuard.enforce_limit!(limit: limit, max_limit: @max_limit)
+      limit
+    end
+
+    def validate_sort!(sort)
+      return nil if sort.nil?
+      raise InvalidDSL, "sort must be an object" unless sort.is_a?(Hash)
+
+      unknown = sort.keys - %w[field direction]
+      raise InvalidDSL, "Unknown sort keys: #{unknown.join(', ')}" if unknown.any?
+
+      field = sort.fetch("field").to_s
+      direction = sort.fetch("direction").to_s.downcase
+
+      validate_field!(field)
+      unless ALLOWED_SORT_DIRECTIONS.include?(direction)
+        raise InvalidDSL, "sort direction must be asc or desc"
+      end
+
+      { "field" => field, "direction" => direction }
+    end
+
+    def validate_joins!(joins)
+      raise InvalidDSL, "joins must be an array" unless joins.is_a?(Array)
+
+      joins.map do |association|
+        name = association.to_s
+        unless @associations.include?(name)
+          raise InvalidDSL, "Unknown association join: #{name}"
+        end
+
+        name
+      end
+    end
+
+    def validate_field!(field)
+      return if @columns.include?(field)
+      return if valid_association_field?(field)
+
+      raise InvalidDSL, "Unknown field: #{field}"
+    end
+
+    def valid_association_field?(field)
+      association_name, column_name = field.split(".", 2)
+      return false if association_name.to_s.empty? || column_name.to_s.empty?
+
+      return false unless @associations.include?(association_name)
+
+      association_columns = @association_columns.fetch(association_name, {}).fetch(:columns, nil) ||
+                            @association_columns.fetch(association_name, {}).fetch("columns", nil)
+      return false unless association_columns
+
+      association_columns.keys.map(&:to_s).include?(column_name)
+    end
+
+    def validate_operator!(operator)
+      return if ALLOWED_OPERATORS.include?(operator)
+
+      raise InvalidDSL, "Unknown operator: #{operator}"
+    end
+
+    def validate_operator_value!(operator, value)
+      case operator
+      when "between"
+        unless value.is_a?(Array) && value.length == 2
+          raise InvalidDSL, "between operator requires exactly two values"
+        end
+      when "in"
+        raise InvalidDSL, "in operator requires an array" unless value.is_a?(Array)
+      when "like"
+        raise InvalidDSL, "like operator requires a scalar value" if value.is_a?(Array) || value.is_a?(Hash)
+      end
+    end
+  end
+end

data/lib/ai_record_finder/errors.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module AIRecordFinder
+  # Base error class for all gem-specific failures.
+  class Error < StandardError; end
+
+  # Raised when the given model is not an ActiveRecord model.
+  class InvalidModelError < Error; end
+
+  # Raised when AI output does not conform to the expected DSL.
+  class InvalidDSL < Error; end
+
+  # Raised when AI API responses are malformed or unusable.
+  class AIResponseError < Error; end
+
+  # Raised when a model is not explicitly whitelisted.
+  class UnauthorizedModel < Error; end
+end

data/lib/ai_record_finder/prompt_builder.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "json"
+
+module AIRecordFinder
+  # Builds strict prompts so the AI emits only the expected JSON DSL.
+  class PromptBuilder
+    ALLOWED_OPERATORS = %w[eq gt lt gte lte between in like].freeze
+
+    def initialize(schema:, max_limit:)
+      @schema = schema
+      @max_limit = max_limit
+    end
+
+    def system_prompt
+      <<~PROMPT
+        You convert user requests into a strict query JSON DSL for ActiveRecord.
+        Output rules:
+        - Return ONLY JSON. No markdown, no code fences, no commentary.
+        - Never output SQL, pseudo-SQL, or Ruby code.
+        - Do not include keys not listed below.
+        - Use only the provided schema fields.
+        - Limit must be an integer between 1 and #{@max_limit}.
+        - Operators allowed: #{ALLOWED_OPERATORS.join(', ')}
+
+        JSON format:
+        {
+          "filters": [
+            { "field": "status", "operator": "eq", "value": "unpaid" }
+          ],
+          "limit": 50,
+          "sort": { "field": "created_at", "direction": "desc" }
+        }
+
+        Field constraints:
+        - Allowed base fields are these columns: #{@schema[:columns].keys.sort.join(', ')}
+        - Associated fields must use "association.column" (example: "user.email")
+        - Allowed sort directions: asc, desc
+        - For operator "between", value must be an array of two values
+        - For operator "in", value must be an array
+
+        Schema summary:
+        #{JSON.pretty_generate(@schema)}
+      PROMPT
+    end
+
+    def user_prompt(natural_language_prompt)
+      natural_language_prompt.to_s.strip
+    end
+  end
+end