> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/clore.ai/clore.ai-eng-fr/developpeurs/python-sdk.md).

# SDK Python (clore-ai)

Le **clore-ai** package est le SDK Python officiel pour la [Clore.ai](https://clore.ai) place de marché de GPU. Il encapsule toute l'API REST dans une interface propre et sûre au niveau des types, avec limitation de débit intégrée, nouvelles tentatives automatiques et gestion structurée des erreurs — afin que vous puissiez vous concentrer sur la location de GPU, pas sur la plomberie HTTP.

***

## Installation

```bash
pip install clore-ai
```

**Conditions requises :** Python 3.9+

Le package installe à la fois le SDK Python et le [`clore` CLI](/clore.ai/clore.ai-eng-fr/developpeurs/cli-guide.md).

***

## Authentification

Obtenez votre clé API depuis le [tableau de bord Clore.ai](https://clore.ai) → **API** section.

### Option 1 : Variable d'environnement (recommandé)

```bash
export CLORE_API_KEY=your_api_key_here
```

Le SDK lit `CLORE_API_KEY` automatiquement — aucun changement de code nécessaire.

### Option 2 : fichier de configuration CLI

```bash
clore config set api_key YOUR_API_KEY
```

Cela stocke la clé dans `~/.clore/config.json`.

### Option 3 : Passez-la directement dans le code

```python
from clore_ai import CloreAI

client = CloreAI(api_key="your_api_key_here")
```

> ⚠️ **Important :** L'API Clore.ai utilise l'en-tête `auth` pour l'authentification, **et non** `Authorization: Bearer`. Le SDK gère cela automatiquement.

***

## Démarrage rapide

```python
from clore_ai import CloreAI

client = CloreAI()
servers = client.marketplace(gpu="RTX 4090", max_price_usd=5.0)
for s in servers:
    print(f"Serveur {s.id} : {s.gpu_model} — ${s.price_usd:.4f}/h")
```

***

## Client synchrone (`CloreAI`)

### Constructeur

```python
CloreAI(
    api_key: str | None = None,       # Retombe sur CLORE_API_KEY de l'env / de la config
    base_url: str | None = None,       # Par défaut : https://api.clore.ai/v1
    timeout: float = 30.0,             # Délai d'attente de la requête en secondes
    max_retries: int = 3               # Nombre de nouvelles tentatives en cas de limitation de débit / d'erreurs réseau
)
```

Le client prend en charge les gestionnaires de contexte pour un nettoyage automatique :

```python
with CloreAI() as client:
    wallets = client.wallets()
    # client.close() appelé automatiquement
```

***

### `wallets()`

Obtenez vos soldes de portefeuille et vos adresses de dépôt.

```python
wallets = client.wallets()

for wallet in wallets:
    print(f"{wallet.name} : {wallet.balance:.8f}")
    if wallet.deposit:
        print(f"  Dépôt : {wallet.deposit}")
```

**Renvoie :** `List[Wallet]`

| Champ            | Type            | Description                                                                     |
| ---------------- | --------------- | ------------------------------------------------------------------------------- |
| `name`           | `str`           | Nom de la devise (p. ex. `"bitcoin"`, `"CLORE-Blockchain"`, `"USD-Blockchain"`) |
| `balance`        | `float \| None` | Solde actuel                                                                    |
| `deposit`        | `str \| None`   | Adresse de dépôt                                                                |
| `withdrawal_fee` | `float \| None` | Frais de retrait                                                                |

***

### `marketplace()`

Recherchez la place de marché GPU avec des filtres côté client facultatifs.

```python
# Tous les serveurs disponibles
servers = client.marketplace()

# Filtrer par modèle de GPU et prix maximum
servers = client.marketplace(
    gpu="RTX 4090",
    max_price_usd=5.0
)

# Configurations multi-GPU avec beaucoup de RAM
servers = client.marketplace(
    min_gpu_count=4,
    min_ram_gb=128.0
)
```

**Paramètres :**

| Paramètre        | Type            | Par défaut | Description                                                                     |
| ---------------- | --------------- | ---------- | ------------------------------------------------------------------------------- |
| `gpu`            | `str \| None`   | `None`     | Filtrer par modèle de GPU (correspondance de sous-chaîne insensible à la casse) |
| `min_gpu_count`  | `int \| None`   | `None`     | Nombre minimum de GPU                                                           |
| `min_ram_gb`     | `float \| None` | `None`     | RAM minimale en Go                                                              |
| `max_price_usd`  | `float \| None` | `None`     | Prix maximum par heure en USD                                                   |
| `available_only` | `bool`          | `True`     | Ne retourner que les serveurs disponibles à la location                         |

**Renvoie :** `List[MarketplaceServer]`

Chaque `MarketplaceServer` fournit des propriétés pratiques pour les champs les plus courants, ainsi qu'un accès aux données imbriquées complètes :

| Propriété        | Type            | Description                                                           |
| ---------------- | --------------- | --------------------------------------------------------------------- |
| `id`             | `int`           | ID unique du serveur                                                  |
| `gpu_model`      | `str \| None`   | Description principale du GPU (p. ex. `"1x NVIDIA GeForce RTX 4090"`) |
| `gpu_count`      | `int`           | Nombre de GPU (à partir de `gpu_array`)                               |
| `ram_gb`         | `float \| None` | RAM en Go                                                             |
| `price_usd`      | `float \| None` | Prix à la demande en USD                                              |
| `spot_price_usd` | `float \| None` | Prix spot en USD                                                      |
| `available`      | `bool`          | Indique si le serveur est disponible (non loué)                       |
| `location`       | `str \| None`   | Code pays provenant des spécifications réseau                         |

Pour des cas d'utilisation avancés, vous pouvez accéder à la structure imbriquée complète :

| Champ         | Type                   | Description                                                                                                   |
| ------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------- |
| `specs`       | `ServerSpecs \| None`  | Spécifications matérielles complètes (`specs.gpu`, `specs.ram`, `specs.cpu`, `specs.disk`, `specs.net`, etc.) |
| `price`       | `ServerPrice \| None`  | Objet de prix complet (`price.usd.on_demand_usd`, `price.usd.spot`, `price.on_demand`, etc.)                  |
| `rented`      | `bool \| None`         | Indique si le serveur est actuellement loué                                                                   |
| `reliability` | `float \| None`        | Score de fiabilité du serveur                                                                                 |
| `rating`      | `ServerRating \| None` | Note du serveur (`rating.avg`, `rating.cnt`)                                                                  |

> **Remarque :** Le `marketplace()` le point de terminaison est public — il fonctionne sans clé API.

***

### `my_servers()`

Listez les serveurs que vous fournissez à la place de marché Clore.ai.

```python
my_servers = client.my_servers()

for server in my_servers:
    print(f"{server.name} : {server.gpu_model} [{server.status}]")
```

**Renvoie :** `List[MyServer]`

| Propriété    | Type            | Description                                                                                          |
| ------------ | --------------- | ---------------------------------------------------------------------------------------------------- |
| `id`         | `int`           | ID du serveur                                                                                        |
| `name`       | `str \| None`   | Nom du serveur                                                                                       |
| `gpu_model`  | `str \| None`   | Description principale du GPU                                                                        |
| `ram_gb`     | `float \| None` | RAM en Go                                                                                            |
| `status`     | `str`           | Statut lisible par l'humain : `"En ligne"`, `"Hors ligne"`, `"Déconnecté"`, ou `"Ne fonctionne pas"` |
| `connecté`   | `bool \| None`  | Indique si le serveur est connecté                                                                   |
| `en ligne`   | `bool \| None`  | Indique si le serveur est en ligne                                                                   |
| `visibilité` | `str \| None`   | `"public"` ou `"private"`                                                                            |

***

### `server_config(server_name)`

Obtenez la configuration d'un serveur spécifique que vous hébergez.

```python
config = client.server_config("MyGPU")

print(f"Serveur : {config.name}")
print(f"GPU : {config.gpu_model}")
print(f"Location minimale : {config.mrl}h")
print(f"À la demande : ${config.on_demand_price}")
print(f"Spot : ${config.spot_price}")
```

**Paramètres :**

| Paramètre     | Type  | Description    |
| ------------- | ----- | -------------- |
| `server_name` | `str` | Nom du serveur |

**Renvoie :** `ServerConfig`

| Propriété         | Type                  | Description                              |
| ----------------- | --------------------- | ---------------------------------------- |
| `name`            | `str \| None`         | Nom du serveur                           |
| `gpu_model`       | `str \| None`         | Description principale du GPU            |
| `mrl`             | `int \| None`         | Durée de location maximale en heures     |
| `on_demand_price` | `float \| None`       | Premier prix USD à la demande disponible |
| `spot_price`      | `float \| None`       | Premier prix USD spot disponible         |
| `specs`           | `ServerSpecs \| None` | Spécifications matérielles complètes     |
| `connecté`        | `bool \| None`        | Indique si le serveur est connecté       |
| `visibilité`      | `str \| None`         | `"public"` ou `"private"`                |

***

### `my_orders(include_completed)`

Obtenez vos commandes en cours, en incluant éventuellement celles terminées/expirées.

```python
# Commandes actives uniquement
orders = client.my_orders()

# Inclure les commandes terminées
all_orders = client.my_orders(include_completed=True)

for order in orders:
    print(f"Commande {order.id} : {order.type} — {order.status}")
    if order.pub_cluster:
        print(f"  IP : {order.pub_cluster}")
    if order.tcp_ports:
        print(f"  Ports : {order.tcp_ports}")
```

**Paramètres :**

| Paramètre           | Type   | Par défaut | Description                              |
| ------------------- | ------ | ---------- | ---------------------------------------- |
| `include_completed` | `bool` | `False`    | Inclure les commandes terminées/expirées |

**Renvoie :** `List[Order]`

| Champ         | Type            | Description                         |
| ------------- | --------------- | ----------------------------------- |
| `id`          | `int`           | ID unique de la commande            |
| `server_id`   | `int \| None`   | ID du serveur                       |
| `type`        | `str`           | `"on-demand"` ou `"spot"`           |
| `status`      | `str \| None`   | Statut de la commande               |
| `image`       | `str \| None`   | Image Docker                        |
| `currency`    | `str \| None`   | Devise de paiement                  |
| `price`       | `float \| None` | Prix de la commande par jour        |
| `pub_cluster` | `str \| None`   | Nom d'hôte public / IP pour l'accès |
| `tcp_ports`   | `dict \| None`  | Mappages de ports TCP               |

***

### `spot_marketplace(server_id)`

Consultez les offres du marché spot pour un serveur spécifique.

```python
spot = client.spot_marketplace(server_id=6)

if spot.offers:
    for offer in spot.offers:
        print(f"Commande {offer.order_id} : ${offer.price}/jour (serveur {offer.server_id})")

if spot.currency_rates_in_usd:
    for coin, rate in spot.currency_rates_in_usd.items():
        print(f"  {coin} : ${rate}")
```

**Paramètres :**

| Paramètre   | Type  | Description              |
| ----------- | ----- | ------------------------ |
| `server_id` | `int` | ID du serveur à vérifier |

**Renvoie :** `SpotMarket`

| Champ                   | Type                       | Description                                                |
| ----------------------- | -------------------------- | ---------------------------------------------------------- |
| `offers`                | `List[SpotOffer] \| None`  | Liste des offres spot (`order_id`, `price`, `server_id`)   |
| `server`                | `SpotServerInfo \| None`   | Infos du serveur (prix minimum, visibilité, état en ligne) |
| `currency_rates_in_usd` | `Dict[str, float] \| None` | Taux de change des devises en USD                          |

***

### `create_order(...)`

Créez une nouvelle commande à la demande ou spot. C'est ainsi que vous louez un GPU.

#### Commande à la demande

```python
order = client.create_order(
    server_id=123,
    image="cloreai/ubuntu22.04-cuda12",
    type="on-demand",
    currency="bitcoin",
    ssh_password="MySecurePass123",
    ports={"22": "tcp", "8888": "http"}
)

print(f"Commande créée : {order.id}")
print(f"Connexion : {order.pub_cluster}")
```

#### Commande spot

```python
order = client.create_order(
    server_id=123,
    image="cloreai/pytorch",
    type="spot",
    currency="bitcoin",
    spot_price=0.000005,
    ssh_password="MySecurePass123",
    ports={"22": "tcp"}
)
```

**Paramètres :**

| Paramètre            | Type        | Requis          | Description                                                                                                                                                                                      |
| -------------------- | ----------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `server_id`          | `int`       | Oui             | ID du serveur à louer                                                                                                                                                                            |
| `image`              | `str`       | Oui             | Image Docker (p. ex. `"cloreai/ubuntu22.04-cuda12"`)                                                                                                                                             |
| `type`               | `str`       | Oui             | `"on-demand"` ou `"spot"`                                                                                                                                                                        |
| `currency`           | `str`       | Oui             | Devise de paiement (p. ex. `"bitcoin"`)                                                                                                                                                          |
| `ssh_password`       | `str`       | Non             | Mot de passe SSH (alphanumérique, 32 caractères max)                                                                                                                                             |
| `ssh_key`            | `str`       | Non             | Clé publique SSH (3072 caractères max)                                                                                                                                                           |
| `ports`              | `dict`      | Non             | Mappages de ports, p. ex. `{"22": "tcp", "8888": "http"}`                                                                                                                                        |
| `env`                | `dict`      | Non             | Variables d'environnement                                                                                                                                                                        |
| `jupyter_token`      | `str`       | Non             | Jeton du notebook Jupyter (32 caractères max)                                                                                                                                                    |
| `command`            | `str`       | Non             | Commande shell à exécuter après le démarrage du conteneur                                                                                                                                        |
| `spot_price`         | `float`     | Spot uniquement | Prix par jour pour les commandes spot                                                                                                                                                            |
| `required_price`     | `float`     | Non             | Verrouillez un prix spécifique (à la demande uniquement)                                                                                                                                         |
| `autossh_entrypoint` | `str`       | Non             | Utilisez le point d'entrée SSH de Clore.ai                                                                                                                                                       |
| `gpu_count`          | `int`       | Non             | Louer seulement N GPU sur des serveurs avec [location partielle](/clore.ai/clore.ai-eng-fr/pour-les-locataires/partial-gpu-rental.md) (uniquement à la demande) ; omettez pour louer tout le rig |
| `gpu_indices`        | `list[int]` | Non             | Emplacements GPU exacts de `partial_gpu_rental.free_indices`; la longueur doit être égale à `gpu_count`; omettez pour sélection automatique                                                      |

**Renvoie :** réponse API brute (`{"code": 0}` en cas de succès) ; récupérez la commande créée via `my_orders()`

> **Limite de débit :** `create_order` a un délai de récupération spécial de 5 secondes entre les appels. Le SDK l'applique automatiquement.

***

### `cancel_order(order_id, issue)`

Annulez une commande active ou une offre spot. Vous pouvez éventuellement signaler un problème avec le serveur.

```python
# Annulation simple
client.cancel_order(order_id=38)

# Annulation avec signalement d'un problème
client.cancel_order(
    order_id=38,
    issue="Le GPU #1 surchauffait et était bridé"
)
```

**Paramètres :**

| Paramètre  | Type  | Requis | Description                                                        |
| ---------- | ----- | ------ | ------------------------------------------------------------------ |
| `order_id` | `int` | Oui    | ID de commande à annuler                                           |
| `issue`    | `str` | Non    | Raison de l'annulation / rapport de problème (2048 caractères max) |

**Renvoie :** `Dict[str, Any]`

***

### `set_server_settings(...)`

Mettre à jour les paramètres d'un serveur que vous hébergez sur la place de marché.

```python
client.set_server_settings(
    name="MyGPU",
    availability=True,
    mrl=96,
    on_demand=0.0001,
    spot=0.00000113
)
```

**Paramètres :**

| Paramètre       | Type    | Requis | Description                          |
| --------------- | ------- | ------ | ------------------------------------ |
| `name`          | `str`   | Oui    | Nom du serveur                       |
| `Disponibilité` | `bool`  | Non    | Si le serveur peut être loué         |
| `mrl`           | `int`   | Non    | Durée de location maximale en heures |
| `à la demande`  | `float` | Non    | Prix à la demande par jour           |
| `spot`          | `float` | Non    | Prix spot minimum par jour           |

**Renvoie :** `Dict[str, Any]`

***

### `set_spot_price(order_id, price)`

Mettre à jour le prix de votre offre sur le marché spot.

```python
client.set_spot_price(order_id=39, price=0.000003)
```

**Paramètres :**

| Paramètre  | Type    | Description               |
| ---------- | ------- | ------------------------- |
| `order_id` | `int`   | ID de commande/offre spot |
| `price`    | `float` | Nouveau prix par jour     |

**Renvoie :** `Dict[str, Any]`

> **Remarque :** Vous ne pouvez baisser les prix spot qu'une fois toutes les 600 secondes, et par un pas limité. L'API renvoie `code: 6` avec des détails si vous dépassez ces limites.

***

## Client asynchrone (`AsyncCloreAI`)

Le `AsyncCloreAI` Le client fournit les mêmes méthodes que `CloreAI`, mais toutes renvoient des coroutines. Utilisez-le lorsque vous avez besoin d'appels API concurrents ou que vous travaillez dans une application asynchrone.

### Utilisation de base

```python
import asyncio
from clore_ai import AsyncCloreAI

async def main():
    async with AsyncCloreAI(api_key="your_key") as client:
        wallets = await client.wallets()
        for w in wallets:
            print(f"{w.name}: {w.balance:.8f}")

asyncio.run(main())
```

### Opérations concurrentes

Exécutez plusieurs appels API en parallèle avec `asyncio.gather`:

```python
import asyncio
from clore_ai import AsyncCloreAI

async def compare_gpus():
    async with AsyncCloreAI() as client:
        # Rechercher plusieurs modèles de GPU simultanément
        rtx4090, rtx3090, a100 = await asyncio.gather(
            client.marketplace(gpu="RTX 4090"),
            client.marketplace(gpu="RTX 3090"),
            client.marketplace(gpu="A100"),
        )

        for name, servers in [("RTX 4090", rtx4090), ("RTX 3090", rtx3090), ("A100", a100)]:
            if servers:
                cheapest = min(s.price_usd or float('inf') for s in servers)
                print(f"{name}: {len(servers)} disponibles, le moins cher ${cheapest:.4f}/h")
            else:
                print(f"{name}: aucun disponible")

asyncio.run(compare_gpus())
```

### Méthodes disponibles

`AsyncCloreAI` prend en charge toutes les mêmes méthodes que `CloreAI`:

| Méthode                             | Description                             |
| ----------------------------------- | --------------------------------------- |
| `await wallets()`                   | Obtenir les soldes des portefeuilles    |
| `await marketplace(...)`            | Rechercher sur la place de marché       |
| `await my_servers()`                | Lister vos serveurs hébergés            |
| `await server_config(name)`         | Obtenir la configuration du serveur     |
| `await my_orders(...)`              | Lister vos commandes                    |
| `await spot_marketplace(server_id)` | Obtenir les offres du marché spot       |
| `await create_order(...)`           | Créer une nouvelle commande             |
| `await cancel_order(...)`           | Annuler une commande                    |
| `await set_server_settings(...)`    | Mettre à jour les paramètres du serveur |
| `await set_spot_price(...)`         | Mettre à jour le prix spot              |

***

## Gestion des erreurs

Le SDK fournit des classes d'exception structurées pour chaque code d'erreur de l'API.

```python
from clore_ai import CloreAI
from clore_ai.exceptions import (
    CloreAPIError,      # Classe de base pour toutes les erreurs d'API
    AuthError,          # Code 3 — clé API invalide
    RateLimitError,     # Code 5 — limite de débit dépassée
    InvalidInputError,  # Code 2 — données de requête incorrectes
    DBError,            # Code 1 — erreur de base de données
    InvalidEndpointError,  # Code 4 — point de terminaison invalide
    FieldError,         # Code 6 — erreur spécifique à un champ
)

client = CloreAI()

try:
    order = client.create_order(
        server_id=123,
        image="cloreai/ubuntu22.04-cuda12",
        type="on-demand",
        currency="bitcoin",
    )
except AuthError:
    print("Clé API invalide. Vérifiez votre CLORE_API_KEY.")
except RateLimitError:
    print("Limite de débit atteinte. Le SDK réessaie automatiquement, mais vous avez atteint le nombre maximal de nouvelles tentatives.")
except InvalidInputError as e:
    print(f"Requête incorrecte : {e}")
except FieldError as e:
    # Les erreurs de code 6 incluent des détails dans la réponse
    print(f"Erreur de champ : {e} (détails : {e.response})")
except CloreAPIError as e:
    print(f"Erreur d'API : {e} (code : {e.code})")
```

### Codes d'erreur

| Code | Exception              | Description                                                           |
| ---- | ---------------------- | --------------------------------------------------------------------- |
| 0    | —                      | Succès                                                                |
| 1    | `DBError`              | Erreur de base de données                                             |
| 2    | `InvalidInputError`    | Données d'entrée invalides                                            |
| 3    | `AuthError`            | Jeton API invalide                                                    |
| 4    | `InvalidEndpointError` | Point de terminaison invalide                                         |
| 5    | `RateLimitError`       | Limite de débit dépassée                                              |
| 6    | `FieldError`           | Erreur dans un champ spécifique (voir `erreur` champ dans la réponse) |

Toutes les classes d'exception héritent de `CloreAPIError` et incluent :

* `e.code` — code d'erreur numérique
* `e.response` — dictionnaire complet de réponse de l'API (si disponible)

***

## Limitation du débit

Le SDK inclut un limiteur de débit intégré qui applique automatiquement les limites de Clore.ai :

| Point de terminaison                 | Limite                   |
| ------------------------------------ | ------------------------ |
| La plupart des points de terminaison | **1 requête/seconde**    |
| `create_order`                       | **1 requête/5 secondes** |

Lorsque l'API renvoie une erreur de limite de débit (code 5), le SDK applique **une temporisation exponentielle** et réessaie jusqu'à `max_retries` fois (par défaut : 3). Vous n'avez pas besoin d'ajouter `time.sleep()` entre les appels.

### Comment ça fonctionne

1. Avant chaque requête, le limiteur de débit attend que l'intervalle minimum se soit écoulé.
2. `create_order` les appels imposent un délai de récupération supplémentaire de 5 secondes.
3. En cas d'erreurs de limite de débit, le SDK augmente le délai de manière exponentielle : 1 s → 2 s → 4 s → ...
4. Après `max_retries` tentatives échouées, une `RateLimitError` est levée.

### Personnaliser le comportement de nouvelle tentative

```python
client = CloreAI(
    max_retries=5,    # Plus de tentatives pour les scripts de longue durée
    timeout=60.0      # Délai d'attente plus long pour les connexions lentes
)
```

***

## Configuration

### Fichier de configuration

Le CLI stocke la configuration dans `~/.clore/config.json`:

```json
{
  "api_key": "your_api_key_here"
}
```

### Ordre de résolution

Le SDK résout la clé API dans cet ordre :

1. `api_key` argument transmis au constructeur
2. `CLORE_API_KEY` variable d'environnement
3. `api_key` champ dans `~/.clore/config.json`

### Variables d'environnement

| Variable        | Description                     |
| --------------- | ------------------------------- |
| `CLORE_API_KEY` | Clé API pour l'authentification |

***

## Étapes suivantes

* [**Référence CLI**](/clore.ai/clore.ai-eng-fr/developpeurs/cli-guide.md) — Utilisez Clore.ai depuis votre terminal
* [**API REST**](/clore.ai/clore.ai-eng-fr/pour-les-hotes/api.md) — Documentation brute de l'API pour des intégrations personnalisées
* [**À la demande vs spot**](/clore.ai/clore.ai-eng-fr/pour-les-locataires/on-demand-vs-spot.md) — Comprendre les modèles de tarification
* [**Images Docker disponibles**](/clore.ai/clore.ai-eng-fr/pour-les-locataires/docker-images.md) — Images préconstruites pour les charges de travail GPU


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.clore.ai/clore.ai/clore.ai-eng-fr/developpeurs/python-sdk.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.