> For the complete documentation index, see [llms.txt](https://docs.wproofreader.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wproofreader.com/deployment/configuration/ai-writing-assistant-aiwa-configuration.md). # AI writing assistant (AIWA) configuration This page explains how to configure the AI writing assistant (AIWA) for the self-hosted version of WProofreader. It covers the AI provider, model configuration, and the AWS setup required to connect the application to foundation models. AIWA is a text rewriter and content generation tool. For the feature overview and supported text operations, see [AI writing assistant (AIWA)](/features/ai-writing-assistant-aiwa.md). {% hint style="info" %} AIWA is disabled by default. To enable it in the SDK, set `aiWritingAssistant: true` in the WProofreader configuration. See [Check types](/integrations/initialization/configuration-options/check-types.md). {% endhint %} ### Prerequisites * A valid license for the self-hosted version of WProofreader. * An AWS account with access to Amazon Bedrock in the region you plan to use. * Permissions to manage IAM policies for the role or user that the application runs under. ### AI provider AIWA currently supports one AI provider: **Amazon Bedrock**. The application uses the bundled AWS SDK to invoke foundation models through Bedrock. {% hint style="info" %} Support for additional providers is planned. This page will be updated when other providers become available. {% endhint %} ### Model configuration Models are defined through configuration, not hardcoded in the application. You can add any model through configuration if its API type is already implemented. This lets you add, replace, or re-target models without rebuilding the application. #### AppServer settings AIWA settings live in `AppServerX.xml` under the `AIWritingAssistant` element: ```xml 3000 100 Resources/prompts.json ``` | Tag | Description | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `MinGenerateInputSize` | Minimum number of characters that must be selected for AIWA to launch. | | `MaxGenerateInputSize` | Maximum number of characters AIWA accepts as input. | | `PromptsPath` | Path to the prompts and models configuration file. The default is `Resources/prompts.json`, resolved relative to the AppServer directory. | For the full list of AppServer parameters, see [AppServer parameters](/deployment/configuration/application-server/appserver-parameters.md). For a safe edit workflow, see [Editing AppServerX.xml](/deployment/configuration/application-server/editing-appserverx.xml.md). Restart AppServer after you change `AppServerX.xml`. #### Configuration file structure Models and prompts are defined in `prompts.json`. By default, the file is located at `AppServer/Resources/prompts.json`. The path is controlled by `PromptsPath`. Models are listed under a `models` array. Each model entry supports these fields: | Field | Required | Description | | ---------------------- | -------- | ----------------------------------------------------------------------------------------- | | `name` | Yes | Unique identifier for the model. Letters, digits, and underscores only. | | `model_id` | Yes | Direct Amazon Bedrock model ID. | | `api_type` | Yes | The API protocol used to call the model. See [Supported API types](#supported-api-types). | | `inference_profile_id` | No | Inference profile ID or ARN used for cross-region inference. | | `replacement_model` | No | Name of another configured model to use instead of this one. | Example model entry: ```json { "models": [ { "name": "CLAUDE_HAIKU_4_5", "model_id": "anthropic.claude-haiku-4-5-20251001-v1:0", "inference_profile_id": "global.anthropic.claude-haiku-4-5-20251001-v1:0", "api_type": "ANTHROPIC_MESSAGES_V2" } ], "prompts": [] } ``` A model is invoked only when a prompt definition references it. Models defined in `models` but unused in any prompt stay inactive. #### Supported API types The application supports these API types: | API type | Description | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ANTHROPIC_MESSAGES` | Anthropic Claude models using the Messages API. | | `ANTHROPIC_MESSAGES_V2` | Anthropic Claude models using the Messages API with a single sampling parameter, either `temperature` or `top_p`. Used by the newest Sonnet and Haiku models. | | `MISTRAL_TEXT_COMPLETION` | Mistral models using the text completion API. | | `MISTRAL_CHAT_COMPLETION` | Mistral models using the chat completion API. | | `AMAZON_TITAN` | Amazon Titan models. | | `AMAZON_NOVA_MESSAGES` | Amazon Nova models. | | `OPENAI_CHAT_COMPLETION` | OpenAI-compatible chat completion protocol. | If a model entry specifies an unsupported API type, configuration parsing fails with this error: ``` Bedrock API type '' is not supported. ``` #### Model ID vs inference profile selection The application uses this priority order when choosing the Bedrock identifier: 1. If `inference_profile_id` is set, it is used. 2. If `inference_profile_id` is empty or omitted, `model_id` is used. 3. Environment variables override both values at parse time. See [Environment variable overrides](#environment-variable-overrides). Some models cannot be invoked with a direct model ID and require an inference profile. In that case, invoking the model ID directly returns a Bedrock error stating that on-demand throughput is not supported and that an inference profile ID or ARN is required. Configure `inference_profile_id` for that model to resolve the error. #### Inference profiles and regions Inference profiles enable cross-region inference and improved request routing. By default, configured inference profile IDs use the global profile, `global.*`, where available. This routes requests across regions and is usually cheaper. Where no global profile exists, the US profile, `us.*`, is used. This simplifies setup for US-based deployments. Some models are available only in specific regions. If a model is unavailable in your deployment region, you have two options: * Replace it with an available model by using `replacement_model`. See [Model replacement](#model-replacement). * Re-target it to a region-specific inference profile through an environment variable. See [Environment variable overrides](#environment-variable-overrides). For current model and inference profile availability, refer to AWS documentation on [supported foundation models](https://docs.aws.amazon.com/bedrock/latest/userguide/model-cards.html) and [supported inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html). For pricing, see [Amazon Bedrock pricing](https://aws.amazon.com/bedrock/pricing/). #### Model replacement The replacement feature substitutes one model with another at runtime. Use it when a model is unavailable in a region, requires unavailable permissions, needs testing against an alternative, or needs a temporary fallback. When a replacement is configured, every prompt that uses the original model uses the replacement instead. The replacement model must be defined in the same configuration file. In the configuration file: ```json { "name": "CLAUDE_HAIKU_4_5", "model_id": "anthropic.claude-haiku-4-5-20251001-v1:0", "api_type": "ANTHROPIC_MESSAGES_V2", "replacement_model": "CLAUDE_SONNET_4_5" } ``` Through an environment variable: ``` CLAUDE_HAIKU_4_5_REPLACEMENT_MODEL=CLAUDE_SONNET_4_5 ``` #### Environment variable overrides Configuration values can be overridden through environment variables. This is useful for container deployments, where the same configuration file can be reused across regions and environments. Environment variables are read when the configuration file is parsed, not continuously at runtime. They are applied: * During application startup when configuration loads. * When the configuration file is modified and reparsed. * After an application restart. {% hint style="warning" %} Changing an environment variable alone does not reload the configuration. Restart the application or modify the configuration file to trigger reparsing. {% endhint %} Variable names follow this format: `{MODEL_NAME}_{SUFFIX}`. The model name must be uppercase and use underscores. Override the inference profile ID: ``` CLAUDE_HAIKU_4_5_INFERENCE_PROFILE_ID=arn:aws:bedrock:eu-west-1::inference-profile/... ``` Replace the model entirely: ``` CLAUDE_HAIKU_4_5_REPLACEMENT_MODEL=CLAUDE_SONNET_4_5 ``` Reset a configured value to empty with `NONE`: ``` CLAUDE_HAIKU_4_5_INFERENCE_PROFILE_ID=NONE CLAUDE_HAIKU_4_5_REPLACEMENT_MODEL=NONE ``` Setting a variable to `NONE` overrides the configuration file value with an empty string. This lets container deployments clear a default inference profile or replacement without editing the configuration file. ### AWS configuration To let the application invoke foundation models, configure model access, credentials, and IAM permissions in your AWS account. #### Model access in Amazon Bedrock Access to serverless foundation models is enabled automatically for every AWS account in all commercial regions. You no longer need to enable each model manually in the Bedrock console. Account administrators control access through IAM policies and Service Control Policies, or SCPs. {% hint style="info" %} Anthropic models are enabled by default but require a one-time first-use form before the first invocation. Submit it through the Amazon Bedrock console by selecting an Anthropic model in the playground, or through the `PutUseCaseForModelAccess` API. In AWS Organizations, submitting it at the management account level through the API extends approval to member accounts. {% endhint %} A subset of serverless models is offered through AWS Marketplace. For those models, the application IAM identity may also need AWS Marketplace subscription permissions so the subscription can complete automatically on first invocation. #### Credentials The AWS SDK resolves credentials through the default credential provider chain. How you provide credentials depends on where the application runs. **Deployed on an Amazon EC2 instance.** Attach an IAM role to the instance through an instance profile. The SDK reads temporary credentials from the instance metadata automatically and refreshes them as they expire. You do not need to store access keys on the instance. This is the recommended approach for EC2 deployments. **Deployed outside AWS, or in a container without an attached role.** Provide credentials explicitly for an IAM user or role that has the required Bedrock permissions. The most common method is environment variables read by the SDK: ``` AWS_ACCESS_KEY_ID= AWS_SECRET_ACCESS_KEY= AWS_REGION= ``` If you use temporary credentials from AWS STS, also set `AWS_SESSION_TOKEN`. The SDK can also read a shared credentials file, `~/.aws/credentials`, or use container credentials when running on Amazon ECS. The full resolution order is described in AWS documentation on the [default credentials provider chain](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials-chain.html). Regardless of the method, the resolved identity must have the IAM permissions described below. #### IAM permissions The role or user that the application runs under must have `bedrock:InvokeModel` permission for the model ARNs and, when inference profiles are used, for the inference profile ARN as well. The following example policy allows the models in the default configuration and any inference profile in the account: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "bedrock:InvokeModel", "Resource": [ "arn:aws:bedrock:*::foundation-model/anthropic.claude-haiku-4-5-20251001-v1:0", "arn:aws:bedrock:*::foundation-model/mistral.mixtral-8x7b-instruct-v0:1", "arn:aws:bedrock:*::foundation-model/google.gemma-3-27b-it", "arn:aws:bedrock:*::foundation-model/amazon.nova-micro-v1:0", "arn:aws:bedrock:*::foundation-model/amazon.nova-2-lite-v1:0", "arn:aws:bedrock:*::inference-profile/*" ] } ] } ``` Adjust the model ARNs to match the models referenced in your prompt configuration. {% hint style="warning" %} Inference profiles require different permissions than direct model IDs. A direct model ID needs permission for the model ARN. An inference profile needs permission for both the inference profile ARN and the underlying model ARN. Switching a model from a direct ID to an inference profile may require an IAM update even if the application previously had access to that model. {% endhint %} If credentials and the IAM policy are configured correctly, the application connects to Amazon Bedrock automatically. To verify engine readiness after setup, use [Status API](/api-reference/auxiliary-api-commands/status-api.md) or [Monitoring system health](/deployment/configuration/monitoring-system-health.md). For more detail, see AWS guides on [granting IAM permissions for Bedrock foundation models](https://docs.aws.amazon.com/bedrock/latest/userguide/security_iam_id-based-policy-examples.html) and [simplified model access](https://aws.amazon.com/blogs/security/simplified-amazon-bedrock-model-access/). #### Cost monitoring There is no built-in limit on AIWA usage in the self-hosted version. Each model has its own per-token price for input and output. Input tokens also include the system prompt instructions, not only the user text. System prompt size is roughly 200 to 300 tokens for English and 300 to 600 tokens for other supported languages, depending on the language and operation. To stay aware of charges, create a billing alarm in AWS: 1. Sign in to the AWS Management Console and open CloudWatch. 2. In **Alarms**, click **Create alarm**. 3. For the metric, choose **Billing** > **Estimated charges**. For example, use the `EstimatedCharges` metric for the `AmazonBedrock` service. 4. Set a static threshold. For example, notify when estimated charges exceed 1 USD per day. 5. Configure an email address or SNS topic to receive alerts. 6. Review and create the alarm. For step-by-step guidance, see [Create a billing alarm to monitor estimated AWS charges](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/monitor_estimated_charges_with_cloudwatch.html). For per-model pricing, see [Amazon Bedrock pricing](https://aws.amazon.com/bedrock/pricing/). ### Enable AIWA in the SDK After the AWS side is configured, enable AIWA in the WProofreader configuration script: ```html ``` For related options, see [Check types](/integrations/initialization/configuration-options/check-types.md). ### Verify the configuration 1. Open a system where WProofreader is integrated into a rich text field. 2. Type or paste a block of at least 100 characters, then select it. 3. An orange AIWA badge appears near the selection. Click it to open the start dialog with the list of operations. 4. Choose an operation, such as **Shorten**. A new view shows the transformed text. 5. Click **Replace** to apply the suggestion, **Retry** to regenerate it, or **Copy** to copy the result. {% hint style="info" %} The **Replace** action is available only while the original text stays selected. If the selection is lost or new text is typed, the action switches to **Copy**. Opening AIWA from the badge menu without a selection works on the whole text field and defaults to **Copy**. {% endhint %} If the badge does not appear, check [Status API](/api-reference/auxiliary-api-commands/status-api.md) and review the application logs. ### Troubleshooting Configuration and AWS errors appear only in the application log files. They do not appear in the UI or in API responses shown to end users. Common AWS errors: * **Model requires an inference profile.** The Bedrock response states that on-demand throughput is not supported and that an inference profile ID or ARN is required. Configure `inference_profile_id` for the model. * **Access denied** or **not authorized to perform `bedrock:InvokeModel`.** The IAM identity lacks permission for the model or inference profile ARN shown in the error. Add that exact ARN to the policy. * **Marketplace subscription error.** The identity lacks AWS Marketplace permissions needed to auto-subscribe to a Marketplace-offered model, or the Anthropic first-use form has not been submitted. Common configuration parsing errors: * `Invalid model name: ''.` A model name contains characters other than letters, digits, or underscores. * `Bedrock API type '' is not supported.` The API type is not implemented. Use one of the [supported API types](#supported-api-types). * `Field 'model_id' is empty for model ''.` A required field is missing. * `Model '' not found.` A prompt references a model that is not defined in the `models` array. * `Replacement model '' for '' not found in configuration.` The replacement model is not defined. * `Duplicated model name: ''.` The same model name appears more than once. AWS SDK errors include the full ARN of the resource being accessed. Use that ARN to verify the inference profile ID, confirm the region matches your deployment, and update IAM policies with the exact value. For deeper diagnosis, see [Enabling detailed errors logging](/deployment/configuration/application-server/enabling-detailed-errors-logging.md) and [Troubleshooting AI model downloads and configuration](/deployment/configuration/ai-engine-setup/troubleshooting-ai-model-downloads-and-configuration.md). ### Related topics * [AI writing assistant (AIWA)](/features/ai-writing-assistant-aiwa.md) — feature overview and supported operations. * [Check types](/integrations/initialization/configuration-options/check-types.md) — enable AIWA in the SDK. * [Editing AppServerX.xml](/deployment/configuration/application-server/editing-appserverx.xml.md) — safe workflow for configuration changes. * [Monitoring system health](/deployment/configuration/monitoring-system-health.md) — health and readiness checks after setup. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.wproofreader.com/deployment/configuration/ai-writing-assistant-aiwa-configuration.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.