​Turn.io Integration

This document provides a overview of Lelapa.ai functions available for integration within Turn.io. These functions expose Vulavula's Natural Language Processing (NLP) capabilities, allowing developers to enhance Turn.io applications with intelligent text processing features.

Prerequisites:

• A Vulavula API Key is required. Obtain it at Vulavula Platform.
• Familiarity with Turn.io platform and its code block functionality.

​Function Details:

All Lelapa.ai functions operate within Turn.io code blocks and require a connection object (conn) established using lelapa_connect().

​1. lelapa_connect(token)

Description:

This function establishes a persistent connection to the Lelapa.ai API using the provided API token. It handles authentication and sets up the necessary context for subsequent Lelapa.ai function calls.

Input Parameters:

• token (String): Your Lelapa.ai API token obtained from your Lelapa.ai account.

Return Value:

• conn (Object): A connection object. This object must be passed as the first argument to all other Lelapa.ai functions. The specific structure of this object is opaque to the Turn.io user and should be treated as a connection handle.

Error Handling:

• Incorrect or invalid tokens will likely result in a connection error. Turn.io code blocks should handle potential errors during connection establishment.

Code Example (Turn.io Start Node):

card Start do
  conn = lelapa_connect("YOUR_LELAPA_API_TOKEN")
  if conn == nil do
    say("Error connecting to Lelapa.ai. Please check your token.")
    stop()
  end
end

​2. lelapa_intent_classification(conn, text, intents)

Description:

This function utilizes Lelapa.ai's Intent Classification API to classify the text based on a provided list of intents. It employs a minimal-training approach, allowing for effective classification with limited examples.

Input Parameters:

• conn (Object): The connection object returned by lelapa_connect().
• text (String): The input text to be classified (e.g., user message).
• intents (List of Lists): A list defining intents and their example phrases. Each inner list has the format: ["intent_name", "example_phrase"].

Return Value:

• result (Map): A map containing the classification result. Structure:

  %{
    "__value__" => "intent_name",  // String:  The highest matched intent name
    "score" => 0.xxxx,            // Float:  Confidence score of the matched intent (0.0 to 1.0)
    "intent" => "intent_name"       // String:  Redundant key, same as "__value__"
  }

  plain

Data Types:

• text: String
• intents: List<List<String>>
• result: Map<String, String | Float>

Code Example (Turn.io Code Block):

card ClassifyIntent do
  user_message = params[:message] # Assuming user message is in params[:message]
  intents_list = [
    ["greeting", "Hello!"],
    ["greeting", "Hi there!"],
    ["goodbye", "Goodbye!"],
    ["goodbye", "See you later!"]
  ]

  classification_result = lelapa_intent_classification(conn, user_message, intents_list)

  if classification_result != nil do # Check for potential errors
    intent = classification_result["intent"]
    score = classification_result["score"]
    say("Detected intent: #{intent} with score: #{score}")
    # Logic based on intent (e.g., route to different flows)
  else
    say("Intent classification failed.") # Handle potential API errors
  end
end

​3. lelapa_entity_recognition(conn, text)

Description:

This function leverages Lelapa.ai's Entity Recognition API to identify and extract entities from the input text. It supports recognition of various entity types (e.g., person, location, organization).

Input Parameters:

• conn (Object): The connection object.
• text (String): The input text for entity recognition.

Return Value:

• entities (List of Maps): A list of extracted entities. Each entity is represented as a map:

  [
    %{
      "entity" => "entity_type", // String: Entity type (e.g., "person", "location")
      "word" => "extracted_word",  // String: The extracted word or phrase representing the entity
      "start" => integer,          // Integer: Starting index of the entity in the input text (0-based)
      "end" => integer            // Integer: Ending index of the entity in the input text (exclusive)
    },
    # ... more entities
  ]

  plain

Data Types:

• text: String
• entities: List<Map<String, String | Integer>>

Code Example (Turn.io Code Block):

card ExtractEntities do
  message_text = params[:message]
  extracted_entities = lelapa_entity_recognition(conn, message_text)

  if extracted_entities != nil do
    if extracted_entities.empty? do
      say("No entities found in the text.")
    else
      say("Extracted Entities:")
      for entity in extracted_entities do
        say("- Type: #{entity["entity"]}, Word: #{entity["word"]}, Start: #{entity["start"]}, End: #{entity["end"]}")
      end
      # Further processing of entities (e.g., store in variables, trigger actions)
    end
  else
    say("Entity recognition failed.")
  end
end

​4. lelapa_sentiment_analysis(conn, text)

Description:

This function utilizes Lelapa.ai's Sentiment Analysis API to determine the sentiment (positive, negative, or neutral) of the input text. It can analyze sentiment at a sentence level and provide an overall sentiment for the entire text.

Input Parameters:

• conn (Object): The connection object.
• text (String): The input text for sentiment analysis.

Return Value:

• sentiment_result (Map): A map containing sentiment analysis results. Structure:

  %{
    "__value__" => "overall_sentiment_label", // String: Overall sentiment ("positive", "negative", "neutral")
    "score" => 0.xxxx,                     // Float: Confidence score of the overall sentiment
    "text" => "input_text",                 // String: The input text analyzed
    "label" => "overall_sentiment_label",  // String: Redundant key, same as "__value__"
    "sentiments" => [                     // List of sentiment analysis results per sentence/phrase
      %{
        "sentiment" => [                   // List, usually contains one sentiment rating
          %{
            "label" => "sentence_sentiment", // String: Sentiment label for the sentence/phrase
            "score" => 0.xxxx             // Float: Confidence score for the sentence sentiment
          }
        ],
        "text" => "analyzed_sentence/phrase" // String: The sentence/phrase analyzed
      },
      # ... more sentence sentiments
    ]
  }

  plain

Data Types:

• text: String
• sentiment_result: Map<String, String | Float | List<Map<String, List<Map<String, String | Float>>>>> (Complex structure, refer to example)

Code Example (Turn.io Code Block):

card AnalyzeSentiment do
  message_content = params[:message]
  sentiment_data = lelapa_sentiment_analysis(conn, message_content)

  if sentiment_data != nil do
    overall_sentiment = sentiment_data["__value__"]
    overall_score = sentiment_data["score"]
    say("Overall Sentiment: #{overall_sentiment} (Score: #{overall_score})")

    # Example: Iterating through sentence-level sentiments
    for sentence_sentiment in sentiment_data["sentiments"] do
      sentence_text = sentence_sentiment["text"]
      sentence_label = sentence_sentiment["sentiment"][0]["label"] # Assuming one sentiment per sentence
      sentence_score = sentence_sentiment["sentiment"][0]["score"]
      say("- Sentence: '#{sentence_text}', Sentiment: #{sentence_label} (Score: #{sentence_score})")
    end
  else
    say("Sentiment analysis failed.")
  end
end

​5. lelapa_translate(conn, text, source_language, target_language)

Description:

This function utilizes Lelapa.ai's Translation API to translate the input text from source_language to target_language. It supports a range of languages, particularly focusing on African languages.

Input Parameters:

• conn (Object): The connection object.
• text (String): The text to be translated.
• source_language (String): Language code of the source text (e.g., "eng_Latn" for English, "zul_Latn" for Zulu). Refer to Lelapa.ai documentation for supported language codes.
• target_language (String): Language code for the desired translation language (following the same code standard as source_language).

Return Value:

• translation_result (Map): A map containing the translation result. Structure:

  %{
    "__value__" => "translated_text", // String: The translated text
    "translation" => [                 // List, typically contains one translation
      %{
        "translation_text" => "translated_text" // String: Redundant key, same as "__value__"
      }
    ]
  }

  plain

Data Types:

• text: String
• source_language: String (Language Code)
• target_language: String (Language Code)
• translation_result: Map<String, String | List<Map<String, String>>>

Code Example (Turn.io Code Block):

card TranslateText do
  text_to_translate = params[:message] # User input in source language
  source_lang = "eng_Latn"          # Example: Assume source is English
  target_lang = "zul_Latn"          # Example: Translate to Zulu

  translation_data = lelapa_translate(conn, text_to_translate, source_lang, target_lang)

  if translation_data != nil do
    translated_text = translation_data["__value__"]
    say("Original Text (#{source_lang}): #{text_to_translate}")
    say("Translated Text (#{target_lang}): #{translated_text}")
  else
    say("Translation failed.")
  end
end

Important Notes:

• Language Codes: Ensure you use correct and supported language codes for source_language and target_language in lelapa_translate(). Refer to language support for the complete list of supported codes.
• Error Handling: Check for nil return values or utilize Turn.io's error handling mechanisms within code blocks.
• Rate Limits and Usage: Be aware of any rate limits or usage quotas associated with your Vulavula account to avoid service interruptions. Consult plans for details.