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/gpt/ask
POST /v1/gpt/ask/vision

Integration - GPT Ask

To send queries with text only, use the endpoint POST /v1/gpt/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
}

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 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.

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/gpt/ask/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/gpt/ask, some parameters are not required such as top_k, keyword_ngram, is_keyword_enabled.