Maira Integration

In the previous tutorials, we went through Maira's Data Management, Data Training, Profile and Settings management. After these steps, now you are ready to integrate Maira into your system, to send queries and get customized responses.

We have two endpoints for getting response from Maira

POST /v1/maira/ask
POST /v1/maira/vision

Integration - GPT Ask

To send queries with text only, use the endpoint POST /v1/maira/ask. Here is a sample request body:

{
  "user_id": "a0cc6beb-2909-459b-be55-62196af78ce4",
  "member_id": "df3456tg-2909-459b-be55-62196afedf85",
  "query": "ask anything you want...",
  "conversation_type": "question",
  "gpt_profile_id": "48b3bc7c-0af1-4fd5-a8c4-b15015f46e44",
  "context_preference": {
    "preferred": {
      "dataset_id": "123456",
      "project_id": 45678
    },
    "excludes": {
      "client_id": "48b3bc7c-0af1-4fd5-a8c4-b15015f46e44"
    }
  },
  "conversation_metadata": {
    "project_id": "project1",
    "client_id": "client1"
  },
  "session_id": "48b3bc7c-0af1-4fd5-a8c4-b15015f46e44",
  "result_includes": [
    "key_name_1",
    "key_name_2"
  ],
  "top_k": 20,
  "keyword_ngram": 3,
  "is_keyword_enabled": true,
  "acknowledge_only": false
}

Lets go through the parameters:

user_id: A unique identifier for the user making the request. This is a required field and must be a non-empty string.
member_id (optional): An identifier for a member associated with the request. member_id represents the logged in unique id of an user. This is useful to identify users across platforms or devices.
query (str): The query text that the user wishes to ask Maira. It must be a non-empty string (required field).
conversation_type (optional): Defines the type of conversation. Acceptable values are question and chat. default value is question. chat type conversation takes previous conversations into context to reply. whereas question type only considers the present query and not aware of the previous interaction. For example:

Chat-based conversation (remembers context):
```
  - User_query-1: I like sci-fi books. Can you suggest some?
  - AI_reply: Sure, here are some great sci-fi books for you.
  - User_query-2: Can you recommend some movies too?
  - AI_reply: Since you like sci-fi, here are some sci-fi movies you might enjoy.
```
Question-based conversation (no memory of context):
```
  - User_query-1: I like sci-fi books. Can you suggest some?
  - AI_reply: Sure, here are some great sci-fi books for you.
  - User_query-2: Can you recommend some movies too?
  - AI_reply: Here are some popular movies --> Not considering the sci-fi preference.
```
Note: using the setting in profiles chat_length, we can set how many previous interactions AI will consider to generate the reply for current query.
gpt_profile_id (Optional): Here you can specify the GPT profile to be used for this session. As discussed in the Profile Tutorial, you can have multiple profiles for various needs. Here, you can pass the profile_id you want to use for the scenario. If no profile_id is provided, the default profile will be used. (Refer to the Profile Tutorial to learn more about the default profile.)
context_preference (Optional): Allows specifying preferences for context usage, including preferred and excluded datasets or projects.In the above example, there is a preference for a dataset_id and a project_id, and a specific client_id is excluded. Here you can use dataset_id, idx_column, secondary_idx_column, or keys you included in filterable_fields of your datasets.
conversation_metadata (optional): Additional metadata related to the conversation, such as project and client identifiers. This can be an empty dictionary/object or omitted. You can add anything here.
session_id (optional): An identifier for the session. Sessions are used to track the context of the conversation. Conversations of the same session, will know the context of the previous conversations. Note that how many previous conversations will be used as context, is defined in the profile under the "chat_history_length": 3 parameter. See more detail in the "Profiles" tutorial
result_includes (optional): A list of specific keys or fields that should be included in the response. Defaults to an empty list/array.
top_k (optional): This controls the number of top keywords to consider, while prioritizing reference documents. The value can be between 1 and 20. Defaults to 20. A higher top_k value considers more keywords, broadening the search, while a lower value narrows it down to fewer, more specific terms, making Maira more strict with its response.
keyword_ngram (optional): Defines the n-gram size for keyword extraction, constrained between 1 and 3. Defaults to 3.
- Based on these settings, the model will identify the top keywords from a query, allowing for more flexible and accurate extractions. For example, for the sentence "I love natural language processing."
  - If value is 1: ["I", "love", "natural", "language", "processing"]
  - If value is 2: ["I love", "love natural", "natural language", "language processing"]
  - If values is 3: ["I love natural", "love natural language", "natural language processing"]
- Each n-gram represents a sequence of words from the sentence based on the specified value of n.
is_keyword_enabled (optional): A flag indicating whether keyword extraction is enabled. Defaults to True.

Tip

When Enabled (True)

The system prioritizes exact keyword matches.
Effect: Enhances precision by ensuring only documents containing the exact terms are retrieved. However, this may exclude relevant results that use different wording.
Use Case: Ideal for scenarios requiring highly specific matches, such as regulatory compliance, legal research, and technical terminology.

Examples:

Supply Chain Management: Searching for "ISO 28000 certification" in a compliance database to find documents that specifically mention this supply chain security standard.
Cybersecurity Reports: Looking for "Zero Trust Architecture" in technical documents to retrieve materials that focus strictly on this specific security framework.

When Disabled (False)

The system prioritizes semantic matching and broader relevance.
Effect: Expands search coverage by considering synonyms and related concepts, which increases the number of results but may reduce precision.
Use Case: Best suited for exploratory research, brainstorming, and when variations of a keyword matter.

Examples

Market Research: Searching for "sustainable fashion trends" to find reports on ethical clothing, eco-friendly materials, and slow fashion.
Academic Research: Looking up "climate change policies" to retrieve papers covering carbon emissions, global warming regulations, and environmental sustainability initiatives.

Recommendation:

Turn On: When highly specific and targeted results are necessary (e.g., compliance verification, legal or technical document retrieval).
Turn Off: When a broader set of relevant results is required (e.g., exploratory research, brainstorming, or when keyword variations are important).

acknowledge_only: If True, only logs the query without returning results. When building AI agents, not all inputs require an immediate response—sometimes, the agent only needs to listen and retain context for future interactions. This flag enables that functionality, improving contextual continuity in conversations.

Now after the project setup is done, if you want to try the endpoint with the minimum required parameters, you can use the below request body. Note that a default profile must be set first (refer to the settings tutorial).

{
  "user_id": "test_12345",
  "query": "tell me what you know",
  "conversation_type": "question",
  "context_preference": {
    "preferred": {},
    "excludes": {}
  },
  "conversation_metadata": { },
  "result_includes": [],
  "top_k": 20,
  "keyword_ngram": 3,
  "is_keyword_enabled": true
}

Note that once you hit the response, in the response, you will get a conversation_id in the response. We will talk about this in detail in the "Maira Evaluation" Tutorial.

Integration - GPT vision

POST /v1/maira/vision endpoint, which can generates response based on image and your query,

Similar to GPT ask in the previous section, to integrate this endpoint, in additional to the above parameters, you have to pass the image. Currently below image formats are acceptable

webp
jpeg
jpg
png

Note that for this endpoint, unlike POST /v1/maira/ask, some parameters are not required such as top_k, keyword_ngram, is_keyword_enabled.