Return Types

By default, the API returns a natural language answer to the question provided. However, what's happening in the background is actually three steps:

1. Aggregation Generation: The question is converted into a MongoDB aggregation query.
2. Query Execution: The aggregation runs against the database using the connection string you provided.
3. Answer Generation: The structured result is transformed into a natural language answer.

You can choose which of these steps you want returned by specifying a returnTypes array with any combination of:

returnTypes Value	Description	Expected Keys in Response
"aggregation"	Returns the generated MongoDB aggregation pipeline, the database and collection used and a confidence score on a scale from 0 to 10 on how confident the AI is that the aggregation will answer the question correct.	confidence, database, collection, aggregation
"result"	Returns the raw query results from the executed aggregation.	result
"answer"	Returns a natural language response based on the results from the executed aggregation.	answer

Example returning all three steps

Imagine a tabletennis collection that records the results of the matches of two players.
Asking the question Who won the last match? results in a request that looks like this:

Node.js

const res = await FlorentineAI.ask({
  question: "Who won the last match?",
  returnTypes: ["aggregation", "result", "answer"]
});

cURL

curl https://nltm.florentine.ai/ask \
  -H "content-type: application/json" \
  -H "florentine-token: <FLORENTINE_API_KEY>" \
   -d '{
    "question": "Who won the last match?",
    "returnTypes": ["aggregation", "result", "answer"]
  }'

And the response looks like this:

{
  "database": "samples",
  "collection": "tabletennis",
  "aggregation": [
    { "$sort": { "year": -1, "matchInYear": -1 } },
    { "$limit": 1 },
    {
      "$project": {
        "winner": {
          "$cond": {
            "if": { "$eq": ["$matchwinner", "home"] },
            "then": "$players.home",
            "else": "$players.away"
          }
        }
      }
    }
  ],
  "result": [{ "_id": "67d352056d3ef0f2281524cf", "winner": "Frank" }],
  "answer": "Frank won the last match. According to our records, he emerged as the winner, highlighting his strong performance in that game."
}

Please note

The API only executes the steps neccessary, so i.e. if you only provide aggregation in the returnTypes, the aggregation is not executed and no natural language answer generated, which increases the response time.