Référence pratique RubyAvancé

sivchari : tester et mesurer la qualité des skills d'agents

L’évaluation des agents IA souffre d’un manque de métriques objectives lors de l’appel d’outils. sivchari résout ce problème en offrant un framework de test unifié pour les skills d’agents.

Le déploiement de fonctions (tools) dans un LLM nécessite une validation rigoureuse du schéma JSON et de la pertinence de l’exécution. Sans cadre de mesure, le taux d’hallucination sur les arguments de fonctions augmente de façon exponentielle avec la complexité du prompt.

Après cette lecture, vous saurez automatiser le cycle de création, de test et de benchmarking de vos compétences d’agents via la CLI sivchari.

🛠️ Prérequis

Installation des dépendances nécessaires pour faire tourner l’environnement de test.

Python 3.11+ (pour le moteur sivchari)
Ruby 3.3+ (pour l’automatisation des suites de tests)
pip install sivchari
Une clé API OpenAI ou Anthropic configurée dans les variables d’environnement

📚 Comprendre sivchari

Un skill dans sivchari n’est pas une simple fonction, mais un triplet : Schéma (Input), Logique (Action) et Observation (Output). Le framework utilise une approche de ‘Golden Dataset’ pour comparer la sortie de l’agent à une réponse attendue.

Architecture d'un test de skill :

[Input Data] --> [Agent + Skill Schema] --> [LLM Execution]
                                                |
                                        [sivchram : Evaluator]
                                                |
                                        [Metrics: Accuracy, Latency, Cost]

Contrairement à RSpec qui teste des retours de méthodes Ruby, sivchari teste la conformité sémantique. On ne vérifie pas seulement si le type est correct, mais si l’argument extrait par le LLM est contextuellement valide par rapport à la base de connaissances fournie.

💎 Le code — sivchari

Ruby

require 'open3'
require 'json'

# Wrapper Ruby pour automatiser l'exécution de sivchari
class SivchariRunner
  def initialize(project_path)
    @project_path = project_path
  end

  # Exécute une suite de tests via la CLI sivchari
  # @param suite_name [String] nom de la suite de test définie dans .sivchari/configs
  def run_suite(suite_name)
    command = "cd #{@project_path} && sivchari eval --suite #{suite_name} --format json"
    
    # Utilisation d'Open3 pour capturer stdout et stderr proprement
    stdout, stderr, status = Open3.capture3(command)

    unless status.success?
      raise "Erreur lors de l'exécution de sivchari: #{stderr}"
    end

    JSON.parse(stdout)
  rescue JSON::ParserError => e
    puts "Échec du parsing du résultat : #{e.message}"
    nil
  end
end

# Exemple d'usage du runner
runner = SivchariRunner.new('./my_agent_project')
results = runner.run_suite('weather_tool_test')

if results
  puts "Score de précision : #{results.dig('metrics', 'accuracy') * 100}%"
end

📖 Explication

Dans le SivchariRunner, l’utilisation de Open3.capture3 est cruciale. Contra\text{t}e de system ou backticks, Open3 permet de séparer le flux d’erreur standard (stderr) du flux de sortie (stdout). C’est indispensable car sivchari écrit ses logs de progression sur stderr, ce qui corromprait le parsing JSON si on utilisait uniquement stdout.

Le SivchariSkillGenerator utilise JSON.pretty_generate. Dans un contexte de configuration, la lisibilité du schéma est primordiale pour le débogage humain. L’utilisation de FileUtils.mkdir_p évite l’erreur classique de dossier parent inexistant lors de la création de nouveaux skills.

Le piège classique avec sivchari est de ne pas spécifier le format de sortie. Par défaut, la CLI produit de la couleur ANSI. Si vous tentez de parser ce flux avec JSON.parse en Ruby, le parsing échouera à cause des caractères d’échappement de couleur. L’argument --format json est obligatoire pour l’automatisation.

Documentation officielle Ruby

🔄 Second exemple

Ruby

require 'json'
require 'fileutils'

# Générateur de template de skill compatible sivchari
class SivchariSkillGenerator
  def initialize(output_dir)
    @output_dir = output_dir
    FileUtils.mkdir_p(output_dir)
  end

  # Crée un fichier JSON Schema pour un nouveau skill
  def create_skill_schema(name, properties)
    schema = {
      name: name,
      description: "Skill généré via automate Ruby",
      parameters: {
        type: "object",
        properties: properties,
        required: properties.keys
      }
    }

    file_path = File.join(@output_dir, "#{name}_schema.json")
    File.write(file_path, JSON.pretty_generate(schema))
    file_path
  end
end

# Utilisation : Génération d'un skill de recherche météo
gen = SivchariSkillGenerator.new('./.sivchari/skills')
props = {
  "location" => { type: "string", description: "La ville cible" },
  "unit" => { type: "string", enum: ["celsius", "fahrenheit"] }
}
path = gen.create_skill_schema('weather_lookup', props)
puts "Schema généré : #{path}"

▶️ Exemple d’utilisation

Exécution d’un test de validation de paramètre via la CLI sivchari.

# Chargement de l'environnement
export OPENAI_API_KEY="sk-..."

# Lancement de l'évaluation de la suite 'weather_lookup'
sivchari eval --suite weather_lookup

# Sortie attendue :
# [INFO] Loading dataset: .sivchari/datasets/weather_lookup.jsonl
# [INFO] Running 15 test cases...
# [PASS] Case 1: Paris weather lookup
# [FAIL] Case 2: Invalid unit 'kelvin'
# [INFO] Summary:
#   - Total: 15
#   - Passed: 14
#   - Failed: 1
#   - Accuracy: 93.3%
#   - Latency (avg): 1.2s

🚀 Cas d’usage avancés

1. Test de régression multi-modèles : Vous pouvez utiliser sivchari pour comparer les performances d’un switch entre GPT-4o et Claude 3.5 Sonnet sur le même set de skills. Le framework génère un rapport comparatif des taux d’erreur par modèle.

2. Validation de Schéma Dynamique : Dans un système où les outils sont injectés dynamiquement, utilisez le générateur Ruby pour pousser les nouveaux schémas dans sivchari avant de les rendre disponibles à l’agent. Cela garantit que l’agent ne tentera jamais d’appeler une fonction dont le contrat est brisé.

3. Benchmarking de Latence de Skill : En utilisant l’option --metrics latency, vous pouvez identifier quels outils ralentissent trop l’agent. Si un skill dépasse 2000ms, il peut être marqué comme ‘non-conforme’ pour les applications temps réel.

✅ Bonnes pratiques

Pour maintenir un environnement de test sain avec sivchari, suivez ces principes de conception.

Immuabilité des datasets : Ne modifiez jamais un dataset de test existant. Si vous changez le comportement de l’agent, créez une nouvelle version du dataset (versioning via Git).
Principe du moindre étonnement : Vos schémas JSON doivent être explicites. Évitez les descriptions vagues comme « param1 ». Utilisez des descriptions qui servent de prompt pour le LLM.
Isolation des tests : Chaque suite de tests sivchari doit être autonome. Ne dépendez pas de l’état d’un autre test pour valider un skill.
Couverture de bord (Edge Cases) : Vos datasets doivent inclure des cas de types incorrects, des chaînes vides et des caractères spéciaux pour tester la résilience du parsing.
Automatisation de la régression : Intégrez systématiquement sivchari eval dans votre pipeline de CI. Un commit qui fait chuter l’accuracy de plus de 2% doit être rejeté automatiquement.

Points clés

sivchari permet d'automatiser l'évaluation des outils (skills) d'agents IA.
Utilisation de fichiers JSONL pour les datasets de test (Golden Datasets).
Validation stricte du JSON Schema pour éviter les hallucinations d'arguments.
Mesure de métriques clés : Précision, Latence et Coût.
Intégration possible dans des pipelines CI/CD via format JUnit.
Nécessite une configuration précise des chemins de dossiers dans .sivchari/config.yaml.
Possibilité de scripts Python personnalisés pour des métriques sémantiques.
Le parsing des résultats en Ruby nécessite de nettoyer les codes ANSI de la CLI.

❓ Questions fréquentes

Peut-on utiliser sivchari avec des modèles locaux (Ollama) ?

Oui, à condition que l’endpoint OpenAI-compatible soit configuré dans les variables d’environnement pour rediriger les appels vers l’URL d’Ollama.

Comment gérer les tests qui dépendent d'une base de données réelle ?

Il est préférable d’utiliser des ‘mocks’ ou des ‘fakes’ dans la logique de votre skill. sivchari teste l’interaction, pas l’infrastructure.

Est-ce que sivchari supporte le format XML ?

Le framework est optimisé pour le JSON et le JSONL. Pour l’XML, il faudra passer par un wrapper de conversion en sortie de l’agent.

Quelle est la différence entre un test de code et un test de skill ?

Le test de code vérifie la logique déterministe. Le test de skill vérifie la conformité probabiliste d’une sortie LLM par rapport à un schéma.

📚 Sur le même blog

🔗 Le même sujet sur nos autres blogs

📝 Conclusion

sivchari transforme l’évaluation des agents d’un processus artisanal en une discipline d’ingénierie mesurable. La clé du succès réside dans la qualité de vos datasets de référence. Pour approfondir la manipulation des schémas JSON, consultez la documentation JSON Schema. Ne négligez jamais la latence : un agent précis mais trop lent est inutile en production.

Rubia, du Ruby

Des codeSnippets Ruby, pour une IA pour les humains

sivchari : tester et mesurer la qualité des skills d’agents