natter 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b2654979a551d969bac208c18667ce2c7c74d7fc
+  data.tar.gz: 5726246cb0c3fdde38783f6e4d77f97a46a3cc7c
+SHA512:
+  metadata.gz: 89a96014d6139600ed0728d18dc030dc5f753e2e1a4676cd7dd522684b0fd0b11785c84661b192ba8cf69cfff84bbc9ec888b55983396e711fafb4179e70b6dd
+  data.tar.gz: f6fd7870a3f35019341f6403791fc96c1a94c35c34d95ed0d3e3a099d2cd41d1ca9fb3b0573bc075821ef063d5778046c2cdf9445ad57dd1d5a82baf46a3d0cb

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in natter.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Garry Pettet
+
+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,39 @@
+# Natter
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/natter`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+TODO: Delete this and the text above, and describe your gem
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'natter'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install natter
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/natter.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+task :default => :spec

data/lib/natter/entity.rb

@@ -0,0 +1,40 @@
+module Natter
+  # Public: An entity is an attribute of an intent.
+  class Entity
+    attr_accessor :name, :type
+    attr_reader :value
+
+    # Public: Constructor.
+    #
+    # name  - Must be unique within an individual intent.
+    # type  - One of the pre-defined EntityType constants (default: 'generic')
+    # value - Will never be nil when generated by the parser but may be nil 
+    #         for some rule definitions (default: nil).
+    def initialize(name, type = EntityType::GENERIC, value = nil)
+      @name = name
+      @type = type
+      @value = value
+    end
+
+    # Public: Returns the value of this entity.
+    # If @type is `generic` then we just return @value, otherwise we will need 
+    # to verify/compute the value to return.
+    #
+    # Returns object or nil (if invalid @value)
+    def value
+      case @type
+      when EntityType::TIME
+        return Chronic.parse(@value) # returns Time or nil
+      else
+        return @value
+      end
+    end
+  end
+
+  # Public: Exists only to expose its constants which are used to define
+  # Entity types.
+  class EntityType
+    GENERIC = 'generic'
+    TIME = 'time'
+  end
+end

data/lib/natter/intent.rb

@@ -0,0 +1,28 @@
+module Natter
+  # Public: Represents an intent derived by the parser from an utterance.
+  class Intent
+    # The string name of this intent.
+    attr_accessor :name
+    # The name of the skill that this intent belongs to.
+    attr_accessor :skill
+    # How confident the parser is that this is the correct intent (from 0.0 - 1.0).
+    attr_accessor :confidence
+    # An array of entities discovered in the utterance. May be empty.
+    attr_accessor :entities
+
+    # Public: Constructor.
+    # 
+    # name       - The String name of this intent. Does not have to be unique.
+    # skill      - The name of the skill that this intent belongs to. Defaults 
+    #              to the global namespace/skill (default: '')
+    # confidence - Float value between 0-1 reflects how confident the parser is 
+    #              that this intent is correct (default: 1.0).
+    # entities   - An array of Natter::Entity objects (default: nil).
+    def initialize(name, skill = '', confidence = 1.0, entities = nil)
+      @name = name
+      @skill = skill
+      @confidence = confidence
+      @entities = entities || []
+    end
+  end
+end

data/lib/natter/parser.rb

@@ -0,0 +1,306 @@
+module Natter
+  # Public: The parser is the main workhorse, responsible for deriving the 
+  # intent from an utterance.
+  class Parser
+    def initialize
+      @known_utterances = Hash.new # key = utterance, value = Intent
+      @contractions = init_contractions # key = contraction, value = expansion
+      @intent_cache = Hash.new # key = utterance, value = Intent
+      @rules = Hash.new # key = rule regex pattern, value = Rule object
+    end
+    # Public: Adds a regex-based Rule to the parser.
+    #
+    # rule - The Natter::Rule to add.
+    def add_rule(rule)
+      raise ArgumentError, "Expected Natter::Rule but got `#{rule}`" unless rule.is_a?(Rule)
+      if @rules.has_key?(rule.pattern)
+        raise ArgumentError, "Regex pattern already defined by " +\
+        "#{@rules[rule.pattern].identifier}: #{rule.pattern}"
+      end
+      @rules[rule.pattern] = rule
+    end
+
+    # Public: Adds a pre-computed utterance/intent pair to the parser.
+    # Used when a specific utterance(s) match a predetermined intent. This saves 
+    # overhead as there is no regex processing required. These utterances are 
+    # evaluated before the regex rules.
+    # Multiple examples can be added at once.
+    # Adding an utterance that already exists will overwrite the old one.
+    #
+    # example - A Hash where:
+    #           key   = A single utterance or array of utterances
+    #           value = Natter::Intent
+    #
+    # Examples
+    #
+    # add_utterance('hello' => Intent.new('greeting'))
+    # add_utterance(['what time is it', 'what is the time'] => Intent.new('currentTime'))
+    # add_utterance(
+    #   'night night' => Intent.new('goodnight'),
+    #   'lock the door' => Intent.new('lock') 
+    # )
+    #
+    # Returns nothing.
+    def add_utterance(example)
+      raise ArgumentError, "Expected {utterance => Intent} or {[utterances] => Intent}" unless example.is_a?(Hash) 
+      example.map do |utterance, intent|
+        if utterance.kind_of?(Array)
+          utterance.each { |phrase| @known_utterances[phrase] = intent }
+        else
+          @known_utterances[utterance] = intent
+        end
+      end
+    end
+    
+    # Public: Analyse an utterance and return any matching intents.
+    #
+    # utterance - The natural language string to analyse
+    # use_cache - If true then we will check a cache of previously returned
+    #             utterance/intent pairs to return rather than re-parsing.
+    #             (default: true)
+    #
+    # Returns an Intent, an array of Intents or nil if the intent cannot be 
+    # determined.
+    def parse(text, use_cache = true)
+      raise ArgumentError, "Cannot parse thin air!" unless text.length > 0
+      
+      # Store the original string for later
+      original = text
+
+      # Tidy up the string for parsing
+      utterance = purify(original)
+      
+      if @known_utterances.has_key?(utterance)
+        return @known_utterances[utterance]
+      end
+
+      if use_cache && @intent_cache.has_key?(utterance)
+        return @intent_cache[utterance]
+      end
+
+      intents = []
+      @rules.each do |pattern, rule|
+        m = utterance.match(rule.pattern)
+        if m == nil
+          next
+        else
+          intent = intent_from_match(rule, m)
+          if intent then intents << intent end
+        end      
+      end
+
+      if intents.empty? then return nil end
+
+      # Calculate the confidence of each intent
+      intents = determine_confidences(intents)
+
+      # Cache the matches
+      @intent_cache[utterance] = intents
+
+      return intents
+    end
+
+    # Internal: Determines the confidence of each intent in the passed array 
+    # and then sorts them based on the calculated confidence values.
+    # Basically, if we have more than one intent then whichever intent has the 
+    # greatest number of entities is likely to be the best match.
+    #
+    # intents - An array of Intent objects.
+    #
+    # Returns a sorted (by confidence) array of Intent objects. Mutates original
+    # array.
+    def determine_confidences(intents)
+      # Handle where there's only one matching intent
+      if intents.length == 1
+        intents[0].confidence = 1.0
+        return intents
+      end
+
+      # First determine the total number of entities in any of the intents
+      total = 0
+      intents.each { |i| total += i.entities.length }
+
+      if total == 0
+        # Edge case: all matching intents contain no entities.
+        # Assign equal confidence to all intents
+        result = intents.map do |i|
+          i.confidence = 1.0/intents.length
+          i # return this intent from the map
+        end
+      else
+        result = intents.map do |i|
+          i.confidence = i.entities.length.to_f/total
+          i # return this intent from the map
+        end
+      end
+
+      # Sort the array by descending confidence values
+      result.sort_by { |i| i.confidence }.reverse
+    end
+
+    # Internal: Converts a positive regex match and returns an Intent object.
+    # Note that the confidence is set to 0 as it will be determined later.
+    #
+    # rule      - The Rule definining this intent.
+    # m         - The positive regex match.
+    #
+    # Returns Intent. 
+    def intent_from_match(rule, m)
+      if m.named_captures.empty?
+        # No capture groups found. Double-check the rule doesn't need any entities
+        if rule.entities.empty?
+          return Intent.new(rule.name, rule.skill, 0)
+        else
+          # Expected at least one entity. This can't be a valid match then
+          return nil
+        end
+      else
+        # Found some entities. Check they match up with the rule
+        intent = Intent.new(rule.name, rule.skill, 0)
+        rule.entities.each do |entity|
+          if m.named_captures.has_key?(entity.name)
+            e = Entity.new(entity.name, entity.type, m.named_captures[entity.name].strip)
+            intent.entities << e
+          else
+            # Found a named capture group that doesn't match an entity defined 
+            # in the rule
+            return nil
+          end
+        end
+        if intent.entities.length != m.named_captures.length
+          # Found some entity matches but not all
+          return nil
+        else
+          return intent
+        end
+      end
+    end
+
+    # Internal: Tidies up the passed string to remove unnecessary characters
+    # and replace ambiguous phrases such as contractions.
+    #
+    # t - The string to purify.
+    #
+    # Examples
+    #
+    # str = "what're you doing?!"
+    # str = purify(str)
+    #  # => "what are you doing"
+    def purify(t)
+      t = expand_contractions(t)
+      t = strip_trailing_punctuation(t)
+    end
+
+    # Internal: Removes trailing '?' and '!' from the passed string.
+    #
+    # t - The string from which to remove superfluous trailing punctuation.
+    def strip_trailing_punctuation(t)
+      t.sub(/[?!]+\z/, '')
+    end
+
+    # Private: Initialise the @contractions Hash. Only needs doing once.
+    # OPTIMISE: Perhaps move these values to an editable text file?
+    def init_contractions
+      {
+        "that's" => "that is",
+        "aren't" => "are not",
+        "can't" => "can not",
+        "could've" => "could have",
+        "couldn't" => "could not",
+        "didn't" => "did not",
+        "doesn't" => "does not",
+        "don't" => "do not",
+        "dunno" => "do not know",
+        "gonna" => "going to",
+        "gotta" => "got to",
+        "hadn't" => "had not",
+        "hasn't" => "has not",
+        "haven't" => "have not",
+        "he'd" => "he had",
+        "he'll" => "he will",
+        "he's" => "he is",
+        "how'd" => "how would",
+        "how'll" => "how will",
+        "how're" => "how are",
+        "how's" => "how is",
+        "i'd" => "i would",
+        "i'll" => "i will",
+        "i'm" => "i am",
+        "i've" => "i have",
+        "isn't" => "is not",
+        "it'd" => "it would",
+        "it'll" => "it will",
+        "it's" => "it is",
+        "mightn't" => "might not",
+        "might've" => "might have",
+        "mustn't" => "must not",
+        "must've" => "must have",
+        "ol'" => "old",
+        "oughtn't" => "ought not",
+        "shan't" => "shall not",
+        "she'd" => "she would",
+        "she'll" => "she will",
+        "she's" => "she is",
+        "should've" => "should have",
+        "shouldn't" => "should not",
+        "somebody's" => "somebody is",
+        "someone'll" => "someone will",
+        "someone's" => "someone is",
+        "something'll" => "something will",
+        "something's" => "something is",
+        "that'll" => "that will",
+        "that'd" => "that would",
+        "there'd" => "there had",
+        "there's" => "there is",
+        "they'd" => "they would",
+        "they'll" => "they will",
+        "they're" => "they are",
+        "they've" => "they have",
+        "wasn't" => "was not",
+        "we'd" => "we had",
+        "we'll" => "we will",
+        "we're" => "we are",
+        "we've" => "we have",
+        "weren't" => "were not",
+        "what'd" => "what did",
+        "what'll" => "what will",
+        "what're" => "what are",
+        "what's" => "what is",
+        "what've" => "what have",
+        "when's" => "when is",
+        "where'd" => "where did",
+        "where's" => "where is",
+        "where've" => "where have",
+        "who'd" => "who would",
+        "who'll" => "who will",
+        "who's" => "who is",
+        "why'd" => "why did",
+        "why're" => "why are",
+        "why's" => "why is",
+        "won't" => "will not",
+        "won't've" => "will not have",
+        "would've" => "would have",
+        "wouldn't" => "would not",
+        "you'd" => "you would",
+        "you'll" => "you will",
+        "you're" => "you are",
+        "you've" => "you have"
+      }
+    end
+
+    # Expand the contractions within this string.
+    # 
+    # Examples
+    #
+    # t = "I'm hot"
+    # t.expand_contractions!
+    #   # => "I am hot"
+    def expand_contractions(text)
+      result = ''
+      text.strip.split(' ').each do |word|
+        result = result + @contractions.fetch(word, word) + ' '
+      end
+      return result.strip
+    end
+  end
+end

data/lib/natter/rule.rb

@@ -0,0 +1,93 @@
+module Natter
+  
+  # Public: The Rule class represents a rule which defines an in intent that 
+  # occurs within an utterance.
+
+  class Rule
+    
+    # The string name of this rule. Defferent rules can share the same name.
+    attr_accessor :name
+    # The regex pattern to search for within the an utterance.
+    attr_accessor :pattern
+    # An array of Entity objects this rule expects. May be empty.
+    attr_accessor :entities
+    # The name of the skill that this rule belongs to. May be '' if global.
+    attr_accessor :skill 
+  
+    # Public: Constructor.
+    #
+    # name     - The name of this intent. Names do not need to be unique 
+    #            within a parser.
+    # pattern  - The regular expression that matches the contents of an 
+    #            utterance. If this intent contains entities then the regex 
+    #            must capture the entities within the utterance as named 
+    #            capture groups. See examples below. Default: //
+    # skill    - The name of the skill that this rule belongs to. If none is 
+    #            specified then we'll assume it's a global rule (default: '').
+    # entities - Optional array of Entity objects in the form:
+    #            Each entity must have a correspondingly named capture group 
+    #            within the regex.
+    def initialize(name, pattern = //, skill = '', *entities)
+      @name = name
+      @pattern = pattern
+      @skill = skill
+      @entities = entities || []
+    end
+
+    # Public: A convenience method to permit prettier building of rules.
+    # Returns the Rule back to the calling method to allow chaining.
+    #
+    # pattern - The regex pattern to assign to this rule
+    #
+    # Examples
+    #
+    # definition = Rule.new('reminder').regex(/remind me to/i)
+    # definition = Rule.new('reminder')\
+    #             .regex(/remind me/)\
+    #             .needs_entity('task', EntityType::GENERIC)
+    def regex(pattern)
+      @pattern = pattern
+      return self
+    end
+
+    # Public: Returns this rule's identifier. An identifier is in the format:
+    # skill.name unless skill = '' in which case we return global.name
+    #
+    # Returns string
+    def identifier
+      "#{@skill == '' ? 'global' : @skill}.#{@name}"
+    end
+
+    # Public: A convenience method to permit prettier building of rules. 
+    # Returns the Rule back to the calling method to allowing chaining.
+    #
+    # skill - The name of the skill that this this rule belongs to.
+    #
+    # Example
+    #
+    # def = Rule.new('play').belongs_to('sonos')
+    def belongs_to(skill)
+      @skill = skill
+      return self
+    end
+
+    # Public: A nicer syntax method for adding an Entity to this rule.
+    #
+    # name - The name of this entity. Must be unique within this rule definition
+    #        and must match a named capture group within the definition's regex.
+    #
+    # type - The entity's type. Should be one of the predefined constants in 
+    #        Natter::EntityType
+    #
+    # Example
+    #
+    # definition.needs_entity('artist', EntityType::GENERIC)
+    def needs_entity(name, type)
+      @entities.each do |entity|
+        return if entity.name == name # this rule already contains this entity
+      end
+      @entities << Entity.new(name, type)
+      return self
+    end
+  end
+end

data/lib/natter/version.rb

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

data/lib/natter.rb

@@ -0,0 +1,16 @@
+# Natter is a rules-based natural language intent parser.
+# Loads the files required by Natter.
+
+# Third party dependencies
+require 'chronic'
+
+# # Modules/classes
+require_relative 'natter/entity'
+require_relative 'natter/intent'
+require_relative 'natter/parser'
+require_relative 'natter/rule'
+require_relative 'natter/version'
+
+module Natter
+
+end

data/natter.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "natter/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "natter"
+  spec.version       = Natter::VERSION
+  spec.authors       = ["Garry Pettet"]
+  spec.email         = ["contact@garrypettet.com"]
+
+  spec.summary       = 'Rules-based natural language intent parser.'
+  spec.description   = 'A rules-based natural language intent parser written in pure Ruby.'
+  spec.homepage      = 'https://github.com/BarnabyAI/natter'
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "chronic", "~> 0.10"
+  spec.add_runtime_dependency "oj", "~> 3.3"
+
+  spec.add_development_dependency "bundler", "~> 1.15"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: natter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Garry Pettet
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-10-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: chronic
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: oj
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: A rules-based natural language intent parser written in pure Ruby.
+email:
+- contact@garrypettet.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/natter.rb
+- lib/natter/entity.rb
+- lib/natter/intent.rb
+- lib/natter/parser.rb
+- lib/natter/rule.rb
+- lib/natter/version.rb
+- natter.gemspec
+homepage: https://github.com/BarnabyAI/natter
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.13
+signing_key: 
+specification_version: 4
+summary: Rules-based natural language intent parser.
+test_files: []