Perform RAG Action

Sends a prompt to, or adds and removes data from, a RAG space on the AI model server specified by a RAG account.

Options 

• RAG Account Name is a text expression of the RAG account for this script step to use. In the current file, use the Configure RAG Account script step to set up the account and assign it this name any time before this script step runs.

• Space ID is a text expression that specifies the unique ID of the RAG space to work with in the specified RAG account.

• Action specifies the type of operation to perform on a RAG space. This option controls the availability of other options in the script step. Choose from:

  • Add Data adds a document (text data or a PDF file) to a RAG space.

  • Send Prompt sends a prompt to query a RAG space and get an AI-generated response.

  • Remove Data removes documents from a RAG space.

Additional options available when Action is Add Data:

• RAG Data specifies the document to add to the RAG space:

  • From Text adds text directly via a text expression, transferred synchronously.

  • From File adds a PDF file given a path, transferred synchronously.

  • From File (Async) adds a PDF file given a path, transferred asynchronously (best for large files).

  • From Container adds a PDF file from a container field, transferred synchronously.

  • From Container (Async) adds a PDF file from a container field, transferred asynchronously (best for large files).

• Input File specifies a list of one or more paths for a PDF file. The script step searches the list and adds the first PDF file it successfully locates. Paths must use one of the image path prefixes. See Creating file paths.

• Container Field specifies the container field that stores the PDF file to add.

• Detect vertical text improves text extraction from PDF files that contain vertical text commonly found in Japanese literary works, newspapers, government documents, and academic papers. This option isn't available when RAG Data is From Text.

• Tokens per Text Chunk is a numeric expression that specifies how many tokens to include in each text chunk when adding text or PDF files to the RAG space. Valid values are 75 to 512. If not specified or set to 0, the value configured for the AI model server in Admin Console is used (200 tokens by default).

• Response Target specifies the field or variable in which to store a JSON object returned by the AI model server about the added document. See Description.

Additional options available when Action is Send Prompt:

• The value for Send Prompt is a text expression for the natural language user prompt or question.

• AI Account Name is a text expression for the name of the AI account to use to generate a response. In the current file, use the Configure AI Account script step to set up this account and assign it this name any time before this script step runs.

• Model is the name of the text generation model to use. Specify the model name as a text expression. For supported models, see FileMaker technical specifications.

• Stream controls how the response is delivered:

  • On: The response is retrieved and delivered incrementally (word by word or in phrases). This can make the FileMaker client feel more responsive.

  • Off: The entire response is retrieved before it is made available. This may cause the FileMaker client to appear unresponsive while waiting for the complete response.

• Prompt Template Name specifies the name of a custom prompt template configured using the Configure Prompt Template script step. Use this option to design an additional prompt to help achieve an optimal response from an AI model.

• Response Target specifies the field or variable where the response from the model is to be stored.

• Parameters is a text expression for a JSON object that can include:

  • FileMaker client parameters that are processed and removed before sending the request:

    CURLOPT_TIMEOUT sets a maximum time (in seconds) for the request to complete. The value must be a non-negative integer. For example: {"CURLOPT_TIMEOUT": 30}. If there's no response in this time, the FileMaker client cancels the request and this script step returns error code 1629 ("Connection timed out").

  • AI model server parameters that override settings configured in Admin Console only for the duration of this script step. If not specified, the values set in Admin Console are used. These parameters are processed and removed before passing any other parameters you include in the JSON object directly to the model provider.

    See Description for details.

  • Model provider-specific parameters that are passed directly to the model provider along with the prompt. For example: {"temperature": 0.7, "seed": 42}.

    Note  Refer to the model provider's documentation for the parameters and values supported by the model you're using.

Additional options available when Action is Remove Data:

• Parameters is a text expression for a JSON object containing an id key whose value is an array of the IDs of the documents to be removed from the specified RAG space. For example:

  Copy

  {"id" : ["5f7677a0-3258-55a3-bc86-737005cb3574", "f95d4266-66cd-5b50-a01b-07a4dd66c501"]}

  Document IDs returned in Response Target when the document was added can be stored and later used to remove a document. Or, to get the IDs of all documents in a RAG space, use the GetRAGSpaceInfo function.

Originated in version 

22.0

Description 

This script step lets you create and manage a knowledge cache of documents (text data and PDF files) on Claris AI Model Server. You can then leverage this cache with a technique called retrieval-augmented generation (RAG). Using this technique, the script step sends a prompt or question to an AI model along with the most relevant facts retrieved from your knowledge cache, improving the reliability and accuracy of the response from the model.

The Action option determines what this script step does.

Add Data action

This action adds RAG Data from the specified document: text (as any text expression), a PDF file by path, or a PDF file from a container field in the current or related record. The process follows these steps:

1. The script step sends the document to the AI model server.

   If adding a PDF file, the script step sends the file synchronously or asynchronously, depending on the RAG Data option. If sending synchronously, the script doesn't continue to the next step until the file transfer is done. If sending asynchronously, the script continues to the next step while the file transfer is in progress (best for large files), allowing the FileMaker client to remain responsive to user interaction.

2. The AI model server assigns an ID to the document then processes it:

   • If the document is a PDF file, the server extracts only text from the PDF file. The extracted text is then processed in the same way as text added using the From Text option.

   • The server breaks the text into chunks based on the Tokens per Text Chunk option (if specified) or the chunk size configured in Admin Console.

     If the text is in JSONL (JSON Lines) format—where each line is a valid JSON object—the server automatically detects this format and treats each line as a separate semantic unit: each line is chunked separately, but lines are never merged together. This helps improve retrieval accuracy for structured data such as that added from a FileMaker table, where each record can be formatted as a single JSON line, ensuring that record boundaries are preserved.

   • Finally, the server gets embedding vectors for all chunks using the text embedding model that's configured for RAG on the server.

3. If a Response Target is specified, the AI model server returns a JSON object containing the document ID and metadata for the added document. This allows you to store the document ID for later use (such as removing the document).

   The returned JSON object contains these keys:

   • id: The document ID assigned by the AI model server as a hexadecimal-encoded Universally Unique Identifier (UUID). For more on the ID format, see Notes.

   • model: The embedding model used by the AI model server to generate embedding vectors for the document.

   • rag_space_id: The ID of the RAG space the document was added to.

   • result or error:

     • result: The status of the added document when there is no error. For successful synchronously transferred documents, the value is "ok". For documents transferred asynchronously, the value is a string that includes the space ID and the cached filename, because the process isn't complete yet.

     • error: An error message string when the AI model server encounters an error.

   • text or file, depending on the option for RAG Data:

     • text: The text of the document when added using the From Text option for RAG Data.

     • file: The filename of the PDF file when added using the file or container options for RAG Data.

   • usage: Token usage information when a document is transferred synchronously. The returned JSON object is {"prompt_tokens":<number>, "total_tokens":<number>}, where prompt_tokens is the number of tokens in the input (the text chunks that were embedded) and total_tokens is the total number of tokens processed. If the AI model server is set not to log token usage, no token counts are returned.

   Note  For documents transferred asynchronously, the rag_space_id, model, and usage keys return "N/A" because these values aren't available until processing completes.

Send Prompt action

This action sends the user prompt to the AI model server to get the most relevant data from the specified RAG space, then sends the user prompt along with the prompt template and RAG content to the AI model. The process follows these steps:

1. The script step sends the prompt specified by Send Prompt and the Space ID to the AI model server specified by RAG Account Name.

2. The AI model server gets embedding vectors for the prompt, performs a semantic search for the prompt in the specified RAG space, then returns the RAG results to the script step.

   The RAG results are the top N most relevant document chunks from the RAG space as text (N can be configured in Admin Console or overridden by the Parameters option as shown below).

3. The script step sends the prompt, prompt template, model Parameters, and RAG results to the model specified by AI Account Name and Model.

4. The model returns a response that the script step stores in Response Target.

AI model server parameters

For the Parameters option, you can use the following keys and values, which are specific to the AI model server, to adjust this script step's behavior. If specified, these values override those set in Admin Console. This is useful when different prompts require different levels of precision or context size (for example, querying a large document set as opposed to a small one). If a key isn't specified, the values configured in Admin Console are used.

For example, this JSON object sets these keys in the Parameters option:

{
    "similarity_threshold" : .5,
    "num_top_ranked_results" : 10
}

Remove Data action

This action removes documents from a RAG space. If specified in the Parameters option, only the specified documents are removed; otherwise all documents in the RAG space are removed.

Note  Removing documents from a RAG space can't be undone. Be sure to retain the original documents elsewhere in case you need to add them again.

Notes 

• A RAG account must be configured using the Configure RAG Account script step before using this script step.

• For Send Prompt actions, an AI account must also be configured using the Configure AI Account script step.

• PDF files with encryption or password protection can't be processed with the Add Data action.

• RAG spaces are persistent and retain their documents until explicitly removed using the Remove Data action.

• If you add a PDF file with the same filename as one already in the RAG space, the existing PDF file is removed and the new PDF file is added with a new document ID. This behavior is the same whether adding the PDF file via a path or a container field.

• Documents added to a RAG space before version 26.0.1 of the AI model server have numeric document IDs (for example, 1, 2, 3). Starting with version 26.0.1, document IDs are UUID strings (for example, "5f7677a0-3258-55a3-bc86-737005cb3574"). When working with RAG spaces that contain documents added before and after the ID format change, your scripts should handle both document ID formats.

  See Example 3.

• If you specify a Prompt Template Name, this script step uses the template set up via the Configure Prompt Template script step. Prompt templates can use the constants like :question: (replaced with the Send Prompt value) and :context: (replaced with the RAG-retrieved document chunks from the RAG space).

• For the Tokens per Text Chunk option:

  • Larger chunk sizes preserve more context but may reduce retrieval precision. Smaller chunk sizes improve precision but may lose context. Consider using larger values (for example, 250 to 300) for languages like Japanese, Chinese, or Korean, where tokenization produces fewer characters per token, so a fixed token count covers significantly less text.

  • To change the chunk size of existing documents in a RAG space, you must remove the documents from the RAG space and add them again with a new chunk size.

  • If you specify a value outside the valid range, this script step returns error code 887 ("Invalid RAG space action").

• The quality of AI responses depends on the model and the relevance and quality of the documents added to the RAG space.

• In FileMaker WebDirect, when this script step uses the Add Data action and RAG Data is From File or From File (Async), the Insert dialog opens for the user to choose a PDF file to upload; the Input File option is ignored.

Example 1 - Add text to a RAG space

Adds text content to a RAG space for a customer knowledge base.

Configure RAG Account [ RAG Account Name: "customer-support-rag-account" ; Endpoint: "https://myserver.example.com/llm/v1/" ; API key: "eyJh..." ; Verify SSL Certificates ]

Perform RAG Action [ RAG Account Name : "customer-support-rag-account" ; Space ID: "knowledge-base" ; Action: Add Data ; RAG Data: From Text ; "Customer support policies and procedures for handling returns and exchanges..." ]

Example 2 - Send a prompt to query a RAG space

Sends a prompt to query the same RAG space as in Example 1 and stores the response in a field.

The script sets up both the RAG account and the AI account to use the AI model server.

The $parameters variable includes similarity_threshold set to 0.6 to ensure only highly relevant RAG results are included, and num_top_ranked_results set to 5 to limit the context to the top 5 most relevant document chunks, overriding the defaults configured in Admin Console. It also includes CURLOPT_TIMEOUT to cancel the request after 30 seconds if there's no response.

When it sends the prompt, the script sends the temperature and max_tokens parameters to the model for response generation and streams the response to a field.

Configure RAG Account [ RAG Account Name: "customer-support-rag-account" ; Endpoint: "https://myserver.example.com/llm/v1/" ; API key: Global::RAG_API_Key ; Verify SSL Certificates ]

Configure AI Account [ Account Name: "AI_Model_Server" ; Model Provider: Custom ; Endpoint: "https://myserver.example.com/llm/v1/" ; API key: Global::Text_Gen_API_Key ; Verify SSL Certificates ]

Set Variable [ $parameters ; Value: 
  JSONSetElement ( "{}" ;
    [ "temperature" ; .3 ; JSONNumber ] ;
    [ "max_tokens" ; 500 ; JSONNumber ] ;
    [ "similarity_threshold" ; .6 ; JSONNumber ] ;
    [ "num_top_ranked_results" ; 5 ; JSONNumber ] ;
    [ "CURLOPT_TIMEOUT" ; 30 ; JSONNumber ]
  )
]

Perform RAG Action [ RAG Account Name: "customer-support-rag-account" ; Space ID: "knowledge-base" ; Action: Send Prompt ; Send Prompt: "What is the return policy for defective products?" ; AI Account Name: "AI_Model_Server" ; Model: Global::ModelName ; Stream: On ; Response Target: Customer_Support::AI_Response ; Parameters: $parameters ]

A possible result in the Customer_Support::AI_Response field begins "The return policy for defective products allows you to return the item within 14 calendar days."

Example 3 - Add and remove a PDF file from a RAG space

Adds a PDF file named Policies.pdf to a RAG space, then removes it.

After configuring the RAG account to use on the AI model server, the script adds the Policies.pdf file to the RAG space by specifying its file path. Before it can remove the file, the script must find the document ID that was assigned when the file was added. The document ID is returned by Response Target and stored in $ragAddResponse. For example:

{
  "file": "Policies.pdf",
  "id": "f95d4266-66cd-5b50-a01b-07a4dd66c501",
  "model": "multi-qa-MiniLM-L6-cos-v1",
  "rag_space_id": "knowledge-base",
  "result": "ok",
  "usage": {
    "prompt_tokens": 3803,
    "total_tokens": 3803
  }
}

First, the script gets the document ID from $ragAddResponse and stores it in $id. It also gets the ID's data type using the JSONGetElementType function and stores it in $idType. The data type will be JSONString for UUIDs or JSONNumber for numeric IDs (see Notes for details on ID formats).

Next, the script builds the $idArrayToRemove variable as a JSON object with an id key whose value is an array containing the document ID to remove. When adding the ID to the array, the script uses $idType to preserve the original data type from $ragAddResponse. This approach ensures the script works correctly regardless of which ID format the AI model server uses.

Finally, the script calls Perform RAG Action to remove the data by setting the Parameters option to $idArrayToRemove.

Configure RAG Account [ RAG Account Name: "customer-support-rag-account" ; Endpoint: "https://myserver.example.com/llm/v1/" ; API key: Global::RAG_API_Key ; Verify SSL Certificates ]

Perform RAG Action [ RAG Account Name: "customer-support-rag-account" ; Space ID: "knowledge-base" ; Action: Add Data ; RAG Data: From File ; "Policies.pdf" ; Response Target: $ragAddResponse ]

Set Variable [ $id ; Value: JSONGetElement ( $ragAddResponse ; "id" ) ]
Set Variable [ $idType ; Value: JSONGetElementType ( $ragAddResponse ; "id" ) ]


Set Variable [ $idArrayToRemove ; Value: 
  JSONSetElement ( "{}" ; "id" ; 
    JSONSetElement ( "[]" ; 0 ; $id ; $idType ) ; 
    JSONArray 
  ) 
]

Perform RAG Action [ RAG Account Name: "customer-support-rag-account" ; Space ID: "knowledge-base" ; Action: Remove Data ; Parameters: $idArrayToRemove ]

Example 4 - Add documents with different chunk sizes

Adds both English and Japanese documentation to the same RAG space, using different chunk sizes optimized for each language.

The script uses a smaller chunk size (150 tokens) for the English technical documentation to enable precise retrieval of specific technical details.

For the Japanese regulatory documentation, the script uses a larger chunk size (300 tokens) because Japanese tokenization produces shorter text segments per token, requiring more tokens to preserve adequate context. The script also selects the Detect vertical text option to improve extraction of vertical text from this PDF file.

Configure RAG Account [ RAG Account Name: "product-docs-rag-account" ; Endpoint: "https://myserver.example.com/llm/v1/" ; API key: Global::RAG_API_Key ; Verify SSL Certificates ]

Perform RAG Action [ RAG Account Name: "product-docs-rag-account" ; Space ID: "product-knowledge" ; Action: Add Data ; RAG Data: From File ; "TechnicalSpecs_EN.pdf" ; Tokens per Text Chunk: 150 ]

Perform RAG Action [ RAG Account Name: "product-docs-rag-account" ; Space ID: "product-knowledge" ; Action: Add Data ; RAG Data: From File ; "Regulations_JA.pdf" ; Detect vertical text ; Tokens per Text Chunk: 300 ]

Example 5 - Add records as JSONL text

Adds FAQ records from a FileMaker table to a RAG space using JSONL format, where each line represents one complete FAQ record.

The script loops through the records in the FAQ table and builds a JSONL text string where each line is a JSON object containing the question ID, question, and answer. When this JSONL-formatted text is added to the RAG space, the AI model server automatically detects the format and treats each line (each FAQ record) as a separate semantic unit, preserving record boundaries and improving retrieval accuracy.

Configure RAG Account [ RAG Account Name: "customer-support-rag-account" ; Endpoint: "https://myserver.example.com/llm/v1/" ; API key: Global::RAG_API_Key ; Verify SSL Certificates ]

Set Variable [ $jsonlText ; Value: "" ]
Go to Layout [ "FAQ" (FAQ) ; Animation: None ]

Go to Record/Request/Page [ First ]
Loop [ Flush: Always ]
  Set Variable [ $jsonLine ; Value: 
    JSONSetElement ( "{}" ;
      [ "id" ; FAQ::QuestionID ; JSONString ] ;
      [ "question" ; FAQ::Question ; JSONString ] ;
      [ "answer" ; FAQ::Answer ; JSONString ]
    )
  ]
  Set Variable [ $jsonlText ; Value: $jsonlText & $jsonLine & ¶ ]
  Go to Record/Request/Page [ Next ; Exit after last: On ]
End Loop

Perform RAG Action [ RAG Account Name: "customer-support-rag-account" ; Space ID: "knowledge-base" ; Action: Add Data ; RAG Data: From Text ; $jsonlText ; Response Target: $ragResponse ]

The resulting $jsonlText variable contains JSONL-formatted text like:

{"id":"001","question":"What is your return policy?","answer":"Items can be returned within 30 days..."}
{"id":"002","question":"How do I track my order?","answer":"You can track your order using the tracking number..."}
{"id":"003","question":"Do you ship internationally?","answer":"Yes, we ship to over 100 countries worldwide..."}

If a line is short enough, the AI model server makes it a single chunk. If a line exceeds the limit for tokens per text chunk, the line is broken into multiple chunks. Because lines are never merged together, when querying the RAG space, the retrieved chunks will only contain content from a single FAQ record, making it easier to identify which record provided the relevant information.

Related topics 

• Configure RAG Account script step

• Configure AI Account script step

• GetRAGSpaceInfo function

• Configure Prompt Template script step

• Script steps reference