top_secret 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b57ce12774e37584e4d7a25a2606799b642ddff1eaaeb6f8fa53c2c1e4cae58
-  data.tar.gz: 60b70028bdf30ea474c1987ea15a27df87c7d5614743b69e9f8a20e00a358401
+  metadata.gz: cef5c9c267dd71870fd244408a3f9a020d19978381810f99e7ed5defc67f12a7
+  data.tar.gz: ec20793792721a47371cc6a7cf3c687ad4284b9c9f1f9b14c57e002118c5532a
 SHA512:
-  metadata.gz: de3cb592711f29551bdcb81c8e2c4effb03d7d0e47a1c995adb7a4c828652a98050f133918b63c9a5cbdd3e03aba1e15c0abd06e969f9c7f711b5ce9f22247de
-  data.tar.gz: cb08a6e173106fa653f16f9abbf8ee7b1dd6018fe4097b6841701004ada46ab37b4a9be2079da7398233e35a6c334ee1a445c8d5f0faf7c82eb4c35b0343b79c
+  metadata.gz: 0eea9a1087e5082e245b73cdbb434543dbfcff277b6d58b7a89e463b1162215e0058f5190df3863a73fd32223fdf42fa65a253781193ea7e44ecc6b68c359e45
+  data.tar.gz: 6626056578ec3feecf27d843a994f782c144b363a6b7473e6e0be0fa80044c2283c329ae068c4f0f66af13f021743039864e13f220174489bd822e0c162872a7

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## [Unreleased]
 
+## [0.3.0] - 2025-09-19
+
+### Added
+
+-   Added `TopSecret::Text.scan` method for detecting sensitive information without redacting text
+-   Added `TopSecret::Text::ScanResult` class to hold scan operation results with `mapping` and `sensitive?` methods
+-   Added `TopSecret::Text::GlobalMapping` class to manage consistent labeling across multiple filtering operations
+-   Added factory methods to domain objects: `BatchResult.from_messages`, `Result.from_messages`, and `Result.with_global_labels`
+-   Added support for disabling NER filtering by setting `model_path` to `nil` for improved performance and deployment flexibility
+-   Added support for Rails 7.0 and newer
+-   Added `#safe?` predicate method as the logical opposite of `#sensitive?` for `BatchResult`, `Result` and `ScanResult` classes
+
+### Changed
+
+-   **BREAKING:** `TopSecret::Text.filter_all` now returns `TopSecret::Text::Result` objects instead of `TopSecret::Text::BatchResult::Item` objects for individual items
+-   Each item in `BatchResult#items` now includes an individual `mapping` attribute containing only the sensitive information found in that specific message
+-   `TopSecret::Text.filter_all` now only processes sensitive results when building global mappings, improving efficiency
+-   Refactored `TopSecret::Text.filter_all` to use domain objects with better separation of concerns and testability
+-   Improved performance by implementing lazy loading of MITIE model and document processing
+-   NER filtering now gracefully falls back when MITIE model is unavailable, continuing with regex-based filters only
+
 ## [0.2.0] - 2025-08-18
 
 ### Added

data/README.md

@@ -34,6 +34,13 @@ gem install top_secret
 >
 > You'll need to download and extract [ner_model.dat][] first.
 
+> [!TIP]
+> Due to its large size, you'll likely want to avoid committing [ner_model.dat][] into version control.
+>
+> You'll need to ensure the file exists in deployed environments. See relevant [discussion][discussions_60] for details.
+>
+> Alternatively, you can disable NER filtering entirely by setting `model_path` to `nil` if you only need regex-based filters (credit cards, emails, phone numbers, SSNs). This improves performance and eliminates the model file dependency.
+
 By default, Top Secret assumes the file will live at the root of your project, but this can be configured.
 
 ```ruby
@@ -156,6 +163,81 @@ result.mapping
 # => {:EMAIL_1=>"ralph@thoughtbot.com", :PERSON_1=>"Ralph"}
 ```
 
+Check if sensitive information was found
+
+```ruby
+result.sensitive?
+
+# => true
+
+result.safe?
+
+# => false
+```
+
+### Scanning for Sensitive Information
+
+Use `TopSecret::Text.scan` to detect sensitive information without redacting the text. This is useful when you only need to check if sensitive data exists or get a mapping of what was found:
+
+```ruby
+TopSecret::Text.scan("Ralph can be reached at ralph@thoughtbot.com")
+```
+
+This will return
+
+```ruby
+<TopSecret::Text::ScanResult
+  @mapping={:EMAIL_1=>"ralph@thoughtbot.com", :PERSON_1=>"Ralph"}
+>
+```
+
+Check if sensitive information was found
+
+```ruby
+result.sensitive?
+
+# => true
+
+result.safe?
+
+# => false
+```
+
+View the mapping of found sensitive information
+
+```ruby
+result.mapping
+
+# => {:EMAIL_1=>"ralph@thoughtbot.com", :PERSON_1=>"Ralph"}
+```
+
+The `scan` method accepts the same filter options as `filter`:
+
+```ruby
+# Override default filters
+email_filter =  TopSecret::Filters::Regex.new(
+  label: "EMAIL_ADDRESS",
+  regex: /\w+\[at\]\w+\.\w+/
+)
+result = TopSecret::Text.scan("Contact user[at]example.com", email_filter:)
+result.mapping
+# => {:EMAIL_ADDRESS_1=>"user[at]example.com"}
+
+# Disable specific filters
+result = TopSecret::Text.scan("Ralph works in Boston", people_filter: nil)
+result.mapping
+# => {:LOCATION_1=>"Boston"}
+
+# Add custom filters
+ip_filter = TopSecret::Filters::Regex.new(
+  label: "IP_ADDRESS",
+  regex: /\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/
+)
+result = TopSecret::Text.scan("Server IP is 192.168.1.1", custom_filters: [ip_filter])
+result.mapping
+# => {:IP_ADDRESS_1=>"192.168.1.1"}
+```
+
 ### Batch Processing
 
 When processing multiple messages, use `filter_all` to ensure consistent redaction labels across all messages:
@@ -176,9 +258,9 @@ This will return
 <TopSecret::Text::BatchResult
   @mapping={:EMAIL_1=>"ralph@thoughtbot.com", :EMAIL_2=>"ruby@thoughtbot.com"},
   @items=[
-    <TopSecret::Text::BatchResult::Item @input="Contact ralph@thoughtbot.com for details", @output="Contact [EMAIL_1] for details">,
-    <TopSecret::Text::BatchResult::Item @input="Email ralph@thoughtbot.com again if needed", @output="Email [EMAIL_1] again if needed">,
-    <TopSecret::Text::BatchResult::Item @input="Also CC ruby@thoughtbot.com on the thread", @output="Also CC [EMAIL_2] on the thread">
+    <TopSecret::Text::Result @input="Contact ralph@thoughtbot.com for details", @output="Contact [EMAIL_1] for details", @mapping={:EMAIL_1=>"ralph@thoughtbot.com"}>,
+    <TopSecret::Text::Result @input="Email ralph@thoughtbot.com again if needed", @output="Email [EMAIL_1] again if needed", @mapping={:EMAIL_1=>"ralph@thoughtbot.com"}>,
+    <TopSecret::Text::Result @input="Also CC ruby@thoughtbot.com on the thread", @output="Also CC [EMAIL_2] on the thread", @mapping={:EMAIL_2=>"ruby@thoughtbot.com"}>
   ]
 >
 ```
@@ -199,10 +281,21 @@ result.items[0].input
 
 result.items[0].output
 # => "Contact [EMAIL_1] for details"
+
+result.items[0].mapping
+# => {:EMAIL_1=>"ralph@thoughtbot.com"}
+
+result.items[0].sensitive?
+# => true
+
+result.items[0].safe?
+# => false
 ```
 
 The key benefit is that identical values receive the same labels across all messages - notice how `ralph@thoughtbot.com` becomes `[EMAIL_1]` in both the first and second messages.
 
+Each item also maintains its own mapping containing only the sensitive information found in that specific message, while the batch result provides a global mapping of all sensitive information across all messages.
+
 ### Restoring Filtered Text
 
 When external services (like LLMs) return responses containing filter placeholders, use `TopSecret::FilteredText.restore` to substitute them back with original values:
@@ -249,6 +342,61 @@ restore_result.unrestored
 
 The restoration process tracks both successful and failed placeholder substitutions, allowing you to handle cases where the LLM response contains placeholders not found in your mapping.
 
+### Working with LLMs
+
+When sending filtered information to LLMs, they'll likely need to be instructed on how to handle those filters. Otherwise, we risk them not being returned in the response, which would break the restoration process.
+
+Here's a recommended approach:
+
+```ruby
+instructions = <<~TEXT
+  I'm going to send filtered information to you in the form of free text.
+  If you need to refer to the filtered information in a response, just reference it by the filter.
+TEXT
+```
+
+Complete example:
+
+```ruby
+require "openai"
+require "top_secret"
+
+openai = OpenAI::Client.new(
+  api_key: Rails.application.credentials.openai.api_key!
+)
+
+original_messages = [
+  "Ralph lives in Boston.",
+  "You can reach them at ralph@thoughtbot.com or 877-976-2687"
+]
+
+# Filter all messages
+result = TopSecret::Text.filter_all(original_messages)
+filtered_messages = result.items.map(&:output)
+
+user_messages = filtered_messages.map { {role: "user", content: it} }
+
+# Instruct LLM how to handle filtered messages
+instructions = <<~TEXT
+  I'm going to send filtered information to you in the form of free text.
+  If you need to refer to the filtered information in a response, just reference it by the filter.
+TEXT
+
+messages = [
+  {role: "system", content: instructions},
+  *user_messages
+]
+
+chat_completion = openai.chat.completions.create(messages:, model: :"gpt-5")
+response = chat_completion.choices.last.message.content
+
+# Restore the response from the mapping
+mapping = result.mapping
+restored_response = TopSecret::FilteredText.restore(response, mapping:).output
+
+puts(restored_response)
+```
+
 ### Advanced Examples
 
 #### Overriding the default filters
@@ -420,6 +568,22 @@ TopSecret.configure do |config|
 end
 ```
 
+### Disabling NER filtering
+
+For improved performance or when the MITIE model file cannot be deployed, you can disable NER-based filtering entirely. This will disable people and location detection but retain all regex-based filters (credit cards, emails, phone numbers, SSNs):
+
+```ruby
+TopSecret.configure do |config|
+  config.model_path = nil
+end
+```
+
+This is useful in environments where:
+
+-   The model file cannot be deployed due to size constraints
+-   You only need regex-based filtering
+-   You want to optimize for performance over NER capabilities
+
 ### Overriding the confidence score
 
 ```ruby
@@ -523,3 +687,4 @@ We are [available for hire][hire].
 [train]: https://github.com/ankane/mitie-ruby?tab=readme-ov-file#training
 [Regex filters]: https://github.com/thoughtbot/top_secret/blob/main/lib/top_secret/filters/regex.rb
 [NER filters]: https://github.com/thoughtbot/top_secret/blob/main/lib/top_secret/filters/ner.rb
+[discussions_60]: https://github.com/thoughtbot/top_secret/discussions/60

data/lib/top_secret/constants.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module TopSecret
+  # @return [String] The path to the NER model file
+  MODEL_PATH = "ner_model.dat"
+
   # @return [Regexp] Matches credit card numbers
   CREDIT_CARD_REGEX = /
     \b[3456]\d{15}\b |

data/lib/top_secret/mapping.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module TopSecret
+  module Mapping
+    # @return [Boolean] Whether sensitive information was found
+    def sensitive?
+      mapping.any?
+    end
+
+    # @return [Boolean] Whether sensitive information was not found
+    def safe?
+      !sensitive?
+    end
+  end
+end

data/lib/top_secret/null_model.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module TopSecret
+  # A null object implementation that provides a no-op interface compatible with Mitie::NER.
+  # Used when NER filtering is disabled (model_path is nil) to eliminate conditional checks
+  # throughout the codebase.
+  #
+  # @example
+  #   model = TopSecret::NullModel.new
+  #   doc = model.doc("some text")
+  #   doc.entities # => []
+  class NullModel
+    # A null document implementation that provides an empty entities array.
+    # Used as the return value from NullModel#doc to maintain interface compatibility.
+    class NullDoc
+      # Returns an empty array of entities.
+      #
+      # @return [Array] Always returns an empty array
+      def entities
+        []
+      end
+    end
+
+    # Creates a null document that returns empty entities.
+    #
+    # @param input [String] The input text (ignored)
+    # @return [NullDoc] A document-like object with empty entities
+    def doc(input)
+      NullDoc.new
+    end
+  end
+end

data/lib/top_secret/text/batch_result.rb

@@ -5,7 +5,9 @@ module TopSecret
     # Holds the result of a batch redaction operation on multiple messages.
     # Contains a global mapping that ensures consistent labeling across all messages
     # and a collection of individual input/output pairs.
-    class BatchResult
+    class BatchResult # TODO Rename to FilterBatchResult
+      include Mapping
+
       # @return [Hash] Global mapping of redaction labels to original values across all messages
       attr_reader :mapping
 
@@ -21,24 +23,19 @@ module TopSecret
         @items = items
       end
 
-      # Represents a single message within a batch redaction operation.
-      # Contains only the input and output text, without individual mappings.
-      # The mapping is maintained at the BatchResult level for global consistency.
-      class Item
-        # @return [String] The original unredacted input
-        attr_reader :input
-
-        # @return [String] The redacted output
-        attr_reader :output
+      # Creates a BatchResult from multiple messages with consistent global labeling
+      #
+      # @param messages [Array<String>] Array of text messages to filter
+      # @param custom_filters [Array] Additional custom filters to apply
+      # @param filters [Hash] Optional filters to override defaults (only valid filter keys accepted)
+      # @return [BatchResult] Contains global mapping and array of Result objects with individual mappings
+      # @raise [ArgumentError] If invalid filter keys are provided
+      def self.from_messages(messages, custom_filters: [], **filters)
+        individual_results = TopSecret::Text::Result.from_messages(messages, custom_filters:, **filters)
+        mapping = TopSecret::Text::GlobalMapping.from_results(individual_results)
+        items = TopSecret::Text::Result.with_global_labels(individual_results, mapping)
 
-        # Creates a new Item instance
-        #
-        # @param input [String] The original text
-        # @param output [String] The redacted text
-        def initialize(input, output)
-          @input = input
-          @output = output
-        end
+        Text::BatchResult.new(mapping:, items:)
       end
     end
   end

data/lib/top_secret/text/global_mapping.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module TopSecret
+  class Text
+    # Manages consistent labeling across multiple filtering operations by ensuring
+    # identical sensitive values receive the same redaction labels globally.
+    class GlobalMapping
+      # Creates a global mapping from individual filter results
+      #
+      # @param individual_results [Array<Result>] Array of individual filter results
+      # @return [Hash] Inverted mapping from filter labels to original values
+      def self.from_results(individual_results)
+        new.build_from_results(individual_results)
+      end
+
+      # Creates a new GlobalMapping instance
+      def initialize
+        @mapping = {}
+        @label_counters = {}
+      end
+
+      # Builds the global mapping by processing all individual results
+      #
+      # @param individual_results [Array<Result>] Array of individual filter results
+      # @return [Hash] Inverted mapping from filter labels to original values
+      def build_from_results(individual_results)
+        individual_results.each { |result| process_result(result) if result.sensitive? }
+
+        mapping.invert
+      end
+
+      private
+
+      attr_reader :mapping
+      attr_reader :label_counters
+
+      # Processes a single result, adding new values to the global mapping
+      #
+      # @param result [Result] Individual filter result to process
+      def process_result(result)
+        result.mapping.each do |individual_key, value|
+          next if mapping.key?(value)
+
+          mapping[value] = generate_global_key(individual_key)
+        end
+      end
+
+      # Generates a consistent global key for a given individual key
+      #
+      # @param individual_key [Symbol] The individual key from a filter result
+      # @return [Symbol] The global key with consistent numbering
+      def generate_global_key(individual_key)
+        # TODO: This assumes labels are formatted consistently.
+        # We need to account for the following for the case where a label could begin with an "_"
+        label_type = individual_key.to_s.rpartition("_").first
+
+        label_counters[label_type] ||= 0
+        label_counters[label_type] += 1
+        :"#{label_type}_#{label_counters[label_type]}"
+      end
+    end
+  end
+end

data/lib/top_secret/text/result.rb

@@ -3,7 +3,9 @@
 module TopSecret
   class Text
     # Holds the result of a redaction operation.
-    class Result
+    class Result # TODO: Rename to FilterResult
+      include Mapping
+
       # @return [String] The original unredacted input
       attr_reader :input
 
@@ -21,6 +23,37 @@ module TopSecret
         @output = output
         @mapping = mapping
       end
+
+      # Filters multiple messages individually using a shared model for performance
+      #
+      # @param messages [Array<String>] Array of text messages to filter
+      # @param custom_filters [Array] Additional custom filters to apply
+      # @param filters [Hash] Optional filters to override defaults (only valid filter keys accepted)
+      # @return [Array<Result>] Array of individual Result objects for each message
+      # @raise [ArgumentError] If invalid filter keys are provided
+      def self.from_messages(messages, custom_filters: [], **filters)
+        shared_model = TopSecret.model_path ? Mitie::NER.new(TopSecret.model_path) : nil
+
+        messages.map do |message|
+          TopSecret::Text.new(message, filters:, custom_filters:, model: shared_model).filter
+        end
+      end
+
+      # Creates Result objects with globally consistent labels applied to text
+      #
+      # @param individual_results [Array<Result>] Array of individual filter results
+      # @param global_mapping [Hash] Global mapping from filter labels to original values
+      # @return [Array<Result>] Array of Result objects with globally consistent redaction and individual mappings
+      def self.with_global_labels(individual_results, global_mapping)
+        individual_results.map do |result|
+          output = global_mapping.reduce(result.input.dup) do |text, (filter, value)|
+            text.gsub(value, "[#{filter}]")
+          end
+          filter_keys = output.scan(/\[([^\]]+)\]/).flatten.map(&:to_sym)
+          mapping = global_mapping.slice(*filter_keys)
+          new(result.input, output, mapping)
+        end
+      end
     end
   end
 end

data/lib/top_secret/text/scan_result.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module TopSecret
+  class Text
+    # Holds the result of a scan operation.
+    class ScanResult
+      include Mapping
+
+      # @return [Hash] Mapping of redacted labels to matched values
+      attr_reader :mapping
+
+      # @param mapping [Hash] Map of labels to matched values
+      def initialize(mapping)
+        @mapping = mapping
+      end
+    end
+  end
+end

data/lib/top_secret/text.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 require "active_support/core_ext/hash/keys"
+require_relative "null_model"
 require_relative "text/result"
 require_relative "text/batch_result"
+require_relative "text/scan_result"
+require_relative "text/global_mapping"
 
 module TopSecret
   # Processes text to identify and redact sensitive information using configured filters.
@@ -16,9 +19,7 @@ module TopSecret
       @output = input.dup
       @mapping = {}
 
-      @model = model || Mitie::NER.new(TopSecret.model_path)
-      @doc = @model.doc(@output)
-      @entities = @doc.entities
+      @model = model || default_model
 
       @filters = filters
       @custom_filters = custom_filters
@@ -44,7 +45,7 @@ module TopSecret
     # @param messages [Array<String>] Array of text messages to filter
     # @param custom_filters [Array] Additional custom filters to apply
     # @param filters [Hash] Optional filters to override defaults (only valid filter keys accepted)
-    # @return [BatchResult] Contains global mapping and array of input/output pairs
+    # @return [BatchResult] Contains global mapping and array of Result objects with individual mappings
     # @raise [ArgumentError] If invalid filter keys are provided
     #
     # @example Basic usage
@@ -52,54 +53,59 @@ module TopSecret
     #   result = TopSecret::Text.filter_all(messages)
     #   result.items[0].output # => "Contact [EMAIL_1]"
     #   result.items[1].output # => "Email [EMAIL_1] again"
+    #   result.items[0].mapping # => { EMAIL_1: "john@test.com" }
     #   result.mapping # => { EMAIL_1: "john@test.com" }
     #
     # @example With custom filters
     #   ip_filter = TopSecret::Filters::Regex.new(label: "IP", regex: /\d+\.\d+\.\d+\.\d+/)
     #   result = TopSecret::Text.filter_all(messages, custom_filters: [ip_filter])
     def self.filter_all(messages, custom_filters: [], **filters)
-      shared_model = Mitie::NER.new(TopSecret.model_path)
-
-      individual_results = messages.map do |message|
-        new(message, filters:, custom_filters:, model: shared_model).filter
-      end
-
-      global_mapping = {}
-      label_counters = {}
-
-      individual_results.each do |result|
-        result.mapping.each do |individual_key, value|
-          next if global_mapping.key?(value)
-
-          # TODO: This assumes labels are formatted consistently.
-          # We need to account for the following for the case where a label could begin with an "_"
-          label_type = individual_key.to_s.rpartition("_").first
-
-          label_counters[label_type] ||= 0
-          label_counters[label_type] += 1
-          global_key = :"#{label_type}_#{label_counters[label_type]}"
-
-          global_mapping[value] = global_key
-        end
-      end
-
-      inverted_global_mapping = global_mapping.invert
-
-      items = individual_results.map do |result|
-        output = result.input.dup
-        inverted_global_mapping.each { |filter, value| output.gsub!(value, "[#{filter}]") }
-        Text::BatchResult::Item.new(result.input, output)
-      end
+      Text::BatchResult.from_messages(messages, custom_filters:, **filters)
+    end
 
-      Text::BatchResult.new(mapping: global_mapping.invert, items:)
+    # Convenience method to scan input text for sensitive information without redacting it
+    #
+    # This method detects sensitive information using configured filters but does not modify
+    # the original text. Use this when you only need to check if sensitive data exists or
+    # get a mapping of what was found.
+    #
+    # @param input [String] The text to scan for sensitive information
+    # @param filters [Hash] Optional filters to override defaults (only valid filter keys accepted)
+    # @param custom_filters [Array] Additional custom filters to apply
+    # @return [ScanResult] Contains mapping of found sensitive information and sensitive? flag
+    # @raise [ArgumentError] If invalid filter keys are provided
+    #
+    # @example Basic scanning
+    #   result = TopSecret::Text.scan("Contact john@example.com")
+    #   result.sensitive? # => true
+    #   result.mapping    # => {:EMAIL_1=>"john@example.com"}
+    #
+    # @example With custom filters
+    #   ip_filter = TopSecret::Filters::Regex.new(label: "IP", regex: /\d+\.\d+\.\d+\.\d+/)
+    #   result = TopSecret::Text.scan("Server IP: 192.168.1.1", custom_filters: [ip_filter])
+    #   result.mapping # => {:IP_1=>"192.168.1.1"}
+    #
+    # @example Overriding default filters
+    #   custom_email = TopSecret::Filters::Regex.new(label: "EMAIL_ADDR", regex: /\w+@\w+/)
+    #   result = TopSecret::Text.scan("user@test.com", email_filter: custom_email)
+    #   result.mapping # => {:EMAIL_ADDR_1=>"user@test.com"}
+    def self.scan(input, custom_filters: [], **filters)
+      new(input, filters:, custom_filters:).scan
     end
 
-    # Applies configured filters to the input, redacting matches and building a mapping.
+    # Scans the input text for sensitive information using configured filters
     #
-    # @return [Result] Contains original input, redacted output, and mapping of labels to values
+    # This method applies all active filters to detect sensitive information but does not
+    # redact the original text. It builds a mapping of found values and returns whether
+    # any sensitive information was detected.
+    #
+    # @return [ScanResult] Contains mapping of found sensitive information and sensitive? flag
     # @raise [Error] If an unsupported filter is encountered
     # @raise [ArgumentError] If invalid filter keys are provided
-    def filter
+    def scan
+      @doc ||= model.doc(@output) if model
+      @entities ||= doc.entities if model
+
       validate_filters!
 
       all_filters.each do |filter|
@@ -116,9 +122,20 @@ module TopSecret
         build_mapping(values, label: filter.label)
       end
 
-      substitute_text
+      ScanResult.new(mapping)
+    end
 
-      Text::Result.new(input, output, mapping)
+    # Applies configured filters to the input, redacting matches and building a mapping.
+    #
+    # @return [Result] Contains original input, redacted output, and mapping of labels to values
+    # @raise [Error] If an unsupported filter is encountered
+    # @raise [ArgumentError] If invalid filter keys are provided
+    def filter
+      scan_result = scan
+
+      substitute_text if scan_result.sensitive?
+
+      Text::Result.new(input, output, scan_result.mapping)
     end
 
     private
@@ -132,6 +149,12 @@ module TopSecret
     # @return [Hash] Mapping from redaction labels to original values
     attr_reader :mapping
 
+    # @return [Object] The NER model (typically Mitie::NER or a test double)
+    attr_reader :model
+
+    # @return [Object] The document created from the output text (typically Mitie::Document or a test double)
+    attr_reader :doc
+
     # @return [Array<Hash>] Named entities extracted by MITIE
     attr_reader :entities
 
@@ -199,5 +222,17 @@ module TopSecret
         location_filter: TopSecret.location_filter
       }
     end
+
+    # Creates the default model based on configuration.
+    # Returns a MITIE NER model if a model path is configured, otherwise returns a null model.
+    #
+    # @return [Mitie::NER, NullModel] The model instance to use for NER processing
+    def default_model
+      if TopSecret.model_path
+        Mitie::NER.new(TopSecret.model_path)
+      else
+        NullModel.new
+      end
+    end
   end
 end

data/lib/top_secret/version.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
 module TopSecret
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
+  MINIMUM_RAILS_VERSION = ">= 7.0.8"
+  MAXIMUM_RAILS_VERSION = "< 9"
 end

data/lib/top_secret.rb

@@ -8,6 +8,7 @@ require "mitie"
 # modules
 require_relative "top_secret/version"
 require_relative "top_secret/constants"
+require_relative "top_secret/mapping"
 require_relative "top_secret/filters/ner"
 require_relative "top_secret/filters/regex"
 require_relative "top_secret/error"
@@ -45,7 +46,7 @@ require_relative "top_secret/filtered_text"
 module TopSecret
   include ActiveSupport::Configurable
 
-  config_accessor :model_path, default: "ner_model.dat"
+  config_accessor :model_path, default: MODEL_PATH
   config_accessor :min_confidence_score, default: MIN_CONFIDENCE_SCORE
 
   config_accessor :custom_filters, default: []

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: top_secret
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Steve Polito
@@ -13,22 +13,22 @@ dependencies:
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '8.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.2
+        version: 7.0.8
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '8.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.2
+        version: 7.0.8
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
 - !ruby/object:Gem::Dependency
   name: mitie
   requirement: !ruby/object:Gem::Requirement
@@ -64,9 +64,13 @@ files:
 - lib/top_secret/filtered_text/result.rb
 - lib/top_secret/filters/ner.rb
 - lib/top_secret/filters/regex.rb
+- lib/top_secret/mapping.rb
+- lib/top_secret/null_model.rb
 - lib/top_secret/text.rb
 - lib/top_secret/text/batch_result.rb
+- lib/top_secret/text/global_mapping.rb
 - lib/top_secret/text/result.rb
+- lib/top_secret/text/scan_result.rb
 - lib/top_secret/version.rb
 - sig/top_secret.rbs
 homepage: https://github.com/thoughtbot/top_secret