Required Inputs

Required Inputs enable secure data separation by ensuring aggregation pipelines filter data based on provided values without relying on the LLM service.

See Required Inputs feature for more information on how you define specific keys as Required Inputs.

Providing Required Inputs

Include a requiredInputs array in your API request with keyPath and value.

Node.js

const res = await FlorentineAI.ask({
  question: "What is the revenue of my products this year?",
  requiredInputs: [
    {
      keyPath: "accountId",
      value: "507f1f77bcf86cd799439011"
    }
  ]
});

cURL

curl https://nltm.florentine.ai/ask \
  -H "content-type: application/json" \
  -H "florentine-token: <FLORENTINE_API_KEY>" \
   -d '{
    "question": "What is the revenue of my products this year?",
   "requiredInputs": [
      {
        "keyPath": "accountId",
        "value": "507f1f77bcf86cd799439011"
      }
    ]
  }'

You may also provide a database and a collections array in case you have Required Inputs with the same keyPath in multiple collections but different value for the collections:

Node.js

const res = await FlorentineAI.ask({
  question: "Whats the current monthly rent of my tenants?",
  requiredInputs: [
    {
      keyPath: "name",
      value: "Sesame Street",
      database: "rentals",
      collections: ["houses"]
    },
    {
      keyPath: "name",
      value: { $in: ["Ernie", "Bert"] },
      database: "rentals",
      collections: ["tenants"]
    }
  ]
});

cURL

curl https://nltm.florentine.ai/ask \
  -H "content-type: application/json" \
  -H "florentine-token: <FLORENTINE_API_KEY>" \
   -d '{
    "question": "Whats the current monthly rent of my tenants?",
   "requiredInputs": [
      {
        "keyPath": "name",
        "value": "Sesame Street",
        "database": "rentals",
        "collections": ["houses"]
      },
      {
        "keyPath": "name",
        "value": { "$in": ["Ernie", "Bert"] },
        "database": "rentals",
        "collections": ["tenants"]
      }
    ]
  }'

Required Inputs Configuration

Field	Required	Type	Description	Constraints
keyPath	Yes	String	The path to the field that should be filtered.	Must be a valid key path.
value	Yes	Any	The value(s) to filter by (type-specific, see Supported Value Types).	Must match the field's type (String, ObjectId, Boolean, Number, or Date).
database	No	String	The database containing the collections to filter.	Must be provided if collections is provided.
collections	No	Array<String>	The specific collections within the database to apply the filter to.	Must contain at least one collection.

Supported Value Types

Based on the type of the values for the key you have different options on what you can provide as a Required Input value:

Type	Format Examples	Operators Supported	Notes
String or Array<String>	"text" { $in: ["text1", "text2"] }	$in	Case-sensitive.
ObjectId or Array<ObjectId>	"507f191e810c19729de860ea" { $in: ["507f191e810c19729de860ea", "507f191e810c19729de860eb"] }	$in	Provided as strings.
Boolean	true/false	—	Only exact values.
Number or Array<Number>	42 { $gt: 10, $lte: 100 } { $in: [1, 2, 3] } { $in: [{$gte:1}, {$lt:10}] }	$gt, $gte, $lt, $lte, $in	Supports decimals.
Date or Array<Date>	"2024-01-01T00:00:00Z" (UTC) "2024-01-01T00:00:00-05:00"(timezone offset)	$gt, $gte, $lt, $lte, $in	ISO 8601 format.

Usage Examples

Example type: String

Usecase: A user should only be able to see statistics of the players he frequently plays with.

Solution: Restricting access by player name to a group of 4 players.

Node.js

const res = await FlorentineAI.ask({
  question: "Which player had the most wins?",
  requiredInputs: [
    {
      keyPath: "name",
      value: { $in: ["Megan", "Frank", "Jen", "Bob"] }
    }
  ]
});

cURL

curl https://nltm.florentine.ai/ask \
  -H "content-type: application/json" \
  -H "florentine-token: <FLORENTINE_API_KEY>" \
   -d '{
    "question": "Which player had the most wins?",
   "requiredInputs": [
    {
      "keyPath": "name",
      "value": { "$in": ["Megan", "Frank", "Jen", "Bob"] }
    }
  ]
  }'

Example type: ObjectId

Usecase: A user should only be able to see the revenue of his own products.

Solution: Restricting the access by the accountId to one specific account.

Node.js

const res = await FlorentineAI.ask({
  question: "Whats the revenue of my products?",
  requiredInputs: [
    {
      keyPath: "accountId",
      value: "507f1f77bcf86cd799439011"
    }
  ]
});

cURL

curl https://nltm.florentine.ai/ask \
  -H "content-type: application/json" \
  -H "florentine-token: <FLORENTINE_API_KEY>" \
   -d '{
    "question": "Whats the revenue of my products?",
   "requiredInputs": [
    {
      "keyPath": "accountId",
      "value": "507f1f77bcf86cd799439011"
    }
  ]
  }'

Example type: Boolean

Usecase: Every analysis of customers should only be performed on paying customers.

Solution: Restricting the access by isPaidAccount to paying customers only.

Node.js

const res = await FlorentineAI.ask({
  question: "How many customers registered in the last year?",
  requiredInputs: [
    {
      keyPath: "isPaidAccount",
      value: true
    }
  ]
});

cURL

curl https://nltm.florentine.ai/ask \
  -H "content-type: application/json" \
  -H "florentine-token: <FLORENTINE_API_KEY>" \
   -d '{
    "question": "How many customers registered in the last year?",
   "requiredInputs": [
    {
      "keyPath": "isPaidAccount",
      "value": true
    }
  ]
  }'

Example type: Number

Usecase: An employee should only be allowed to see payment information for payments below a certain amount.

Solution: Restricting the access by amount to payments below 10.000.

Node.js

const res = await FlorentineAI.ask({
  question: "List all payments we received.",
  requiredInputs: [
    {
      keyPath: "amount",
      value: { $lt: 10000 }
    }
  ]
});

cURL

curl https://nltm.florentine.ai/ask \
  -H "content-type: application/json" \
  -H "florentine-token: <FLORENTINE_API_KEY>" \
   -d '{
    "question": "List all payments we received.",
   "requiredInputs": [
    {
      "keyPath": "amount",
      "value": { "$lt": 10000 }
    }
  ]
  }'

Example type: Date

Usecase: The analysis of financial data should only include one specific year.

Solution: Restricting the access by transactionDate to all transactions in 2024.

Node.js

const res = await FlorentineAI.ask({
  question: "What was our revenue, profit and margin per month?",
  requiredInputs: [
    {
      keyPath: "transactionDate",
      value: {
        $gte: "2023-01-01T00:00:00Z",
        $lt: "2024-01-01T00:00:00Z"
      }
    }
  ]
});

cURL

curl https://nltm.florentine.ai/ask \
  -H "content-type: application/json" \
  -H "florentine-token: <FLORENTINE_API_KEY>" \
   -d '{
    "question": "List all payments we received.",
    "requiredInputs": [
      {
        "keyPath": "amount",
        "value": {
          "$gte": "2023-01-01T00:00:00Z",
          "$lt": "2024-01-01T00:00:00Z"
        }
      }
    ]
  }'