Introduction: AcQA API Access
Learn how to access the AcQA API to be able to add data into the knowledge base (KB) of the Q&A System. Learn the following steps:
- Auth into Q&A API using JSON Web Token (JWT)
- Remove all the data from the KB.
- Add data to be processed by the Q&A.
- Example using CSV to generate data to the Q&A System.
Step 1: Authenticate Into the REST API
To be able to access the API, we have to login into the API using the API: https://acqa.di.uminho.pt/audio/api-token-auth/ and passing the username and password of an admin user. In the following example, we used Renato as the username and Renatopassword as the password. Example using Python - Requests:
import requests
url = "https://acqa.di.uminho.pt/audio/api-token-auth/"
payload={'username': 'Renato',
'password': 'Renatopassword'}
files=[]
headers = {}
response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text) If the username and password are correctthe API returns JSON content that has a variable named token. The token variable contains the valid token that has to be passed as an argument in the requests made to the Q&A API. The following example shows how a success request is made for the login API.
{
"token": "valid.token"
}
If the username or the password did not match one of the database, the following JSON is returned: {
"non_field_errors": [
"Unable to log in with provided credentials."
]
}
Step 2: Send Data to the REST API to Be Processed As the Knowledge Base
To send data to the UPLOAD API, we have to make a PUT request to the URL https://acqa.di.uminho.pt/audio/api/v1/upload/file... with the headers Content-Type equals to 'text/plain' and Authorization equals to 'Bearer token.returned.on.login'. The content that we want to process into the kb is sent into the payload as an XML file. The XML file has to follow the AcQA input format. We have a main tag, and we have a tag for each pair of questions and answers. Inside the tag we have to define the and tags. In the following example, we have one question/answer: Question: "Em que sala é a aula do professor Maria João Tinoco Varanda Pereira na Segunda-Feira de Manhã?" Answer: "A aula do professor Maria João Tinoco Varanda Pereira, na disciplina Algoritmos e Estruturas de Dados, é na sala 101, das 08:00 as 10:00 na Segunda-Feira".
If the Authorization and XML are correct, the system returns the HTTP code 201 (Created) and starts processing the data. The URL https://acqa.di.uminho.pt/audio/status/ presents the processing status of the data sent to be processed.
import requests
url = "https://acqa.di.uminho.pt/audio/api/v1/upload/filename.txt"
payload="<dataset><QA><question>Em que sala é a aula do professor Maria João Tinoco Varanda Pereira na Segunda-Feira de Manhã?</question><answer>A aula do professor Maria João Tinoco Varanda Pereira, na disciplina Algoritmos e Estruturas de Dados, é na sala 101, das 08:00 as 10:00 na Segunda-Feira</answer></QA></dataset>"
headers = {
'Content-Type': 'text/plain',
'Authorization': 'Bearer json.token.content'
}
response = requests.request("PUT", url, headers=headers, data=payload)
print(response.text)
Step 3: Clean the KB
To delete all the KB content, we have to send a DELETE request to the URL: https://acqa.di.uminho.pt/audio/api/v1/kb/delete. This request has to be done with the Authorization header. This header has to contain a valid authorization token. The following example presents a request to clean the KB.
import requests
url = "https://acqa.di.uminho.pt/audio/api/v1/kb/delete"
payload={}
headers = {
'Authorization': 'Bearer jwt.token'
}
response = requests.request("DELETE", url, headers=headers, data=payload)
print(response.text)
Step 4: Create a XML File From a CSV Datafile
In this step, we show how to generate an XML file that contains information about classroom localization in a given university. With this generated XML, the Q&A process our file and generate a Q&A System capable of answering questions about where a class, professor, or meeting is in a given university.
Let's start our example with the CSV containing the following columns: Day; StartHour; FinishHour; Discipline; Room; Professor.
To be able to process this CSV to generate an XML recognized by AcQA, we can use the following Python3 example:
import csv
with open('file.csv', 'r', newline='', encoding='utf-8-sig') as csvfile:
with open('./output2.xml', 'w') as f1:
f1.write('<dataset>') # write the main XML tag
reader = csv.DictReader(csvfile, delimiter=";") #in our example the file is delimited by ;
for row in reader:
try:
turno = ""
hora = int(row['StartHour'].split(":")[0])
if hora < 12:
turno = "Manhã"
elif hora < 18:
turno = "Tarde"
else:
turno = "Noite"
f1.write(
'<QA><question>' + ('Em que sala é a aula do professor ' + row['Professor']) + ' na ' + row['Day'] + ' de ' +
turno + '?</question><answer>' + (
'A aula do professor ' + row['Professor']) + ', na disciplina ' + row['Discipline'] +', é na sala ' + row['Room'] + ', das ' + row['StartHour'] + ' as ' + row['FinishHour'] + ' na '+row['Day']+ '</answer></QA>')
f1.write(
'<QA><question>' + ('Em que sala é a disciplina ' + row['Discipline']) + ' na ' + row[
'Day'] + ' de ' +
turno + '?</question><answer>' + (
'A disciplina de ' + row['Discipline']) + ', é na sala ' + row['Room'] + ', das ' + row[
'StartHour'] + ' as ' + row['FinishHour'] + ' na '+row['Day'] + '</answer></QA>')
f1.write(
'<QA><question>' + ('Em que sala é a disciplina ' + row['Discipline'] + ' do professor '+row['Professor']) + ' na ' + row[
'Day'] + ' de ' +
turno + '?</question><answer>' + (
'A disciplina de ' + row['Discipline']) + ', é na sala ' + row['Room'] + ', das ' + row[
'StartHour'] + ' as ' + row['FinishHour'] + ' na '+row['Day'] + '</answer></QA>')
except:
pass
f1.write('</dataset>') #finish the main tag
f1.close()
In this example, we used the Portuguese language, as our example server setup was made in Portuguese. Our example server can answer questions in several languages, but the knowledge base contents are in Portuguese. This example is in Portuguese, so the Q&A System can answer questions about the professor's classes, as the professor's names are mainly in the Portuguese language (João, José, etc.).
The generated file (output2.xml in the example) can now be sent to the REST API to be processed by the Q&A System.