class QnAMaker::Client

Client instance

Constants

BASE_URL

Attributes

data_extraction_results[R]

@!attribute [r] data_extraction_results

@return [Array<String>]
knowledgebase_id[R]

@!attribute [r] knowledgebase_id

@return [String]
subscription_key[R]

@!attribute [r] subscription_key

@return [String]

Public Class Methods

create_kb(name, subscription_key, qna_pairs = [], urls = []) click to toggle source

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

# File lib/qna_maker/endpoints/create_kb.rb, line 55
def self.create_kb(name, subscription_key, qna_pairs = [], urls = [])
  response = HTTP.headers('Ocp-Apim-Subscription-Key' => subscription_key).post(
    "#{BASE_URL}/create",
    json: {
      name: name,
      qnaPairs: qna_pairs.map { |pair| { question: pair[0], answer: pair[1] } },
      urls: urls
    }
  )

  case response.code
  when 201
    QnAMaker::Client.new(
      response.parse['kbId'],
      subscription_key,
      response.parse['dataExtractionResults']
    )
  when 400
    raise BadArgumentError, response.parse['error']['message'].join(' ')
  when 401
    raise UnauthorizedError, response.parse['error']['message']
  else
    raise UnknownError, "Oh no! (#{response.code})"
  end
end
delete_kb(knowledgebase_id, subscription_key) click to toggle source

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

# File lib/qna_maker/endpoints/delete_kb.rb, line 40
def self.delete_kb(knowledgebase_id, subscription_key)
  response = HTTP.headers('Ocp-Apim-Subscription-Key' => subscription_key).delete(
    "#{BASE_URL}/#{knowledgebase_id}"
  )

  case response.code
  when 204
    nil
  when 400
    raise BadArgumentError, response.parse['error']['message'].join(' ')
  when 401
    raise UnauthorizedError, response.parse['error']['message']
  when 403
    raise ForbiddenError, response.parse['error']['message']
  when 404
    raise NotFoundError, response.parse['error']['message']
  when 409
    raise ConflictError, response.parse['error']['message']
  else
    raise UnknownError, "Oh no! (#{response.code})"
  end
end
new(knowledgebase_id, subscription_key, data_extraction_results = []) click to toggle source

<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.

# File lib/qna_maker.rb, line 45
def initialize(knowledgebase_id, subscription_key, data_extraction_results = [])
  @knowledgebase_id = knowledgebase_id
  @subscription_key = subscription_key
  @data_extraction_results = data_extraction_results
  @http = HTTP.headers('Ocp-Apim-Subscription-Key' => @subscription_key)
end

Public Instance Methods

create_kb(name, qna_pairs = [], urls = []) click to toggle source

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

# File lib/qna_maker/endpoints/create_kb.rb, line 14
def create_kb(name, qna_pairs = [], urls = [])
  response = @http.post(
    "#{BASE_URL}/create",
    json: {
      name: name,
      qnaPairs: qna_pairs.map { |pair| { question: pair[0], answer: pair[1] } },
      urls: urls
    }
  )

  case response.code
  when 201
    QnAMaker::Client.new(
      response.parse['kbId'],
      @subscription_key,
      response.parse['dataExtractionResults']
    )
  when 400
    raise BadArgumentError, response.parse['error']['message'].join(' ')
  when 401
    raise UnauthorizedError, response.parse['error']['message']
  else
    raise UnknownError, "Oh no! (#{response.code})"
  end
end
delete_kb() click to toggle source

Deletes the current knowledge base and all data associated with it.

@return [nil] on success

# File lib/qna_maker/endpoints/delete_kb.rb, line 8
def delete_kb
  response = @http.delete(
    "#{BASE_URL}/#{knowledgebase_id}"
  )

  case response.code
  when 204
    nil
  when 400
    raise BadArgumentError, response.parse['error']['message'].join(' ')
  when 401
    raise UnauthorizedError, response.parse['error']['message']
  when 403
    raise ForbiddenError, response.parse['error']['message']
  when 404
    raise NotFoundError, response.parse['error']['message']
  when 409
    raise ConflictError, response.parse['error']['message']
  else
    raise UnknownError, "Oh no! (#{response.code})"
  end
end
download_alterations() click to toggle source

Downloads all word alterations (synonyms) that have been automatically

mined or added by the user.

@return [Array<Alteration>] list of alterations

# File lib/qna_maker/endpoints/download_alterations.rb, line 9
def download_alterations
  response = @http.get(
    "#{BASE_URL}/#{@knowledgebase_id}/downloadAlterations"
  )

  case response.code
  when 200
    response.parse['wordAlterations'].map do |alteration|
      Alteration.new(
        alteration['word'].normalize,
        alteration['alterations'].map(&:normalize)
      )
    end
  when 400
    raise BadArgumentError, response.parse['error']['message'].join(' ')
  when 401
    raise UnauthorizedError, response.parse['error']['message']
  when 403
    raise ForbiddenError, response.parse['error']['message']
  when 404
    raise NotFoundError, response.parse['error']['message']
  else
    raise UnknownError, "Oh no! (#{response.code})"
  end
end
download_kb() click to toggle source

Downloads all the data associated with the specified knowledge base

@return [String] SAS url (valid for 30 mins) to tsv file in blob storage

# File lib/qna_maker/endpoints/download_kb.rb, line 8
def download_kb
  response = @http.get(
    "#{BASE_URL}/#{@knowledgebase_id}"
  )

  case response.code
  when 200
    response.parse
  when 400
    raise BadArgumentError, response.parse['error']['message'].join(' ')
  when 401
    raise UnauthorizedError, response.parse['error']['message']
  when 403
    raise ForbiddenError, response.parse['error']['message'].join(' ')
  when 404
    raise NotFoundError, response.parse['error']['message'].join(' ')
  else
    raise UnknownError, "Oh no! (#{response.code})"
  end
end
generate_answer(question, top = 1) click to toggle source

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.
# File lib/qna_maker/endpoints/generate_answer.rb, line 14
def generate_answer(question, top = 1)
  response = @http.post(
    "#{BASE_URL}/#{@knowledgebase_id}/generateAnswer",
    json: { question: question, top: top }
  )

  case response.code
  when 200
    response.parse['answers'].map do |answer|
      Answer.new(
        answer['answer'].normalize,
        answer['questions'].map(&:normalize),
        answer['score']
      )
    end
  when 400
    raise BadArgumentError, response.parse['error']['message'].join(' ')
  when 401
    raise UnauthorizedError, response.parse['error']['message']
  when 403
    raise QuotaExceededError, response.parse['error']['message']
  when 404
    raise NotFoundError, response.parse['error']['message']
  when 408
    raise OperationTimeOutError, response.parse['error']['message']
  when 429
    raise RateLimitExceededError, response.parse['error']['message']
  else
    raise UnknownError, "Oh no! (#{response.code})"
  end
end
publish_kb() click to toggle source

Publish all unpublished in the knowledgebase to the prod endpoint

@return [nil] on success

# File lib/qna_maker/endpoints/publish_kb.rb, line 8
def publish_kb
  response = @http.put(
    "#{BASE_URL}/#{@knowledgebase_id}"
  )

  case response.code
  when 204
    nil
  when 400
    raise BadArgumentError, response.parse['error']['message'].join(' ')
  when 401
    raise UnauthorizedError, response.parse['error']['message']
  when 403
    raise ForbiddenError, response.parse['error']['message']
  when 404
    raise NotFoundError, response.parse['error']['message']
  when 409
    raise ConflictError, response.parse['error']['message']
  else
    raise UnknownError, "Oh no! (#{response.code})"
  end
end
train_kb(feedback_records = []) click to toggle source

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

# File lib/qna_maker/endpoints/train_kb.rb, line 14
def train_kb(feedback_records = [])
  feedback_records = feedback_records.map do |record|
    { userId: record[0],
      userQuestion: record[1],
      kbQuestion: record[2],
      kbAnswer: record[3] }
  end
  response = @http.patch(
    "#{BASE_URL}/#{@knowledgebase_id}/train",
    json: { feedbackRecords: feedback_records }
  )

  case response.code
  when 204
    nil
  when 400
    raise BadArgumentError, response.parse['error']['message'].join(' ')
  when 401
    raise UnauthorizedError, response.parse['error']['message']
  when 403
    raise ForbiddenError, response.parse['error']['message']
  when 404
    raise NotFoundError, response.parse['error']['message']
  when 408
    raise OperationTimeOutError, response.parse['error']['message']
  when 429
    raise RateLimitExceededError, response.parse['error']['message']
  else
    raise UnknownError, "Oh no! (#{response.code})"
  end
end
update_alterations(add = [], delete = []) click to toggle source

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

# File lib/qna_maker/endpoints/update_alterations.rb, line 11
def update_alterations(add = [], delete = [])
  response = @http.patch(
    "#{BASE_URL}/#{@knowledgebase_id}/updateAlterations",
    json: { add: add.map {|i| {word: i[0], alterations: i[1]} },
    delete: delete.map {|i| {word: i[0], alterations: i[1]} } }
  )

  case response.code
  when 204
    nil
  when 400
    raise BadArgumentError, response.parse['error']['message'].join(' ')
  when 401
    raise UnauthorizedError, response.parse['error']['message']
  when 403
    raise ForbiddenError, response.parse['error']['message']
  when 404
    raise NotFoundError, response.parse['error']['message']
  when 409
    raise ConflictError, response.parse['error']['message']
  else
    raise UnknownError, "Oh no! (#{response.code})"
  end
end
update_kb(add: [], delete: [], add_urls: []) click to toggle source

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

# File lib/qna_maker/endpoints/update_kb.rb, line 12
def update_kb(add: [], delete: [], add_urls: [])
  response = @http.patch(
    "#{BASE_URL}/#{@knowledgebase_id}",
    json: {
      add: {
        qnaPairs: add.map { |pair| { question: pair[0], answer: pair[1] } },
        urls: add_urls
      },
      delete: { qnaPairs: delete.map { |pair| { question: pair[0], answer: pair[1] } } }
    }
  )

  case response.code
  when 204
    nil
  when 400
    raise BadArgumentError, response.parse['error']['message'].join(' ')
  when 401
    raise UnauthorizedError, response.parse['error']['message']
  when 403
    raise ForbiddenError, response.parse['error']['message']
  when 404
    raise NotFoundError, response.parse['error']['message']
  when 409
    raise ConflictError, response.parse['error']['message']
  else
    raise UnknownError, "Oh no! (#{response.code})"
  end
end