> ## Documentation Index
> Fetch the complete documentation index at: https://doc.lucidworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lucidworks AI Prediction query stage

export const schema = {
  "type": "object",
  "title": "LWAI Prediction",
  "description": "General purpose integration between Fusion and Lucidworks AI.",
  "required": ["accountName", "useCase", "modelName", "inputContextVariable", "outputContextVariable"],
  "properties": {
    "skip": {
      "type": "boolean",
      "title": "Skip This Stage",
      "description": "Set to true to skip this stage.",
      "default": false,
      "hints": ["advanced"]
    },
    "label": {
      "type": "string",
      "title": "Label",
      "description": "A unique label for this stage.",
      "hints": ["advanced"],
      "maxLength": 255
    },
    "condition": {
      "type": "string",
      "title": "Condition",
      "description": "Define a conditional script that must result in true or false. This can be used to determine if the stage should process or not.",
      "hints": ["code", "code/javascript", "advanced"]
    },
    "legacy": {
      "type": "boolean",
      "title": "Legacy",
      "description": "True if this stage only supports legacy mode",
      "hints": ["readonly", "hidden"]
    },
    "asyncConfig": {
      "type": "object",
      "title": "Asynchronous Execution Config",
      "required": ["enabled", "asyncId"],
      "properties": {
        "enabled": {
          "type": "boolean",
          "title": "Enable Async Execution",
          "description": "Run the expensive data loading or processing part of this stage in a separate thread allowing the pipeline to continue executing. The results of this asynchronous execution can be merged into the pipeline request using a downstream \"Merge Async Results\" stage.",
          "default": false
        },
        "asyncId": {
          "type": "string",
          "title": "Async ID",
          "description": "A unique value to use as reference in downstream \"Merge Async Results\" stages."
        }
      }
    },
    "accountName": {
      "type": "string",
      "title": "Account Name",
      "description": "Lucidworks AI integration name as defined by your Fusion Administrator.  This entry should match the account name set in the LWAI Gateway.",
      "hints": ["enumUrl:/api/query-stages/lwai-accounts"]
    },
    "useCase": {
      "type": "string",
      "title": "Use Case",
      "description": "Lucidworks AI Use Case as defined in documentation",
      "hints": ["enumUrl:/api/query-stages/lwai-usecase?account=${accountName}"]
    },
    "useCaseConfig": {
      "type": "array",
      "title": "Use Case Configuration",
      "description": "Additional Use Case keys and values to be sent to Lucidworks AI",
      "minItems": 0,
      "items": {
        "type": "object",
        "required": ["key"],
        "properties": {
          "key": {
            "type": "string",
            "title": "Parameter Name"
          },
          "value": {
            "type": "string",
            "title": "Parameter Value"
          }
        }
      }
    },
    "modelName": {
      "type": "string",
      "title": "Model",
      "description": "Lucidworks AI Model as defined in documentation",
      "hints": ["enumUrl:/api/query-stages/lwai-model?account=${accountName}&useCase=${useCase}"]
    },
    "modelConfig": {
      "type": "array",
      "title": "Model Configuration",
      "description": "Additional Model configuration parameters to be sent to Lucidworks AI",
      "minItems": 0,
      "items": {
        "type": "object",
        "required": ["key"],
        "properties": {
          "key": {
            "type": "string",
            "title": "Parameter Name"
          },
          "value": {
            "type": "string",
            "title": "Parameter Value"
          }
        }
      }
    },
    "inputContextVariable": {
      "type": "string",
      "title": "Input context variable",
      "description": "Name of the variable in context to be used as input. Supports template expressions."
    },
    "outputContextVariable": {
      "type": "string",
      "title": "Destination Variable Name & Context Output",
      "description": "The name here is used to populate two things with the prediction results:  1) A query response header with this name, and 2) A context variable with this name that will contain the prediction."
    },
    "groundingOptions": {
      "type": "object",
      "title": "Grounding Options",
      "description": "Options for grounding the RAG use case.",
      "properties": {
        "groundingDocsSource": {
          "type": "string",
          "title": "Grounding Documents Location",
          "description": "For use cases that support grounding via attached documents, this is the location. For example, if the response documents are stored in  a context variable named 'responseDocs', then this value should be set to 'responseDocs'.",
          "enum": ["Solr Response", "Context Variable"],
          "default": "Solr Response"
        },
        "groundingDocsKey": {
          "type": "string",
          "title": "Grounding Documents Key",
          "description": "The key in the context variable that contains the grounding documents. For example, if the grounding documents are stored in a context variable named 'responseDocs', then this value should be set to 'responseDocs'. Note:  When the Grounding Documents Location is set to 'Solr Response', this value is ignored and the response documents are used.",
          "default": "responseDocs"
        },
        "numberOfGroundingDocs": {
          "type": "integer",
          "title": "Number of Grounding Documents",
          "description": "How many grounding documents should be included with the RAG request?",
          "default": 3
        },
        "fieldMappings": {
          "type": "array",
          "title": "Document Field Mappings",
          "description": "Only needed/used for 'rag' use case.  Maps fields from the input documents to the fields expected by the Lucidworks AI RAG use case.  Required LW AI fields are: body and source.  Optional fields are title and date.  If not provided, the default field mappings will be used.",
          "default": [{
            "key": "title",
            "value": "title_t"
          }, {
            "key": "body",
            "value": "description_t"
          }, {
            "key": "source",
            "value": "link_t"
          }, {
            "key": "date",
            "value": "_lw_file_modified_tdt"
          }],
          "hints": ["advanced"],
          "items": {
            "type": "object",
            "required": ["key", "value"],
            "properties": {
              "key": {
                "type": "string",
                "title": "LW AI Document Field Name"
              },
              "value": {
                "type": "string",
                "title": "Response Document Field Name"
              }
            }
          }
        }
      }
    },
    "failOnError": {
      "type": "boolean",
      "title": "Fail on Error",
      "description": "Flag to indicate if this stage should throw an exception if an error occurs.",
      "default": false
    },
    "apiKey": {
      "type": "string",
      "title": "API Key",
      "description": "Secret associated with the model.  For example, for OpenAI models, the value would start with 'sk-'.",
      "hints": ["secret"]
    }
  },
  "category": "AI",
  "categoryPriority": 10,
  "unsafe": false
};

export const SchemaParamFields = ({schema}) => {
  const sanitize = str => {
    if (typeof str !== "string") return str;
    return str.replace(/^"(.*)"$/s, "$1").replace(/\\/g, "").replace(/"/g, "'");
  };
  const formatDescription = str => {
    const s = sanitize(str);
    return (/[.!?]\)*$/).test(s) ? s : `${s}.`;
  };
  const {description, properties = {}, required: requiredProps = []} = schema;
  const visibleProps = useMemo(() => Object.entries(properties).filter(([, prop]) => !prop.hints?.includes("hidden")), [properties]);
  return <div>
      {description && <p>{formatDescription(description)}</p>}

      {visibleProps.map(([name, prop]) => {
    const isRequired = requiredProps.includes(name);
    const hasDefault = prop.default !== undefined;
    const rawDefault = prop.default;
    const isComplexDefault = hasDefault && (typeof rawDefault === "object" || typeof rawDefault === "string" && (rawDefault.length > 20 || rawDefault.includes('"')));
    const fieldProps = {
      key: name,
      body: prop.title || name,
      type: prop.type,
      ...prop.title && ({
        post: [<><span className="text-stone-400 dark:text-stone-500">API property: </span>{name}</>]
      }),
      ...isRequired && ({
        required: true
      }),
      ...!isComplexDefault && hasDefault ? {
        default: sanitize(String(rawDefault))
      } : {}
    };
    const isObject = prop.type === "object" && prop.properties;
    const isArrayOfObjects = prop.type === "array" && prop.items?.type === "object" && prop.items.properties;
    return <ParamField {...fieldProps}>
            {prop.description && <p>{formatDescription(prop.description)}</p>}

            {isComplexDefault && <div className="flex">
                <p>
                  <strong>Default:</strong>
                </p>
                <pre className="!my-0">
                  <code>
                    {JSON.stringify(rawDefault, null, 2)}
                  </code>
                </pre>
              </div>}

            {isArrayOfObjects && <div className="flex">
              <p>
                <strong>Object attributes:</strong>
              </p>
              <pre className="!my-0">
                <code>
                  {'{\n'}
                  {Object.entries(prop.items.properties).map(([iname, iprop]) => <>
                      {`  ${iname}`}
                      {prop.items?.required?.includes(iname) && <span style={{
      color: 'red'
    }}> required</span>}
                      {`: {\n    display name: ${sanitize(iprop.title || '')}\n    type: ${iprop.type}\n  }\n`}
                    </>)}
                  {'}'}
                </code>
              </pre>
              </div>}

            {isObject && <Expandable title="properties">
                <SchemaParamFields schema={{
      properties: prop.properties,
      required: prop.required
    }} />
              </Expandable>}
          </ParamField>;
  })}
    </div>;
};

export const LwTemplate = ({title = "Key questions to get you started", icon = "sparkles", cta = "Powered by Agent Studio", linkHref = "https://lucidworks.com/demo/?utm_source=docs&utm_medium=referral&utm_campaign=docs_cta_ai"}) => {
  const [isLoaded, setIsLoaded] = useState(false);
  useEffect(() => {
    const timer = setTimeout(() => {
      setIsLoaded(true);
    }, 500);
    return () => clearTimeout(timer);
  }, []);
  return <div className="lw-template-container">
      <Card title={title} icon={icon}>
        {isLoaded && <span dangerouslySetInnerHTML={{
    __html: `<lw-template id="a029c1a9-28be-427e-b0e1-5d918920246a"></lw-template
            >`
  }} />}
        <Link href={linkHref} className="agent-studio-link text-left text-gray-600 gap-2 dark:text-gray-400 text-sm font-medium flex flex-row items-center hover:text-primary dark:hover:text-primary-light group-hover:text-primary group-hover:dark:text-primary-light">Powered by Lucidworks Agent Studio</Link>
      </Card>
    </div>;
};

[old doc.lw link]: https://doc.lucidworks.com/managed-fusion/5.9/hnuyky

[localhost link]: http://localhost:3000/docs/lw-platform/lw-ai/lw-ai-stages/lucidworks-ai-prediction-query-stage

[mintlify link]: https://doc.lucidworks.com/docs/lw-platform/lw-ai/lw-ai-stages/lucidworks-ai-prediction-query-stage

The LWAI Prediction query stage is an integration between Fusion and Lucidworks AI and invokes the following APIs:

* [Lucidworks AI Prediction API](/docs/lw-platform/lw-ai/lw-ai-apis/lw-ai-prediction-api/overview), which is used to send synchronous API calls that run predictions from pre-trained or custom embedding models.
* [Lucidworks AI Async Prediction API](/docs/lw-platform/lw-ai/lw-ai-apis/lw-ai-async-prediction-api/overview), which is used to send asynchronous API calls that run predictions on specific models.

The stage enriches search results using [Generative AI](/docs/lw-platform/lw-ai/lw-ai-generative-ai) such as OpenAI, Google Vertex, and Anthropic models. In addition, the stage can use [pre-trained embedding models](/docs/lw-platform/lw-ai/lw-ai-pre-trained-embedding-models). Your organization needs to choose the models that best suit your goals.

If you are a business user, you can set up the Lucidworks AI Prediction query stage in your pipeline so that when a user enters a query, they will see generative AI predictions based on the query. For example, if the user searches for warranty information on your products, the user can see not only the search results but the results of the Lucidworks AI Prediction query stage, which will summarize warranty information for your products alongside the results.

<iframe src="https://app.supademo.com/embed/cmiopvzs9001uxj0ivl8p7sg1?embed_v=2&utm_source=embed" loading="lazy" title="Configure LWAI Prediction Query stage" allow="clipboard-write" frameborder="0" webkitallowfullscreen="true" mozallowfullscreen="true" allowfullscreen style={{  width: '100%', height: '500px' }} />

<Accordion title="Configure the LWAI Prediction query stage">
  The LWAI Prediction AI query stage is a Fusion pipeline query stage that enriches your search results with [Generative AI](/docs/lw-platform/lw-ai/lw-ai-generative-ai) predictions.

  For reference information, see [LWAI Prediction query stage](/docs/lucidworks-search/09-developer-documentation/config-specs/query-pipeline-stages/lucidworks-ai-prediction-query-stage).

  To use this stage, non-admin Fusion users must be granted the `PUT,POST,GET:/LWAI-ACCOUNT-NAME/**` permission in Fusion, which is the Lucidworks AI API Account Name defined in Lucidworks AI Gateway when this stage is configured.

  <Note>
    This section describes how to configure the stage when your organization generates and manages the authentication and API keys. If your organization has opted to contract with Lucidworks to provide the API keys to execute generative AI (Gen-AI) models, see [Generative AI using Lucidworks-managed keys](/docs/lw-platform/lw-ai/lw-ai-generative-ai-using-lw-keys).
  </Note>

  To configure this stage:

  1. Sign in to Fusion and click **Querying > Query Pipelines**.

  2. Click **Add+** to add a new pipeline.

  3. Enter the name in **Pipeline ID**.

  4. Click **Add a new pipeline stage**.

  5. In the AI section, click **LWAI Prediction**.

  6. In the **Label** field, enter a unique identifier for this stage.

  7. In the **Condition** field, enter a script that results in true or false, which determines if the stage should process.

  8. Select **Asynchronous Execution Config** if you want to run this stage asynchronously. If this field is enabled, complete the following fields:
     1. Select **Enable Async Execution**. Fusion automatically assigns an **Async ID** value to this stage.  Change this to a more memorable string that describes the asynchronous stages you are merging, such as `signals` or `access_control`.
     2. Copy the **Async ID** value.

  9. In the **Account Name** field, enter your Lucidworks AI API Account Name as defined in the Lucidworks AI Gateway Service.

  10. In the **Use Case** field, select the Lucidworks AI use case to associate with this stage.
      * To generate a list of the use cases for your organization, see [Use Case API](/docs/lw-platform/lw-ai/lw-ai-apis/lw-ai-use-case-api).
      * The available use cases are described in [Prediction API](/docs/lw-platform/lw-ai/lw-ai-apis/lw-ai-prediction-api/overview).

  11. In the **Use Case Configuration** section, click the **+** sign to enter the parameter name and value to send to Lucidworks AI.
      * The `useCaseConfig` parameter is only applicable to certain use cases. For more information, see the [Async Prediction API](/docs/lw-platform/lw-ai/lw-ai-apis/lw-ai-async-prediction-api/overview) and the [Prediction API](/docs/lw-platform/lw-ai/lw-ai-apis/lw-ai-prediction-api/overview).
      * The `memoryUuid` parameter is required in the Standalone Query Rewriter use case, and is optional in the RAG use case.

        For more information, see [Prediction API](/docs/lw-platform/lw-ai/lw-ai-apis/lw-ai-prediction-api/overview).

  12. In the **Model** field, select the Lucidworks AI model to associate with this stage.\
      If you do not see any model names and you are a non-admin Fusion user, verify with a Fusion administrator that your user account has these permissions: `PUT,POST,GET:/LWAI-ACCOUNT-NAME/**`

      Your Fusion account name must match the name of the account that you selected in the **Account Name** dropdown.\
      For more information about models, see:

      * [Pre-trained embedding models](/docs/lw-platform/lw-ai/lw-ai-pre-trained-embedding-models)
      * [Custom embedding model training](/docs/lw-platform/lw-ai/lw-ai-custom-embedding-model-training/overview)
      * [Generative AI models](/docs/lw-platform/lw-ai/lw-ai-generative-ai)

  13. In the **Model Configuration** section, click the **+** sign to enter the parameter name and value to send to Lucidworks AI. Several `modelConfig` parameters are common to generative AI use cases. For more information, see [Prediction API](/docs/lw-platform/lw-ai/lw-ai-apis/lw-ai-prediction-api/overview).

  14. In the **Input context variable** field, enter the name of the context variable to be used as input. Template expressions are supported.

  15. In the **Destination variable name and context output** field, enter the name that will be used as both the query response header in the prediction results and the context variable that contains the prediction.

      {/* // tag::lwai-prediction-query-stage[] */}

      * If a value is entered in this field:

        * `{destination name}_t`  is the full response.

        * In the context:

          * `_lw_ai_properties_ss` contains the Lucidworks account, boolean setting for async, use case, input for the call, and the collection.

      * If *no* value is entered in this field:

        * `_lw_ai_{use case}_t` is the `response.response` object, which is the raw model output.

        * `_lw_ai_{use case}_response_s` is the full response.

        {/* // end::lwai-prediction-query-stage[] */}

  16. **Grounding Options** is only used for the RAG use case, and connects model output to the data source. This provides more trustworthy responses in a scalable, cost-efficient manner. If selected, enter appropriate values in the following options:

      1. In the **Grounding Documents Location** field, enter the location where response documents are stored for use cases that support grounding via attached documents.

      2. In the **Grounding Documents Key** field, enter the key in the context variable that contains the grounding documents. If the value of the **Grounding Document Location** field is `SolrResponse`, the value in this field is ignored and the response documents are used.

      3. In the **Number of Grounding Documents** field, enter the number of documents to include in the RAG request.

  17. In the **Document Field Mappings** section, enter the **LW AI Document field name** and its corresponding **Response document field name** to map from input documents to the fields accepted by the Prediction API RAG use case. The fields are described in the [Prediction API](/docs/lw-platform/lw-ai/lw-ai-apis/lw-ai-prediction-api/overview).

      If information is not entered in this section, the default mappings are used.

      * The `body` and `source` fields are required.
        * `body` - `description_t` is the document content.
        * `source` - `link_t` is the URL/ID of the document.
      * The `title` and `date` fields are optional.
        * `title` - `title_t` is the title of the document.
        * `date` - `_lw_file_modified_tdt` is the creation date of the document in epoch time format.

  18. Select the **Fail on Error** checkbox to generate an exception if an error occurs during this stage.

  19. In the **API Key** field, enter the secret value specified in the external model. For:
      * OpenAI models, `"apiKey"` is the value in the model’s `"[OPENAI_API_KEY]"` field. For more information, see [Authentication API keys](https://platform.openai.com/docs/api-reference/authentication).
      * Azure OpenAI models, `"apiKey"` is the value generated by Azure in either the model’s `"[KEY1 or KEY2]"` field. For requirements to use Azure models, see [Generative AI models](/docs/lw-platform/lw-ai/lw-ai-generative-ai).
      * Google VertexAI models, `"apiKey"` is the value in the model’s

        `"[BASE64_ENCODED_GOOGLE_SERVICE_ACCOUNT_KEY]"` field. For more information, see [Create and delete Google service account keys](https://cloud.google.com/iam/docs/keys-create-delete).

  20. Click **Save**.
</Accordion>

You can also configure the stage using the parameters listed in this topic.

<Note>To use this stage, non-admin Fusion users must be granted the `PUT,POST,GET:/LWAI-ACCOUNT-NAME/**` permission in Fusion, which is the Lucidworks AI API Account Name defined in [Lucidworks AI Gateway](/docs/lw-platform/lw-ai/lw-ai-gateway) when this stage is configured.</Note>

<LwTemplate />

## Query pipeline stage condition examples

Stages can be triggered conditionally when a script in the **Condition** field evaluates to true.

<Tabs>
  <Tab title="Mobile clients">
    ```javascript theme={"dark"}
    params.deviceType === "mobile"
    ```
  </Tab>

  <Tab title="Debugging enabled">
    ```javascript theme={"dark"}
    params.debug === "true"
    ```
  </Tab>

  <Tab title="Includes 'sale'">
    ```javascript theme={"dark"}
    params.q && params.q.includes("sale")
    ```
  </Tab>

  <Tab title="Multiple conditions">
    ```javascript theme={"dark"}
    request.hasParam("fusion-user-name") && request.getFirstParam("fusion-user-name").equals("SuperUser");
    !request.hasParam("isFusionPluginQuery");
    ```

    The first condition checks that the request parameter `fusion-user-name` is present and has the value `SuperUser`.\
    The second condition checks that the request parameter `isFusionPluginQuery` is not present.
  </Tab>
</Tabs>

## Configuration

<Tip>When entering configuration values in the UI, use *unescaped* characters, such as `\t` for the tab character. When entering configuration values in the API, use *escaped* characters, such as `\\t` for the tab character.</Tip>

<SchemaParamFields schema={schema} />