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éthodeRôleRoute
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 commande reperes (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/skills

Exemples 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é ; detail dit 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}")