Score

Un Score est un type de question System One qui note un contenu selon des niveaux ordonnés et descriptifs. La réponse inclut un score, une probabilité pour chaque niveau et la confiance.

Utilise un Score quand la réponse est une position sur un spectre que tu peux décrire par étapes. Par exemple, la gravité d’un bug, le degré de satisfaction d’un client, ou l’expérience d’un candidat en Python. Si la réponse est l’une d’un ensemble fixe d’options sans ordre entre elles, utilise un Choice. Si c’est un oui ou un non, utilise un Noul. Choisis un type de question compare les trois.

Une réponse Score est une position le long de tes niveaux, dans score, qui peut tomber entre deux niveaux. Le modèle renvoie aussi une probabilité pour chaque niveau dans probabilities, et une valeur confidence pour la réponse.

Les nombres devant chaque étape sont des positions, expliquées dans Les niveaux.

Structure de la requête

Le corps de la requête POST vers l’API TypeSafe a les mêmes trois champs de niveau supérieur que tout autre type de question : state, qui est le contenu à évaluer ; model ; et questions. Chaque question Score a les champs suivants :

• type : toujours "score".
• instructions : la question à laquelle le modèle répond. Ce qu’il note.
• criteria : un tableau ordonné de descriptions de niveaux, du bas de l’échelle vers le haut. Doit avoir au moins deux niveaux ; l’API en accepte jusqu’à 10.

Voici une requête où l’état est un rapport de bug et la question est la gravité du bug :

{
  "state": "The export button crashes the settings page in Safari. It works in Chrome, but a few of our customers only use Safari.",
  "questions": {
    "bug_severity": {
      "type": "score",
      "instructions": "How severe is the reported issue?",
      "criteria": [
        "Cosmetic; no impact to functionality",
        "Broken or degraded feature, but workaround exists",
        "Blocking issue; no workaround exists"
      ]
    }
  }
}

Tu choisis l’id de question, bug_severity ici. Cet id n’est pas envoyé au modèle. La réponse est renvoyée sous le même id.

Les niveaux

Chaque entrée de criteria est un niveau : un point sur le spectre des réponses possibles, décrit en mots. Le numéro d’un niveau est sa position dans le tableau criteria, à partir de 0, donc les trois entrées ci-dessus sont les niveaux 0, 1 et 2. L’ordre du tableau est la numérotation.

Le modèle reçoit les descriptions et rien d’autre, et chaque niveau est jugé pour lui-même face à l’état.

Le score de la réponse est une position sur le spectre des niveaux. Pour une échelle à trois niveaux, il va de 0 à 2, et il peut tomber entre deux niveaux.

Nos SDK clients fournissent des questions typées. En Python, la même question est un Score :

from typesafe_sdk import Score, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state="The export button crashes the settings page in Safari. It works in Chrome, but a few of our customers only use Safari.",
        questions={
            "bug_severity": Score(
                instructions="How severe is the reported issue?",
                criteria=[
                    "Cosmetic; no impact to functionality",
                    "Broken or degraded feature, but workaround exists",
                    "Blocking issue; no workaround exists",
                ],
            ),
        },
    )

    print(response.answers["bug_severity"].score)

Utilise la méthode system_one ou l’endpoint https://api.typesafe.ai/v1/systemone pour appeler un modèle System One. Le champ model sélectionne quel modèle traite la requête. Construire avec TypeSafe indique où appeler cela dans ton code.

Utilise l’un de nos SDK clients ou appelle directement l’API TypeSafe. Si un agent de codage écrit l’intégration pour toi, installe d’abord le skill d’agent TypeSafe pour qu’il connaisse les formes de la requête et de la réponse.

Structure de la réponse

La réponse a une entrée dans answers par question, sous les ids de la requête. Voici la réponse à la requête d’exemple ci-dessus :

{
  "model": "jev-1.13.0",
  "answers": {
    "bug_severity": {
      "type": "score",
      "score": 1.43,
      "confidence": 0.35,
      "legend": {
        "0": "Cosmetic; no impact to functionality",
        "1": "Broken or degraded feature, but workaround exists",
        "2": "Blocking issue; no workaround exists"
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.57,
        "2": 0.43
      }
    }
  },
  "usage": {
    "input_tokens": 332,
    "output_tokens": 18
  }
}

Chaque réponse Score a cinq valeurs :

• type : le type de question TypeSafe.
• probabilities : la probabilité de chaque niveau, indexée par le numéro de niveau sous forme de chaîne. La somme de toutes les valeurs vaut 1.
• score : la position sur la droite des numéros de niveau, de 0 au numéro du niveau le plus haut, qui est 2 ici. C’est chaque numéro de niveau multiplié par sa probabilité, le tout additionné : 0 x 0.0 + 1 x 0.57 + 2 x 0.43 = 1.43.
• legend : chaque numéro de niveau associé à sa description.
• confidence : un nombre de 0 à 1 calculé à partir de la façon dont probabilities se répartit. Un pic unique sur un niveau signifie une confiance élevée. Une probabilité répartie sur plusieurs niveaux signifie une confiance faible.

Un score de 1.43 signifie que le modèle est partagé entre les niveaux 1 et 2, avec une légère préférence pour le niveau 1. Cela correspond au rapport : l’export est cassé, et passer à Chrome est un contournement pour la plupart des clients, mais pas pour ceux qui n’utilisent que Safari. Le modèle met 0.57 sur « un contournement existe » et 0.43 sur « aucun contournement », et la confiance est de 0.35 parce qu’il est partagé.

Avec le SDK Python, ScoreAnswer a score, confidence, probabilities et legend comme champs typés. Le SDK indexe probabilities et legend par un niveau entier plutôt que par une chaîne.

Lire un Score

Regardons comment le score change selon les entrées. Par exemple, avec la question et ses niveaux de la requête ci-dessus :

"How severe is the reported issue?"
  → 0: Cosmetic; no impact to functionality
  → 1: Broken or degraded feature, but workaround exists
  → 2: Blocking issue; no workaround exists

On peut voir comment différents rapports de bug changent le score :

Dans ces exemples, une confiance de 1.0 signifie que la distribution renvoyée met toute sa probabilité sur un seul niveau. Cela décrit la réponse du modèle, pas une garantie que la réponse est correcte.

Le score est une moyenne des numéros de niveau pondérée par les probabilités. Dans les troisième et quatrième exemples, la probabilité est partagée entre les niveaux 1 et 2. Plus de poids sur le niveau 2 fait monter le score. Il ne mesure pas la fraction de clients sans contournement.

Des distributions différentes peuvent produire le même score. Un score de 1.0 peut signifier que toute la probabilité est sur le niveau 1, ou que la moitié est sur chacun des niveaux 0 et 2. Lis probabilities et confidence en même temps que le score pour distinguer ces cas.

Un score fractionnaire est une position. Tu peux l’utiliser pour classer des rapports par gravité, ou l’arrondir au niveau le plus proche quand ton code a besoin d’une seule issue. Notre cookbook d’alignement d’entités montre un exemple d’arrondi au niveau le plus proche pour prendre une décision.

Une confiance faible sur un Score signifie généralement l’une de trois choses. Les niveaux se chevauchent pour cet état, la question mesure plus d’une chose, ou l’état n’en dit pas assez pour le placer. Notre documentation Confiance explique comment l’utiliser dans ton code.

Écrire de bons niveaux

Décris des situations, pas des degrés. « Fonctionnalité cassée ou dégradée, mais un contournement existe » donne au modèle quelque chose à quoi comparer l’état. « Modérément grave », non. Des descriptions concrètes peuvent aider le modèle à distinguer les niveaux. Vérifie les réponses sur des exemples connus ; une confiance plus élevée ne prouve pas à elle seule qu’une description est meilleure.

Chaque niveau est évalué séparément. Le modèle ne voit ni le numéro d’un niveau ni ses voisins, donc « pire que le niveau précédent » ne signifie rien pour lui, et les nombres dans les descriptions ou les instructions n’aident pas. Voici ce qui se passe quand les niveaux ne sont que des nombres, sur le rapport du bouton décalé du tableau ci-dessus :

instructions: "Rate severity from 0 to 2, where 2 is worst"
criteria: ["0", "1", "2"]
→ score 0.55, confidence 0.33, probabilities 0: 0.45, 1: 0.55, 2: 0.0

Le même rapport avec les trois niveaux descriptifs obtient un score de 0.0 à une confiance de 1.0. Avec seulement des nombres, le modèle n’a rien à quoi se comparer et partage la probabilité entre 0 et 1.

Utilise autant de niveaux que tu peux en décrire distinctement, jusqu’à 10. Trois suffisent. N’ajoute pas de niveaux que tu ne peux pas décrire distinctement.

Garde chaque question Score sur une seule dimension. Si une description dit « ponctuel et intelligent et expérimenté », la question mesure trois choses, et une entrée forte sur l’une et faible sur une autre ne peut pas être placée. La confiance baisse et le score signifie moins. Sépare-la en une question Score par chose et combine-les en code, comme le montre la section suivante.

Si le haut de ton échelle a un cas extrême rare sur lequel tu dois agir différemment, donne-lui son propre niveau. Une échelle de sentiment qui se termine à « très en colère » peut ajouter « insultant ou menaçant ». Sans ce niveau, les deux messages peuvent recevoir un score proche du sommet. Le score seul risque de ne pas les distinguer.

S’il n’y a pas d’entre-deux du tout, et que la réponse est l’une de quelques catégories discrètes, utilise plutôt un Choice, ou sépare la question en plusieurs questions Noul. Il est important de tester tes niveaux sur tes propres données. Deux formulations de la même échelle peuvent se comporter différemment sur tes données.

Diviser un jugement complexe en plusieurs questions Score

Un jugement complexe, qui dépend de plusieurs choses, se découpe au mieux en une question Score par chose. Tu peux ensuite combiner les Scores renvoyés par TypeSafe dans ton code pour rendre le jugement. Certaines questions Score peuvent compter plus que d’autres, alors donne à chaque question Score un poids pour son importance relative. Les poids sont les tiens. Quand le résultat combiné ne correspond pas à ce que ton équipe déciderait, change-les en code et relance. Envoie les questions Score en une seule requête. Elles sont évaluées en parallèle. Ajouter des questions ne change presque pas le temps de réponse et coûte quelques jetons de question en plus ; voir Poser plusieurs questions ensemble.

La requête ci-dessous est le ticket du sablier, issu du tableau ci-dessus, avec un peu plus de contexte. Elle pose trois questions Score : la gravité du bug, la frustration du client, et ce que le rapport donne à un ingénieur pour travailler.

{
  "state": "Export to PDF fails with a spinner that never finishes. Some of our team say CSV export still works for them, others say it fails too. This is the third time I'm writing in and honestly I'm done. Steps: open any report, click Export, choose PDF. Chrome 128 on macOS.",
  "questions": {
    "severity": {
      "type": "score",
      "instructions": "How severe is the reported issue?",
      "criteria": [
        "Cosmetic; no impact to functionality",
        "Broken or degraded feature, but workaround exists",
        "Blocking issue; no workaround exists"
      ]
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated is the customer?",
      "criteria": [
        "Calm, just stating facts",
        "Frustrated but civil",
        "Very angry, strong language or threatening to leave"
      ]
    },
    "report_quality": {
      "type": "score",
      "instructions": "How much does the report give an engineer to work with?",
      "criteria": [
        "No detail; just says something is broken",
        "Names the feature but no steps or environment",
        "Steps to reproduce or environment, but not both",
        "Steps to reproduce and environment"
      ]
    }
  }
}

La réponse de TypeSafe :

{
  "model": "jev-1.13.0",
  "answers": {
    "severity": {
      "type": "score",
      "score": 1.24,
      "confidence": 0.64,
      "legend": {
        "0": "Cosmetic; no impact to functionality",
        "1": "Broken or degraded feature, but workaround exists",
        "2": "Blocking issue; no workaround exists"
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.76,
        "2": 0.24
      }
    },
    "frustration": {
      "type": "score",
      "score": 1.28,
      "confidence": 0.58,
      "legend": {
        "0": "Calm, just stating facts",
        "1": "Frustrated but civil",
        "2": "Very angry, strong language or threatening to leave"
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.72,
        "2": 0.28
      }
    },
    "report_quality": {
      "type": "score",
      "score": 3.0,
      "confidence": 1.0,
      "legend": {
        "0": "No detail; just says something is broken",
        "1": "Names the feature but no steps or environment",
        "2": "Steps to reproduce or environment, but not both",
        "3": "Steps to reproduce and environment"
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.0,
        "2": 0.0,
        "3": 1.0
      }
    }
  },
  "usage": {
    "input_tokens": 468,
    "output_tokens": 43
  }
}

Chaque question est répondue pour elle-même face au ticket et reçoit un score :

• severity vaut 1.24 à une confiance de 0.64. Même lecture que l’exemple d’ouverture : l’export est cassé et certains ont un contournement.
• frustration vaut 1.28 à une confiance de 0.58. La formulation est polie, mais « troisième fois » et « j’en ai assez » font glisser une partie du score vers le niveau le plus haut, donc le modèle partage 0.72 et 0.28 entre « frustré mais poli » et « très en colère ». Pour ce ticket, les deux niveaux se chevauchent, d’où la confiance modérée.
• report_quality vaut 3.0 à une confiance de 1.0. Les étapes et la version du navigateur sont toutes deux indiquées.

Les trois échelles ont des longueurs différentes, alors avant de les combiner, normalise chaque score. Une échelle à quatre niveaux va de 0 à 3 et une échelle à trois niveaux va de 0 à 2, donc un score maximal sur l’une est plus grand qu’un score maximal sur l’autre. Divise chaque score par son numéro de niveau le plus haut, len(criteria) - 1, pour ramener chaque score entre 0 et 1. Alors les poids veulent dire ce qu’ils disent : 0.6 sur la gravité et 0.3 sur la frustration font compter la gravité deux fois plus.

Le code du SDK Python de TypeSafe ci-dessous pose les trois questions, normalise chaque score et les combine à l’aide d’un exemple de calcul de priorité :

from typesafe_sdk import Score, TypeSafeClient

TRIAGE_QUESTIONS = {
    "severity": Score(
        instructions="How severe is the reported issue?",
        criteria=[
            "Cosmetic; no impact to functionality",
            "Broken or degraded feature, but workaround exists",
            "Blocking issue; no workaround exists",
        ],
    ),
    "frustration": Score(
        instructions="How frustrated is the customer?",
        criteria=[
            "Calm, just stating facts",
            "Frustrated but civil",
            "Very angry, strong language or threatening to leave",
        ],
    ),
    "report_quality": Score(
        instructions="How much does the report give an engineer to work with?",
        criteria=[
            "No detail; just says something is broken",
            "Names the feature but no steps or environment",
            "Steps to reproduce or environment, but not both",
            "Steps to reproduce and environment",
        ],
    ),
}

def normalized(answers, question_id: str) -> float:
    """Put a score on 0 to 1 by dividing by its top level number."""
    top_level = len(TRIAGE_QUESTIONS[question_id].criteria) - 1
    return answers[question_id].score / top_level

def priority(ticket: str) -> float:
    with TypeSafeClient() as client:
        response = client.system_one(
            state=ticket,
            questions=TRIAGE_QUESTIONS,
        )
    answers = response.answers

    severity = normalized(answers, "severity")
    frustration = normalized(answers, "frustration")
    report_quality = normalized(answers, "report_quality")

    # A detailed report helps an engineer investigate, so it raises priority a little.
    return 0.6 * severity + 0.3 * frustration + 0.1 * report_quality

Pour la réponse d’exemple ci-dessus, les scores normalisés sont 0.62 pour la gravité, 0.64 pour la frustration et 1.0 pour la qualité du rapport. La priorité est 0.6 × 0.62 + 0.3 × 0.64 + 0.1 × 1.0 = 0.664, qui s’arrondit à 0.66.

Les poids vivent dans ton code, donc tu vois exactement comment le nombre est construit et tu peux le changer quand le classement ne correspond pas à ce que ferait ton équipe. Si tu as ensuite besoin de plus de questions Score, ajoute-les à TRIAGE_QUESTIONS. Le nombre de requêtes reste à un. Cette technique qui consiste à découper un jugement complexe en Scores séparés puis à les combiner avec des poids dans ton code s’appelle le patron Notation composite.

Descriptions de niveaux structurées

Commence par une description textuelle de base pour chaque niveau. Quand le modèle note sans cesse entre deux niveaux voisins sur des entrées que tu juges claires, donne à chaque niveau un objet au lieu d’une chaîne, avec un champ pour ce que le niveau couvre et un champ avec quelques situations d’exemple. Utilise les mêmes noms de champ sur chaque niveau pour que le modèle puisse comparer ce qui est comparable.

La requête ci-dessous est le ticket du sablier que nous avons utilisé plus tôt, mais avec des exemples sur chaque niveau :

{
  "state": "Export to PDF fails with a spinner that never finishes. Some of our team say CSV export still works for them, others say it fails too.",
  "questions": {
    "bug_severity": {
      "type": "score",
      "instructions": "How severe is the reported issue?",
      "criteria": [
        {
          "what": "Cosmetic; no impact to functionality",
          "examples": [
            "typo in a label",
            "misaligned icon"
          ]
        },
        {
          "what": "Broken or degraded feature, but workaround exists",
          "examples": [
            "export fails in one browser but works in another"
          ]
        },
        {
          "what": "Blocking issue; no workaround exists",
          "examples": [
            "cannot log in",
            "data loss"
          ]
        }
      ]
    }
  }
}

La réponse :

{
  "model": "jev-1.13.0",
  "answers": {
    "bug_severity": {
      "type": "score",
      "score": 1.09,
      "confidence": 0.87,
      "legend": {
        "0": {
          "what": "Cosmetic; no impact to functionality",
          "examples": [
            "typo in a label",
            "misaligned icon"
          ]
        },
        "1": {
          "what": "Broken or degraded feature, but workaround exists",
          "examples": [
            "export fails in one browser but works in another"
          ]
        },
        "2": {
          "what": "Blocking issue; no workaround exists",
          "examples": [
            "cannot log in",
            "data loss"
          ]
        }
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.91,
        "2": 0.09
      }
    }
  },
  "usage": {
    "input_tokens": 379,
    "output_tokens": 18
  }
}

Avec de simples chaînes, ce ticket obtenait 1.11 avec une confiance de 0.84. Avec des exemples, il obtient 1.09 à une confiance de 0.87, un léger décalage parce que les chaînes simples le plaçaient déjà bien. L’effet est plus grand quand les chaînes simples laissent le modèle partagé, comme le montre le tableau suivant.

Les exemples orientent le modèle, et ils n’aident que lorsqu’ils ressemblent à tes vraies entrées. Le tableau ci-dessous est le rapport Safari d’ouverture avec trois ensembles différents d’objets de niveau :

Dans cette comparaison, l’exemple correspondant concentre presque toute la probabilité sur un seul niveau. L’exemple sans rapport donne le même résultat que les chaînes simples. Une confiance plus élevée n’établit pas quelle réponse est correcte. Choisis des exemples dont les niveaux attendus sont connus, puis teste les descriptions révisées sur des entrées distinctes avant de les garder.