[63415] Neural API support for Python SDK

[mrashed-dev]

Description

This PR brings support for the Nylas Neural API. The Neural API exposes endpoints that perform intelligent analysis on items in your Nylas account. This change will enable users to access the features of the Nylas Neural API and provides some utility functions to help improve the user's workflow.

Usage

To use Sentiment Analysis:

# To perform sentiment analysis on a message, pass in the list of message ID:
message_analysis = nylas.neural.sentiment_analysis_message([MESSAGE_ID])

# To perform sentiment analysis on just text, pass in a string:
text_analysis = nylas.neural.sentiment_analysis_text("Hi, thank you so much for reaching out! We can catch up tomorrow.")

To use Signature Extraction:

const signature = nylas.neural.extract_signature([MESSAGE_ID])

# The method also accepts two optional parameters
# parseContact, a boolean for whether Nylas should parse the contact from the signature (API defaults to true)
# options, an object of options that can be enabled for the Neural endpoint, of type NeuralMessageOptions:
options = NeuralMessageOptions(
    ignore_links=False,
    ignore_images=False,
    ignore_tables=False,
    remove_conclusion_phrases=False,
    images_as_markdowns=False
)

signature = nylas.neural.extract_signature([MESSAGE_ID], true, options)

and to parse the contact and convert it to the standard Nylas contact object:

contact = signature[0].contacts.to_contact_object()

To use Clean Conversations:

convo = nylas.neural.clean_conversation([MESSAGE_ID])

# You can also pass in an object of options that can be enabled for the Neural endpoint, of type NeuralMessageOptions
convo = nylas.neural.clean_conversation([MESSAGE_ID], options);

and to extract images from the result:

convo[0].extract_images()

To use Optical Character Recognition:

ocr = nylas.neural.ocr_request(FILE_ID)

# This endpoint also supports a second, optional parameter for an array specifying the pages that the user wants analyzed:
ocr = nylas.neural.ocr_request(FILE_ID, [2, 3])

To use Categorizer

cat = nylas.neural.categorize([MESSAGE_ID])

# You can also send a request to recategorize the message:
cat = cat[0].recategorize("conversation")

License

I confirm that this contribution is made under the terms of the MIT license and that I have the authority necessary to make this contribution on behalf of its copyright owner.

[shortcut-integration]

This pull request has been linked to Clubhouse Story #63415: Neural API support for Python SDK.

[mrashed-dev]

Many Neural objects are objects that extend an existing class (such as Message), but unlike Drafts the server payload still denotes the object key as message instead of - say 'signature'. To prevent this from breaking existing functionality, we check if the class being created is the subclass of the inbound payload's object value.

[mrashed-dev]

We do this because the Neural API series of endpoints don't support the same operations as the typical Nylas API objects. Thus this allows us to extend the minimum required functionality shared by both the typical Nylas API objects and Neural API objects.

[egginsect]

Is this the restriction of the python SDK? conversation and signature can actually return list of objects.

[egginsect]

If the endpoints get more than 1 message id, it will return multiple messages

[mrashed-dev]

Oops, I did not know that. I thought from the documentation it was always 1:1. I will update the code to reflect this.

[mrashed-dev]

@egginsect I have pushed a change to reflect your comments. Does the same apply to OCR? Or does OCR only support one file ID at a time? Thanks!

[egginsect]

Yeah it takes only 1 file_id per request

[jhatch28]

Didn't review for potential bugs, just for the interface, which looks great