Primitive (Fragen)

Die drei TypeSafe-Fragetypen (Choice, Score, Noul), ihre typisierten Antworten und wie du zwischen ihnen wählst.

Die Primitive von TypeSafe sind die kleinen, typisierten Bausteine, die du im Code zusammensetzt. Sie treten paarweise auf: Eine Frage definiert ein Urteil, das ein System One-Modell über einen Zustand fällen soll, und ihre Antwort ist der typisierte Wert, der zurückkommt. Du setzt die Antworten in deinem Code zusammen, um Entscheidungen zu treffen. Es gibt drei Fragetypen, jeder gibt eine andere Form von Antwort zurück.

Du kannst eine Frage stellen oder mehrere zusammen senden. Jede Frage in einer Anfrage sieht denselben Zustand, wird unabhängig ausgewertet und gibt eine typisierte Antwort unter der von dir gewählten ID zurück.

Ein einziges schnelles Urteil pro Frage

System One-Modelle sind für schnelle, fokussierte Urteile gebaut. Bitte um ein Urteil, das eine kundige Person in einer Sekunde mit dem richtigen Kontext fällt. „Drückt diese Nachricht Dringlichkeit aus?“ ist eine gute Frage. „Analysiere diese Nachricht und bestimme die beste Vorgehensweise“ ist es nicht. Das braucht langsames Nachdenken und ist ein Signal, die Aufgabe in kleine Fragen zu zerlegen und die Antworten im Code zusammenzusetzen.

Wenn das gewünschte Urteil von mehreren unabhängigen Faktoren abhängt, frage jeden Faktor separat ab und kombiniere die Antworten mit deiner eigenen Logik. Frage statt „bewerte diesen Startup-Pitch“ nach Marktgröße, technischer Machbarkeit und Differenzierung und gewichte sie dann im Code nach ihrer relativen Bedeutung. Wenn sich die Prioritäten verschieben, ändere den Wert der Gewichte, statt einen Prompt neu zu schreiben. Mehrere Fragen zusammen stellen zeigt, wie das geht.

Eine Frage definieren

Jede Frage hat eine ID, einen type und instructions. Choice- und Score-Fragen nehmen außerdem criteria, die die Optionen für eine Choice-Frage oder die Stufen für einen Score definieren. Noul-Fragen akzeptieren criteria als optionale Klärung dessen, was ja und nein bedeuten.

• ID. Der Schlüssel, den du wählst, etwa refund_requested. Er identifiziert die Antwort in der Antwort.
• type. Einer von choice, score oder noul.
• instructions. Die Frage, die du über den Zustand stellst. Hier steckt deine Auswertungslogik. Schreibe sie als klare, spezifische Frage oder als Aussage, die das Modell beurteilen soll. Eine Zeichenkette reicht für die meisten Fragen. Sie kann auch ein Objekt oder ein Array sein, das die Frage in ein Feld und die Daten, auf die sie sich bezieht, in andere legt; siehe Struktur in den Fragen verwenden.
• criteria. Die möglichen Antworten: eine Map von Optionen für eine Choice-Frage, eine geordnete Liste von Stufen für einen Score und eine optionale Beschreibung von ja und nein für einen Noul. Die Seite jedes Fragetyps behandelt seine Form.

Diese Frage erkundigt sich, ob ein Kunde eine Erstattung verlangt hat:

from typesafe_sdk import Noul

questions = {
    "refund_requested": Noul(
        instructions="Does the customer request a refund?",
    ),
}

Einen Fragetyp wählen

Wähle den Typ, der zur Form der benötigten Antwort passt.

• Choice passt, wenn die Antwort eine aus einer bekannten Menge von Optionen ohne Reihenfolge ist: ein Ticket an eine Abteilung routen, einen Dokumenttyp klassifizieren, eine Programmiersprache erkennen. Gib die vollständige Liste der Optionen an und füge eine Option other oder none of the above hinzu, wenn die Liste womöglich nicht jede Eingabe abdeckt.

• Score passt, wenn die Antwort auf einem Spektrum liegt und du beschreiben kannst, was jeder Punkt dieses Spektrums bedeutet: Fehlerschwere, Kundenfrust, Kompetenzniveau. Die Stufen legst du fest, und das Modell gibt eine Position entlang ihnen zurück.

• Noul passt zu einer klaren Ja/Nein-Frage, bei der die Wahrscheinlichkeit selbst das nützliche Signal ist: Enthält diese Nachricht personenbezogene Daten, verlangt der Kunde eine Erstattung, erwähnt der Lebenslauf verteilte Systeme.

Wenn zwei Typen zu passen scheinen, bevorzuge den, dessen Antwort dein Code direkt verarbeiten kann. Ein Choice zwischen refund, rebook und information bildet direkt auf drei Codepfade ab. Ein Score des Kundenfrusts bildet auf einen Schwellenwert ab. Ein Noul bildet auf ein if ab.

Was zurückkommt

Antworten sind ebenfalls Primitive. Jeder Fragetyp gibt einen typisierten Wert zurück, den dein Code vergleichen, mit einem Schwellenwert belegen, sortieren, in weitere Logik übergeben oder in den Zustand einer Folgeanfrage legen kann (siehe Wenn eine Frage von einer anderen abhängt).

Zwei Eigenschaften dieser Antworten machen sie kombinierbar:

• Jede Antwort ist auf die von dir angegebenen Optionen beschränkt. Das Modell gibt eine Wahrscheinlichkeitsverteilung über deine Optionen oder Stufen zurück, nie einen Wert außerhalb davon. Dein Code muss nie einen Wert aus generierter Prosa zurückgewinnen.
• Jede Antwort ist unabhängig. Die Antwort einer Frage ist kein versteckter Kontext für eine andere. Du kannst Fragen hinzufügen oder entfernen, ohne die Ergebnisse der anderen zu ändern.

Konfidenz erklärt, wie confidence aus probabilities abgeleitet wird und wie du damit entscheidest, wann du automatisch handelst und wann du an einen Menschen eskalierst.

Bestimmte Felder referenzieren

Der Inhalt, der ausgewertet wird, der Zustand, ist oft ein JSON-Objekt mit mehreren Teilen: eine Konversation, ein Datensatz, eine Richtlinie. Wenn eine Frage eines dieser Teile betrifft, benenne ihn in den instructions mit einem Punkt-und-Index-Pfad zu seinem Schlüssel, einschließlich der Backticks. Das Modell weiß dann, welchen Teil des Zustands es beurteilen soll.

Nimm die Support-Konversation von der Zustandsseite:

{
  "ticket": {
    "subject": "Duplicate charge",
    "messages": [
      {"from": "customer", "text": "I was charged twice for order A-104. Please refund the duplicate."},
      {"from": "support", "text": "We are checking the charges."}
    ]
  },
  "order": {
    "id": "A-104",
    "charges": [
      {"amount_usd": 49, "status": "captured"},
      {"amount_usd": 49, "status": "captured"}
    ]
  },
  "refund_policy": "Duplicate charges are eligible for a refund."
}

Diese beiden Fragen zeigen per Pfad auf die Nachricht des Kunden, die Richtlinie und die Abbuchungen:

questions = {
    "refund_requested": {
        "type": "noul",
        "instructions": "Does `ticket.messages[0].text` request a refund?",
    },
    "policy_supports_refund": {
        "type": "noul",
        "instructions": (
            "Does `refund_policy` support the refund requested "
            "in `ticket.messages[0].text`, given `order.charges`?"
        ),
    },
}

Explizite Pfade machen klar, welche Teile eines strukturierten Zustands jedes Urteil informieren sollten. Siehe Zustand für die Strukturierung der Eingabe.

Mehrere Fragen zusammen stellen

Sende jede Frage, die denselben Zustand nutzt, in einer Anfrage. Du kannst Fragetypen frei mischen. System One-Modelle werten jede Frage in einer Anfrage parallel aus. Das Hinzufügen von Fragen ändert die Antwortzeit kaum und kostet nur die Token für die zusätzlichen Fragen, die günstig sind. Eine Frage zu stellen, die du vielleicht nicht brauchst, ist nahezu kostenlos.

Diese Anfrage klassifiziert eine Kundennachricht, prüft auf Dringlichkeit und bewertet den Frust auf einmal:

{
  "state": "Our API integration started returning 500 errors on every request about 20 minutes ago, and we can't process any customer orders until this is fixed.",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this",
      "criteria": {
        "billing": "Payment or subscription issues",
        "technical": "Bugs or integration problems",
        "sales": "Pricing or account questions"
      }
    },
    "is_urgent": {
      "type": "noul",
      "instructions": "The message conveys urgency or time-sensitivity"
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated the customer appears",
      "criteria": [
        "Calm, just stating facts",
        "Frustrated but civil",
        "Very angry, strong language"
      ]
    }
  }
}

Unsere Client-SDKs bieten typisierte Fragen und Antworten. Übergib in Python ein questions-Dictionary aus Choice-, Noul- und Score-Objekten an client.system_one(...). Diese Anfrage sendet ein Ticket und eine Erstattungsrichtlinie einmal und erhält für jede Frage eine typisierte Antwort:

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

state = {
    "ticket_message": "My flight was cancelled. Can I get a refund?",
    "refund_policy": "Cancelled flights are eligible for a full refund.",
}

with TypeSafeClient() as client:
    response = client.system_one(
        state=state,
        questions={
            "refund_requested": Noul(
                instructions="Does `ticket_message` request a refund?",
            ),
            "request_type": Choice(
                instructions="What is the main request in `ticket_message`?",
                criteria={
                    "refund": "The customer wants money returned.",
                    "rebooking": "The customer wants a replacement flight.",
                    "information": "The customer is asking for information only.",
                },
            ),
            "frustration": Score(
                instructions="How frustrated does the customer appear in `ticket_message`?",
                criteria=[
                    "Calm and neutral.",
                    "Concerned but civil.",
                    "Very angry or using strong language.",
                ],
            ),
        },
    )

print(response.answers["refund_requested"].noul)
print(response.answers["request_type"].choice)
print(response.answers["frustration"].score)

Siehe Client-SDKs für Installation und Nutzung in deiner Sprache.

Spekulative Fragen stellen

Stelle jede Frage, die dein Code brauchen könnte, auch solche, deren Antwort nur für manche Eingaben zählt, und lass den Code entscheiden, welche Antworten er verwendet. Stellt sich ein Ticket als kein Fehlerbericht heraus, ignoriere die Schwere-Antwort. Wir nennen das das Muster Spekulativer Fan-out. Das Cookbook „Parallele Fragen“ zeigt, wie das Bündeln von 13 Fragen in einen Aufruf 11.5x günstiger und 9.6x schneller ist als 13 separate Aufrufe, ohne dass sich die Antworten ändern.

Ein komplexes Urteil in mehrere Fragen aufteilen

Ein Urteil, das von mehreren Dingen abhängt, wird am besten in eine Frage pro Ding aufgeteilt. Kombiniere die Antworten in deinem Code und gib jeder ein Gewicht für ihre relative Bedeutung. Die Gewichte gehören dir. Wenn das kombinierte Ergebnis nicht dem entspricht, was dein Team entscheiden würde, ändere sie im Code und führe erneut aus. Das Hinzufügen von Fragen ändert die Antwortzeit kaum, weil sie innerhalb einer Anfrage parallel laufen. Die Aufteilung kostet ein paar zusätzliche Frage-Token.

Zum Beispiel könnte die Ticket-Priorität aus drei Score-Fragen gebildet werden: wie schwerwiegend der Fehler ist, wie frustriert der Kunde ist und wie viel der Bericht einem Ingenieur zum Arbeiten gibt. Die Score-Seite führt durch diese Anfrage und den Code, der die Antworten in Ein komplexes Urteil in mehrere Scores aufteilen normalisiert und gewichtet. Diese Technik heißt das Muster Zusammengesetzte Bewertung.

Wenn eine Frage von einer anderen abhängt

Fragen in derselben Anfrage sind unabhängig: Eine Antwort wird nicht zum Kontext für eine andere Frage. Wenn ein späteres Urteil von einer früheren Antwort abhängt, stelle im Code eine zweite Anfrage. Die Abhängigkeit ist nur dann real, wenn dein Code die zweite Anfrage nicht bauen kann, bis er die erste Antwort hat: Er braucht die Antwort, um weitere Daten für den Zustand zu holen, um zu entscheiden, woraus der Zustand besteht, oder um die Optionen der nächsten Frage zu wählen. Andernfalls stelle die Fragen zusammen und kombiniere ihre Antworten im Code.

Zwei Anfragen sind die Ausnahme, nicht die Regel. Wenn die Fragen der zweiten Anfrage auch gegen den ursprünglichen Zustand hätten gestellt werden können, stelle sie in der ersten Anfrage und lass den Code die ignorieren, die er nicht braucht. Drei Cookbooks stellen aus einem echten Grund eine zweite Anfrage. Skill-Vorschlag rankt 182 Skills in einer Anfrage, holt dann den Volltext der Top drei und beurteilt sie erneut gegen diese bessere Evidenz. Strukturwiederherstellung fragt, ob jeder Zeilenumbruch einen Satz getrennt hat, führt Zeilen anhand dieser Antworten zu Blöcken zusammen und klassifiziert dann die Blöcke, die es erst gab, nachdem die erste Anfrage geantwortet hatte. Hierarchische Klassifizierung nutzt jede Choice-Antwort, um zu entscheiden, welche Optionen die nächste Anfrage anbietet.

Siehe Mit TypeSafe bauen für Hinweise, wie du einen Workflow in fokussierte Urteile zerlegst.

Nächste Schritte

Um zu sehen, wie sich diese zu Systemarchitekturen zusammensetzen, gehe zu Muster.