> For the complete documentation index, see [llms.txt](https://cleyrop.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cleyrop.gitbook.io/docs/support-and-ressources/references-techniques-api-sdk/sdk-py-ai-cleyrop.md).

# SDK py-ai-cleyrop

Le SDK `py-ai-cleyrop` regroupe un ensemble de modules Python conçus pour intégrer facilement des capacités d'intelligence artificielle dans vos pipelines de données sur la plateforme Cleyrop. Il s'appuie sur LangChain et est compatible avec le format OpenAI.

Il couvre trois cas d'usage principaux : la conversation avec des modèles de langage (Chat), la transformation de textes en vecteurs (Embeddings), et la détection automatique de la langue de documents (Language Detection).

{% hint style="danger" %}
Une montée de version de Langchain vers Langchain v1 va être réalisée durant la release 4.5
{% endhint %}

***

## Installation dans le DevSpace

Installez le SDK depuis le registre GitLab Cleyrop via la commande suivante dans votre DevSpace :

```bash
uv pip install "py_ai_cleyrop" --extra-index-url "https:/gitlab.com/api/v4/projects/60268872/packages/pypi/simple"
```

## Modèles par défaut de la plateforme

Trois modèles par défaut peuvent être configurés par les Platform Managers depuis **Administration > Gérer les modèles et clés API**. Ces modèles sont accessibles directement dans PyAI via des noms conventionnels, sans avoir à spécifier l'identifiant exact du modèle.

| Modèle               | Usage                                                  | Nom dans PyAI         |
| -------------------- | ------------------------------------------------------ | --------------------- |
| **Modèle instruct**  | Utilisé par le Druide pour les conversations           | `"default-instruct"`  |
| **Modèle embedding** | Utilisé pour la vectorisation des corpus               | `"default-embedding"` |
| **Modèle coder**     | Utilisé pour les fonctionnalités de code (MCP Dataset) | `"default-coder"`     |

## Module Chat

Le module Chat permet d'interroger différents modèles de langage (LLMs) via une interface unifiée. Il est particulièrement adapté pour construire des chatbots, des agents conversationnels, ou automatiser des tâches de génération de texte.

**Dépendances requises :** `langchain >= 0.2.6`, `langchain-openai >= 0.1.23`, `requests 2.31.0`

### Appel simple (synchrone et asynchrone)

```python
from py_ai_cleyrop.chat.chat_bot import ChatCleyrop

chat = ChatCleyrop(
    llm_endpoint="http://ai-gen-proxy.cleyrop.svc.cluster.local/llm/cleyrop/v1",
    llm_token="your-api-key",
    model_name="Mistral-Small-3.2-24B-Instruct-2506",
    max_tokens=8192
)

# Appel synchrone
response = chat.invoke("Qu'est-ce que le machine learning ?")
print(response.content)

# Appel asynchrone
async def chat_async():
    response = await chat.ainvoke("Explique-moi l'IA générative.")
    return response.content
```

> **Bon à savoir :** Pour lister les modèles disponibles sur votre environnement :
>
> python
>
> ```python
> import requests, json
> print(json.dumps(requests.get("http://ai-gen-proxy.cleyrop.svc.cluster.local/llm/models").json(), indent=2))
> ```

### Intégration avec LangChain

Combinez `ChatCleyrop` avec les prompts et parseurs LangChain pour construire des chaînes de traitement.

```python
from py_ai_cleyrop.chat.chat_bot import ChatCleyrop
from langchain.prompts import ChatPromptTemplate
from langchain.schema.output_parser import StrOutputParser

chat = ChatCleyrop(
    llm_endpoint="http://ai-gen-proxy.cleyrop.svc.cluster.local/llm/cleyrop/v1",
    llm_token="your-api-key",
    model_name="Mistral-Small-3.2-24B-Instruct-2506",
)

prompt = ChatPromptTemplate.from_messages([
    ("system", "Tu es un expert en {domain}"),
    ("user", "{question}")
])

chain = prompt | chat | StrOutputParser()

result = chain.invoke({
    "domain": "cybersécurité",
    "question": "Qu'est-ce qu'une injection SQL ?"
})
print(result)
```

### Streaming de réponse

Activez le streaming pour recevoir la réponse token par token, idéal pour les interfaces conversationnelles temps réel.

```python
chat = ChatCleyrop(
    llm_endpoint="http://ai-gen-proxy.cleyrop.svc.cluster.local/llm/cleyrop/v1",
    llm_token="your-api-key",
    model_name="Mistral-Small-3.2-24B-Instruct-2506",
    streaming=True
)

# Streaming synchrone
for chunk in chat.stream("Raconte-moi une courte histoire"):
    print(chunk.content, end="", flush=True)

# Streaming asynchrone
async def stream_response():
    async for chunk in chat.astream("Explique l'informatique quantique"):
        print(chunk.content, end="", flush=True)
```

### Sortie structurée

Obtenez une réponse formatée selon un schéma Pydantic, utile pour extraire des données structurées depuis une réponse LLM.

```python
from py_ai_cleyrop.chat.chat_bot import ChatCleyrop
from pydantic import BaseModel

class StructuredOutput(BaseModel):
    title: str
    summary: str

chat = ChatCleyrop(
    temperature=0.1,
    llm_endpoint="http://ai-gen-proxy.cleyrop.svc.cluster.local/llm/cleyrop/v1",
    llm_token="your-api-key",
    model_name="Mistral-Small-3.2-24B-Instruct-2506",
    max_tokens=100
).with_structured_output(StructuredOutput)

result = chat.invoke([
    ("system", "Tu es un assistant de résumé."),
    ("human", "Résume cet article en une phrase."),
])
print(result)
```

### Paramètres de configuration — Chat

| Paramètre      | Type    | Description                         | Défaut  |
| -------------- | ------- | ----------------------------------- | ------- |
| `llm_endpoint` | `str`   | URL de l'endpoint du modèle         | Requis  |
| `llm_token`    | `str`   | Token d'authentification API        | Requis  |
| `model_name`   | `str`   | Nom du modèle à utiliser            | Requis  |
| `max_tokens`   | `int`   | Nombre maximum de tokens en réponse | `None`  |
| `temperature`  | `float` | Créativité de la génération (0 à 1) | `None`  |
| `streaming`    | `bool`  | Activation du streaming de réponse  | `False` |

## Module Embeddings

Le module Embeddings convertit des textes en représentations vectorielles (vecteurs numériques). Ces vecteurs permettent ensuite d'effectuer des recherches sémantiques, de calculer des similarités entre documents, ou d'alimenter des pipelines RAG (Retrieval-Augmented Generation).

```python
from py_ai_cleyrop.embeddings.embedding import EmbeddingsCleyrop

embeddings = EmbeddingsCleyrop(
    base_url="http://ai-gen-proxy.cleyrop.svc.cluster.local/emb/cleyrop",
    chunk_size=512,
    model_name="BAAI/bge-m3",
    api_key="your-api-key"
)

# Vectoriser plusieurs documents
documents = ["texte 1", "texte 2", "texte 3"]
embeddings_list = embeddings.embed_documents(documents)

# Vectoriser une requête unique
query = "ma requête de recherche"
query_embedding = embeddings.embed_query(query)
```

**Bon à savoir :** Pour lister les modèles d'embeddings disponibles :

```python
import requests, json
print(json.dumps(requests.get("http://ai-gen-proxy.cleyrop.svc.cluster.local/emb/models").json(), indent=2))
```

### Paramètres de configuration — Embeddings

| Paramètre           | Type  | Description                                     |
| ------------------- | ----- | ----------------------------------------------- |
| `base_url`          | `str` | URL de l'endpoint du service d'embeddings       |
| `chunk_size`        | `int` | Taille maximale des chunks de texte traités     |
| `model_name`        | `str` | Nom du modèle d'embeddings à utiliser           |
| `api_key`           | `str` | Clé d'authentification (optionnelle)            |
| `query_instruction` | `str` | Préfixe ajouté aux requêtes avant vectorisation |

## Module Language Detection

Le module Language Detection identifie automatiquement la langue dominante d'un ensemble de documents. Il est utile pour router des traitements différents selon la langue, ou filtrer des documents avant une étape de traitement NLP.

### Utilisation

```python
from langchain_core.documents import Document
from py_ai_cleyrop.language_detection.language_detection import detect_language

# Utilisation avec les langues par défaut (anglais et français)
documents = [Document(page_content="Texte à analyser")]
result = detect_language(documents)

# Détection personnalisée sur plusieurs langues
result = detect_language(
    documents=documents,
    languages_to_detect=["en", "fr", "es", "de"],
    language_threshold=0.1
)

print(f"Langue principale : {result.major_language}")
print(f"Distribution des langues : {result.language_details}")
```

### Paramètres de configuration — Language Detection

| Paramètre             | Type        | Description                                  | Défaut         |
| --------------------- | ----------- | -------------------------------------------- | -------------- |
| `languages_to_detect` | `list[str]` | Codes ISO 639-1 des langues à détecter       | `["en", "fr"]` |
| `language_threshold`  | `float`     | Seuil minimum de confiance pour la détection | `0`            |

**Bon à savoir :** Le résultat retourne deux informations : `major_language` (la langue principale détectée) et `language_details` (la distribution en pourcentage de chaque langue identifiée).

***

### Bonnes pratiques

* **Gérez toujours les erreurs** : encapsulez vos appels dans un bloc `try/except` pour anticiper les indisponibilités d'endpoint ou les problèmes d'authentification.
* **Limitez** `max_tokens` selon votre cas d'usage : une valeur de 512 est souvent suffisante pour des réponses courtes, ce qui réduit la latence.
* **Vérifiez les modèles disponibles** avant de configurer votre client, car les endpoints et noms de modèles peuvent évoluer.
* **Privilégiez le streaming** pour les interfaces utilisateur interactives afin d'améliorer la réactivité perçue.
* **Définissez un** `language_threshold` adapté à votre corpus pour éviter les faux positifs sur des textes très courts ou multilingues.
* **Les métadonnées Cleyrop** (`PROJECT_ID`, `HOSTNAME`) sont automatiquement ajoutées à chaque appel Chat pour assurer la traçabilité.