google-cloud-language 0.20.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: da9908ff47a91433d085aaf757cd9dcec332d728
+  data.tar.gz: b92bfd0427360fed57ff4093ad5415c8b0c618fc
+SHA512:
+  metadata.gz: 7a55abb2096a8c0b82f32554570eb5ec284f7548d182ec3eaaf53e28fe14d0a926506c480f7d8362e94739c1851b786b154e0a9d29017de31cf408adeb5c7d88
+  data.tar.gz: df1e73e98864c3212d72c7e308dab64d2a350f8468627a3a507c701486e40ea12aa065ebbbd2026c496e6abc4df9d39aa36eb00e03ce738509b82eab45d2b6ca

data/lib/google-cloud-language.rb

@@ -0,0 +1,116 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+##
+# This file is here to be autorequired by bundler, so that the .language and
+# #language methods can be available, but the library and all dependencies won't
+# be loaded until required and used.
+
+
+gem "google-cloud-core"
+require "google/cloud"
+
+module Google
+  module Cloud
+    ##
+    # Creates a new object for connecting to the Language service.
+    # Each call creates a new connection.
+    #
+    # For more information on connecting to Google Cloud see the [Authentication
+    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+    #
+    # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+    #   set of resources and operations that the connection can access. See
+    #   [Using OAuth 2.0 to Access Google
+    #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+    #
+    #   The default scope is:
+    #
+    #   * `"https://www.googleapis.com/auth/cloud-platform"`
+    # @param [Integer] retries Number of times to retry requests on server
+    #   error. The default value is `3`. Optional.
+    # @param [Integer] timeout Default timeout to use in requests. Optional.
+    #
+    # @return [Google::Cloud::Language::Project]
+    #
+    # @example
+    #   require "google/cloud"
+    #
+    #   gcloud = Google::Cloud.new
+    #   language = gcloud.language
+    #   topic = language.topic "my-topic"
+    #   topic.publish "task completed"
+    #
+    # @example The default scope can be overridden with the `scope` option:
+    #   require "google/cloud"
+    #
+    #   gcloud  = Google::Cloud.new
+    #   platform_scope = "https://www.googleapis.com/auth/cloud-platform"
+    #   language = gcloud.language scope: platform_scope
+    #
+    def language scope: nil, retries: nil, timeout: nil
+      Google::Cloud.language @project, @keyfile, scope: scope,
+                                                 retries: (retries || @retries),
+                                                 timeout: (timeout || @timeout)
+    end
+
+    ##
+    # Creates a new object for connecting to the Language service.
+    # Each call creates a new connection.
+    #
+    # For more information on connecting to Google Cloud see the [Authentication
+    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+    #
+    # @param [String] project Project identifier for the Language service you
+    #   are connecting to.
+    # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
+    #   file path the file must be readable.
+    # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+    #   set of resources and operations that the connection can access. See
+    #   [Using OAuth 2.0 to Access Google
+    #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+    #
+    #   The default scope is:
+    #
+    #   * `"https://www.googleapis.com/auth/cloud-platform"`
+    # @param [Integer] retries Number of times to retry requests on server
+    #   error. The default value is `3`. Optional.
+    # @param [Integer] timeout Default timeout to use in requests. Optional.
+    #
+    # @return [Google::Cloud::Language::Project]
+    #
+    # @example
+    #   require "google/cloud/language"
+    #
+    #   language = Google::Cloud.language
+    #
+    #   topic = language.topic "my-topic"
+    #   topic.publish "task completed"
+    #
+    def self.language project = nil, keyfile = nil, scope: nil, retries: nil,
+                      timeout: nil
+      require "google/cloud/language"
+      project ||= Google::Cloud::Language::Project.default_project
+      if keyfile.nil?
+        credentials = Google::Cloud::Language::Credentials.default scope: scope
+      else
+        credentials = Google::Cloud::Language::Credentials.new(
+          keyfile, scope: scope)
+      end
+      Google::Cloud::Language::Project.new(
+        Google::Cloud::Language::Service.new(
+          project, credentials, retries: retries, timeout: timeout))
+    end
+  end
+end

data/lib/google/cloud/language.rb

@@ -0,0 +1,229 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "google-cloud-language"
+require "google/cloud/language/project"
+
+module Google
+  module Cloud
+    ##
+    # # Google Cloud Natural Language API
+    #
+    # Google Cloud Natural Language API reveals the structure and meaning of
+    # text by offering powerful machine learning models in an easy to use REST
+    # API. You can use it to extract information about people, places, events
+    # and much more, mentioned in text documents, news articles or blog posts.
+    # You can use it to understand sentiment about your product on social media
+    # or parse intent from customer conversations happening in a call center or
+    # a messaging app. You can analyze text uploaded in your request or
+    # integrate with your document storage on Google Cloud Storage. Combine the
+    # API with the Google Cloud Speech API and extract insights from audio
+    # conversations. Use with Vision API OCR to understand scanned documents.
+    # Extract entities and understand sentiments in multiple languages by
+    # translating text first with Translate API.
+    #
+    # The Google Cloud Natural Language API is currently a beta release, and
+    # might be changed in backward-incompatible ways. It is not subject to any
+    # SLA or deprecation policy and is not intended for real-time usage in
+    # critical applications.
+    #
+    # For more information about Cloud Natural Language API, read the [Google
+    # Cloud Natural Language API
+    # Documentation](https://cloud.google.com/natural-language/docs/).
+    #
+    # The goal of google-cloud is to provide an API that is comfortable to
+    # Rubyists. Authentication is handled by {Google::Cloud#language}. You can
+    # provide the project and credential information to connect to the Cloud
+    # Natural Language API, or if you are running on Google Compute Engine this
+    # configuration is taken care of for you. You can read more about the
+    # options for connecting in the [Authentication
+    # Guide](https://googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).
+    #
+    # ## Creating documents
+    #
+    # Cloud Natural Language API supports UTF-8, UTF-16, and UTF-32 encodings.
+    # (Ruby uses UTF-8 natively, which is the default sent to the API, so unless
+    # you're working with text processed in different platform, you should not
+    # need to set the encoding type.) Be aware that only English, Spanish, and
+    # Japanese language content are supported, and `sentiment` analysis only
+    # supports English text.
+    #
+    # Use {Language::Project#document} to create documents for the Cloud Natural
+    # Language service. You can provide text or HTML content as a string:
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # language = gcloud.language
+    #
+    # document = language.document "It was the best of times, it was..."
+    # ```
+    #
+    # Or, you can pass a Google Cloud Storage URI for a text or HTML file:
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # language = gcloud.language
+    #
+    # document = language.document "gs://bucket-name/path/to/document"
+    # ```
+    #
+    # Or, you can initialize it with a Google Cloud Storage File object:
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage
+    #
+    # bucket = storage.bucket "bucket-name"
+    # file = bucket.file "path/to/document"
+    #
+    # language = gcloud.language
+    #
+    # document = language.document file
+    # ```
+    #
+    # You can specify the format and language of the content:
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # language = gcloud.language
+    #
+    # document = language.document "<p>El viejo y el mar</p>",
+    #                              format: :html, language: "es"
+    # ```
+    #
+    # Creating a Document instance does not perform an API request.
+    #
+    # ## Annotating documents
+    #
+    # The instance methods on {Language::Document} invoke Cloud Natural
+    # Language's detection features individually. Each method call makes an API
+    # request. If you want to run multiple features in a single request, see
+    # the examples for {Language::Document#annotate}, below. Calling `annotate`
+    # with no arguments will perform **all** analysis features. Each feature
+    # is priced separately. See [Pricing](https://cloud.google.com/natural-language/pricing)
+    # for details.
+    #
+    # Sentiment analysis inspects the given text and identifies the prevailing
+    # emotional opinion within the text, especially to determine a writer's
+    # attitude as positive, negative, or neutral. Sentiment analysis can be
+    # performed with the {Language::Document#sentiment} method. Currently, only
+    # English is supported for sentiment analysis.
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # language = gcloud.language
+    #
+    # content = "Darth Vader is the best villain in Star Wars."
+    # document = language.document content
+    # sentiment = document.sentiment # API call
+    #
+    # sentiment.polarity #=> 1.0
+    # sentiment.magnitude #=> 0.8999999761581421
+    # ```
+    #
+    # Entity analysis inspects the given text for known entities (proper nouns
+    # such as public figures, landmarks, etc.) and returns information about
+    # those entities. Entity analysis can be performed with the
+    # {Language::Document#entities} method.
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # language = gcloud.language
+    #
+    # content = "Darth Vader is the best villain in Star Wars."
+    # document = language.document content
+    # entities = document.entities # API call
+    #
+    # entities.count #=> 2
+    # entities.first.name #=> "Darth Vader"
+    # entities.first.type #=> :PERSON
+    # entities.first.name #=> "Star Wars"
+    # entities.first.type #=> :WORK_OF_ART
+    # ```
+    #
+    # Syntactic analysis extracts linguistic information, breaking up the given
+    # text into a series of sentences and tokens (generally, word boundaries),
+    # providing further analysis on those tokens. Syntactic analysis can be
+    # performed with the {Language::Document#syntax} method.
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # language = gcloud.language
+    #
+    # content = "Darth Vader is the best villain in Star Wars."
+    # document = language.document content
+    # syntax = document.syntax # API call
+    #
+    # syntax.sentences.count #=> 1
+    # syntax.tokens.count #=> 10
+    # ```
+    #
+    # To run multiple features on a document in a single request, pass the flag
+    # for each desired feature to {Language::Document#annotate}:
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # language = gcloud.language
+    #
+    # content = "Darth Vader is the best villain in Star Wars."
+    # document = language.document content
+    # annotation = document.annotate entities: true, text: true
+    #
+    # annotation.sentiment #=> nil
+    # annotation.entities.count #=> 2
+    # annotation.sentences.count #=> 1
+    # annotation.tokens.count #=> 10
+    # ```
+    #
+    # Or, simply call {Language::Document#annotate} with no arguments to process
+    # the document with **all** features:
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # language = gcloud.language
+    #
+    # content = "Darth Vader is the best villain in Star Wars."
+    # document = language.document content
+    # annotation = document.annotate
+    #
+    # annotation.sentiment.polarity #=> 1.0
+    # annotation.sentiment.magnitude #=> 0.8999999761581421
+    # annotation.entities.count #=> 2
+    # annotation.sentences.count #=> 1
+    # annotation.tokens.count #=> 10
+    # ```
+    #
+    module Language
+    end
+  end
+end

data/lib/google/cloud/language/annotation.rb

@@ -0,0 +1,630 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "google/cloud/core/grpc_utils"
+
+module Google
+  module Cloud
+    module Language
+      ##
+      # # Annotation
+      #
+      # The results of all requested document analysis features.
+      #
+      # See {Project#annotate} and {Document#annotate}.
+      #
+      # @example
+      #   require "google/cloud"
+      #
+      #   gcloud = Google::Cloud.new
+      #   language = gcloud.language
+      #
+      #   content = "Darth Vader is the best villain in Star Wars."
+      #   document = language.document content
+      #   annotation = document.annotate
+      #
+      #   annotation.sentiment.polarity #=> 1.0
+      #   annotation.sentiment.magnitude #=> 0.8999999761581421
+      #   annotation.entities.count #=> 2
+      #   annotation.sentences.count #=> 1
+      #   annotation.tokens.count #=> 10
+      #
+      class Annotation
+        ##
+        # @private The AnnotateTextResponse Google API Client object.
+        attr_accessor :grpc
+
+        ##
+        # @private Creates a new Annotation instance.
+        def initialize
+          @grpc = nil
+        end
+
+        ##
+        # The sentences returned by syntactic analysis.
+        #
+        # @return [Array<TextSpan>] an array of pieces of text including
+        #   relative location
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   language = gcloud.language
+        #
+        #   content = "I love dogs. I hate cats."
+        #   document = language.document content
+        #   annotation = document.annotate
+        #
+        #   text_span = annotation.sentences.last
+        #   text_span.text #=> "I hate cats."
+        #   text_span.offset #=> 13
+        #
+        def sentences
+          @sentences ||= begin
+            Array(grpc.sentences).map { |g| TextSpan.from_grpc g.text }
+          end
+        end
+
+        ##
+        # The tokens returned by syntactic analysis.
+        #
+        # @return [Array<Token>] an array of the smallest syntactic building
+        #   blocks of the text
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   language = gcloud.language
+        #
+        #   content = "Darth Vader is the best villain in Star Wars."
+        #   document = language.document content
+        #   annotation = document.annotate
+        #
+        #   annotation.tokens.count #=> 10
+        #   token = annotation.tokens.first
+        #
+        #   token.text_span.text #=> "Darth"
+        #   token.text_span.offset #=> 0
+        #   token.part_of_speech #=> :NOUN
+        #   token.head_token_index #=> 1
+        #   token.label #=> :NN
+        #   token.lemma #=> "Darth"
+        #
+        def tokens
+          @tokens ||= Array(grpc.tokens).map { |g| Token.from_grpc g }
+        end
+
+        ##
+        # The entities returned by entity analysis.
+        #
+        # @return [Entities]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   language = gcloud.language
+        #
+        #   content = "Darth Vader is the best villain in Star Wars."
+        #   document = language.document content
+        #   annotation = document.annotate
+        #
+        #   entities = annotation.entities
+        #   entities.count #=> 2
+        #   entity = entities.first
+        #
+        #   entity.name #=> "Darth Vader"
+        #   entity.type #=> :PERSON
+        #   entity.salience #=> 0.8421939611434937
+        #   entity.mentions.count #=> 1
+        #   entity.mentions.first.text # => "Darth Vader"
+        #   entity.mentions.first.offset # => 0
+        #   entity.wikipedia_url #=> "http://en.wikipedia.org/wiki/Darth_Vader"
+        #
+        def entities
+          @entities ||= Entities.from_grpc @grpc
+        end
+
+        ##
+        # The result of sentiment analysis.
+        #
+        # @return [Sentiment]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   language = gcloud.language
+        #
+        #   content = "Darth Vader is the best villain in Star Wars."
+        #   document = language.document content
+        #   annotation = document.annotate
+        #   sentiment = annotation.sentiment
+        #
+        #   sentiment.polarity #=> 1.0
+        #   sentiment.magnitude #=> 0.8999999761581421
+        #   sentiment.language #=> "en"
+        #
+        def sentiment
+          return nil if @grpc.document_sentiment.nil?
+          @sentiment ||= Sentiment.from_grpc @grpc
+        end
+
+        ##
+        # The language of the document (if not specified, the language is
+        # automatically detected). Both ISO and BCP-47 language codes are
+        # supported.
+        #
+        # @return [String] the language code
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   language = gcloud.language
+        #
+        #   content = "Darth Vader is the best villain in Star Wars."
+        #   document = language.document content
+        #   annotation = document.annotate
+        #   annotation.language #=> "en"
+        #
+        def language
+          @grpc.language
+        end
+
+        # @private
+        def to_s
+          tmplt = "(sentences: %i, tokens: %i, entities: %i," \
+                  " sentiment: %s, language: %s)"
+          format tmplt, sentences.count, tokens.count, entities.count,
+                 !sentiment.nil?, language.inspect
+        end
+
+        # @private
+        def inspect
+          "#<#{self.class.name} #{self}>"
+        end
+
+        ##
+        # @private New Annotation from a V1beta1::AnnotateTextResponse object.
+        def self.from_grpc grpc
+          new.tap { |a| a.instance_variable_set :@grpc, grpc }
+        end
+
+        ##
+        # Represents a piece of text including relative location.
+        #
+        # @attr_reader [String] text The content of the output text.
+        # @attr_reader [Integer] offset The API calculates the beginning offset
+        #   of the content in the original document according to the `encoding`
+        #   specified in the API request.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   language = gcloud.language
+        #
+        #   content = "I love dogs. I hate cats."
+        #   document = language.document content
+        #   annotation = document.annotate
+        #
+        #   text_span = annotation.sentences.last
+        #   text_span.text #=> "I hate cats."
+        #   text_span.offset #=> 13
+        #
+        class TextSpan
+          attr_reader :text, :offset
+          alias_method :content, :text
+          alias_method :begin_offset, :offset
+
+          ##
+          # @private Creates a new Token instance.
+          def initialize text, offset
+            @text   = text
+            @offset = offset
+          end
+
+          ##
+          # @private New TextSpan from a V1beta1::TextSpan object.
+          def self.from_grpc grpc
+            new grpc.content, grpc.begin_offset
+          end
+        end
+
+        ##
+        # Represents the smallest syntactic building block of the text. Returned
+        # by syntactic analysis.
+        #
+        # @attr_reader [TextSpan] text_span The token text.
+        # @attr_reader [Symbol] part_of_speech Represents part of speech
+        #   information for a token.
+        # @attr_reader [Integer] head_token_index Represents the head of this
+        #   token in the dependency tree. This is the index of the token which
+        #   has an arc going to this token. The index is the position of the
+        #   token in the array of tokens returned by the API method. If this
+        #   token is a root token, then the headTokenIndex is its own index.
+        # @attr_reader [Symbol] label The parse label for the token.
+        # @attr_reader [String] lemma [Lemma](https://en.wikipedia.org/wiki/Lemma_(morphology))
+        #   of the token.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   language = gcloud.language
+        #
+        #   content = "Darth Vader is the best villain in Star Wars."
+        #   document = language.document content
+        #   annotation = document.annotate
+        #
+        #   annotation.tokens.count #=> 10
+        #   token = annotation.tokens.first
+        #
+        #   token.text_span.text #=> "Darth"
+        #   token.text_span.offset #=> 0
+        #   token.part_of_speech #=> :NOUN
+        #   token.head_token_index #=> 1
+        #   token.label #=> :NN
+        #   token.lemma #=> "Darth"
+        #
+        class Token
+          attr_reader :text_span, :part_of_speech, :head_token_index, :label,
+                      :lemma
+
+          ##
+          # @private Creates a new Token instance.
+          def initialize text_span, part_of_speech, head_token_index, label,
+                         lemma
+            @text_span        = text_span
+            @part_of_speech   = part_of_speech
+            @head_token_index = head_token_index
+            @label            = label
+            @lemma            = lemma
+          end
+
+          def text
+            @text_span.text
+          end
+          alias_method :content, :text
+
+          def offset
+            @text_span.offset
+          end
+          alias_method :begin_offset, :offset
+
+          ##
+          # @private New Token from a V1beta1::Token object.
+          def self.from_grpc grpc
+            text_span = TextSpan.from_grpc grpc.text
+            new text_span, grpc.part_of_speech.tag,
+                grpc.dependency_edge.head_token_index,
+                grpc.dependency_edge.label, grpc.lemma
+          end
+        end
+
+        ##
+        # The entities returned by entity analysis.
+        #
+        # @attr_reader [String] language The language of the document (if not
+        #   specified, the language is automatically detected). Both ISO and
+        #   BCP-47 language codes are supported.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   language = gcloud.language
+        #
+        #   content = "Darth Vader is the best villain in Star Wars."
+        #   document = language.document content
+        #   annotation = document.annotate
+        #
+        #   entities = annotation.entities
+        #   entities.count #=> 2
+        #   entities.people.count #=> 1
+        #   entities.artwork.count #=> 1
+        #
+        class Entities < DelegateClass(::Array)
+          attr_accessor :language
+
+          ##
+          # @private Create a new Entities with an array of Entity instances.
+          def initialize entities = [], language = nil
+            super entities
+            @language = language
+          end
+
+          ##
+          # Returns the entities for which {Entity#type} is `:UNKNOWN`.
+          #
+          # @return [Array<Entity>]
+          #
+          def unknown
+            select(&:unknown?)
+          end
+
+          ##
+          # Returns the entities for which {Entity#type} is `:PERSON`.
+          #
+          # @return [Array<Entity>]
+          #
+          def people
+            select(&:person?)
+          end
+
+          ##
+          # Returns the entities for which {Entity#type} is `:LOCATION`.
+          #
+          # @return [Array<Entity>]
+          #
+          def locations
+            select(&:location?)
+          end
+          alias_method :places, :locations
+
+          ##
+          # Returns the entities for which {Entity#type} is `:ORGANIZATION`.
+          #
+          # @return [Array<Entity>]
+          #
+          def organizations
+            select(&:organization?)
+          end
+
+          ##
+          # Returns the entities for which {Entity#type} is `:EVENT`.
+          #
+          # @return [Array<Entity>]
+          #
+          def events
+            select(&:event?)
+          end
+
+          ##
+          # Returns the entities for which {Entity#type} is `:WORK_OF_ART`.
+          #
+          # @return [Array<Entity>]
+          #
+          def artwork
+            select(&:artwork?)
+          end
+
+          ##
+          # Returns the entities for which {Entity#type} is `:CONSUMER_GOOD`.
+          #
+          # @return [Array<Entity>]
+          #
+          def goods
+            select(&:good?)
+          end
+
+          ##
+          # Returns the entities for which {Entity#type} is `:OTHER`.
+          #
+          # @return [Array<Entity>]
+          #
+          def other
+            select(&:other?)
+          end
+
+          ##
+          # @private New Entities from a V1beta1::AnnotateTextResponse or
+          # V1beta1::AnalyzeEntitiesResponse object.
+          def self.from_grpc grpc
+            entities = Array(grpc.entities).map { |g| Entity.from_grpc g }
+            new entities, grpc.language
+          end
+        end
+
+        ##
+        # Represents a phrase in the text that is a known entity, such as a
+        # person, an organization, or location. The API associates information,
+        # such as salience and mentions, with entities.
+        #
+        # @attr_reader [String] name The representative name for the entity.
+        # @attr_reader [Symbol] type The type of the entity.
+        # @attr_reader [Hash<String,String>] metadata Metadata associated with
+        #   the entity. Currently, only Wikipedia URLs are provided, if
+        #   available. The associated key is "wikipedia_url".
+        # @attr_reader [Float] salience The salience score associated with the
+        #   entity in the [0, 1.0] range. The salience score for an entity
+        #   provides information about the importance or centrality of that
+        #   entity to the entire document text. Scores closer to 0 are less
+        #   salient, while scores closer to 1.0 are highly salient.
+        # @attr_reader [Array<TextSpan>] mentions The mentions of this entity in
+        #   the input document. The API currently supports proper noun mentions.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   language = gcloud.language
+        #
+        #   content = "Darth Vader is the best villain in Star Wars."
+        #   document = language.document content
+        #   annotation = document.annotate
+        #
+        #   entities = annotation.entities
+        #   entities.count #=> 2
+        #   entity = entities.first
+        #
+        #   entity.name #=> "Darth Vader"
+        #   entity.type #=> :PERSON
+        #   entity.salience #=> 0.8421939611434937
+        #   entity.mentions.count #=> 1
+        #   entity.mentions.first.text # => "Darth Vader"
+        #   entity.mentions.first.offset # => 0
+        #   entity.wikipedia_url #=> "http://en.wikipedia.org/wiki/Darth_Vader"
+        #
+        class Entity
+          attr_reader :name, :type, :metadata, :salience, :mentions
+
+          ##
+          # @private Creates a new Entity instance.
+          def initialize name, type, metadata, salience, mentions
+            @name     = name
+            @type     = type
+            @metadata = metadata
+            @salience = salience
+            @mentions = mentions
+          end
+
+          ##
+          # Returns `true` if {#type} is `:UNKNOWN`.
+          #
+          # @return [Boolean]
+          #
+          def unknown?
+            type == :UNKNOWN
+          end
+
+          ##
+          # Returns `true` if {#type} is `:PERSON`.
+          #
+          # @return [Boolean]
+          #
+          def person?
+            type == :PERSON
+          end
+
+          ##
+          # Returns `true` if {#type} is `:LOCATION`.
+          #
+          # @return [Boolean]
+          #
+          def location?
+            type == :LOCATION
+          end
+          alias_method :place?, :location?
+
+          ##
+          # Returns `true` if {#type} is `:ORGANIZATION`.
+          #
+          # @return [Boolean]
+          #
+          def organization?
+            type == :ORGANIZATION
+          end
+
+          ##
+          # Returns `true` if {#type} is `:EVENT`.
+          #
+          # @return [Boolean]
+          #
+          def event?
+            type == :EVENT
+          end
+
+          ##
+          # Returns `true` if {#type} is `:WORK_OF_ART`.
+          #
+          # @return [Boolean]
+          #
+          def artwork?
+            type == :WORK_OF_ART
+          end
+
+          ##
+          # Returns `true` if {#type} is `:CONSUMER_GOOD`.
+          #
+          # @return [Boolean]
+          #
+          def good?
+            type == :CONSUMER_GOOD
+          end
+
+          ##
+          # Returns `true` if {#type} is `:OTHER`.
+          #
+          # @return [Boolean]
+          #
+          def other?
+            type == :OTHER
+          end
+
+          ##
+          # Returns the `wikipedia_url` property of the {#metadata}.
+          #
+          # @return [String]
+          #
+          def wikipedia_url
+            metadata["wikipedia_url"]
+          end
+
+          ##
+          # @private New Entity from a V1beta1::Entity object.
+          def self.from_grpc grpc
+            metadata = Core::GRPCUtils.map_to_hash grpc.metadata
+            mentions = Array(grpc.mentions).map do |g|
+              TextSpan.from_grpc g.text
+            end
+            new grpc.name, grpc.type, metadata, grpc.salience, mentions
+          end
+        end
+
+        ##
+        # Represents the result of sentiment analysis.
+        #
+        # @attr_reader [Float] polarity Polarity of the sentiment in the
+        #   [-1.0, 1.0] range. Larger numbers represent more positive
+        #   sentiments.
+        # @attr_reader [Float] magnitude A non-negative number in the [0, +inf]
+        #   range, which represents the absolute magnitude of sentiment
+        #   regardless of polarity (positive or negative).
+        # @attr_reader [String] language The language of the document (if not
+        #   specified, the language is automatically detected). Both ISO and
+        #   BCP-47 language codes are supported.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   language = gcloud.language
+        #
+        #   content = "Darth Vader is the best villain in Star Wars."
+        #   document = language.document content
+        #   annotation = document.annotate
+        #
+        #   sentiment = annotation.sentiment
+        #   sentiment.polarity #=> 1.0
+        #   sentiment.magnitude #=> 0.8999999761581421
+        #   sentiment.language #=> "en"
+        #
+        class Sentiment
+          attr_reader :polarity, :magnitude, :language
+
+          ##
+          # @private Creates a new Sentiment instance.
+          def initialize polarity, magnitude, language
+            @polarity  = polarity
+            @magnitude = magnitude
+            @language  = language
+          end
+
+          ##
+          # @private New Sentiment from a V1beta1::AnnotateTextResponse or
+          # V1beta1::AnalyzeSentimentResponse object.
+          def self.from_grpc grpc
+            new grpc.document_sentiment.polarity,
+                grpc.document_sentiment.magnitude, grpc.language
+          end
+        end
+      end
+    end
+  end
+end