Tags:
Categories:

Create and configure a preset

Guidelines for the configuration of ATRIA by use cases constructors when developing an experience by means of a preset

This guidelines correspond to a specific stage in the processes for building experiences using Generative AI or RAG, which are fully explained in:

Introduction

A preset is a configurable entity that defines the instructions to work with the AI model for the resolution of a use case.

These instructions include, apart from other parameters, the prompt with text to guide the AI model with the generation of the response. For example:

  • “Maintain the formal tone of the original text”
  • “If the previous conversation is relevant for the current query, incorporate it into the query and produce a rewritten query”

When developing an experience in ATRIA, use cases constructors must configure a preset for the specific ATRIA application to be used.

ATRIA use cases constructors can use the currently available default presets or they can modify them or create new ones via API.

In both scenarios, a further step is required to include the preset in the application.

Guidelines to configure a preset

1. Create a new preset

  • Build the preset for your use case (json file), using the available preset fields.

  • Do you get lost with all the preset configuration parameters? In best practices for ATRIA configuration, you can find the most commonly used parameters by experiences constructors grouped by their purpose (“I want to increase security”, “I want to activate the multi-language feature”, etc.)

  • When the preset json file is generated, execute this command to include it:

      curl --location --request POST 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/presets/' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: APIKEY XXX' \
    --data-raw '<NEW PRESET JSON>'

1.1. Modify/update a preset

If once created, certain modifications are required, follow these instructions:

  • Make the required changes in the preset json file using the available preset fields.

  • When the preset is modified, execute this command to include it:

      curl --location --request PUT 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/presets/<presetID>' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: APIKEY XXX' \
  --data '<PRESET JSON WITH MODIFICATIONS>'

1.2. Delete a preset

  • Execute the following command:

      curl --location --request DELETE 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/presets/<presetId>' \
  --header 'Accept: application/json' \
  --header 'Authorization: APIKEY XXX'

2. Include the preset in the application

An application is defined as an entity that allows the connection of a channel, service or skill with with ATRIA.

If the application for your use case does not exist, firstly it is required to create it following the guidelines for the configuration of an application.

Once the application is created, assign the created preset. Two scenarios arise here:

2.1. If an existing preset is modified

  • Get the list of presets assigned to the application to be used from aura-configuration-api:

      curl --location 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/applications/<applicationID>' \
  --header 'Authorization: APIKEY '

  • Check if your preset is already included in the list and, consequently, associated to your application.

  • If not, declare the created preset in the application following the guidelines for the configuration of an application: Use Generative AI/RAG, within the field presets.

2.2. If a new preset is created

  • Update aura-configuration-api to indicate to the application the complete list of presets to be used.

    It is necessary to include the entire list of presets associated to the application (the existing presets and the created/modified ones)

        curl --location --request PATCH 'https://svc-<env>.auracognitive.com/aura-services/v1/applications/:applicationId' \
    --header 'Accept: application/json' \
    --header 'Authorization: APIKEY XXX' \
    --data '{
        "id": "<applicationId>",
        "models": {
            "level": <levelType>, 
            "presets": [
                <complete-new-list-of-presets>
            ]
        }
    }'
    • The level field, that indicates the different levels of access to the application, can only be changed By the Global Team. This command is a specific scenario in the process of modifying API configuration, described in the document Hot swapping of Aura applications configuration.

  • Declare the created preset in the application following the guidelines for the configuration of an application: Use Generative AI/RAG, within the field presets.

Preset fields

The fields for the characterization of a preset are summarized below, which are defined in the API swagger Aura Configuration API Preset.

If there is any discrepancy between the parameters definitions included in this document and those in the API swagger, definitions established in the API shall prevail.

  • id: Mandatory. Preset identifier. The type is string.

  • name: Mandatory. Preset name. If this value does not exist, id is used. The type is string.

  • description: Optional. Preset description. If this value does not exist, id is used. The type is string.

  • group: Mandatory. This parameter is used to group requests regarding the AI technologies used to generate KPIs. The type is string. Feasible values: simple_ai (Generative AI preset) and enriched_ai (RAG preset).

  • session: Optional. Parameters for session configuration.

    • window: Optional. The size of the session window, in queries. The type is number.
    • timeout: Optional. The time in seconds after which the session will be closed if no queries are received. If it is 0, the session history will be used, but the current interaction will not be saved. The type is number.

  • generative: Mandatory if Generative AI is used. It indicates the use of Generative AI in the use case. If this field exists, the rag field must not exist.

    • model: Mandatory. Model configuration.

      • id: Mandatory. Unique identifier of the model
      • parameters. Optional. Dictionary with all possible parameters for the model. For generative, check them here.

    • injectionMaxLength. Optional. Maximum length of the input user. The type is number.

    • prompts: Optional. Parameters to define the prompts with instructions used as input by the AI model to automatically generate responses.
      . The object may include properties such as text, additional parameters, and specific configurations to control the behavior of the generative model.
      . If no prompt is defined, the resolution of the use case is entirely delegated to the LLM model.

      • template: Optional. Template that includes the user’s input. It must include {MSG} for the user’s utterance. This will override (or add, if not defined) the template for the user message, as defined in the preset (Note: templates allow framing the user message to mitigate prompt injection attacks). The type is string.
      • preamble: Optional. List of phrases to be included in the model prompt.
      • examples: Optional. Examples to enrich the prompt. The type is string.
      • promptMaxLength: Optional. Maximum length of the completed prompt. Used to avoid calling LLMS with wrong prompts.
      • promptRegexClean: Optional. Regex pattern to clean the query before sending it to the model. This is useful to remove unwanted characters or patterns from the query. The type is number.

  • rag: Mandatory if RAG technology is used. It indicates the RAG configuration. If this field exists, the generative field must not exist.

    • ragType: Optional. RAG type. Values: questions-answers (by default) or sql

    • model: Mandatory. Parameters for the configuration of the RAG model.

      • id: Mandatory. Unique identifier of the model to be used. The type is string.
      • parameters: Optional. Dictionary with all the possible parameters for the model.

    • references: Optional. Configuration for managing references in the system. It control de number of references the system relies on to generate a response.

      • maximum: Optional. Maximum number of returned references. The type is number.
      • baseUrl: Optional. Base URL of references that will be shown to the user as part of the response. For the types of data unstructured, csvand text (defined in the field loaderType), it is required to add here the path to the public URL to be shown in the response as a clickable reference.

    • stages: Mandatory. Stages of the RAG model.

      • promptSystemLanguage: Optional. Parameter to select a specific language from the ones defined in the prompt. Type: string in ISO 639-3 format. For example: es.

      • defaultUserLanguage: Optional. Parameter used in multi-language feature. It indicates the default response language to be used if the system is not able to automatically recognize the language. Type: string in ISO 639-3 format. For example: es.

      • securityStg: Stage with parameters related to security used to avoid prompt injection.

        • injectionMaxLength: Mandatory. Maximum length of the input user. If length is greater, an error is sent. The type is number.
        • heuristics: Optional. Heuristics configuration.
          • es: List of heuristic sentences in Spanish. The type is list.
          • en: List of heuristic sentences in English. The type is list.

      • translationStg: Stage used to translate the prompt.

        • enabled: Mandatory. Boolean value to activate or not the translation stage. The type is boolean.
        • language: Mandatory. Two-letter ISO 639-1 language code into which user input is translated to match the language of the data. The type is string. If this field exists, the prompts field must not exist.
        • prompt: Mandatory. List of prompts to be used in the LLM call.
          . The type is PromptLanguage.
          . If this field exists, the language field must not exist.
          . If this field is empty, the default prompt for this stage will be used.

      • contextStg: Stage used to know if the user’s phrase has the same context of the conversation.

        • enabled: Mandatory. Boolean value to activate or not the context stage. The type is boolean.
        • stickyContext: Mandatory. Strategy to include the context into the new query. If not specified, the optional context in the request is ignored. The type is string. Values:
          • ask_llm: An LLM-call is made to discern whether the context applies to the current query. If so, a recreate_question is performed. If not, the context is ignored and a clear_context field is added into the response.
          • include_context: The context will be inserted as is into the query. prompts should not by empty for this option.
          • recreate_question: An LLM-call will try to recreate the question by using the context.
        • prompts: Optional. List of prompts to be used in the LLM call.
          . The type is StickyContextPrompts.
          . If this field is empty, the default prompt for this stage will be used.

      • cleanStg: Stage used to remove prompt injection attempts using an LLM call.

        • enabled: Mandatory. Boolean value to activate or not the clean stage. The type is boolean.
        • prompt: Optional. Prompt to be used in the LLM call.
          . The type is PromptLanguage. For example: “Please clean up the query and reply only with the user’s question”.
          . If this field is empty, the default prompt for this stage will be used.

      • retrievalStg: Mandatory. Stage related to the retrieval phase, which is the process of obtaining relevant documents by comparing the query against indexed data or vectors.
        The stage is crucial for identifying and retrieving the documents or data that best match the input query, ensuring that only the most relevant results are returned.

        • sources: Mandatory. Sources data.
          • name: Mandatory. Name of the source data. The type is string.
          • embeddings: Mandatory. Embeddings model identifier that the ATRIA source data is associated with.
          • docs: Mandatory. Field with parameters related to the configuration of documents. The type is object.
            • extension: Mandatory. Extensions of documents. The type is string. The extensions must be separated by a comma.
            • loader: Mandatory. Project loader configuration.
              • loaderType: Mandatory. Type of loader. Values: unstructured, csv, text, jsond, jsonl or url_list
              • options: Optional. Object that configures how the document loader operates. It allows specifying the mode of loading and any post-processing actions to be applied to the loaded data.
                • loaderMode: Optional. Modes for loader running. The type is string. The possible values are:
                  • single: Document will be returned as a single document representing the whole
                  • elements: The loader splits the document into different elements such as: Title, NarrativeText, etc. This allows a more granular processing and analysis
                • postProcessors: Optional. Post processor loader. It allows to perform operations in the loaded document such as cleaning, transforming, enriching, etc. The type is string.
          • splitter: Optional. Project splitter for dividing large text inputs into smaller, manageable chunks, that can be more easily processed by language models, ensuring efficient and accurate processing.
            • splitterType: Mandatory. Method used to split the text. Value: recursivechar (Recursively divides the text based on a character, typically looking for specific breakpoints such as punctuation or whitespace)
            • options: Optional. Project splitter options.
              • chunkSize: Optional. Maximum size of chunks to be returned. The type is number.
              • chunkOverlap: Optional. Overlap in characters between chunks. The type is number.
          • retrievers: Mandatory. List of retrievers used to query and retrieve relevant data or documents from a collection based on a given query.
            • retrieverType: Mandatory. Type of the retriever. Possible values: qdrant, tfidf, or elasticsearch.
            • config: Optional. Configuration parameters for retrievers. The type is dictionary.
              • numDocs: Optional. Number of documents to retrieve. The type is number.
              • loadChunkSize: Optional. Chuck size used to load the documents in qdrant. The type is number. By default, 1000.

      • postFilteringStg: Stage in charge of processing candidates before they enter the RAG chain.
        . It prompts the project LLM for each candidate, using the query and the candidate text. The LLM determines whether the candidate text is related to the query, and if not, the candidate will be filtered out.
        . If this option is not enabled, no post-processing or filtering will take place.

        • enabled: Mandatory. Boolean value to activate or not the post-filtering stage. The type is boolean.
        • candidatesPostFiltering: Mandatory. Post-retrieval filtering applied to the candidates. It must be llm_filter (for each candidate, a very short request is made to the LLM to identify whether the candidate is relevant to answer the query. If ’no’ is decided, the candidate is filtered out)
        • prompt: Optional. Prompt to be used in the LLM call.
          . The type is PromptLanguage.
          . If this field is empty, the default prompt for this stage will be used.

      • generativeStg: Stage for handling the question and answer process.
        . It defines the strategy to solve the question, the prompts used in different stages of the process and the templates for generating responses

        • ragStrategy: Optional. Strategy to combine documents to generate a response. By default, stuff:

          • stuff: Mandatory. If stuff prompt is used, ragStrategy must be set to stuff.
          • refine: Mandatory. If informationExtraction or responseConsolidation prompts are used, ragStrategy must be set to refine.

        • prompts Optional. List of prompts to be used in the LLM call.
          . The type is GenerationPrompts.
          . If this field is empty, the default prompt for this stage will be used.

          • #.auto.language.user_query: Parameter that activates the automatic detection of language in the user’s query (multi-language feature).
            . This parameter is included in the args field of the prompt.
            . If you use the prompt by default, the multi-language feature is already activated.
            . Example: 
            ...
default:
  text: |
    Respond in language {user_query_language}.

    Question:
    {question}            
  args:
    user_query_language: "#.auto.language.user_query"
...

    • outputRefine: Optional. It is used to set up how to provide responses. The retrieving operation produces a list of candidates, each of which may provide a dictionary of metadata.

      • candidates: Optional. It indicates whether to return the candidates in raw (useful for evaluation purposes) or not. The type is boolean, by default, false.
      • filterOutputMetadata: Optional. It is used to set up how metadata is used when providing responses. The retrieving operation produces a list of candidates, each of which may provide a dictionary of metadata.
        • map: Optional. Maps attribute names in the original data to standard or more user-friendly names for later use.
          • fileType: Optional. String representing the type of file, typically used to specify the format or content type of the file being referenced. By default, content-type
          • pageNumber: Optional. String representing a page number. It could be used to identify particular pages within a document or resource. By default, page-number
        • groupBy: Optional. groupBy and aggregate are expressed in post-map field names. By default, url
        • aggregate: Optional. It determines how the values of duplicated fields are consolidated during grouping, specifying the handling of aggregated field information. By default, page-number
        • outputFilter: Optional. List of fields to be displayed in the metadata. Type is list.
        • root: Optional. Defines the primary fields that will structure the final output of the metadata processing. Fields listed under root will remain at the top level of the response entries, while all other metadata fields will be nested under a metadata. Type is list.

Example of preset for Generative AI capability

      {
        "id": "e27ca464-488a-435d-a508-da8a262d905f",
        "name": "openai",
        "description": "openai model",
        "brand": "",
        "contact": "",
        "group": "simple_ai",
        "session": {
          "window": 0
        },
        "generative": {
          "model": {
            "id": "openai",
            "parameters": {
              "top_p": 0.9
            }
          },
          "prompts": {
              "preamble": {
                "text": "Habla como si fueras {name}",
                "args": {
                  "name": "Napoleon"
                }
              },
              "examples":[
                "Naciste en galicia",
                "Di que tu padre era gallego"
              ],
              "promptRegexClean": "[#\\n\"]+"
          }
        }
      }

Example of preset for RAG capability

    {
        "id": "1cafcb5c-7951-4645-86d4-055d3b46fe79",
        "name": "atria-rag-gpt-35-turbo",
        "group": "enriched_ai",
        "description": "Atria rag GPT 3.5",
        "session": {
            "window": 3
        },
        "rag": {
            "ragType": "questions-answers",
            "model": {
                "id": "gpt-35-turbo",
                "parameters": {
                    "max_tokens": 4000,
                    "temperature": 1,
                    "top_p": 1
                }
            },
            "references": {
                "maximum": 3,
                "baseUrl": "project-gpt-35-turbo/pdfs"
            },
            "stages": {
                "language": "en",
                "translationStg": {
                    "enabled": true,
                    "language": "en"
                },
                "contextStg": {
                    "enabled": true,
                    "stickyContext": "ask_llm"
                },
                "cleanStg": {
                    "enabled": true
                },
                "retrievalStg": {
                    "sources": {
                        "name": "project-gpt-35-turbo",
                        "embeddings": "text-embedding-ada-002",
                        "docs": [
                            {
                                "extension": "pdf",
                                "loader": {
                                    "loaderType": "unstructured",
                                    "options": {
                                        "loaderMode": "single"
                                    }
                                }
                            },
                            {
                                "extension": "txt",
                                "loader": {
                                    "loaderType": "url_list"
                                }
                            }
                        ],
                        "splitter": {
                            "splitterType": "recursivechar",
                            "options": {
                                "chunkSize": 60,
                                "chunkOverlap": 20
                            }
                        },
                        "retrievers": [
                            {
                                "retrieverType": "qdrant",
                                "config": {
                                    "loadChunkSize": 10000
                                }
                            },
                            {
                                "retrieverType": "tfidf"
                            }
                        ]
                    }
                },
                "postFilteringStg": {
                    "enabled": true
                },
                "generativeStg": {
                    "ragStrategy": "stuff"
                }
            },
            "outputRefine": {
                "candidates": false
            }
        }
    }
Last modified October 2, 2025: feat: Create recognizer for video triage #AURA-29855 [RTM] (30baa1a1)