qfa-api

Qualitative Feedback Analysis (QFA) API.

Description

Synopsis: a dockerized python API to analyze qualitative feedback.

Powered by open-source language models. Uses Poetry for dependency management.

Setup classification with Kobo

1. Prepare a kobo form as follows:
   • add one question of type text, whose content will be classified. Example: feedback.
   • add up to three cascading select questions of type select_one, which determine how the text will be classified. Example: type, category, code.
   • fill in the possible choices in the choices sheet of the form exactly as explained here.
   • upload and deploy the form.

Tip

The text will be classified according to the labels of the choices. A few tips to improve the accuracy of the classification:

• The model cannot possibly know all humanitarian acronyms, so make sure to spell them out. Example: use Water, Sanitation and Hygiene instead of WASH, or Red Crescent instead of RC.
• Avoid using ambiguous labels and be specific. Example: use distribution of non-food items and distribution of cash instead of relief and cash.
• The more choices you provide, the less accurate the classification will be. Keep the number of choices as low as possible.

2. Register a new Kobo REST Service and configure it as follows:
   • insert as Endpoint URL

   https://qfa-api.azurewebsites.net/classify-text
   

   • add the following headers under Custom HTTP Headers:
     • under Name insert text-field and under Value the name of the text question to be classified. Example: feedback.
     • under Name insert source-name and under Value just kobo.
     • under Name insert source-origin and under Value the ID of the form (see where to find it).
     • under Name insert source-authorization and under Value your Kobo token (see how to get one).
     • under Name insert source-level1 and under Value the name of the first of the cascading select questions. Example: type.
     • under Name insert source-level2 and under Value the name of the second of the cascading select questions. Example: category.
     • under Name insert source-level3 and under Value the name of the third of the cascading select questions. Example: code.

That's it. Your submissions will be automatically classified in a few seconds. Happy qualitative feedback analysis!

API Usage

See the docs.

Configuration

cp example.env .env

and edit the provided ENV-variables accordingly.

Run locally

pip install poetry
poetry install --no-root
uvicorn main:app --reload

Run with Docker

docker compose up --detach