qna_maker 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ee955956af27b2b001676c32496cd94f4c89db0ee3bd7c5d3717c22e955209e
-  data.tar.gz: e664c1ac7c731bbf5aa0c6fd9c81603674a489824fa1cdd475d123f6deade505
+  metadata.gz: 29492e8b4bfac09cf1e52269c608dba416a723e2d6738e5b0b41377a21798935
+  data.tar.gz: 7789f79de95d5996c3809a2b34ebb134ac9097451e3e19166d4d7bb63e425686
 SHA512:
-  metadata.gz: 6ee21db904abbf80f6eb34edb3d9da0ffc19e4f7bb47e5ff846c137b874b7286857b63fae99913aaac388830d411e317ad54daf64aecf66c4f2de7823661b469
-  data.tar.gz: 1c0785b5c633dc95f3c32aa4af42bd42a9f53885a2b22c0473b661c58bf8d44bfb14783dab92027c61118405c58f95b7d5ec65c5bae9b43f232e99213efff977
+  metadata.gz: 4d1f018e0be2926afc882e26a099b04edcce677d85588bbbea8d722365bf1ab0d25d56c4230c03c48ba72e6cce802ceb39d9c6f69046ac26d3676504c51678fc
+  data.tar.gz: 808612670bdbcdf03972db62f1f082d1e78f575889a4e85c55985f70e71069c0604b86f1ff90323bdd9ce4cf89fb4a939d2ff16e86cf764bb14500c4d0a00a66

data/README.md

@@ -1,11 +1,15 @@
 # QnAMaker
 
-![Gem](https://img.shields.io/gem/dv/qna_maker/stable.svg)
+[![Gem](https://img.shields.io/gem/v/qna_maker.svg)](https://rubygems.org/gems/qna_maker)
+[![Gem](https://img.shields.io/gem/dt/qna_maker.svg)](https://rubygems.org/gems/qna_maker)
 [![Build Status](https://travis-ci.org/Birdie0/qna_maker.svg?branch=master)](https://travis-ci.org/Birdie0/qna_maker)
-[![Maintainability](https://api.codeclimate.com/v1/badges/96bf3ebcfe21cd1b9359/maintainability)](https://codeclimate.com/github/Birdie0/qna_maker/maintainability)
+[![Inline docs](https://inch-ci.org/github/Birdie0/qna_maker.svg?branch=master&style=shields)](https://inch-ci.org/github/Birdie0/qna_maker)
+[![Maintainability](https://codeclimate.com/github/Birdie0/qna_maker/badges/gpa.svg)](https://codeclimate.com/github/Birdie0/qna_maker/maintainability)
 
 API wrapper for [QnA Maker](https://qnamaker.ai)
 
+## [QnA API docs](https://westus.dev.cognitive.microsoft.com/docs/services/58994a073d9e04097c7ba6fe)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -53,7 +57,7 @@ Gem is under active development! It isn't finished yet!
   * [x] **PATCH** - Train Knowledge Base
   * [x] **PATCH** - Update Alterations
   * [x] **PATCH** - Update Knowledge Base
-* [ ] Documentation
+* [x] Documentation
 * [ ] Tests
 
 ## Development

data/bin/setup

@@ -1,8 +1,7 @@
 #!/usr/bin/env bash
+
 set -euo pipefail
 IFS=$'\n\t'
 set -vx
 
 bundle install
-
-# Do any other automated setup that you need to do here

data/lib/qna_maker.rb

@@ -18,11 +18,30 @@ require 'qna_maker/endpoints/update_alterations'
 require 'http'
 
 module QnAMaker
+  #
+  # Client instance
+  #
   class Client
     BASE_URL = 'https://westus.api.cognitive.microsoft.com/QnAMaker/v2.0/knowledgebases'.freeze
 
-    attr_reader :knowledgebase_id, :subscription_key, :data_extraction_results
+    # @!attribute [r] knowledgebase_id
+    #   @return [String]
+    attr_reader :knowledgebase_id
+    # @!attribute [r] subscription_key
+    #   @return [String]
+    attr_reader :subscription_key
+    # @!attribute [r] data_extraction_results
+    #   @return [Array<String>]
+    attr_reader :data_extraction_results
 
+    #
+    # <Description>
+    #
+    # @param [String] knowledgebase_id this should be get from QnAMaker portal
+    # @param [String] subscription_key QnAMaker::Client provides access to
+    #   this API. Found in your QnAMaker Service accounts (https://qnamaker.ai
+    # @param [Array<Hash{String => String, String => String, String => String}>] data_extraction_results ata extraction results.
+    #
     def initialize(knowledgebase_id, subscription_key, data_extraction_results = [])
       @knowledgebase_id = knowledgebase_id
       @subscription_key = subscription_key

data/lib/qna_maker/alteration.rb

@@ -1,7 +1,21 @@
 module QnAMaker
+  #
+  # Alteration class
+  #
   class Alteration
-    attr_reader :word, :alterations
+    # @!attribute [r] word
+    #   @return [String] word of alteration
+    attr_reader :word
+    # @!attribute [r] alterations
+    #   @return [Array<Alteration>] list of alterations for word
+    attr_reader :alterations
 
+    #
+    # Creates an object for alteration.
+    #
+    # @param [String] word
+    # @param [Array<Alteration>] alterations list of alterations
+    #
     def initialize(word, alterations)
       @word = word
       @alterations = alterations

data/lib/qna_maker/answer.rb

@@ -1,7 +1,17 @@
 module QnAMaker
+  #
+  # Answer class
+  #
   class Answer
     attr_reader :answer, :questions, :score
 
+    #
+    # Creates an object for storing data about answer.
+    #
+    # @param [String] answer text
+    # @param [Array<String>] questions list of questions for asked question
+    # @param [Float] score probability that answer suits asked question
+    #
     def initialize(answer, questions, score)
       @answer = answer
       @questions = questions

data/lib/qna_maker/endpoints/create_kb.rb

@@ -1,5 +1,16 @@
 module QnAMaker
   class Client
+    #
+    # Creates a new knowledge base.
+    #
+    # @param [String] name friendly name for the knowledge base (Required)
+    # @param [Array<Array(String, String)>] qna_pairs list of question and answer pairs to be added to the knowledge base.
+    #   Max 1000 Q-A pairs per request.
+    # @param [Array<String>] urls list of URLs to be processed and indexed in the knowledge base.
+    #   In case of existing URL, it will be fetched again and KB will be updated with new data. Max 5 urls per request.
+    #
+    # @return [Client] client object
+    #
     def create_kb(name, qna_pairs = [], urls = [])
       response = @http.post(
         "#{BASE_URL}/create",
@@ -12,7 +23,7 @@ module QnAMaker
 
       case response.code
       when 201
-        QnA.new(
+        QnAMaker::Client.new(
           response.parse['kbId'],
           @subscription_key,
           response.parse['dataExtractionResults']
@@ -26,6 +37,21 @@ module QnAMaker
       end
     end
 
+    #
+    # Creates a new knowledge base.
+    #
+    # @param [String] name friendly name for the knowledge base (Required)
+    # @param [String] subscription_key Subscription key which provides access to
+    #   this API. Found in your QnAMaker Service accounts (https://qnamaker.ai)
+    # @param [Array<Array(String, String)>] qna_pairs list of question and
+    #   answer pairs to be added to the knowledge base. Max 1000 Q-A pairs per
+    #   request.
+    # @param [Array<String>] urls list of URLs to be processed and indexed in
+    #   the knowledge base. In case of existing URL, it will be fetched again
+    # and KB will be updated with new data. Max 5 urls per request.
+    #
+    # @return [Client] client object
+    #
     def self.create_kb(name, subscription_key, qna_pairs = [], urls = [])
       response = HTTP.headers('Ocp-Apim-Subscription-Key' => subscription_key).post(
         "#{BASE_URL}/create",
@@ -38,7 +64,7 @@ module QnAMaker
 
       case response.code
       when 201
-        QnA.new(
+        QnAMaker::Client.new(
           response.parse['kbId'],
           subscription_key,
           response.parse['dataExtractionResults']

data/lib/qna_maker/endpoints/delete_kb.rb

@@ -1,5 +1,10 @@
 module QnAMaker
   class Client
+    #
+    # Deletes the current knowledge base and all data associated with it.
+    #
+    # @return [nil] on success
+    #
     def delete_kb
       response = @http.delete(
         "#{BASE_URL}/#{knowledgebase_id}"
@@ -23,6 +28,15 @@ module QnAMaker
       end
     end
 
+    #
+    # Deletes the specified knowledge base and all data associated with it.
+    #
+    # @param [String] knowledgebase_id knowledge base identity
+    # @param [String] subscription_key Subscription key which provides access to
+    #   this API. Found in your QnAMaker Service accounts (https://qnamaker.ai)
+    #
+    # @return [nil] on success
+    #
     def self.delete_kb(knowledgebase_id, subscription_key)
       response = HTTP.headers('Ocp-Apim-Subscription-Key' => subscription_key).delete(
         "#{BASE_URL}/#{knowledgebase_id}"

data/lib/qna_maker/endpoints/download_alterations.rb

@@ -1,5 +1,11 @@
 module QnAMaker
   class Client
+    #
+    # Downloads all word alterations (synonyms) that have been automatically
+    #   mined or added by the user.
+    #
+    # @return [Array<Alteration>] list of alterations
+    #
     def download_alterations
       response = @http.get(
         "#{BASE_URL}/#{@knowledgebase_id}/downloadAlterations"

data/lib/qna_maker/endpoints/download_kb.rb

@@ -1,5 +1,10 @@
 module QnAMaker
   class Client
+    #
+    # Downloads all the data associated with the specified knowledge base
+    #
+    # @return [String] SAS url (valid for 30 mins) to tsv file in blob storage
+    #
     def download_kb
       response = @http.get(
         "#{BASE_URL}/#{@knowledgebase_id}"

data/lib/qna_maker/endpoints/generate_answer.rb

@@ -1,5 +1,16 @@
 module QnAMaker
   class Client
+    #
+    # Returns the list of answers for the given question sorted in descending
+    # order of ranking score.
+    #
+    # @param [String] question user question to be queried against your
+    #   knowledge base.
+    # @param [Integer] top number of ranked results you want in the output.
+    #
+    # @return [Array<Answer>] list of answers for the user query sorted in
+    #   decreasing order of ranking score.
+    #
     def generate_answer(question, top = 1)
       response = @http.post(
         "#{BASE_URL}/#{@knowledgebase_id}/generateAnswer",

data/lib/qna_maker/endpoints/publish_kb.rb

@@ -1,5 +1,10 @@
 module QnAMaker
   class Client
+    #
+    # Publish all unpublished in the knowledgebase to the prod endpoint
+    #
+    # @return [nil] on success
+    #
     def publish_kb
       response = @http.put(
         "#{BASE_URL}/#{@knowledgebase_id}"

data/lib/qna_maker/endpoints/train_kb.rb

@@ -1,5 +1,16 @@
 module QnAMaker
   class Client
+    #
+    # The developer of the knowledge base service can use this API to submit
+    # user feedback for tuning question-answer matching. QnA Maker uses active
+    # learning to learn from the user utterances that come on a published
+    # Knowledge base service.
+    #
+    # @param [Array<Array(String, String, String, String)>] feedback_records
+    #   \[user_id, user_question, kb_question, kb_answer]
+    #
+    # @return [nil] on success
+    #
     def train_kb(feedback_records = [])
       feedback_records = feedback_records.map do |record|
         { userId: record[0],

data/lib/qna_maker/endpoints/update_alterations.rb

@@ -1,9 +1,18 @@
 module QnAMaker
   class Client
+    #
+    # Replaces word alterations (synonyms) for the KB with the give records.
+    #
+    # @param [Array(String, Array<String>)] add word alterations to be added
+    # @param [Array(String, Array<String>)] delete word alterations to be removed
+    #
+    # @return [nil] on success
+    #
     def update_alterations(add = [], delete = [])
       response = @http.patch(
         "#{BASE_URL}/#{@knowledgebase_id}/updateAlterations",
-        json: { add: add, delete: delete }
+        json: { add: add.map {|i| {word: i[0], alterations: i[1]} },
+        delete: delete.map {|i| {word: i[0], alterations: i[1]} } }
       )
 
       case response.code

data/lib/qna_maker/endpoints/update_kb.rb

@@ -1,6 +1,15 @@
 module QnAMaker
   class Client
-    def update_kb(add = [], delete = [], add_urls = [])
+    #
+    # Add or delete QnA Pairs and / or URLs to an existing knowledge base.
+    #
+    # @param [Array<Array(String, String)>] add \[question, answer\] data to be added to the knowledge base.
+    # @param [Array<Array(String, String)>] delete \[question, answer\] data to be removed to the knowledge base.
+    # @param [Array<String>] add_urls list of URLs to be processed and indexed in the knowledge base.
+    #
+    # @return [nil] on success
+    #
+    def update_kb(add: [], delete: [], add_urls: [])
       response = @http.patch(
         "#{BASE_URL}/#{@knowledgebase_id}",
         json: {

data/lib/qna_maker/errors.rb

@@ -1,28 +1,31 @@
 module QnAMaker
-  class BadArgumentError < StandardError
+  class Error < StandardError
   end
 
-  class NotFoundError < StandardError
+  class BadArgumentError < Error
   end
 
-  class UnauthorizedError < StandardError
+  class NotFoundError < Error
   end
 
-  class QuotaExceededError < StandardError
+  class UnauthorizedError < Error
   end
 
-  class OperationTimeOutError < StandardError
+  class QuotaExceededError < Error
   end
 
-  class RateLimitExceededError < StandardError
+  class OperationTimeOutError < Error
   end
 
-  class ConflictError < StandardError
+  class RateLimitExceededError < Error
   end
 
-  class ForbiddenError < StandardError
+  class ConflictError < Error
   end
 
-  class UnknownError < StandardError
+  class ForbiddenError < Error
+  end
+
+  class UnknownError < Error
   end
 end

data/lib/qna_maker/string.rb

@@ -2,7 +2,15 @@ require 'htmlentities'
 
 CODER = HTMLEntities.new
 
+#
+# Monkey-patched String method for fixing responses.
+#
 class String
+  #
+  # Fixes <, & and other &'s characters, replaces crlf to lf newlines.
+  #
+  # @return [String] same text with correctly displayed &xxxx; characters and lf newlines.
+  #
   def normalize
     CODER.decode(self).gsub(/\r\n?/, "\n")
   end

data/lib/qna_maker/version.rb

@@ -1,3 +1,3 @@
 module QnAMaker
-  VERSION = '0.2.0'.freeze
+  VERSION = '0.3.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: qna_maker
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Birdie0
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-04-11 00:00:00.000000000 Z
+date: 2018-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: htmlentities