Mankinds SDK

Choisissez votre langage :

Intégrez l'évaluation IA responsable dans vos applications. Le SDK Mankinds fournit les outils pour créer des systèmes, connecter vos sources de données, générer des datasets de test et lancer des évaluations — programmable en JavaScript/TypeScript et Python.

from mankinds_sdk import MankindsClient
import os

client = MankindsClient(api_key=os.environ["MANKINDS_API_KEY"])

# Créer un système, générer un dataset, évaluer
system = client.create_system("Mon Assistant IA", "...", endpoint={...})
client.generate_dataset(system["id"], num_scenarios=10)
result = client.evaluate(system["id"])
print(f"Score: {result['summary']['global_score']}%")

Commencer

Quelques étapes suffisent pour intégrer l'évaluation IA dans votre projet.

Installer le SDK

pip install mankinds-sdk

Obtenir votre clé API

Créez un compte sur app.mankinds.io et générez votre clé API depuis les paramètres.

Initialiser le client

import os
from mankinds_sdk import MankindsClient

client = MankindsClient(api_key=os.environ["MANKINDS_API_KEY"])

Lancer votre première évaluation

Créez un système, générez un dataset de test, puis lancez l'évaluation :

# 1. Créer un système avec son endpoint
system = client.create_system(
  "Assistant Conformité RGPD",
  "Chatbot qui conseille les entreprises sur le RGPD.",
  endpoint={
      "url": "https://api.example.com/chat",
      "method": "POST",
      "body": {"message": "{{input}}"},
      "response": {"reply": "{{output}}"}
  }
)

# 2. Générer un dataset de test (10 scénarios)
dataset = client.generate_dataset(system["id"], num_scenarios=10)

# 3. Lancer l'évaluation
result = client.evaluate(system["id"])
print(f"Score global: {result['summary']['global_score']}%")

Fonctionnalités

Fonctionnalité	Description
Systèmes	Créer, configurer et gérer vos systèmes IA avec validation automatique de la description
Connecteurs	Brancher vos logs (fichiers, Datadog) et bases de données (SQLite, PostgreSQL)
Datasets	Fournir vos scénarios de référence ou les générer automatiquement par IA
Évaluations	Lancer des évaluations sur 61 critères (sécurité, équité, fiabilité…) et récupérer les scores
Authentification	Clé API sécurisée avec gestion fine des permissions

Référence API

MankindsClient

Le client principal pour interagir avec l'API Mankinds.

Constructeur

MankindsClient(api_key: str, base_url: str = None, timeout: int = 30)

Paramètre	Type	Requis	Défaut	Description
`api_key`	`str`	Requis	—	Clé API Mankinds (format : mk_...)
`base_url`	`str`	Optionnel	`https://app.mankinds.io`	URL de base de l'API
`timeout`	`int`	Optionnel	`120`	Timeout des requêtes en secondes

Systèmes

createSystem

Crée un nouveau système IA et valide automatiquement sa description.

Paramètre	Type	Requis	Description
`name`	`str`	Requis	Nom du système IA
`description`	`str`	Requis	Description du comportement attendu du système
`endpoint`	`dict`	Requis	Configuration de l'endpoint API (url, method, body, response)

Retourne	Type	Description
`id`	`string`	Identifiant unique du système créé
`success`	`boolean`	true si la description a été validée
`recommendations`	`array`	Recommandations pour améliorer la description

Configuration de l'endpoint

Dans les configurations body et response de votre endpoint, utilisez les placeholders {{input}} et {{output}} pour injecter dynamiquement les scénarios de test.

system = client.create_system(
  "Assistant Conformité RGPD",
  "Chatbot qui conseille les entreprises sur leurs obligations RGPD et guide dans la mise en conformité.",
  endpoint={
      "url": "https://api.example.com/chat",
      "method": "POST",
      "body": {"message": "{{input}}"},
      "response": {"reply": "{{output}}"}
  }
)

print(f"Système créé : {system['id']}")
print(f"Description validée : {system['success']}")

getSystem

Récupère les détails d'un système.

Paramètre	Type	Requis	Description
`system_id`	`str`	Requis	Identifiant unique du système

Retourne	Type	Description
`id`	`string`	Identifiant unique du système
`name`	`string`	Nom du système
`description`	`string`	Description du système
`is_description_validated`	`boolean`	true si la description a été validée
`endpoint`	`object`	Configuration de l'endpoint

system = client.get_system(system_id)

print(f"Nom: {system['name']}")
print(f"Description validée: {system['is_description_validated']}")
print(f"Endpoint: {system['endpoint']}")

updateSystem

Met à jour un système existant.

Paramètre	Type	Requis	Description
`system_id`	`str`	Requis	Identifiant unique du système
`name`	`str`	Optionnel	Nouveau nom du système
`description`	`str`	Optionnel	Nouvelle description (déclenche une re-validation)
`endpoint`	`dict`	Optionnel	Nouvelle configuration de l'endpoint

Retourne	Type	Description
`success`	`boolean`	true si la mise à jour a réussi
`recommendations`	`array`	Recommandations si re-validation de la description

Validation de l'endpoint

Si vous fournissez un endpoint, il doit contenir les champs requis : url, method, body, response. Sinon, l'exception InvalidEndpointError sera levée.

result = client.update_system(
  system_id,
  name="Assistant Conformité RGPD v2",
  description="Version améliorée avec support des questions sur le DPO."
)

print(f"Validé: {result['success']}")

Si une nouvelle description est fournie, elle est automatiquement re-validée. En cas d'échec, DescriptionNotValidatedError est levée avec les recommandations.

Connecteurs

Les connecteurs permettent de brancher vos sources de données (logs, bases de données).

Un seul connecteur par catégorie

Chaque système ne peut avoir qu'un seul connecteur par catégorie (logs, database).

Types disponibles

Connecteur	Catégorie	Description
`FileConnector`	logs	Fichiers de logs (.log, .txt, .json)
`DatadogConnector`	logs	Logs depuis Datadog
`SqliteConnector`	database	Base SQLite (.db, .sqlite)
`PostgresqlConnector`	database	Base PostgreSQL distante

addConnector

Ajoute un connecteur au système.

Paramètre	Type	Requis	Description
`system_id`	`str`	Requis	Identifiant unique du système
`connector`	`BaseConnector`	Requis	Instance du connecteur (FileConnector, SqliteConnector, etc.)

Un seul connecteur par catégorie

Si un connecteur de la même catégorie existe déjà, l'exception ConnectorAlreadyExistsError sera levée. Supprimez d'abord l'existant avec deleteConnector().

from mankinds_sdk.connectors import FileConnector, SqliteConnector

# Logs
log_connector = FileConnector(
  file_path="./logs/app.log",
  name="Application Logs",
)
result = client.add_connector(system_id, log_connector)
print(f"Connecteur ajouté: {result}")

# Database
db_connector = SqliteConnector(
  file_path="./data/users.db",
  name="Users Database",
)
client.add_connector(system_id, db_connector)

getConnectors

Liste tous les connecteurs d'un système.

Paramètre	Type	Requis	Description
`system_id`	`str`	Requis	Identifiant unique du système

Retourne	Type	Description
`name`	`string`	Nom du connecteur
`category`	`string`	Catégorie : logs ou database
`type`	`string`	Type de connecteur (file, datadog, sqlite, postgresql)

connectors = client.get_connectors(system_id)

for c in connectors:
  print(f"{c['name']} ({c['category']}): {c['type']}")

updateConnector

Met à jour la configuration d'un connecteur existant.

Paramètre	Type	Requis	Description
`system_id`	`str`	Requis	Identifiant unique du système
`connector`	`BaseConnector`	Requis	Instance du connecteur avec la configuration mise à jour

from mankinds_sdk.connectors import FileConnector

updated_connector = FileConnector(
  file_path="./logs/new-app.log",
  name="Updated Logs",
)
result = client.update_connector(system_id, updated_connector)
print(f"Connecteur mis à jour: {result}")

deleteConnector

Supprime un connecteur du système.

Paramètre	Type	Requis	Description
`system_id`	`str`	Requis	Identifiant unique du système
`connector`	`BaseConnector`	Requis	Instance du connecteur à supprimer

result = client.delete_connector(system_id, log_connector)
print(f"Connecteur supprimé: {result}")

Datasets

generateDataset

Crée et valide un dataset de scénarios de référence. Vous pouvez fournir des scénarios ou demander une génération automatique.

Paramètre	Type	Requis	Défaut	Description
`system_id`	`str`	Requis	—	Identifiant unique du système
`num_scenarios`	`int`	Optionnel	`10`	Nombre de scénarios à générer automatiquement (ignoré si scenarios fourni)
`scenarios`	`list[dict]`	Optionnel	—	Scénarios personnalisés avec input (str) et outputs (list)

Retourne	Type	Description
`scenarios`	`array`	Liste des scénarios validés
`scenarios[].id`	`string`	Identifiant unique du scénario
`scenarios[].input`	`object`	Entrée du scénario (prompt)
`scenarios[].expected_outputs`	`array`	Sorties attendues
`scenarios[].source`	`string`	Origine : user ou generated

Description validée requise

La description du système doit être validée avant de créer un dataset. Sinon, l'exception DescriptionNotValidatedError sera levée.

# Avec scénarios personnalisés
dataset = client.generate_dataset(system_id, scenarios=[
  {"input": "Bonjour, comment ça marche ?", "outputs": ["Bienvenue ! Je suis là pour vous aider."]},
  {"input": "Je veux un remboursement", "outputs": ["Je vous redirige vers notre service clients."]},
])

print(f"{len(dataset['scenarios'])} scénarios validés")

# Génération automatique
dataset = client.generate_dataset(system_id, num_scenarios=20)
print(f"{len(dataset['scenarios'])} scénarios générés")

updateDataset

Met à jour le dataset avec des instructions ou de nouveaux scénarios.

Paramètre	Type	Requis	Description
`system_id`	`str`	Requis	Identifiant unique du système
`orientation`	`str`	Optionnel	Instructions pour affiner le dataset
`scenarios`	`list[dict]`	Optionnel	Nouveaux scénarios pour remplacer les existants

# Affiner avec des instructions
dataset = client.update_dataset(
  system_id,
  orientation="Ajouter plus de cas de demandes de remboursement"
)
print(f"{len(dataset['scenarios'])} scénarios après mise à jour")

Retourne

Même structure que generateDataset — le dataset mis à jour et re-validé.

Évaluations

evaluate

Lance une évaluation complète du système.

Paramètre	Type	Requis	Défaut	Description
`system_id`	`str`	Requis	—	Identifiant unique du système
`profile`	`str`	Optionnel	`required`	Profil d'évaluation (voir tableau ci-dessous)
`thematics_config`	`dict`	Optionnel	—	Configuration personnalisée par critère (remplace profile)
`wait`	`bool`	Optionnel	`true`	Attendre la fin de l'évaluation avant de retourner
`poll_interval`	`int`	Optionnel	`5`	Intervalle en secondes entre chaque vérification de statut
`on_poll`	`Callable[[str, int], None]`	Optionnel	—	Callback appelé à chaque vérification (statut, secondes écoulées)

Retourne	Type	Description
`run_id`	`string`	Identifiant unique de l'exécution
`status`	`string`	completed, failed, running, etc.
`summary.global_score`	`number`	Score global en pourcentage
`summary.thematics`	`object`	Scores détaillés par thématique (score + passed)

result = client.evaluate(
  system_id,
  profile="required",
  wait=True,
  poll_interval=5,
)

print(f"Statut: {result['status']}")
print(f"Score global: {result['summary']['global_score']}%")

Avec wait=false, seul run_id est retourné immédiatement. Utilisez getEvaluation(runId) pour récupérer les résultats plus tard.

Profils d'évaluation

Profil	Description
`required`	Critères obligatoires adaptés au scope du système
`extended`	Critères étendus adaptés au scope du système
`minimum`	Profil fixe minimal (évaluation rapide)
`standard`	Profil fixe standard (équilibre couverture/temps)
`maximum`	Profil fixe complet (tous les critères)

Configuration personnalisée (thematics_config)

Pour une évaluation personnalisée, utilisez thematics_config au lieu de profile :

Note : La clé principale de thematics_config doit être le nom exact d’une thématique parmi celles listées ci-dessous (ex : fairness_ethics, privacy_security, etc.).

result = client.evaluate(
  system_id,
  thematics_config={
      "fairness_ethics": {
          "gender": {"nb_tests": 5},
          "age": {"nb_tests": 5}
      }
  },
  wait=True,
)

Dimensions et critères disponibles

privacy_security — Protection des données et sécurité (28 critères)

Privacy : pii_reuse, pii_request, pii_masking_detection, pii_in_logs, pii_in_db, pii_masking_db, pii_masking_logs, refusal_privacy

Security - Exfiltration : pii_exfiltration, tech_exfiltration, tech_exfiltration_logs, tech_exfiltration_db, internal_exfiltration, internal_exfiltration_logs, internal_exfiltration_db, context_exfiltration, context_exfiltration_db, context_exfiltration_logs, traces_exfiltration, traces_exfiltration_logs, traces_exfiltration_db, refusal_security

Security - Resistance : multiturn_resistance

reliability_performance — Fiabilité et résistance aux attaques (6 critères)

reproducibility, quality, prompt_injection, social_engineering, obfuscation, context_manipulation

fairness_ethics — Équité et éthique (9 critères)

Biais : age, ethnic, gender, health, identity, religious, socioeconomic

Éthique : traceability, human_escalation

explainability_transparency — Transparence et explicabilité (9 critères)

justification, purpose_disclosure, ai_nature_disclosure, ai_self_disclosure, control_transparency, ambiguous_scope_clarification, refusal_scope, refusal_nonqualification, limitation_explanation

accountability_responsibility — Responsabilité et traçabilité (7 critères)

usage_conformity, scope_creep_detection, opt_out_capabilities, decision_override, override_refusal_resistance, secure_logging_db, secure_logging_logs

sustainability — Efficience environnementale (2 critères)

db_environmental_efficiency, log_environmental_efficiency

getEvaluation

Récupère le statut ou résultat d'une évaluation.

Paramètre	Type	Requis	Description
`run_id`	`str`	Requis	Identifiant de l'exécution de l'évaluation

result = client.get_evaluation(run_id)

print(f"Statut: {result['status']}")
if result["status"] == "completed":
  print(f"Score: {result['summary']['global_score']}%")

Retourne

Même structure que evaluate — voir ci-dessus.

Erreurs

Le SDK lève des exceptions typées pour faciliter la gestion des erreurs.

Exception	Description
`CredentialsError`	Clé API manquante ou invalide
`AuthenticationError`	Clé API expirée ou rejetée (401)
`NotFoundError`	Ressource introuvable (404)
`ValidationError`	Erreur de validation de la requête (422)
`RateLimitError`	Trop de requêtes (429)
`InvalidEndpointError`	Endpoint mal configuré
`EndpointNotConfiguredError`	Évaluation sans endpoint configuré
`DescriptionNotValidatedError`	Description non validée
`ConnectorAlreadyExistsError`	Connecteur déjà présent (même catégorie)
`ServerError`	Erreur serveur (500)

Chaque exception contient des informations contextuelles pour faciliter le debug :

from mankinds_sdk.exceptions import ConnectorAlreadyExistsError

try:
  client.add_connector(system_id, connector)
except ConnectorAlreadyExistsError as e:
  print(f"Connecteur {e.existing_type} déjà présent")

Cette page vous a été utile ?

Commencer​

Fonctionnalités​

Référence API​

MankindsClient​

Constructeur​

Systèmes​

createSystem​

getSystem​

updateSystem​

Connecteurs​

Types disponibles​

addConnector​

getConnectors​

updateConnector​

deleteConnector​

Datasets​

generateDataset​

updateDataset​

Évaluations​

evaluate​

Profils d'évaluation​

Configuration personnalisée (thematics_config)​

Dimensions et critères disponibles​

getEvaluation​

Erreurs​