Articut

Articut: An Introduction

Articut is a Word-Segmentation/POS-tagging system based on "Syntactic Rules."

Since Articut is based on syntax structure, it does not require BigData for training. Accuracy improvement takes just few minutes and can be deployed offline. Articut does not include a dictionary. That enables the ability to inference new words.

In addition to Word-Segmentation, Articut is also POS-tagging system. It calculates "Segmentation", "Part-of-Speech" and "Named Entity Recognition (NER)" at the same time. This helps computers to extract words as their minimal meaning units in the sentence.

Calling Articut API

Sample Code:

from requests import post

url = "https://nlu.droidtown.co/Articut_EN/API/"
payload = {
    "username": "",
    "api_key":"",
    "input_str": "Don't give up. You can make it good."
}

response = post(url, json=payload).json()

var url = "https://nlu.droidtown.co/Articut_EN/API/";

var xhr = new XMLHttpRequest();
xhr.open("POST", url);

xhr.setRequestHeader("Accept", "application/json");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.onreadystatechange = function () {
    if (xhr.readyState === 4) {
        console.log(xhr.status);
        console.log(xhr.responseText);
    }
};

var data = `{
    "username": "",
    "api_key" : "",
    "input_str":"Don't give up. You can make it good."
}`;

xhr.send(data);

Result returned as a JSON object:

{'exec_time': 0.016721010208129883,
 'result_pos': ['<MODAL>Do</MODAL> <FUNC_negation>not</FUNC_negation> '
                '<VerbP>give up</VerbP>',
                '.',
                '<ENTITY_pronoun>You</ENTITY_pronoun> <MODAL>can</MODAL> '
                '<ACTION_verb>make</ACTION_verb> '
                '<ENTITY_pronoun>it</ENTITY_pronoun> <MODIFIER>good</MODIFIER>',
                '.'],
 'result_segmentation': 'Do/not/give up/./You/can/make/it/good/.',
 'result_obj': [[{'text': 'Do', 'pos': 'MODAL'},
                 {'text': 'not', 'pos': 'FUNC_negation'},
                 {'text': 'give up', 'pos': 'VerbP'}],
                [{'text': '.', 'pos': 'PUNCTUATION'}],
                [{'text': 'You', 'pos': 'ENTITY_pronoun'},
                 {'text': 'can', 'pos': 'MODAL'},
                 {'text': 'make', 'pos': 'ACTION_verb'},
                 {'text': 'it', 'pos': 'ENTITY_pronoun'},
                 {'text': 'good', 'pos': 'MODIFIER'}],
                [{'text': '.', 'pos': 'PUNCTUATION'}]],
 'level': 'lv1',
 'version': 'v100',
 'status': True,
 'msg': 'Success!',
 'word_count_balance': 1992}

HTTP Request

POST https://nlu.droidtown.co/Articut_EN/API/

Arguments

Argument	Type	Default	Description
username	str	""	The email account you registered and used to login https://nlu.droidtown.co
api_key	str	""	After purchasing your own quota, you will see a 31 character-long key string at your personal `Info` page after logging.
input_str	str	""	The text you want Articut to process. (Note: For better performance, we recommend you to limit your text under 2000 words at each request to avoid Internet issues like "Connection TimeOut Error.")
version	str	"latest"	`version` is an optional argument. If you leave it unspecified or blank. Articut would use the latest algorithm to process your input_str. Or, if you specified an available version (e.g., `"v100"`) Articut would use algorithm of `v100` to process your input_str.
level	str	"lv1"	Currently, Articut only provide lv1 for English texts.
user_defined_dict_file	dict	{}	A dictionary format data. The key must be a string and the values are stored in a list. The list can be an empty list. (e.g. UserDefinedDICT = {"key": ["value1", "value2",...],...}).

Result Returned

Returned message	Type	Description
status	bool	The value could be True or False.
msg	str	The value could be as listed below:
		- Success!: Request completed successfully.
		- Specified version does not exist.: Specified algorithm version is unavailable. Please check again to specify another version.
		- Specified level does not exist.: Currently, Articut only provide lv1 for English texts.
		- Authtication failed.: Account (email) and API key doesn't match.
		- API_Key failed.: Invalid api_key! Please check your api_key again.
		- Your input_str is too long. (over 2000 characters.): input_str is too long (over 2000 characters) and may cause Connection TimeOut Error.
		- Insufficient word count balance.: There's no enough quota under your account to process your request.
		- Internal server error. (Your word count balance is not consumed, don't worry. System will reboot in 5min, please try again later.): Well...it seems there's something wrong with our server. Don't worry, we are fixing it and the server is scheculed to reboo and go online in 5 min. Please try again later. Don't worry, your quota stays intact.
		- Invalid content_type.: The format has to be in Json format (application/json).
		- Invalid arguments.: Argument format error. Please check the types of your arguments.
versions	dict	Currently available Articut Versions
		- UserDefinedDICT Parsing ERROR. (Please check your the format and encoding.): Cannot load user_defined_dict_file. Please double check the format (as JSON dictionary format) and the encoding (as UTF-8).
		- Maximum UserDefinedDICT file size exceeded! (UserDefinedDICT file shall be samller than 10MB.): The user_defined_dict_file is bigger than 10MB. This may cause potential Connection TimeOut Error.
result_pos	list	Each sentence is stored as a list. Each word/phrase goes with its POS tag in the list.
result_obj	list	Each sentence is stored as a list. Each word/phrase goes with its POS tag in a dictionary.
result_segmentation	str	Each sentence is processed with a '/' marking wound/phrase boundaries in a string.
exec_time	float	Processing time at server end.
version	str	Algorithm version.
level	str	Currently, Articut only provide lv1 for English texts.
word_count_balance	int	Remaining quota under your account

Get current Articut Version

Sample Code:

from requests import post

url = "https://nlu.droidtown.co/Articut_EN/Versions/"
payload = {
    "username": "",
    "api_key": ""
}

response = post(url, json=payload).json()

var url = "https://nlu.droidtown.co/Articut_EN/Versions/";

var xhr = new XMLHttpRequest();
xhr.open("POST", url);

xhr.setRequestHeader("Accept", "application/json");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.onreadystatechange = function () {
   if (xhr.readyState === 4) {
      console.log(xhr.status);
      console.log(xhr.responseText);
   }};

var data = `{
    "username": "",
    "api_key" : ""
}`;

xhr.send(data);

Result returned as a JSON object:

{
    "status": true,
    "msg": "Success!",
    "versions": [
        {
            "version": "latest",
            "release_date": "2022-01-20",
            "level": ["lv1"],
        },
        {   
            "version": "v100"
            "release_date": "2022-01-05",
            "level": ["lv1"],
        }
    ]
}

HTTP Request

POST https://nlu.droidtown.co/Articut_EN/Versions/

Arguments

Argument	Type	Default	Description
username	str	""	The email account you registered and used to login https://nlu.droidtown.co(email)。
api_key	str	""	After purchasing your own quota, you will see a 31 character-long key string at your personal `Info` page after logging.

Result Returned

Returned message	Type	Description
status	bool	The value could be True or False.
msg	str	The value could be as listed below:
		- Success!: Request completed successfully.
		- Authtication failed.: Account (email) and API key doesn't match.
		- Internal server error. (Your word count balance is not consumed, don't worry. System will reboot in 5min, please try again later.): Well...it seems there's something wrong with our server. Don't worry, we are fixing it and the server is scheculed to reboo and go online in 5 min. Please try again later. Don't worry, your quota stays intact.
		- Invalid content_type.: The format has to be in Json format (application/json).
		- Invalid arguments.: Argument format error. Please check the types of your arguments.
versions	dict	Currently available Articut Versions
		- version: Version number
		- release_date: Released date
		- level: Available algorithm levels

Using UserDefined Dictionary

Sample Code:

from requests import post

url = "https://nlu.droidtown.co/Articut_EN/API/"
payload = {
    "username": "",
    "api_key": "",
    "input_str": "I am working on a SDAC project",
    "user_defined_dict_file": {"SDAC": ["super duper awesome cool"]}
}

response = post(url, json=payload).json()

var url = "https://nlu.droidtown.co/Articut_EN/API/";

var xhr = new XMLHttpRequest();
xhr.open("POST", url);

xhr.setRequestHeader("Accept", "application/json");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.onreadystatechange = function () {
   if (xhr.readyState === 4) {
      console.log(xhr.status);
      console.log(xhr.responseText);
   }};

var data = `{
    "username": "",
    "api_key" : "",
    "input_str": "I am working on a SDAC project",
    "user_defined_dict_file": {"SDAC": ["super duper awesome cool"]}
}`;

xhr.send(data);

Result returned as a JSON object:

{'exec_time': 0.017722606658935547,
 'result_pos': ['<ENTITY_pronoun>I</ENTITY_pronoun> '
                '<ACTION_verb>am</ACTION_verb> <VerbP>working on</VerbP> '
                '<FUNC_determiner>a</FUNC_determiner> '
                '<UserDefined>SDAC</UserDefined> '
                '<ENTITY_noun>project</ENTITY_noun>'],
 'result_segmentation': 'I/am/working on/a/SDAC/project',
 'result_obj': [[{'text': 'I', 'pos': 'ENTITY_pronoun'},
                 {'text': 'am', 'pos': 'ACTION_verb'},
                 {'text': 'working on', 'pos': 'VerbP'},
                 {'text': 'a', 'pos': 'FUNC_determiner'},
                 {'text': 'SDAC', 'pos': 'UserDefined'},
                 {'text': 'project', 'pos': 'ENTITY_noun'}]],
 'level': 'lv1',
 'version': 'v100',
 'status': True,
 'msg': 'Success!',
 'word_count_balance': 1979}

The "SDAC" listed in the user_defined_dict_file in the payload is taken into consideration when processing the inputSTR. Therefore the SDAC is tagged as <UserDefined>.

HTTP Request

POST https://nlu.droidtown.co/Articut_EN/API/

Arguments

Arguments	Type	Default	Description
username	str	""	The email account you registered and used to login https://nlu.droidtown.co
api_key	str	""	After purchasing your own quota, you will see a 31 character-long key string at your personal `Info` page after logging.
input_str	str	""	The text you want Articut to process. (Note: For better performance, we recommend you to limit your text under 2000 words at each request to avoid Internet issues like "Connection TimeOut Error.")
user_defined_dict_file	dict	{}	A dictionary format data. The key must be a string and the values are stored in a list. The list can be an empty list. (e.g. UserDefinedDICT = {"key": ["value1", "value2",...],...}).

Result Returned

Returned message	Type	Description
status	bool	The value could be True or False.
msg	str	The value could be as listed below:
		- Success!: Request completed successfully.
		- UserDefinedDICT Parsing ERROR. (Please check your the format and encoding.): Cannot load user_defined_dict_file. Please double check the format (as JSON dictionary format) and the encoding (as UTF-8).
		- Maximum UserDefinedDICT file size exceeded! (UserDefinedDICT file shall be samller than 10MB.): The user_defined_dict_file is bigger than 10MB. This may cause potential Connection TimeOut Error.

Part-of-speech (POS)

Do(MODAL) not(FUNC_negation) give up(VerbP). We(ENTITY_pronoun) look forward to(VerbP) seeing(ACTION_verb) strong(MODIFIER) AI(ENTITY_nouny) soon(MODIFIER).

Without the idea of POS, words are just a string of symbols connected by space. It takes the knowledge of POS to compile the meanings of sentences.

Human understand natural language basing on the POS of the words and its meaning to identify the contribution of them in the sentence.

Tag Categories

Category	Tag
Entity	Tags start with `ENTITY`
Verbs	Tags start with `ACTION`, `ASPECT`, `MODAL`, `AUX`
Temporal Expressions	Tags start with `TIME`
Adjectives & Adverbs	`IDIOM`, `MODIFIER`, `ModifierP`, `DegreeP`, `QUANTIFIER`
Functional Words	Tags start with `FUNC`
Clausal markers	Tags start with `CLAUSE`
Named_Entity_Recognition	Tags start with `LOCATION`, `KNOWLEDGE`, `UserDefined` and `RANGE`

Entity

Entities are usually seen as synonym of noun words. They refer to person, items, things, times, emotions, concepts and directions in both concret and abstrac ways.

When doing NLP with entities, there are few rules you can take advantages of...

Sequential nouny can be taken as a big noun and thus considered as an entity. E.g., Coffee(ENTITY_nouny) cup(ENTITY_nouny) can be seen as Coffee cup(ENTITY_NP)

Tag	Description
`<ENTITY_num>`	Numeral Expressions
`<ENTITY_classifier>`	Classifier/Measuring methods of something
`<ENTITY_measurement>`	Measuring result (e.g., 10kg)
`<ENTITY_person>`	Entity as a person's name
`<ENTITY_pronoun>`	Entitiy as a pronoun
`<ENTITY_possessive>`	Entity in its possessive case
`<ENTITY_noun>`	Entity as noun
`<ENTITY_nounHead>`	Entity as head of a nominal expression
`<ENTITY_nouny>`	Entity as noun
`<ENTITY_oov>`	Entity as noun
`<ENTITY_DetPhrase>`	Determiner phrase is composed of a determiner and a ordinal number. It can be used as a pronoun referencing to something/someone in the context. E.g., `<ENTITY_DetPhrase>the first</ENTITY_DetPhrase>`

Verb

A verb is a word that contribute the main meaning of the sentence. It usually indicates an action, an event or a state of existence.

Tag	Description
`<ACTION_lightVerb>`	Light verbs (e.g., make, let, cause...).
`<ACTION_verb>`	Common verbs.
`<VerbP>`	A phrasal verb consisits of a `Verb` and a `Proposition` or `Functional word` that create a different meaning from either parts of the phrase. e.g.,
	`<VerbP>Look up</VerbP> <FUNC_determiner>the</FUNC_determiner> <ENTITY_nouny>dictionary</ENTITY_nouny>`
	`<VerbP>turn on</VerbP> <FUNC_determiner>the</FUNC_determiner> <ENTITY_nouny>light</ENTITY_nouny>`
`<AUX>`	AUX means auxiliary verbs. Articut tags Be-Verbs as AUX (e.g., is, am, were).
`<MODAL>`	MODAL means modality verbs. It's a semantic marker indicating the ability or permission depending on the contexts (e.g., may, will, should...).

Time

Time/temporal related words/expressions.

Tag	Description
`<TIME_holiday>`	Temporal expressions related to known holidays.
`<TIME_justtime>`	Temporal expressions related to current time or a relatively short period of time.
`<TIME_day>`	Temporal expressions counted by day base.
`<TIME_week>`	Temporal expressions counted by week base.
`<TIME_month>`	Temporal expressions counted by month base.
`<TIME_season>`	Temporal expressions counted by season base.
`<TIME_year>`	Temporal expressions counted by year base.
`<TIME_decade>`	Temporal expressions counted by time that is longer than year base.

Modifier

Modifiers includes adjectives and adverbs. They are used to modify a sentence, an action, an event in the context or simply a noun.

Articut uses MODIFIER to cover both adjectives and adverbs.

Tag	Description
`<MODIFIER>`	Adjectives and adverbs
`<QUANTIFIER>`	Quantification markers such "all", "some"...etc.

Function Word

Functions words indicate a word that plays as a syntactical function in a sentence or between sentences.

Tag	Description
`<FUNC_conjunction>`	Conjunction words such as "and"
`<FUNC_determiner>`	Determiners are words placed in front of a noun to make it clear what the noun refers to. Such as "the", "that"...etc.
`<FUNC_inner>`	Function words that indicates some in-sentence semantics. (e.g., "in" may indicate a relation between an action and a place in `I live in this town.`)
`<FUNC_inter>`	Function words that indicates some inter-sentence semantics. (e.g., "however" may indicate an existence of other sentence. (e.g., `I usually don't eat breakfast. However, this toast is just too delicious.`)
`<FUNC_negation>`	Negation words

Clause

Clause tag indicates whether the sentence is a question or not. Clause_particle tags the interjections in a sentence.

Tag	Description
`<CLAUSE_YesNoQ>`	Yes-No question
`<CLAUSE_WhoQ>`	A question about WHO
`<CLAUSE_WhatQ>`	A question about WHAT
`<CLAUSE_WhereQ>`	A question about WHERE
`<CLAUSE_WhenQ>`	A question about WHEN
`<CLAUSE_WhyQ>`	A question about WHY
`<CLAUSE_HowQ>`	A question about the method/degree with HOW
`<CLAUSE_particle>`	Interjections

Named Entity Recognition (NER)

Named Entiteis means an object in the real world. It could be a place (LOCATION), a person, an organization, a product or proper names of some concret/abstract item. NER helps identify entities that has specific meaning (and thus indicated meaningful features) in a text.

Tag	Description
`<LOCATION>`	Names of a place
`<RANGE_locality>`	Propositions that act as range markers of a place
`<RANGE_period>`	Propositions that act as range markers of a temporal expression
`<UserDefined>`	Strings/Words defiend by users
`<KNOWLEDGE_addUS>`	Address expressions of USA
`<KNOWLEDGE_currency>`	Money with amount `<KNOWLEDGE_currency>100 US dollars</KNOWLEDGE_currency>` or `<KNOWLEDGE_currency>one pound</KNOWLEDGE_currency> <FUNC_conjunction>and</FUNC_conjunction> <KNOWLEDGE_currency>four pence</KNOWLEDGE_currency>`
`<KNOWLEDGE_lawUS>`	Index of legal documents
`<KNOWLEDGE_routeUS>`	Road/Street names
`<KNOWLEDGE_url>`	URL links

Loki

Loki: an introduction

Loki stands for Linguistic Oriented Keyword Interface. It is a next-gen (Natural Language Understanding, NLU engine.

Loki is driven by syntactic analysis. It converts text into a Python-compatible Regex with condition code blocks.

Comparing to Microsoft LUIS or Google DiaglogFlow, Loki saves tremendous amount of development time and only requires small data.

Loki Solved two problems at the same time:
1. Comparing to other machine-learning block box, the regular expression model generated by Loki is "human-readable/adjustable."
2. No massive amount of data is required! For each utterance pattern, only one occurrance is required to generate a valid regular expression and its conditional block.

Loki Quickstart Guide

Login Loki

Open the webpage https://nlu.droidtown.co/loki/ Login your account and click Loki > Start Loki

Create Project

Key-in a project name. The project name should be composed of alphabets [a-z, A-Z] (with digits [0-9] or underline [_]). Click [Create Project].

Project Name

Create Intent

Click the [Project]then click green [Create Intent]。
Key-in an intent name. The project name should be composed of alphabets [a-z, A-Z] (with digits [0-9] or underline [_]). Click blue [Create Intent].
You may optionally add some words (usually product names, abbrivations and acronyms) in UserDefined Dictionary. Each entries should be seperated with a comma ,.

Both key and value will be used as UserDefined words. Therefore, it is a good idea to put synonyms or words with similar attributions in one item. For example, if you want to put crypto currency as a self defined word, we recommend you use the strategy illustrated below: key: "_crypto_coin" value: ["DOGE", "ETH", "BTC"] The benefit of doing so is obvious. Since keys in the UserDefined dictionary will be used as words, we can use a "unlikely" word as a key to avoid confusion, and keep the flexibility of dictionary to let "DOGE", "ETH", and "BTC" to refer to the same category (a.k.a. _crypto_coin) in the coding session to come. This can help formalize the terms if you need to look it up in the database. For instance:

SELECT _crypto_coin FROM ...

UserDefined Dictionary

After adding the utterance text, click[Analyze] to analyze the syntactic structure/pattern of the utterance. All puncturations in the utterances will be ignored by Loki. Alternatively, you may also enter all the utterance text then click [Analyze All]。
Select (check) the [argument] to represent the intent in the utterance. Usually the arguments indicate words that may vary in this sentence. We will use these selected words for further semantic calculation later.
Key-in a version number to control the version of your model. Then, click [Deploy Model]. Last deploy time will be shown on the button as a reminder.
Enter a testing text in [Testing Tool] to evaluate the model and make sure the arguments in Step 04 are properly arranged.
Repeat Step 04 to Step 06 untill all testing texts can be captured by the model under this [Intent].

Load Existing Intent Model

Login Loki

Open the webpage https://nlu.droidtown.co/loki/ Login your account and click Loki > Start Loki

Create Project

Key-in a project name. The project name should be composed of alphabets [a-z, A-Z] (with digits [0-9] or underline [_]). Click [Create Project].

Project Name

Load Existing Intent Model

In addition to Loki official .ref format, Loki can also import pure text .txt file and utterance texts exported from Google DialogFlow and Microsoft LUIS as well.

Select [ArticutModel]

Select [ArticutModel] under the [Project] then click [Browse] > choose .ref file (You can choose 10 .ref files at once) > [Load Intent].
Load TXT text

Select [Txt] under the [Project] then click [Browse] > choose .txt file (You can choose 10 .txt files at once) > [Load Intent].
Load LUIS utterance json

Select [LUIS] under the [Project] then click [Browse] > choose .json file (You can choose 10 .json files at once) > [Load Intent].
Load DialogFlow utterance json

Select [DialogFlow] under the [Project] then click [Browse] > choose .json file (You can choose 10 .json files at once) > [Load Intent].

Analyze and Deploy Model

Please refer to Quickstart Guide Step 04 to complete the model settings.

Changing Articut Version

Every Loki project would use the latest version of Articut NLP as backend. However, you can also choose a version manually.

Login Loki

Open the webpage https://nlu.droidtown.co/loki/ Login your account and click Loki > Start Loki

Changing Articut Version

Click the dropdown list and select the Articut version to be used. Changing Articut version may take few minutes, please hold.
After changing Articut version, please enter the [Intent], utterances afftected will be highlightened with pink background in Step 04. Make sure to check the arguments in Step 04 [Argument Setting].
Click [Deploy Model] to complete Articut version-chaning operation.

Using Loki Template

Loki provides Python3, Java (Android) and AppInventor2 (AI2) code templates.

Edit the semantics behind the Intents of your Project

Go to the front page of Loki, click [Template] and select a programming language that suits you (e.g., Python) to download the code template.

unzip the .zip downloaded. The file/directory should be like this:

Project_Name.py

intent/Loki_Intent.py
Open theProject_Name.pyfile, fill-in USERNAME and LOKI_KEY The Key can be found at the front page of Loki. Each project has a Loki_Key of its own.
Open intent/Loki_Intent.py to compose the semantic logic behind the utterances.
Start using your Loki project(s).

Update Loki Template

Loki has an Updater.py for Python3 users.

Download new Loki template and put the new intent folder inside old intent folder (project/intent/) and rename the new intent as new_intent.
Execute Updater.py and specify the new and the old intent folders pathes.
- -o the old intent directory
- -n the new intent directory
- python3 Updater.py -o ./intent -n ./new_intent
After execution, there will be a Loki_<intent>_updated.py shows up if there is any differences between the old and the new intents. Utterances only seen in the new intent will be listed at the end of the Loki_<intent>_updated.py file.

Calling Loki API

Sample Code:

from requests import post

url = "https://nlu.droidtown.co/Loki_EN/API/"
payload = {
    "username": "demo@droidtown.co",
    "loki_key": "H94mWAzQ5_nq^o&3EA+H_4Bz#zf+_ai",
    "input_str": "I would like to exchange 50 USD into euros"
} 

response = post(url, json=payload).json()

var url = "https://nlu.droidtown.co/Loki_EN/API/";

var xhr = new XMLHttpRequest();
xhr.open("POST", url);

xhr.setRequestHeader("Accept", "application/json");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.onreadystatechange = function () {
    if (xhr.readyState === 4) {
        console.log(xhr.status);
        console.log(xhr.responseText);
    }
};

var data = `{
    "username": "demo@droidtown.co",
    "loki_key": "H94mWAzQ5_nq^o&3EA+H_4Bz#zf+_ai",
    "input_str": "I would like to exchange 50 USD into euros"
}`;

xhr.send(data);

Result returned as a JSON object:

{
 'status': True,
 'msg': 'Success!',
 'version': 'v100',
 'results': [{'intent': 'change_currency',
              'pattern': '<ENTITY_pronoun>[^<]*?</ENTITY_pronoun><MODAL>[^<]*?</MODAL><VERB_P>like</VERB_P><FUNC>[^<]*?</FUNC><VERB_P>(exchange|swap|change)</VERB_P><KNOWLEDGE_currency>[^<]*?</KNOWLEDGE_currency><RANGE>[^<]*?</RANGE><ENTITY_UserDefined>[^<]*?</ENTITY_UserDefined>',
              'utterance': '[I] would like [to] exchange [50 USD] [into] '
                           '[euros]',
              'argument': ['I', 'to', '50 USD', 'into', 'euros']}]
}

HTTP Request

POST https://nlu.droidtown.co/Loki_EN/API/

Arguments

Argument	Type	Default	Description
username	str	""	The email account you registered and used to login https://nlu.droidtown.co
loki_key	str	""	After purchasing your own quota, you will see a 31 character-long key string under every Loki project after logging. `(You can have many projects.)`
input_str	str	""	Texts to be sent to Loki for intent analysis. `(Texts should be shorter than 2000 character in length.)`
filter_list	list	[]	Default as empty list, meaning it will check every intent under the projects. If the list is not empty, Loki will only check the intent specified.

Result Returned

Returned message	Type	Description
status	bool	The value could be True or False.
msg	str	The value could be as listed below:
		- Success!: Request completed successfully.
		- No matching intent.: No intent in the project matches the text requested.
		- Invalid content_type.: The format has to be in Json format (application/json).
		- Invalid arguments.: Argument format error. Please check the types of your arguments.
		- Authentication failed.: Account (email) and API key doesn't match.
		- Invalid project.: loki_key is invalid. Please make sure your loki_key is correct and all projects have been deployed.
		- Internal server error. (Your word count balance is not consumed, don't worry. System will reboot in 5min, please try again later.): Well...it seems there's something wrong with our server. Don't worry, we are fixing it and the server is scheculed to reboo and go online in 5 min. Please try again later. Don't worry, your quota stays intact.
version	str	Algorithm version used for the request.
word_count_balance	int	Remaining quota under your account.

Calling Loki Bulk API

Sample Code:

from requests import post

url = "https://nlu.droidtown.co/Loki_EN/BulkAPI/"
payload = {
    "username": "demo@droidtown.co",
    "loki_key": "H94mWAzQ5_nq^o&3EA+H_4Bz#zf+_ai",
    "input_list": [
        "How much is 100 US dollars in NTD",
        "Could I exchange 300 pesos to USD"
    ]
} 

response = post(url, json=payload).json()

var url = "https://nlu.droidtown.co/Loki_EN/BulkAPI/";

var xhr = new XMLHttpRequest();
xhr.open("POST", url);

xhr.setRequestHeader("Accept", "application/json");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.onreadystatechange = function () {
    if (xhr.readyState === 4) {
        console.log(xhr.status);
        console.log(xhr.responseText);
    }
};

var data = `{
    "username": "demo@droidtown.co",
    "loki_key": "H94mWAzQ5_nq^o&3EA+H_4Bz#zf+_ai",
    "input_list": [
        "How much is 100 US dollars in NTD",
        "Could I exchange 300 pesos to USD"
    ]
}`;

xhr.send(data);

Result returned as a JSON object:

{
 'msg': 'Success!',
 'result_list': [{'msg': 'Success!',
                  'results': [{'argument': ['much',
                                            '100 US dollars',
                                            'in',
                                            'NTD'],
                               'intent': 'change_currency',
                               'pattern': '<ENTITY_UserDefined>How</ENTITY_UserDefined>(<QUANTIFIER>[^<]*?</QUANTIFIER>)?<AUX>[^<]*?</AUX><KNOWLEDGE_currency>[^<]*?</KNOWLEDGE_currency><RANGE>[^<]*?</RANGE><ENTITY_UserDefined>[^<]*?</ENTITY_UserDefined>',
                               'utterance': 'How [much] is [100 USD] [in] '
                                            '[NTD]'}],
                  'status': True},
                 {'msg': 'Success!',
                  'results': [{'argument': ['I', '300 pesos', 'to', 'USD'],
                               'intent': 'change_currency',
                               'pattern': '<CLAUSE_YesNoQ>[^<]*?</CLAUSE_YesNoQ><ENTITY_pronoun>[^<]*?</ENTITY_pronoun><VERB_P>exchange</VERB_P><KNOWLEDGE_currency>[^<]*?</KNOWLEDGE_currency><FUNC>[^<]*?</FUNC><ENTITY_UserDefined>[^<]*?</ENTITY_UserDefined>',
                               'utterance': 'Could [I] exchange [300 pesos] '
                                            '[to] [NTD]'}],
                  'status': True}],
 'status': True,
 'version': 'v100'
}

HTTP Request

POST https://nlu.droidtown.co/Loki_EN/BulkAPI/

Arguments

Argument	Type	Default	Description
username	str	""	The email account you registered and used to login https://nlu.droidtown.co
loki_key	str	""	After purchasing your own quota, you will see a 31 character-long key string under every Loki project after logging. `(You can have many projects.)`
input_str	str	""	Texts to be sent to Loki for intent analysis. `(Texts should be shorter than 2000 character in length.)`
filter_list	list	[]	Default as empty list, meaning it will check every intent under the projects. If the list is not empty, Loki will only check the intent specified.

Result Returned

Returned message	Type	Description
status	bool	The value could be True or False.
msg	str	The value could be as listed below:
		- Success!: Request completed successfully.
		- No matching intent.: No intent in the project matches the text requested.
		- Invalid content_type.: The format has to be in Json format (application/json).
		- Invalid arguments.: Argument format error. Please check the types of your arguments.
		- Your input is too many (over 20 sentence).: input_list should be under 20 elements.
		- Authentication failed.: Account (email) and API key doesn't match.
		- Invalid project.: loki_key is invalid. Please make sure your loki_key is correct and all projects have been deployed.
		- Internal server error. (Your word count balance is not consumed, don't worry. System will reboot in 5min, please try again later.): Well...it seems there's something wrong with our server. Don't worry, we are fixing it and the server is scheculed to reboo and go online in 5 min. Please try again later. Don't worry, your quota stays intact.
version	str	Algorithm version used for the request.
word_count_balance	int	Remaining quota under your account.

Calling Loki Command

Sample Code:

from requests import post

url = "https://nlu.droidtown.co/Loki_EN/Command/"
payload = {
    "username": "demo@droidtown.co",
    "loki_key": "H94mWAzQ5_nq^o&3EA+H_4Bz#zf+_ai",
    "intent": "change_currency",
    "utterance": [
        "How much is 100 US dollars in NTD",
        "Could I exchange 300 pesos to USD"
    ],
    "func": "insert"
} 

response = post(url, json=payload).json()

var url = "https://nlu.droidtown.co/Loki_EN/Command/";

var xhr = new XMLHttpRequest();
xhr.open("POST", url);

xhr.setRequestHeader("Accept", "application/json");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.onreadystatechange = function () {
    if (xhr.readyState === 4) {
        console.log(xhr.status);
        console.log(xhr.responseText);
    }
};

var data = `{
    "username": "demo@droidtown.co",
    "loki_key": "H94mWAzQ5_nq^o&3EA+H_4Bz#zf+_ai",
    "intent": "change_currency",
    "utterance": [
        "How much is 100 US dollars in NTD",
        "Could I exchange 300 pesos to USD"
    ],
    "func": "insert"
}`;

Result returned as a JSON object:

{
    "status": true,
    "msg": "Success!",
    "result_list": [
        {"status": true, "msg": "Success!"},
        {"status": true, "msg": "Success!"}
    ]
}

Loki Command is used to insert utterances without opening webpage from browser. It's a handy API tool for massive utterances and workflow integration.

HTTP Request

POST https://api.droidtown.co/Loki_EN/Command/

Arguments

Argument	Type	Default	Description
username	str	""	The email account you registered and used to login https://nlu.droidtown.co
loki_key	str	""	After purchasing your own quota, you will see a 31 character-long key string under every Loki project after logging. `(You can have many projects.)`
intent	str	""	Name of the intent in the project with the loki_key specified. `Notice! If the project does not have the intent, the request will be failed.`
utterance	list	[]	Texts to be sent to Loki to be inserted to the intent specified. `(Texts should be shorter than 2000 character in length.)`
func	str	insert	The value could be as listed below:
			- insert: Insert multiple utterances. `Notice! The utterance of the same as pattern will not be inserted.`
			- match: Match the same pattern of utterances in the intent.

Result Returned

Returned message	Type	Description
status	bool	The value could be True or False.
msg	str	The value could be as listed below:
		- Success!: Utterances have been inserted to the intent successfully.
		- Invalid content_type.: The format has to be in Json format (application/json).
		- Invalid arguments.: Argument format error. Please check the types of your arguments.
		- Authentication failed.: Account (email) and API key doesn't match.
		- Invalid project.: loki_key is invalid. Please make sure your loki_key is correct and all projects have been deployed.
		- Invalid intent.: Intent is invalid. Please make sure your "intent" exists in your project.
		- Utterance already exist.: There's already an identical utterance in this intent. You don't need to insert it twice.
		- Pattern same as Utterance.: There's already an identical pattern in this intent. You don't need to insert it twice.

Calling Loki Utterance

Sample Code:

from requests import post

url = "https://api.droidtown.co/Loki_EN/Utterance/"
payload = {
    # 若您是使用 Docker 版本，無須填入 username, loki_key 參數
    "username" : "demo@droidtown.co",
    "loki_key" : "H94mWAzQ5_nq^o&3EA+H_4Bz#zf+_ai",
    "intent_list": ["change_currency"]
} 

response = post(url, json=payload).json()

var url = "https://api.droidtown.co/Loki_EN/Utterance/";

var xhr = new XMLHttpRequest();
xhr.open("POST", url);

xhr.setRequestHeader("Accept", "application/json");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.onreadystatechange = function () {
    if (xhr.readyState === 4) {
        console.log(xhr.status);
        console.log(xhr.responseText);
    }
};

var data = `{
    "username" : "demo@droidtown.co",
    "loki_key" : "H94mWAzQ5_nq^o&3EA+H_4Bz#zf+_ai",
    "intent_list": ["change_currency"]
}`;

xhr.send(data);

Result returned as a JSON object:

{
    "status": true,
    "msg": "Success!",
    "results": {
        "change_currency": [
            "How much is 100 US dollars in NTD",
            "Could I exchange 300 pesos to USD"
        ]
    }
}

HTTP Request

POST https://api.droidtown.co/Loki_EN/Utterance/

Arguments

Argument	Type	Default	Description
username	str	""	The email account you registered and used to login https://nlu.droidtown.co
loki_key	str	""	After purchasing your own quota, you will see a 31 character-long key string under every Loki project after logging.
intent_list	list	[]	Get utterances of specific intent.

Result Returned

Returned message	Type	Description
status	bool	The value cloud be True or False.
msg	str	The value could be as listed below:
		- Success!: Request completed successfully.matches the text requested.
		- Invalid content_type.: The format has to be in Json format (application/json).
		- Invalid arguments.: Argument format error. Please check the types of your arguments.
		- Authentication failed.: Account (email) and API key doesn't match.
		- Invalid project.: loki_key is invalid. Please make sure your loki_key is correct and all projects have been deployed.
		- Utterance not found.: No utterance in the intent.