framework sivchari

framework sivchari : automatiser le test des Agent Skills

Non classé

Référence pratique COBOLIntermédiaire

framework sivchari : automatiser le test des Agent Skills

L’imprévisibilité des LLM rend le déploiement en production aussi risqué qu’un programme COBOL sans unit test. On ne peut pas valider un agent simplement en regardant quelques logs de sortie.

Le framework sivchari résout ce problème en apportant une couche de déterminisme sur des processus non-déterministes. Il permet de transformer un prompt vague en une compétence (Skill) mesurable avec des métriques de précision et de latence.

Après la lecture de ce guide, vous saurez définir une Skill, orchestrer une suite de tests automatisés et interpréter les rapports de performance pour itérer sur vos prompts.

framework sivchari

🛠️ Prérequis

Installation de l’environnement de test et du framework.

  • Python 3.12+ (indispensable pour le typage strict des outils)
  • pip install sivchari
  • Accès à une API compatible OpenAI (format 1.0+)
  • Installation de GnuCOBOL (si vous testez des bridges legacy) : sudo apt install gnucobol

📚 Comprendre framework sivchari

Le framework sivchari repose sur l’analogie de la sous-routine mainframe. Une Skill est un module autonome avec une interface définie (Input/Output) et des effets de bord contrôlés (Tools).

Contra est de l’approche traditionnelle : en COBOL, la logique est codée en dur. Dans le framework sivcharant, la logique réside dans le prompt, mais la structure est encadrée par un schéma JSON. Le framework agit comme un compilateur de comportement.

Structure d'une Skill :
  [Input] --> [Prompt Template] --> [LLM] --> [Output Validation]
                                     | 
                               [Tools/Functions]

Comparaison des approches :
- Approche 'Prompt Engineering' simple : 0% de test, 100% d'incertitude.
- Approche framework sivchari : Tests de régression, calcul de score F1, suivi du coût par appel.

🏦 Le code — framework sivchari

COBOL
from sivchari import Skill, Tool, Schema

# Définition d'un schéma de sortie strict pour éviter les hallucinations
output_schema = Schema(
    type="object",
    properties={
        "status": {"type": "string", "enum": ["UP", "DOWN", "MAINT"]},
        "lpar_id": {"type": "integer"}
    },
    required=["status", "lpar_id"]
)

@Tool(name="get_zOS_info")
def get_zos_info(lpar_name: str) -> str:
    # Simulation d'un appel vers un système z/OS via une API REST
    # Dans un vrai projet, on utilisererait un wrapper Python vers un module C ou COBOL
    data = {"LPAR01": "UP", "LPAR02": "MAINT"}
    status = data.get(lpar_name, "UNKNOWN")
    return f"Status of {lpar_name} is {status}"

# Création de la Skill avec le framework sivchari
mainframe_skill = Skill(
    name="mainframe_monitor",
    prompt="Analyze the status of LPAR {lpar_name} and return JSON.",
    tools=[get_zos_info],
    response_format=output_schema
)

📖 Explication

Dans le premier snippet, l’utilisation de Schema est cruciale. Contrairement à un script Python classique, on définit ici un contrat d’interface. Si le LLM renvoie un type incorrect, le framework sivcharant lèvera une exception avant même que la donnée ne touche votre logique métier.

L’annotation @Tool transforme une fonction Python standard en une ressource accessible par l’agent. Attention : la doc officielle suggère d’utiliser des types primitifs (str, int, float) pour garantir la compatibilité avec le JSON-schema.

Dans le second snippet, SkillTester est l’objet central. Le choix de AccuracyMetric permet de comparer le JSON généré avec le expected du dataset. Le piège classique est d’oublier LatencyMetric : un agent très précis mais répondant en 30 secondes est inutile dans un environnement transactionnel type CICS.

Documentation officielle COBOL

🔄 Second exemple

COBOL
import json
from sivchari.tester import SkillTester
from sivchari.metrics import AccuracyMetric, LatencyMetric

# Chargement de la suite de tests (Golden Dataset)
# Ce fichier contient les inputs et les outputs attendus (Ground Truth)
test_dataset = "tests/mainframe_tests.json"

def run_regression_suite(skill_to_test):
    tester = SkillTester(skill_to: skill_to_test)
    
    # Configuration des métriques de performance
    tester.add_metric(AccuracyMetric())
    tester.add_metric(LatencyMetric(threshold_ms=500))
    
    # Exécution des tests
    results = tester.run(test_dataset)
    
    # Export des résultats pour monitoring
    with open("test_report.json", "w") as f:
        json.dump(results.summary(), f, indent=2)

if __name__ == "__main__":
    run_regression_suite(mainframe_skill)

Référence pratique

Cette section regroupe les procédures opérationnelles pour utiliser le framework sivchari en production.

1. Initialisation d’un nouveau projet de Skill

Ne créez pas vos fichiers à la main. Utilisez la commande CLI pour générer la structure standardisée respectant les conventions de nommage.

sivchari init --project mainframe-agent
# Génère :
# /skills (définitions)
# /tests (datasets)
# /tools (fonctions Python)
# /config (paramètres LLM)

2. Création d’un Dataset de test (Golden Dataset)

Le succès du framework sivchari dépend de la qualité de vos données de référence. Un fichier tests/mainframe_tests.json doit suivre ce format :

[
  {
    "input": {"lpar_name": "LPAR01"},
    "expected": {"status": "UP", "lpar_id": 1},
    "tags": ["regression", "critical"]
  },
  {
    "input": {"lpar_name": "LPAR02"},
    "expected": {"status": "MAINT", "lpar_id": 2},
    "tags": ["edge-case"]
  }
]

3. Automatisation de la mesure de qualité

Pour mesurer la dérive (drift) de votre agent, intégrez le framework sivchari dans votre pipeline CI/CD. Si le score d’exactitude descend en dessous de 95%, le build doit échouer.

# Commande pour validation en pipeline
sivchari test --skill mainframe_monitor --threshold 0.95 --format junit

4. Utilisation de la stratégie d’amélioration (Prompt Optimization)

Le framework sivchari inclut un module ‘Optimizer’. Il utilise un second agent (LLM-as-a-judge) pour réécrire le prompt original afin de maximiser le score de la suite de tests.

sivchari improve --skill mainframe_monitor --strategy back-translation --iterations 5

▶️ Exemple d’utilisation

Exécution d’un test de régression sur la Skill ‘mainframe_monitor’ avec un dataset de 50 cas.

$ sivchari test --skill mainframe_monitor --dataset tests/mainframe_tests.json

[INFO] Running 50 test cases...
[INFO] Metric: Accuracy -> 98.0%
[INFO] Metric: Latency (avg) -> 420ms
[INFO] Metric: Token Cost (avg) -> $0.002
[SUCCESS] All tests passed above threshold (0.95).

🚀 Cas d’usage avancés

1. Bridge Legacy COBOL/LLM : Utiliser une Skill pour traduire des requêtes naturelles en appels JCL. Le framework sivchari valide que le JCL généré respecte la syntaxe syntaxique via un parser intégré.

2. Audit de conformité : Intégration de règles de sécurité dans le response_format. Si l’agent tente d’accéder à un paramètre sensible, le test de conformité échoue via une règle de validation personnalisée.

3. Test de régression multi-modèles : Utiliser le même dataset pour comparer GPT-4o et Claude 3.5 Sonnet. Le framework sivchari génère un tableau comparatif des coûts et de la précision.

🐛 Erreurs courantes

⚠️

Le LLM renvoie un string au lieu d’un integer pour l’ID de la LPAR.

✗ Mauvais

"lpar_id": "01"
✓ Correct

"lpar_id": 1

⚠️

L’absence de validation permet au prompt de changer la structure de sortie sans prévenir.

✗ Mauvais

prompt = "Donne moi le statut"
✓ Correct

prompt = "Réponds en JSON selon le schéma défini"

⚠️

L’agent ne sait pas quand appeler la fonction car le docstring est absent.

✗ Mauvais

def get_info(x): return x
✓ Correct

def get_info(x): 
    """Récupère l'info pour x"""
    return x

⚠️

L’injection de trop de contextes dans la Skill sature la fenêtre de contexte.

✗ Mauvais

prompt = context_from_db + user_query
✓ Correct

prompt = summarize(context_from_db) + user_query

✅ Bonnes pratiques

Pour industrialiser vos agents, suivez ces règles de gestion de configuration.

  • Immuabilité des tests : Ne modifiez jamais un dataset de test sans incrémenter la version de la Skill.
  • Typage strict : Utilisez toujours Pydantic ou JSON-Schema pour l’output. Le non-déterminisme du LLM ne doit pas polluer votre code métier.
  • Isolation des outils : Chaque @Tool doit être une fonction pure ou encapsuler ses propres erreurs.
  • Monitoring de coût : Intégrez toujours TokenCostMetric pour éviter les explosions budgétaires en cas de boucle infinie de l’agent.
  • Versioning : Traitez vos prompts comme du code source (Git). Un changement de prompt est un changement de logique applicative.
Points clés

  • Le framework sivchari apporte du déterminisme aux LLM.
  • Utilisez des schémas JSON pour verrouiller la structure de sortie.
  • Les tests de régression sont indispensables pour éviter les régressions de prompt.
  • Mesurez systématiquement la latence et le coût par appel.
  • L'approche 'Golden Dataset' est la seule méthode fiable de validation.
  • Intégrez les tests dans votre pipeline CI/CD.
  • Le framework permet d'automatiser l'optimisation des prompts.
  • Considérez une Skill comme une sous-routine mainframe avec interface fixe.

❓ Questions fréquentes

Peut-on utiliser le framework sivchari avec des modèles locaux (Llama 3) ?

Oui, tant que l’endpoint respecte l’API OpenAI. Le framework sivchari ne dépend pas du fournisseur, mais de la structure des requêtes.

Comment gérer les changements de version de Python ?

Le framework est compatible avec Python 3.12+. Pour les projets legacy, utilisez un environnement virtuel (venv) dédié.

Le framework peut-il tester des appels SQL ?

Absolument. Il suffit de créer un @Tool qui exécute la requête et de définir le schéma de retour attendu.

Quelle est la différence entre une Skill et un Agent ?

Une Skill est une unité de compétence spécialisée (une fonction). Un Agent est un orchestrateur qui utilise plusieurs Skills pour résoudre un problème complexe.

📚 Sur le même blog

🔗 Le même sujet sur nos autres blogs

📝 Conclusion

Le framework sivchari transforme l’expérimentation de prompt en ingénierie logicielle. En appliquant des concepts de validation familiers (schémas, tests unitaires, métriques), on réduit drastiquement le risque de mise en production. Pour aller plus loin, explorez l’intégration de traces OpenTelemetry pour monitorer vos Skills en temps réel. Lien doc : documentation COBOL officielle. Le vrai défi reste la gestion de l’état entre deux appels de skill.

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *