cape.client package

Module contents

Cape API client module.

This module provides a python interface to the Cape API: http://thecape.ai

class cape.client.CapeClient(api_base='https://responder.thecape.ai/api', admin_token=None)

The CapeClient provides access to all methods of the Cape API.

add_annotation(question, answer, document_id, start_offset=None, end_offset=None, metadata=None)

Create a new annotation for a specified document.

Annotations are made up of a pair consisting of a canonical question, the response it should produce and a location within a specific document that this answer corresponds to.

In addition to the canonical question an annotation may have many paraphrased questions associated with it which should produce the same answer (e.g. “How old are you?” vs “What is your age?”).

Parameters:
  • question – The question this annotation relates to.
  • answer – The answer to reply with when the question is asked.
  • document_id – The document which this annotation corresponds to.
  • start_offset – The starting location of the annotation within the specified document.
  • end_offset – The ending location of the annotation within the specified document.
  • metadata – A dictionary containing user definable metadata about this annotation.
Returns:

The IDs of the new annotation and answer.
add_annotation_answer(annotation_id, answer)

Add a new answer to an existing annotation.

Parameters:
  • annotation_id – The ID of the annotation to add this answer to.
  • answer – The answer to add to the annotation.
Returns:

The ID of the answer that was created.
add_annotation_paraphrase_question(annotation_id, question)

Add a new paraphrase question to an existing annotation.

Parameters:
  • annotation_id – The ID of the annotation to add this question to.
  • question – The new paraphrase of this annotation’s canonical question.
Returns:

The ID of the new question.
add_answer(reply_id, answer)

Add a new answer to an existing saved reply.

Parameters:
  • reply_id – The ID of the saved reply to add this answer to.
  • answer – A new answer to add to the saved reply.
Returns:

The ID of the newly created answer.
add_document(title, text=None, file_path=None, document_id='', origin='', replace=False, document_type=None, monitor_callback=None)

Create a new document or replace an existing document.

Parameters:
  • title – The title to give the new document.
  • text – The plain text contents of the document (either text or file_path must be supplied).
  • file_path – A file to upload (either text or file_path must be supplied).
  • document_id – The ID to give the new document (Default: An SHA256 hash of the document contents).
  • origin – Where the document came from.
  • replace – If true and a document already exists with the same document ID it will be overwritten with the new upload. If false an error is returned when a document ID already exists.
  • document_type – Whether this document was created by inputting text or uploading a file (if not set this will be automatically determined).
  • monitor_callback – A method to call with updates on the file upload progress.
Returns:

The ID of the uploaded document.
add_paraphrase_question(reply_id, question)

Add a new paraphrase question to an existing saved reply.

Parameters:
  • reply_id – The ID of the saved reply to add this question to.
  • question – The new paraphrase of this saved reply’s canonical question.
Returns:

The ID of the new question.
add_saved_reply(question, answer)

Create a new saved reply.

Saved replies are made up of a pair consisting of a canonical question and the response it should produce. In addition to the canonical question a saved reply may have many paraphrased questions associated with it which should produce the same answer (e.g. “How old are you?” vs “What is your age?”).

Parameters:
  • question – The question this saved reply relates to.
  • answer – The answer to reply with when the question is asked.
Returns:

The IDs of the new saved reply and answer.
answer(question, user_token=None, threshold=None, document_ids=None, source_type='all', speed_or_accuracy='balanced', number_of_items=1, offset=0, text=None)

Provide a list of answers to a given question.

Parameters:
  • question – The question to ask.
  • user_token – A token retrieved from get_user_token (Default: the token for the currently authenticated user).
  • threshold – The minimum confidence of answers to return (‘verylow’/’low’/’medium’/’medium’/’veryhigh’).
  • document_ids – A list of documents to search for answers (Default: all documents).
  • source_type – Whether to search documents, saved replies or all (‘document’/’saved_reply’/’all’).
  • speed_or_accuracy – Prioritise speed or accuracy in answers (‘speed’/’accuracy’/’balanced’).
  • number_of_items – The number of answers to return.
  • offset – The starting point in the list of answers, used in conjunction with number_of_items to retrieve multiple batches of answers.
  • text – An inline text to be treated as a document with id “Inline Text”.
Returns:

A list of answers.
archive_inbox(inbox_id)

Archive an inbox item.

Parameters:inbox_id – The inbox item to archive.
Returns:The ID of the inbox item that was archived.
delete_annotation(annotation_id)

Delete an annotation.

Parameters:annotation_id – The ID of the annotation to delete.
Returns:The ID of the annotation that was deleted.
delete_annotation_answer(answer_id)

Delete an answer from an annotation.

At least one answer must remain associated with an annotation.

Parameters:answer_id – The answer to delete
Returns:The ID of the answer that was deleted
delete_annotation_paraphrase_question(question_id)

Delete an annotation’s paraphrase question.

Parameters:question_id – The ID of the question to delete.
Returns:The ID of the question that was deleted.
delete_answer(answer_id)

Delete an existing an answer.

Parameters:answer_id – The ID of the answer to delete.
Returns:The ID of the answer that was deleted.
delete_document(document_id)

Delete a document.

Parameters:document_id – The ID of the document to delete.
Returns:The ID of the document that was deleted.
delete_paraphrase_question(question_id)

Delete a paraphrase question.

Parameters:question_id – The ID of the paraphrase question to delete.
Returns:The ID of the paraphrase question that was deleted.
delete_saved_reply(reply_id)

Delete a saved reply.

Parameters:reply_id – The ID of the saved reply to delete.
Returns:The ID of the saved reply that was deleted.
edit_annotation_answer(answer_id, answer)

Edit an annotation’s answer.

Parameters:
  • answer_id – The ID of the answer to edit.
  • answer – The new text to be used for this answer.
Returns:

The ID of the answer that was edited.
edit_annotation_canonical_question(annotation_id, question)

Edit the canonical question of an annotation.

Parameters:
  • annotation_id – The ID of the annotation to edit.
  • question – The new canonical question for this annotation.
Returns:

The ID of the annotation that was edited.
edit_annotation_paraphrase_question(question_id, question)

Modify an existing paraphrase question in an annotation.

Parameters:
  • question_id – The ID of the question to modify.
  • question – The modified question text.
Returns:

The ID of the question that was modified.
edit_answer(answer_id, answer)

Modify an existing answer.

Parameters:
  • answer_id – The ID of the answer to edit.
  • answer – The modified answer text.
Returns:

The ID of the answer that was modified.
edit_canonical_question(reply_id, question)

Modify the canonical question belonging to a saved reply.

Parameters:
  • reply_id – The ID of the saved reply to modify the canonical question of.
  • question – The modified question text.
Returns:

The ID of the saved reply that was modified.
edit_paraphrase_question(question_id, question)

Modify an existing paraphrase question.

Parameters:
  • question_id – The ID of the question to modify.
  • question – The modified question text.
Returns:

The ID of the question that was modified.
get_admin_token()

Retrieve the admin token for the currently logged in user.

Returns:An admin token.
get_annotations(search_term='', annotation_ids=None, document_ids=None, pages=None, number_of_items=30, offset=0)

Retrieve a list of annotations.

Parameters:
  • search_term – Filter annotations based on whether they contain the search term.
  • annotation_ids – A list of annotations to return/search within (Default: all annotations).
  • document_ids – A list of documents to return annotations from (Default: all documents).
  • pages – A list of pages to return annotations from (Default: all pages).
  • number_of_items – The number of annotations to return.
  • offset – The starting point in the list of annotations, used in conjunction with number_of_tems to retrieve multiple batches of annotations.
Returns:

A list of annotations.
get_default_threshold()

Retrieve the default threshold used if one isn’t explicitly specified when calling answer().

Returns:The current default threshold (either ‘verylow’, ‘low’, ‘medium’, ‘high’ or ‘veryhigh’).
get_documents(document_ids=None, number_of_items=30, offset=0)

Retrieve this user’s documents.

Parameters:
  • document_ids – A list of documents to return.
  • number_of_items – The number of documents to return.
  • offset – The starting point in the list of documents, used in conjunction with number_of_items to retrieve multiple batches of documents.
Returns:

A list of documents in reverse chronological order (newest first).
get_inbox(read='both', answered='both', search_term='', number_of_items=30, offset=0)

Retrieve the items in the current user’s inbox.

Parameters:
  • read – Filter messages based on whether they have been read.
  • answered – Filter messages based on whether they have been answered.
  • search_term – Filter messages based on whether they contain the search term.
  • number_of_items – The number of inbox items to return.
  • offset – The starting point in the list of inbox items, used in conjunction with number_of_tems to retrieve multiple batches of inbox items.
Returns:

A list of inbox items in reverse chronological order (newest first).
get_profile()

Retrieve the current user’s profile.

Returns:A dictionary containing the user’s profile.
get_saved_replies(search_term='', saved_reply_ids=None, number_of_items=30, offset=0)

Retrieve a list of saved replies.

Parameters:
  • search_term – Filter saved replies based on whether they contain the search term.
  • saved_reply_ids – List of saved reply IDs to return.
  • number_of_items – The number of saved replies to return.
  • offset – The starting point in the list of saved replies, used in conjunction with number_of_tems to retrieve multiple batches of saved replies.
Returns:

A list of saved replies in reverse chronological order (newest first).
get_user_token()

Retrieve a user token suitable for making ‘answer’ requests.

Returns:A user token.
logged_in()

Reports whether we’re currently logged in.

Returns:Whether we’re logged in or not.
login(login, password)

Log in to the Cape API as an AI builder.

Parameters:
  • login – The username to log in with.
  • password – The password to log in with.
Returns:
logout()

Log out and clear the current session cookie.

Returns:
mark_inbox_read(inbox_id)

Mark an inbox item as having been read.

Parameters:inbox_id – The inbox item to mark as being read.
Returns:The ID of the inbox item that was marked as read.
set_default_threshold(threshold)

Set the default threshold used if one isn’t explicitly specified when calling answer().

Parameters:threshold – The new default threshold to set, must be either ‘verylow’, ‘low’, ‘medium’, ‘high’ or ‘veryhigh’.
Returns:The new default threshold that’s just been set.
set_forward_email(email)

Set the email address that emails which couldn’t be answered automatically are forwarded to.

Parameters:email – The new forward email address to set.
Returns:The new forward email address that’s just been set.