Développer · SDK Python
SDK et framework Python
Le paquet reperes est à la fois le client de l'API et un framework pour construire des agents sur REPERES, depuis Python 3.10 ou plus, sans dépendance. Il contient aussi la CLI. Code source sous licence Apache 2.0 : confidensia-lab/reperes-kit ; paquet : PyPI.
Installation
pip install reperes
export REPERES_API_KEY=rpr_sk_…La clé se crée sur la page de connexion MCP (voir Démarrage). Le client la lit dans REPERES_API_KEY, ou la reçoit en argument.
Exemple
from reperes import Reperes, CreditsEpuises
client = Reperes()
smic = client.valeur("smic.horaire", date="2026-03-01")
v = smic["valeurs"][0]
print(v["valeur"], v["valide_du"], v["source"]["titre"])
plafond = client.valeur("apa.domicile.plafond", coordonnees={"gir": 1})
contexte = client.context("Quels repères pour construire un projet de service ?")
for s in contexte["sources"]:
print(s["title"], s["url"])
simulation = client.remuneration({
"convention": "ccn66",
"emploi": "educateur_specialise",
"anciennete_ans": 10,
"type_etablissement": "mecs",
})
print(simulation["statut"], simulation.operation_id)Résultats
Chaque méthode rend un Resultat : le JSON de la réponse (un dict), au contrat déclaré dans schema_version et décrit dans Contrats. Il porte aussi operation_id (à communiquer au support), statut_http et, quand l'opération dépasse la franchise du mois, credits_debites et credits_restants. Une simulation non couverte (emploi inconnu, date hors période) rend son résultat avec statut: "erreur" et statut_http == 422.
| Méthode | Rôle | Route |
|---|---|---|
context(question, exploration=False) | Contexte sourcé d'une question ; l'appelant rédige. | POST /api/v1/context |
precision(question) | Information ponctuelle et citation vérifiée, ou statut not_found, depends. | POST /api/v1/precision |
answer(question) | Réponse rédigée et ses sources (option Génération ou crédits). | POST /api/v1/answer |
valeur(id, date=, territoire=, coordonnees=) | Valeur applicable d'un paramètre (etalon.result.v1). | GET /api/v1/valeurs/{id} |
historique(id) | Valeurs successives d'un paramètre. | GET /api/v1/valeurs/{id}/historique |
resoudre(question) | Valeur du paramètre qui répond à une question en français. | GET /api/v1/valeurs?q=…&resoudre=1 |
rechercher(q, famille=) | Paramètres candidats ou catalogue d'une famille. | GET /api/v1/valeurs |
remuneration(profil), modeles() | Simulation CCN 66 ou CCN 51 (calcul.remuneration.v1) et catalogue des emplois. | /api/v1/calcul/remuneration |
trajectoire(demande) | Euros courants et constants (calcul.trajectoire.v1). | POST /api/v1/calcul/trajectoire |
esat(demande) | Rémunération garantie en ESAT (calcul.esat.v1). | POST /api/v1/calcul/esat |
autonomie(scenario) | APA à domicile, reste à charge d'un mois (calcul.autonomie.v1). | POST /api/v1/calcul/autonomie |
source(id, contenu=False), contrats(), schema(nom), openapi(), outils_mcp() | Publics : passeports de preuve, contrats, description de l'API, outils du connecteur. | sans clé |
Framework : agents et outils
Au-delà du client, le paquet est un framework pour construire des agents sur REPERES. Les règles, les valeurs et les calculs viennent de REPERES ; le framework apporte la structure.
reperes.connexion- REPERES par l'API (
ConnexionAPI) ou par la commandereperes(ConnexionCLI) : même interface, même résultat. reperes.outils- Outils pour modèles, tirés du catalogue publié des outils MCP ; formats OpenAI/Mistral et Anthropic ; vos outils propres.
reperes.agent- Boucle modèle ↔ outils, consignes, garde-fou de sourçage des montants, trace, session reprise.
reperes.modeles- Modèles au format de chat OpenAI (Mistral par défaut, OpenAI, serveurs locaux) ; un autre fournisseur s'ajoute en implémentant
Modele. reperes.kits- Agents métier prêts à l'emploi (APA à domicile, rémunération, ESAT), aussi publiés en compétences Agent Skills.
from reperes.agent import Agent
from reperes.connexion import ConnexionAPI, outils
from reperes.modeles import ModeleChat # MISTRAL_API_KEY par défaut
connexion = ConnexionAPI() # ou ConnexionCLI() : même interface
agent = Agent(
ModeleChat(),
outils(connexion, ["reperes_context", "reperes_valeur", "reperes_autonomie"]),
consignes="Tu accompagnes les familles d'un service d'aide à domicile. Tu n'attribues jamais de GIR.",
)
r = agent.repondre("Quel reste à charge pour 30 h par mois à 29 €, GIR 2, participation 15 % ?")
print(r.texte, r.montants_non_sources)Garde-fou : tout montant en euros cité par l'agent doit figurer dans un résultat d'outil ou dans le message de l'utilisateur ; sinon le modèle est relancé une fois, puis le montant est signalé dans montants_non_sources, jamais réécrit. La trace suit le vocabulaire OpenTelemetry GenAI ; la session se sauve en JSON et se reprend.
Kits métier et compétences
Trois agents prêts à l'emploi : apa (APA à domicile, consignes issues des fiches de terrain BMSE), remuneration (CCN 66 et CCN 51) et esat. Chacun est aussi une compétence au format Agent Skills (SKILL.md et ses consignes), qu'un agent de code charge telle quelle et qui appelle REPERES par la CLI.
from reperes.kits import creer_agent
from reperes.connexion import ConnexionCLI
from reperes.modeles import ModeleChat
agent = creer_agent("apa", ConnexionCLI(), ModeleChat(), consignes_supplementaires="Département : Rhône.")
# Pour un agent de code (Claude Code, Codex…) :
# reperes skills --exporter .claude/skillsExemples dans le dépôt : un agent personnalisé avec un outil propre à votre organisation, l'usage minimal du contexte, une simulation de rémunération. Voir les exemples.
Erreurs
Toutes dérivent de ErreurReperes (statut_http, code, detail, upgrade_url) et ne contiennent jamais la clé ni le texte de la question. Un débit dépassé est retenté deux fois en respectant Retry-After (Reperes(tentatives=0) pour s'en passer).
ErreurConfiguration- Clé absente ou invalide, adresse invalide : rien n'est envoyé.
ErreurRequete- Corps ou paramètre refusé ;
detaildit lequel. ErreurAuthentification- Clé invalide ou révoquée (401).
ErreurDroit- Opération hors du droit du compte (403,
upgrade_url). CreditsEpuises- Franchise du mois atteinte, crédits insuffisants (402,
credits_requis,solde). DebitDepasse- Débit dépassé après les nouvelles tentatives (429,
attente). ServiceIndisponible- API injoignable ou moteur indisponible ; l'opération n'est pas comptée.
try:
r = client.context("Question")
except CreditsEpuises as e:
print(f"{e.credits_requis} crédits nécessaires, solde {e.solde} : {e.upgrade_url}")