From d30406043eec03444a1a53ef61bccf71a2b774d7 Mon Sep 17 00:00:00 2001
From: Gildas <1122076+djhi@users.noreply.github.com>
Date: Wed, 26 Feb 2025 15:08:04 +0100
Subject: [PATCH] [Doc] Improve `<FormFillerButton>` documentation by
 explaining the `dataProvider.getCompletion()`

---
 docs/FormFillerButton.md | 52 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/docs/FormFillerButton.md b/docs/FormFillerButton.md
index 7fec0a0813..f8d405991a 100644
--- a/docs/FormFillerButton.md
+++ b/docs/FormFillerButton.md
@@ -33,6 +33,23 @@ export const ContactEdit = () => (
 );
 ```
 
+You must define a `dataProvider.getCompletion()` method to fetch the completion suggestions from your API. This method must return a promise that resolves to a `{ data: completionString }` object.
+
+For instance, to use the OpenAI Completion API:
+
+```jsx
+// in src/dataProvider.js
+import jsonServerProvider from 'ra-data-json-server';
+import { addGetCompletionBasedOnOpenAIAPI } from '@react-admin/ra-ai';
+
+const baseDataProvider = jsonServerProvider(
+    import.meta.env.VITE_JSON_SERVER_URL
+);
+export const dataProvider = addGetCompletionBasedOnOpenAIAPI(baseDataProvider),
+```
+
+`addGetCompletionBasedOnOpenAIAPI` expects the OpenAI API key to be stored in the localStorage under the key `ra-ai.openai-api-key`. It's up to you to add the key to the localStorage (e.g. in `authProvider.login()`) and to remove it (e.g. in `authProvider.logout()`)
+
 **Tip**: `<FormFillerButton>` requires a model with Vision capabilities to extract text from images. We recommend using OpenAI's `gpt-4o-mini` or `gpt-4o` models.
 
 ## Props
@@ -148,3 +165,38 @@ Props to pass to the Dialog component.
 <FormFillerButton DialogProps={{ maxWidth: 'md' }} />
 ```
 {% endraw %}
+
+## `dataProvider.getCompletion()`
+
+In order to use the AI-powered components, your Data Provider must expose a `getCompletion()` method to suggest a completion for a prompt.
+
+-   input format: `{ prompt, stop, temperature, maxSize, meta }` (only the `prompt` property is required)
+-   output: `Promise({ data: completionString })`
+
+```jsx
+dataProvider
+    .getCompletion({ prompt: 'Lorem ipsum' })
+    .then(response => console.log(response.data));
+// ' dolor sit amet, consectetur adipiscing elit.'
+```
+
+It's your responsibility to implement the `dataProvider.getCompletion()` method. You can rely on an API to fetch the completion, or use a local completion model.
+
+If you rely on the [OpenAI Completion API](https://platform.openai.com/docs/api-reference/completions), you can use the `addGetCompletionBasedOnOpenAIAPI()` helper:
+
+```jsx
+// in src/dataProvider.js
+import jsonServerProvider from 'ra-data-json-server';
+import { addGetCompletionBasedOnOpenAIAPI } from '@react-admin/ra-ai';
+
+const baseDataProvider = jsonServerProvider(
+    import.meta.env.VITE_JSON_SERVER_URL
+);
+export const dataProvider = addGetCompletionBasedOnOpenAIAPI(baseDataProvider);
+```
+
+`addGetCompletionBasedOnOpenAIAPI` expects the OpenAI API key to be stored in the localStorage under the key `ra-ai.openai-api-key`. It's up to you to store the key in the localStorage (e.g. in `authProvider.login()`) and to remove it (e.g. in `authProvider.logout()`).
+
+**Tip**: A more secure way of using the OpenAI API is to add a proxy route in your API backend to the OpenAI API. That way, `getCompletion` will use the same credentials as the other data provider methods, and your OpenAI API key will never transit in the browser.
+
+If you rely on another API, you'll need to fetch it yourself.
\ No newline at end of file