# AI Prompt Provider

The AI Prompt Provider module is designed to streamline the process of generating prompts for both custom and natively supported AI providers.

[AI Prompt Provider Module](https://support.crowdin.com/developer/crowdin-apps-module-ai-prompt-provider/)

## Sample

```js ins="aiPromptProvider" title="index.js"
    import crowdinModule from '@crowdin/app-project-module';
    import { PromptActions } from '@crowdin/app-project-module/modules/ai-prompt-provider';

    const configuration = {
      baseUrl: 'https://123.ngrok.io',
      clientId: 'clientId',
      clientSecret: 'clientSecret',
      name: 'Sample App',
      identifier: 'sample-app',
      description: 'Sample App description',
      dbFolder: import.meta.dirname,
      imagePath: import.meta.dirname + '/logo.png',
      aiPromptProvider: [
        {
          actions: [PromptActions.PRE_TRANSLATE],
          allowRetryOnQaIssues: false,
          formSchema: {
            type: "object",
            properties: {
              firstOption: {
                title: "Option 1",
                type: "string"
              }
            },
            required: ['firstOption']
          },
          compile: async function({ options, payload, client, context, requestData }) {
            return 'Prompt text compiled based on options and payload';
          }
        }
      ]
    };

    crowdinModule.createApp(configuration);
    ```
  ```ts ins="aiPromptProvider" title="index.ts"
    import crowdinModule from '@crowdin/app-project-module';
    import type { ClientConfig } from '@crowdin/app-project-module';
    import { PromptActions } from '@crowdin/app-project-module/modules/ai-prompt-provider';

    const configuration: ClientConfig = {
      baseUrl: 'https://123.ngrok.io',
      clientId: 'clientId',
      clientSecret: 'clientSecret',
      name: 'Sample App',
      identifier: 'sample-app',
      description: 'Sample App description',
      dbFolder: import.meta.dirname,
      imagePath: import.meta.dirname + '/logo.png',
      aiPromptProvider: [
        {
          actions: [PromptActions.PRE_TRANSLATE],
          allowRetryOnQaIssues: false,
          formSchema: {
            type: "object",
            properties: {
              firstOption: {
                title: "Option 1",
                type: "string"
              }
            },
            required: ['firstOption']
          },
          compile: async function({ options, payload, client, context, requestData }) {
            return 'Prompt text compiled based on options and payload';
          }
        }
      ]
    };

    crowdinModule.createApp(configuration);
    ```
  ## Configuration

| Parameter                 | Description                                                                                                                                                                 |
|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `actions`                 | An array of supported prompt actions. If not provided, all actions are supported. Available action types: `pre_translate`, `assist`, `qa_check`, `custom:type-of-action`.   |
| `allowRetryOnQaIssues`    | If `false`, disables auto-retry on QA issues in the user interface. Default: `true`.                                                                                        |
| `formSchema`              | [React JSON Schema](/app-project-module/user-interface/) for the form.                                                                                                      |
| `status`                  | Optional handler that returns prompt status info (used providers, configuration state, errors/warnings). When provided, a `statusUrl` is automatically exposed in the manifest. |

### `compile` Function

Used to generate prompts based on the options and payload provided.

#### Parameters

- `options` - Options selected by the user.
- `payload` - Data provided by the AI provider.
- `client` - Crowdin API client.
- `context` - [Context object](/app-project-module/reference/context/).
- `requestData` - the remaining request body data.

#### Return Value

The function should return the prompt text.

### `status` Function

Optional handler that returns prompt status information. When provided, Crowdin will call this endpoint to display real-time status for external prompts.

#### Parameters

- `options` - Options selected by the user.
- `aiPromptId` - The ID of the AI prompt.
- `client` - Crowdin API client.
- `context` - [Context object](/app-project-module/reference/context/).

#### Return Value

The function should return an object with the following properties:

| Property            | Type                                        | Description                              |
|---------------------|---------------------------------------------|------------------------------------------|
| `usedAiProviderIds` | `number[]`                                  | IDs of AI providers used by the prompt.  |
| `isConfigured`      | `boolean`                                   | Whether the prompt is fully configured.  |
| `errors`            | `Array<{ code: string; message: string }>`  | List of errors, if any.                  |
| `warnings`          | `Array<{ code: string; message: string }>`  | List of warnings, if any.               |

#### Example

```js title="index.js"
const configuration = {
  // ... other configuration
  aiPromptProvider: [
    {
      compile: async ({ options, payload }) => {
        return 'Prompt text';
      },
      status: async ({ options, aiPromptId, client, context }) => {
        return {
          usedAiProviderIds: [1, 2],
          isConfigured: true,
          errors: [],
          warnings: [],
        };
      }
    }
  ]
};
```

### Multiple Prompt Providers

You can register multiple AI prompt providers in a single app by providing an array:

```js title="index.js"
import { PromptActions } from '@crowdin/app-project-module/modules/ai-prompt-provider';

const configuration = {
  // ... other configuration
  aiPromptProvider: [
    {
      name: 'Translation Prompt',
      actions: [PromptActions.PRE_TRANSLATE],
      compile: async ({ options, payload }) => {
        return 'Translate the following text: ' + payload;
      }
    },
    {
      name: 'QA Prompt',
      actions: [PromptActions.QA_CHECK],
      compile: async ({ options, payload }) => {
        return 'Check the quality of the following translation: ' + payload;
      }
    }
  ]
};
```