pattern-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 76b9f40922a19e84b9da9c7a0ccb8027b6a3d99f75782a248c8edd3111bf063f
+  data.tar.gz: b7d845a9dff5e5e479d3f74e5268d118da67cbe821450be6bb5e32586402a333
+SHA512:
+  metadata.gz: de646d6f5b0c9a8924a835986b55c4c33ae10da4b96040ce53e5ba6392ecf40520879d66f39f2655f88d84745a41ea7856f6d5a42b4653483eaa53080ce7aed9
+  data.tar.gz: 3fea24e0b08f2620e4b3da933a60d44abc9371283feab5648b2c8630f5fd69b41a0bf8e37c5c18065e678f491ee2f5f5c5cc2bc804c92437de46a412ad167512

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 (2026-03-07)
+
+- Initial release
+- Router DSL with intent matching
+- Pattern compiler: literals, entities, optionals, alternatives, wildcards
+- Entity types: string, number, integer, email, phone, url, currency
+- Custom entity type registration
+- Regex pattern support
+- Context-aware matching
+- Multi-intent matching with scoring
+- Pipeline for preprocessing chains
+- Conversation state with slot filling
+- Minitest test helpers

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Johannes Dwi Cahyo
+
+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,191 @@
+# pattern-ruby
+
+A deterministic pattern detection and intent matching engine for Ruby. Built for chatbots and conversational AI where you need fast, predictable, rule-based matching — no API calls, no model inference, no latency.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "pattern-ruby"
+```
+
+```bash
+gem install pattern-ruby
+```
+
+## Quick Start
+
+```ruby
+require "pattern_ruby"
+
+router = PatternRuby::Router.new do
+  intent :greeting do
+    pattern "hello"
+    pattern "hi"
+    pattern "good morning"
+    response "Hello! How can I help you?"
+  end
+
+  intent :weather do
+    pattern "weather in {city}"
+    pattern "what's the weather in {city}"
+    entity :city, type: :string
+  end
+
+  fallback { |input| puts "Unknown: #{input}" }
+end
+
+result = router.match("weather in Tokyo")
+result.intent    # => :weather
+result.entities  # => { city: "Tokyo" }
+result.matched?  # => true
+```
+
+## Pattern Syntax
+
+```
+hello                        Literal match (case-insensitive)
+{name}                       Named entity capture
+{name:\d+}                   Entity with regex constraint
+{name:opt1|opt2|opt3}        Entity with enum constraint
+[optional words]             Optional section
+(alt1|alt2|alt3)             Alternatives
+*                            Wildcard (any text)
+```
+
+### Examples
+
+```ruby
+# Optional words
+"book [a] flight"              # matches "book a flight" and "book flight"
+
+# Entity with constraint
+"order {id:\d+}"               # captures only digits
+
+# Alternatives
+"i want to (fly|travel|go)"    # matches any of the three verbs
+
+# Combined
+"book [a] flight from {origin} to {destination} [on {date}]"
+```
+
+## Entity Types
+
+Built-in types: `:string`, `:number`, `:integer`, `:email`, `:phone`, `:url`, `:currency`
+
+```ruby
+# Register custom entity types
+router = PatternRuby::Router.new do
+  entity_type :zipcode, pattern: /\d{5}/, parser: ->(s) { s.to_i }
+
+  intent :locate do
+    pattern "find stores near {zip}"
+    entity :zip, type: :zipcode
+  end
+end
+```
+
+Entities support defaults:
+
+```ruby
+intent :weather do
+  pattern "weather in {city}"
+  entity :city, type: :string
+  entity :time, type: :string, default: "today"
+end
+```
+
+## Regex Patterns
+
+Use raw regex for complex matching:
+
+```ruby
+intent :order_status do
+  pattern(/order\s*#?\s*(?<order_id>\d{5,})/i)
+end
+
+result = router.match("Where is order #12345?")
+result.entities[:order_id]  # => "12345"
+```
+
+## Multi-Intent Matching
+
+```ruby
+results = router.match_all("book a flight to Paris")
+results.each do |r|
+  puts "#{r.intent}: #{r.score}"
+end
+```
+
+## Context-Aware Matching
+
+```ruby
+router = PatternRuby::Router.new do
+  intent :confirm do
+    pattern "yes"
+    context :awaiting_confirmation
+  end
+
+  intent :greeting do
+    pattern "yes"  # only matches without context
+  end
+end
+
+router.match("yes")                                    # => :greeting
+router.match("yes", context: :awaiting_confirmation)   # => :confirm
+```
+
+## Conversation State
+
+```ruby
+convo = PatternRuby::Conversation.new(router)
+
+result = convo.process("book a flight from NYC to London")
+# => { origin: "NYC", destination: "London" }
+
+result = convo.process("tomorrow")
+# => fills missing date slot: { origin: "NYC", destination: "London", date: "tomorrow" }
+
+convo.reset  # clear all state
+```
+
+## Pipeline
+
+Chain preprocessing steps before matching:
+
+```ruby
+pipeline = PatternRuby::Pipeline.new do
+  step(:normalize) { |input| input.strip.downcase.gsub(/[?!.]/, "") }
+  step(:correct)   { |input| input.gsub(/wether/, "weather") }
+  step(:match)     { |input| router.match(input) }
+end
+
+result = pipeline.process("Wether in Tokyo?")
+# => intent: :weather, entities: { city: "tokyo" }
+```
+
+## Test Helpers
+
+```ruby
+require "pattern_ruby/rails/test_helpers"
+
+class MyTest < Minitest::Test
+  include PatternRuby::TestHelpers
+
+  def test_greeting
+    assert_matches_intent :greeting, "hello", router: @router
+  end
+
+  def test_entity
+    assert_extracts_entity :city, "Tokyo", "weather in Tokyo", router: @router
+  end
+
+  def test_no_match
+    refute_matches "quantum physics", router: @router
+  end
+end
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,9 @@
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test" << "lib"
+  t.pattern = "test/test_*.rb"
+  t.warning = true
+end
+
+task default: :test

data/examples/chatbot.rb

@@ -0,0 +1,64 @@
+require "pattern_ruby"
+
+router = PatternRuby::Router.new do
+  intent :greeting do
+    pattern "hello"
+    pattern "hi"
+    pattern "hey"
+    pattern "good morning"
+    response "Hello! How can I help you today?"
+  end
+
+  intent :farewell do
+    pattern "goodbye"
+    pattern "bye"
+    pattern "see you"
+    response "Goodbye! Have a great day!"
+  end
+
+  intent :weather do
+    pattern "weather in {city}"
+    pattern "what's the weather in {city}"
+    pattern "how's the weather in {city} {time:today|tomorrow|this week}"
+    entity :city, type: :string
+    entity :time, type: :string, default: "today"
+  end
+
+  intent :help do
+    pattern "help"
+    pattern "what can you do"
+    response "I can help with weather, orders, and general questions."
+  end
+
+  fallback do |input|
+    puts "  [Fallback] Would route to LLM: #{input}"
+  end
+end
+
+puts "=== Chatbot Demo ==="
+puts
+
+inputs = [
+  "Hello",
+  "What's the weather in Tokyo",
+  "how's the weather in London tomorrow",
+  "help",
+  "Tell me a joke",
+  "bye"
+]
+
+inputs.each do |input|
+  result = router.match(input)
+  print "User: #{input}\n"
+
+  if result.matched?
+    print "  Intent: #{result.intent}"
+    print " | Entities: #{result.entities}" unless result.entities.empty?
+    print " | Score: #{result.score.round(2)}"
+    print "\n  Response: #{result.response}" if result.response
+    puts
+  else
+    puts "  [No match]"
+  end
+  puts
+end

data/examples/customer_service.rb

@@ -0,0 +1,53 @@
+require "pattern_ruby"
+
+router = PatternRuby::Router.new do
+  intent :order_status do
+    pattern "where is my order {order_id:\\d+}"
+    pattern "track order {order_id:\\d+}"
+    pattern(/order\s*#?\s*(?<order_id>\d{5,})/i)
+    entity :order_id, type: :string
+  end
+
+  intent :refund do
+    pattern "i want a refund"
+    pattern "refund my order {order_id:\\d+}"
+    pattern "can i get a refund"
+    entity :order_id, type: :string
+  end
+
+  intent :book_flight do
+    pattern "book [a] flight from {origin} to {destination} [on {date}]"
+    pattern "fly from {origin} to {destination}"
+    pattern "i want to (fly|travel|go) from {origin} to {destination}"
+    entity :origin, type: :string
+    entity :destination, type: :string
+    entity :date, type: :string
+  end
+
+  fallback { |_| }
+end
+
+# Demonstrate conversation with slot filling
+puts "=== Customer Service Conversation ==="
+puts
+
+convo = PatternRuby::Conversation.new(router)
+
+messages = [
+  "book a flight from NYC to London",
+  "Friday",
+  "where is my order #55678",
+  "i want a refund"
+]
+
+messages.each do |msg|
+  result = convo.process(msg)
+  puts "Customer: #{msg}"
+  if result.matched?
+    puts "  Intent: #{result.intent}"
+    puts "  Entities: #{result.entities}" unless result.entities.empty?
+  else
+    puts "  [Route to agent]"
+  end
+  puts
+end

data/examples/with_llm_fallback.rb

@@ -0,0 +1,71 @@
+require "pattern_ruby"
+
+# This example shows how to use pattern-ruby as a first-pass filter
+# before routing to an LLM for complex queries.
+
+router = PatternRuby::Router.new do
+  intent :greeting do
+    pattern "hello"
+    pattern "hi"
+    pattern "hey"
+    response "Hello! How can I help you?"
+  end
+
+  intent :hours do
+    pattern "what are your hours"
+    pattern "when are you open"
+    pattern "business hours"
+    response "We're open Monday-Friday, 9am-5pm EST."
+  end
+
+  intent :pricing do
+    pattern "how much does {product} cost"
+    pattern "price of {product}"
+    pattern "pricing"
+    entity :product, type: :string
+  end
+
+  fallback { |_| }
+end
+
+pipeline = PatternRuby::Pipeline.new do
+  step(:normalize) { |input| input.strip }
+
+  step(:match) do |input|
+    result = router.match(input)
+
+    if result.matched?
+      # Deterministic response — no LLM needed
+      puts "  [Pattern Match] Intent: #{result.intent}"
+      if result.response
+        puts "  Response: #{result.response}"
+      else
+        puts "  Entities: #{result.entities}"
+        puts "  [Would look up #{result.entities} in database]"
+      end
+    else
+      # Route to LLM
+      puts "  [LLM Fallback] Sending to LLM: #{input}"
+      puts "  [LLM would generate a contextual response here]"
+    end
+
+    result
+  end
+end
+
+puts "=== Hybrid Pattern + LLM Demo ==="
+puts
+
+inputs = [
+  "hello",
+  "what are your hours",
+  "how much does the Pro plan cost",
+  "Can you explain the difference between your plans?",
+  "What's your refund policy for annual subscriptions?",
+]
+
+inputs.each do |input|
+  puts "User: #{input}"
+  pipeline.process(input)
+  puts
+end

data/lib/pattern_ruby/conversation.rb

@@ -0,0 +1,82 @@
+module PatternRuby
+  class Conversation
+    attr_reader :context, :history, :slots
+
+    def initialize(router)
+      @router = router
+      @context = nil
+      @history = []
+      @slots = {}
+    end
+
+    def process(input)
+      result = @router.match(input, context: @context)
+
+      if result.matched?
+        # Merge new entities into accumulated slots
+        result.entities.each do |k, v|
+          @slots[k] = v unless v.nil?
+        end
+
+        # Build enriched result with accumulated slots
+        result = MatchResult.new(
+          intent: result.intent,
+          entities: @slots.dup,
+          pattern: result.pattern,
+          score: result.score,
+          input: result.input,
+          response: result.response
+        )
+      elsif !@history.empty? && @slots.any?
+        # Try to fill a missing slot from context
+        last = @history.last
+        if last&.matched?
+          filled = try_slot_fill(input, last.intent)
+          if filled
+            result = MatchResult.new(
+              intent: last.intent,
+              entities: @slots.dup,
+              pattern: last.pattern,
+              score: last.score,
+              input: input,
+              response: last.response
+            )
+          end
+        end
+      end
+
+      @history << result
+      result
+    end
+
+    def set_context(ctx)
+      @context = ctx
+    end
+
+    def clear_context
+      @context = nil
+    end
+
+    def reset
+      @context = nil
+      @history = []
+      @slots = {}
+    end
+
+    private
+
+    def try_slot_fill(input, intent_name)
+      intent = @router.intents.find { |i| i.name == intent_name }
+      return false unless intent
+
+      # Find entity definitions that don't have a slot value yet
+      unfilled = intent.entity_definitions.select { |name, _| !@slots.key?(name) || @slots[name].nil? }
+      return false if unfilled.empty?
+
+      # Try the input as a value for the first unfilled slot
+      name, defn = unfilled.first
+      @slots[name] = input.strip
+      true
+    end
+  end
+end

data/lib/pattern_ruby/entity.rb

@@ -0,0 +1,17 @@
+module PatternRuby
+  class Entity
+    attr_reader :name, :type, :value, :raw, :span
+
+    def initialize(name:, type: :string, value: nil, raw: nil, span: nil)
+      @name = name.to_sym
+      @type = type.to_sym
+      @value = value
+      @raw = raw
+      @span = span
+    end
+
+    def to_h
+      { name: @name, type: @type, value: @value, raw: @raw }
+    end
+  end
+end

data/lib/pattern_ruby/entity_types.rb

@@ -0,0 +1,38 @@
+module PatternRuby
+  module EntityTypes
+    BUILT_IN = {
+      string: { pattern: nil, parser: nil },
+      number: { pattern: /\d+(?:\.\d+)?/, parser: ->(s) { s.include?(".") ? s.to_f : s.to_i } },
+      integer: { pattern: /\d+/, parser: ->(s) { s.to_i } },
+      email: { pattern: /[\w.+\-]+@[\w\-]+\.[\w.]+/, parser: nil },
+      phone: { pattern: /\+?\d[\d\s\-()]{7,}/, parser: nil },
+      url: { pattern: %r{https?://\S+}, parser: nil },
+      currency: { pattern: /\$[\d,]+(?:\.\d{2})?/, parser: ->(s) { s.delete(",").delete("$").to_f } },
+    }.freeze
+
+    class Registry
+      def initialize
+        @types = BUILT_IN.dup
+      end
+
+      def register(name, pattern: nil, parser: nil)
+        @types[name.to_sym] = { pattern: pattern, parser: parser }
+      end
+
+      def get(name)
+        @types[name.to_sym]
+      end
+
+      def pattern_for(name)
+        type = get(name)
+        type && type[:pattern]
+      end
+
+      def parse(name, raw_value)
+        type = get(name)
+        return raw_value unless type && type[:parser]
+        type[:parser].call(raw_value)
+      end
+    end
+  end
+end

data/lib/pattern_ruby/intent.rb

@@ -0,0 +1,144 @@
+module PatternRuby
+  class Intent
+    attr_reader :name, :compiled_patterns, :entity_definitions, :response_text, :context_requirement
+
+    def initialize(name, compiler:)
+      @name = name.to_sym
+      @compiler = compiler
+      @compiled_patterns = []
+      @entity_definitions = {}
+      @response_text = nil
+      @context_requirement = nil
+    end
+
+    def pattern(pat)
+      if pat.is_a?(Regexp)
+        @compiled_patterns << RegexPattern.new(pat)
+      else
+        @compiled_patterns << @compiler.compile(pat)
+      end
+    end
+
+    def entity(name, type: :string, **options)
+      @entity_definitions[name.to_sym] = { type: type, **options }
+    end
+
+    def response(text)
+      @response_text = text
+    end
+
+    def context(ctx)
+      @context_requirement = ctx
+    end
+
+    def match(input, entity_registry: nil)
+      @compiled_patterns.each do |cp|
+        md = cp.match(input)
+        next unless md
+
+        entities = extract_entities(md, cp, entity_registry)
+        score = compute_score(cp, md, input)
+
+        return MatchResult.new(
+          intent: @name,
+          entities: entities,
+          pattern: cp.source,
+          score: score,
+          input: input,
+          response: @response_text
+        )
+      end
+      nil
+    end
+
+    private
+
+    def extract_entities(match_data, compiled_pattern, entity_registry)
+      entities = {}
+
+      if compiled_pattern.is_a?(RegexPattern)
+        match_data.named_captures.each do |name, value|
+          entities[name.to_sym] = parse_entity(name.to_sym, value, entity_registry)
+        end
+        # Also capture numbered groups if no named captures
+        if entities.empty? && match_data.captures.any?
+          match_data.captures.each_with_index do |cap, i|
+            entities[:"capture_#{i}"] = cap
+          end
+        end
+      else
+        compiled_pattern.entity_names.each do |ename|
+          raw = match_data[ename]
+          next unless raw
+          entities[ename] = parse_entity(ename, raw, entity_registry)
+        end
+      end
+
+      # Apply defaults from entity definitions
+      @entity_definitions.each do |ename, defn|
+        next if entities.key?(ename)
+        entities[ename] = defn[:default] if defn.key?(:default)
+      end
+
+      entities
+    end
+
+    def parse_entity(name, raw_value, entity_registry)
+      defn = @entity_definitions[name]
+      if defn && entity_registry
+        parsed = entity_registry.parse(defn[:type], raw_value)
+        return parsed if parsed
+      end
+      raw_value
+    end
+
+    def compute_score(compiled_pattern, match_data, input)
+      if compiled_pattern.is_a?(RegexPattern)
+        matched_length = match_data[0].length.to_f
+        return (matched_length / input.length).clamp(0.0, 1.0)
+      end
+
+      score = 0.0
+
+      # Literal ratio: more literal tokens = more specific
+      if compiled_pattern.token_count > 0
+        literal_ratio = compiled_pattern.literal_count.to_f / compiled_pattern.token_count
+        score += literal_ratio * 0.5
+      end
+
+      # Entity fill ratio
+      if compiled_pattern.entity_count > 0
+        filled = compiled_pattern.entity_names.count { |n| match_data[n] && !match_data[n].empty? }
+        entity_ratio = filled.to_f / compiled_pattern.entity_count
+        score += entity_ratio * 0.3
+      else
+        score += 0.3
+      end
+
+      # Coverage: how much of the input was consumed
+      matched_length = match_data[0].strip.length.to_f
+      coverage = input.strip.empty? ? 0.0 : matched_length / input.strip.length
+      score += coverage * 0.2
+
+      score.clamp(0.0, 1.0)
+    end
+  end
+
+  # Wraps a raw Regexp as a pattern
+  class RegexPattern
+    attr_reader :source, :regex, :entity_names, :literal_count, :token_count, :entity_count
+
+    def initialize(regex)
+      @source = regex.source
+      @regex = regex
+      @entity_names = regex.named_captures.keys.map(&:to_sym)
+      @literal_count = 0
+      @token_count = 1
+      @entity_count = @entity_names.size
+    end
+
+    def match(input)
+      @regex.match(input)
+    end
+  end
+end

data/lib/pattern_ruby/match_result.rb

@@ -0,0 +1,29 @@
+module PatternRuby
+  class MatchResult
+    attr_reader :intent, :entities, :pattern, :score, :input, :metadata, :response
+
+    def initialize(intent: nil, entities: {}, pattern: nil, score: 0.0,
+                   input: nil, metadata: {}, response: nil, fallback: false)
+      @intent = intent
+      @entities = entities
+      @pattern = pattern
+      @score = score
+      @input = input
+      @metadata = metadata
+      @response = response
+      @fallback = fallback
+    end
+
+    def matched?
+      @intent != nil && !fallback?
+    end
+
+    def fallback?
+      @fallback
+    end
+
+    def to_h
+      { intent: @intent, entities: @entities, score: @score, pattern: @pattern }
+    end
+  end
+end

data/lib/pattern_ruby/pattern_compiler.rb

@@ -0,0 +1,171 @@
+module PatternRuby
+  class CompiledPattern
+    attr_reader :source, :regex, :entity_names, :literal_count, :token_count, :entity_count
+
+    def initialize(source:, regex:, entity_names:, literal_count:, token_count:, entity_count:)
+      @source = source
+      @regex = regex
+      @entity_names = entity_names
+      @literal_count = literal_count
+      @token_count = token_count
+      @entity_count = entity_count
+    end
+
+    def match(input)
+      @regex.match(input)
+    end
+  end
+
+  class PatternCompiler
+    def initialize(entity_registry: nil)
+      @entity_registry = entity_registry
+    end
+
+    def compile(pattern_string)
+      tokens = tokenize(pattern_string)
+      entity_names = []
+      literal_count = 0
+      regex_parts = []
+
+      tokens.each do |token|
+        case token
+        when EntityToken
+          entity_names << token.name.to_sym
+          regex_parts << build_entity_regex(token)
+        when OptionalToken
+          inner = compile_inner(token.content)
+          entity_names.concat(inner[:entity_names])
+          regex_parts << "(?:\\s+#{inner[:regex]})?"
+        when AlternationToken
+          alts = token.alternatives.map { |a| Regexp.escape(a) }
+          regex_parts << "(?:#{alts.join('|')})"
+          literal_count += 1
+        when WildcardToken
+          regex_parts << "(.+)"
+        when LiteralToken
+          regex_parts << Regexp.escape(token.text)
+          literal_count += 1
+        end
+      end
+
+      token_count = tokens.size
+      entity_count = entity_names.size
+
+      # Join with \s+ but make whitespace before optional groups flexible
+      regex_str = +""
+      regex_parts.each_with_index do |part, i|
+        if i > 0 && !part.start_with?("(?:\\s+") # optional groups already include leading \s+
+          regex_str << "\\s+"
+        end
+        regex_str << part
+      end
+
+      regex = Regexp.new("\\A\\s*#{regex_str}\\s*\\z", Regexp::IGNORECASE)
+
+      CompiledPattern.new(
+        source: pattern_string,
+        regex: regex,
+        entity_names: entity_names,
+        literal_count: literal_count,
+        token_count: token_count,
+        entity_count: entity_count
+      )
+    end
+
+    private
+
+    EntityToken = Struct.new(:name, :constraint)
+    OptionalToken = Struct.new(:content)
+    AlternationToken = Struct.new(:alternatives)
+    WildcardToken = Class.new
+    LiteralToken = Struct.new(:text)
+
+    def tokenize(pattern_string)
+      tokens = []
+      scanner = StringScanner.new(pattern_string.strip)
+
+      until scanner.eos?
+        scanner.skip(/\s+/)
+        break if scanner.eos?
+
+        if scanner.scan(/\{([^}]+)\}/)
+          # Entity: {name} or {name:constraint}
+          content = scanner[1]
+          name, constraint = content.split(":", 2)
+          tokens << EntityToken.new(name.strip, constraint&.strip)
+        elsif scanner.scan(/\[/)
+          # Optional: [content]
+          depth = 1
+          content = +""
+          until depth == 0 || scanner.eos?
+            if scanner.scan(/\[/)
+              depth += 1
+              content << "["
+            elsif scanner.scan(/\]/)
+              depth -= 1
+              content << "]" if depth > 0
+            else
+              content << scanner.getch
+            end
+          end
+          tokens << OptionalToken.new(content.strip)
+        elsif scanner.scan(/\(([^)]+)\)/)
+          # Alternation: (a|b|c)
+          alts = scanner[1].split("|").map(&:strip)
+          tokens << AlternationToken.new(alts)
+        elsif scanner.scan(/\*/)
+          tokens << WildcardToken.new
+        else
+          # Literal word(s) — scan until next special token or whitespace
+          word = scanner.scan(/[^\s\[\]{}()*]+/)
+          tokens << LiteralToken.new(word) if word
+        end
+      end
+
+      tokens
+    end
+
+    def build_entity_regex(token)
+      if token.constraint
+        if token.constraint.include?("|")
+          # Enum constraint: {time:today|tomorrow|this week}
+          alts = token.constraint.split("|").map { |a| Regexp.escape(a.strip) }
+          "(?<#{token.name}>#{alts.join('|')})"
+        else
+          # Regex constraint: {order_id:\\d+}
+          "(?<#{token.name}>#{token.constraint})"
+        end
+      else
+        # Check entity registry for type-specific pattern
+        type_pattern = @entity_registry&.pattern_for(token.name)
+        if type_pattern
+          "(?<#{token.name}>#{type_pattern.source})"
+        else
+          # Default: capture any non-greedy text
+          "(?<#{token.name}>.+?)"
+        end
+      end
+    end
+
+    def compile_inner(content)
+      inner_tokens = tokenize(content)
+      entity_names = []
+      parts = []
+
+      inner_tokens.each do |token|
+        case token
+        when EntityToken
+          entity_names << token.name.to_sym
+          parts << build_entity_regex(token)
+        when LiteralToken
+          parts << Regexp.escape(token.text)
+        when AlternationToken
+          alts = token.alternatives.map { |a| Regexp.escape(a) }
+          parts << "(?:#{alts.join('|')})"
+        end
+      end
+
+      { regex: parts.join("\\s+"), entity_names: entity_names }
+    end
+  end
+end

data/lib/pattern_ruby/pipeline.rb

@@ -0,0 +1,24 @@
+module PatternRuby
+  class Pipeline
+    def initialize(&block)
+      @steps = []
+      instance_eval(&block) if block
+    end
+
+    def step(name, &block)
+      @steps << { name: name, handler: block }
+    end
+
+    def process(input)
+      result = input
+      @steps.each do |s|
+        result = s[:handler].call(result)
+      end
+      result
+    end
+
+    def steps
+      @steps.map { |s| s[:name] }
+    end
+  end
+end

data/lib/pattern_ruby/rails/test_helpers.rb

@@ -0,0 +1,23 @@
+module PatternRuby
+  module TestHelpers
+    def assert_matches_intent(expected_intent, input, router:, message: nil)
+      result = router.match(input)
+      msg = message || "Expected input #{input.inspect} to match intent :#{expected_intent}, but got :#{result.intent}"
+      assert result.matched?, msg
+      assert_equal expected_intent, result.intent, msg
+    end
+
+    def assert_extracts_entity(entity_name, expected_value, input, router:, message: nil)
+      result = router.match(input)
+      msg = message || "Expected entity :#{entity_name} to be #{expected_value.inspect}"
+      assert result.matched?, "Input #{input.inspect} did not match any intent"
+      assert_equal expected_value, result.entities[entity_name.to_sym], msg
+    end
+
+    def refute_matches(input, router:, message: nil)
+      result = router.match(input)
+      msg = message || "Expected input #{input.inspect} not to match, but matched :#{result.intent}"
+      refute result.matched?, msg
+    end
+  end
+end

data/lib/pattern_ruby/router.rb

@@ -0,0 +1,79 @@
+module PatternRuby
+  class Router
+    attr_reader :intents
+
+    def initialize(&block)
+      @intents = []
+      @fallback_handler = nil
+      @entity_registry = EntityTypes::Registry.new
+      @compiler = PatternCompiler.new(entity_registry: @entity_registry)
+      instance_eval(&block) if block
+    end
+
+    def intent(name, &block)
+      i = Intent.new(name, compiler: @compiler)
+      i.instance_eval(&block) if block
+      @intents << i
+      i
+    end
+
+    def fallback(&block)
+      @fallback_handler = block
+    end
+
+    def entity_type(name, **options)
+      @entity_registry.register(name, **options)
+    end
+
+    def match(input, context: nil)
+      input = input.to_s.strip
+      return fallback_result(input) if input.empty?
+
+      candidates = []
+
+      @intents.each do |i|
+        # Skip intents that require a specific context
+        if i.context_requirement
+          next unless context == i.context_requirement
+        end
+
+        result = i.match(input, entity_registry: @entity_registry)
+        candidates << result if result
+      end
+
+      return candidates.max_by(&:score) unless candidates.empty?
+
+      fallback_result(input)
+    end
+
+    def match_all(input, context: nil)
+      input = input.to_s.strip
+      return [] if input.empty?
+
+      candidates = []
+
+      @intents.each do |i|
+        if i.context_requirement
+          next unless context == i.context_requirement
+        end
+
+        result = i.match(input, entity_registry: @entity_registry)
+        candidates << result if result
+      end
+
+      candidates.sort_by { |r| -r.score }
+    end
+
+    private
+
+    def fallback_result(input)
+      @fallback_handler&.call(input)
+
+      MatchResult.new(
+        intent: nil,
+        input: input,
+        fallback: true
+      )
+    end
+  end
+end

data/lib/pattern_ruby/version.rb

@@ -0,0 +1,3 @@
+module PatternRuby
+  VERSION = "0.1.0"
+end

data/lib/pattern_ruby.rb

@@ -0,0 +1,15 @@
+require "strscan"
+
+require_relative "pattern_ruby/version"
+require_relative "pattern_ruby/match_result"
+require_relative "pattern_ruby/entity"
+require_relative "pattern_ruby/entity_types"
+require_relative "pattern_ruby/pattern_compiler"
+require_relative "pattern_ruby/intent"
+require_relative "pattern_ruby/router"
+require_relative "pattern_ruby/pipeline"
+require_relative "pattern_ruby/conversation"
+
+module PatternRuby
+  class Error < StandardError; end
+end

data/pattern-ruby.gemspec

@@ -0,0 +1,36 @@
+require_relative "lib/pattern_ruby/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "pattern-ruby"
+  spec.version       = PatternRuby::VERSION
+  spec.authors       = ["Johannes Dwi Cahyo"]
+  spec.summary       = "Deterministic pattern detection and intent matching engine for Ruby"
+  spec.description   = "A rule-based pattern matching engine for chatbots and conversational AI. " \
+                        "Provides a DSL for defining intents, extracting entities, and routing " \
+                        "user input — deterministically, with zero latency and no API calls."
+  spec.homepage      = "https://github.com/johannesdwicahyo/pattern-ruby"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.files = Dir[
+    "lib/**/*.rb",
+    "examples/**/*.rb",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "Rakefile",
+    "pattern-ruby.gemspec"
+  ]
+
+  spec.metadata = {
+    "homepage_uri"    => spec.homepage,
+    "source_code_uri" => spec.homepage,
+    "changelog_uri"   => "#{spec.homepage}/blob/main/CHANGELOG.md",
+  }
+
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: pattern-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Johannes Dwi Cahyo
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: A rule-based pattern matching engine for chatbots and conversational
+  AI. Provides a DSL for defining intents, extracting entities, and routing user input
+  — deterministically, with zero latency and no API calls.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- examples/chatbot.rb
+- examples/customer_service.rb
+- examples/with_llm_fallback.rb
+- lib/pattern_ruby.rb
+- lib/pattern_ruby/conversation.rb
+- lib/pattern_ruby/entity.rb
+- lib/pattern_ruby/entity_types.rb
+- lib/pattern_ruby/intent.rb
+- lib/pattern_ruby/match_result.rb
+- lib/pattern_ruby/pattern_compiler.rb
+- lib/pattern_ruby/pipeline.rb
+- lib/pattern_ruby/rails/test_helpers.rb
+- lib/pattern_ruby/router.rb
+- lib/pattern_ruby/version.rb
+- pattern-ruby.gemspec
+homepage: https://github.com/johannesdwicahyo/pattern-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/johannesdwicahyo/pattern-ruby
+  source_code_uri: https://github.com/johannesdwicahyo/pattern-ruby
+  changelog_uri: https://github.com/johannesdwicahyo/pattern-ruby/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Deterministic pattern detection and intent matching engine for Ruby
+test_files: []