Primitivas (preguntas)

Los tres tipos de pregunta de TypeSafe (Choice, Score, Noul), las respuestas con tipo que devuelven, cómo elegir entre ellos y cómo hacer varias preguntas a la vez.

Las primitivas de TypeSafe son los bloques de construcción pequeños y con tipo que compones en el código. Vienen en pares: una pregunta define un juicio para que un modelo System One lo haga sobre un estado, y su respuesta es el valor con tipo que se devuelve. Tú compones las respuestas en tu código para tomar decisiones. Hay tres tipos de pregunta, y cada uno devuelve una forma de respuesta distinta.

Puedes hacer una pregunta o enviar varias juntas. Cada pregunta de una solicitud ve el mismo estado, se evalúa de forma independiente y devuelve una respuesta con tipo bajo el ID que hayas elegido.

Pide un solo juicio rápido por pregunta

Los modelos System One están hechos para juicios rápidos y concretos. Pide un juicio que una persona con conocimientos haría en un segundo con el contexto adecuado. «¿Transmite urgencia este mensaje?» es una buena pregunta. «Analiza este mensaje y determina el mejor curso de acción» no lo es. Eso necesita razonamiento lento, y es una señal de que hay que dividir la tarea en preguntas pequeñas y componer las respuestas en el código.

Si el juicio que quieres depende de varios factores independientes, pregunta por cada factor por separado y combina las respuestas con tu propia lógica. En lugar de «puntúa este pitch de startup», pregunta por el tamaño del mercado, la viabilidad técnica y la diferenciación, y luego pondéralos en el código según su importancia relativa. Cuando cambien las prioridades, cambia el valor de los pesos en lugar de reescribir un prompt. Haz varias preguntas a la vez muestra cómo hacerlo.

Define una pregunta

Cada pregunta tiene un ID, un type y unas instructions. Las preguntas Choice y Score también aceptan criteria, que definen las opciones de una pregunta Choice o los niveles de un Score. Las preguntas Noul aceptan criteria como aclaración opcional de qué significan sí y no.

• ID. La clave que eliges, como refund_requested. Identifica la respuesta devuelta.
• type. Uno de choice, score o noul.
• instructions. La pregunta que haces sobre el estado. Aquí es donde va tu lógica de evaluación. Escríbela como una pregunta clara y específica, o como una afirmación para que el modelo la juzgue. Una cadena basta para la mayoría de las preguntas. También puede ser un objeto o un array, lo que pone la pregunta en un campo y los datos a los que se refiere en otros; consulta Usa estructura en las preguntas.
• criteria. Las respuestas posibles: un mapa de opciones para una pregunta Choice, una lista ordenada de niveles para un Score, y una descripción opcional de sí y no para un Noul. La página de cada tipo de pregunta cubre su forma.

Esta pregunta comprueba si un cliente solicitó un reembolso:

from typesafe_sdk import Noul

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

Elige un tipo de pregunta

Elige el tipo que coincida con la forma de la respuesta que necesitas.

• Choice encaja cuando la respuesta es una de un conjunto conocido de opciones sin orden entre ellas: enrutar un ticket a un departamento, clasificar un tipo de documento, detectar un lenguaje de programación. Da la lista completa de opciones y añade una opción other o none of the above cuando la lista pueda no cubrir todas las entradas.

• Score encaja cuando la respuesta cae en un espectro y puedes describir qué significa cada punto de ese espectro: gravedad de un error, frustración del cliente, nivel de habilidad. Los niveles los defines tú, y el modelo devuelve una posición a lo largo de ellos.

• Noul encaja en una pregunta clara de sí/no donde la propia probabilidad es la señal útil: si este mensaje contiene información de identificación personal, si el cliente solicita un reembolso, si el currículum menciona sistemas distribuidos.

Si dos tipos parecen encajar, prefiere el que dé una respuesta sobre la que tu código pueda actuar directamente. Un Choice entre refund, rebook e information se corresponde directamente con tres rutas de código. Un Score de frustración del cliente se corresponde con un umbral. Un Noul se corresponde con un if.

Qué se devuelve

Las respuestas también son primitivas. Cada tipo de pregunta devuelve un valor con tipo que tu código puede comparar, usar con umbrales, ordenar, pasar a más lógica o poner en el estado de una solicitud posterior (consulta Cuando una pregunta depende de otra).

Dos propiedades de estas respuestas las hacen componibles:

• Toda respuesta está limitada a las opciones que hayas dado. El modelo devuelve una distribución de probabilidad sobre tus opciones o niveles, nunca un valor fuera de ellos. Tu código nunca tiene que recuperar un valor de texto generado.
• Toda respuesta es independiente. La respuesta de una pregunta no es contexto oculto para otra. Puedes añadir o eliminar preguntas sin cambiar los resultados de las demás.

Confianza explica cómo se deriva confidence de probabilities y cómo usarla para decidir cuándo actuar automáticamente y cuándo escalar a una persona.

Haz referencia a campos concretos

El contenido que se evalúa, el estado, suele ser un objeto JSON con varias partes: una conversación, un registro, una política. Cuando una pregunta trate sobre una de esas partes, nómbrala en las instructions con una ruta de puntos e índices hasta su clave, incluidos los acentos graves. Así el modelo sabe qué parte del estado debe juzgar.

Toma la conversación de soporte de la página de Estado:

{
  "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."
}

Estas dos preguntas apuntan al mensaje del cliente, la política y los cargos mediante rutas:

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`?"
        ),
    },
}

Las rutas explícitas dejan claro qué partes de un estado estructurado deben informar cada juicio. Consulta Estado para saber cómo estructurar la entrada.

Haz varias preguntas a la vez

Envía en una sola solicitud todas las preguntas que usen el mismo estado. Puedes mezclar tipos de pregunta con libertad. Los modelos System One evalúan en paralelo cada pregunta de una solicitud. Añadir preguntas apenas cambia el tiempo de respuesta y solo cuesta los tokens de las preguntas extra, que son baratos. Hacer una pregunta que quizá no necesites sale casi gratis.

Esta solicitud clasifica un mensaje de cliente, comprueba la urgencia y puntúa la frustración, todo a la vez:

{
  "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"
      ]
    }
  }
}

Nuestros SDK de cliente ofrecen preguntas y respuestas con tipo. En Python, pasa un diccionario questions de objetos Choice, Noul y Score a client.system_one(...). Esta solicitud envía un ticket y una política de reembolso una sola vez y obtiene una respuesta con tipo para cada pregunta:

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)

Consulta SDK de cliente para la instalación y el uso en tu lenguaje.

Haz preguntas especulativas

Haz todas las preguntas que tu código pueda necesitar, incluidas aquellas cuya respuesta solo importa para algunas entradas, y deja que el código decida qué respuestas usar. Si resulta que un ticket no es un informe de error, ignora la respuesta de gravedad. A esto lo llamamos patrón Fan-out especulativo. El cookbook de preguntas en paralelo muestra cómo agrupar 13 preguntas en una sola llamada es 11.5 veces más barato y 9.6 veces más rápido que 13 llamadas separadas, sin cambios en las respuestas.

Divide un juicio complejo en varias preguntas

Un juicio que depende de varias cosas es mejor dividirlo en una pregunta por cosa. Combina las respuestas en tu código, dando a cada una un peso según su importancia relativa. Los pesos son tuyos. Cuando el resultado combinado no coincida con lo que decidiría tu equipo, cámbialos en el código y vuelve a ejecutar. Añadir preguntas apenas cambia el tiempo de respuesta, porque se ejecutan en paralelo dentro de una misma solicitud. La división cuesta unos pocos tokens de pregunta extra.

Por ejemplo, la prioridad de un ticket podría construirse a partir de tres preguntas Score: cuán grave es el error, cuán frustrado está el cliente y cuánta información da el informe a un ingeniero. La página de Score recorre esta solicitud y el código que normaliza y pondera las respuestas en Dividir un juicio complejo en varios Scores. Esta técnica se llama patrón Puntuación compuesta.

Cuando una pregunta depende de otra

Las preguntas de una misma solicitud son independientes: una respuesta no se convierte en contexto de otra pregunta. Si un juicio posterior depende de una respuesta anterior, haz una segunda solicitud en el código. La dependencia es real solo cuando tu código no puede construir la segunda solicitud hasta tener la primera respuesta: necesita la respuesta para obtener más datos para el estado, para decidir de qué se compone el estado o para elegir las opciones de la siguiente pregunta. Si no, haz las preguntas juntas y combina sus respuestas en el código.

Dos solicitudes son la excepción, no la regla. Si las preguntas de la segunda solicitud podrían haberse hecho contra el estado original, hazlas en la primera solicitud y deja que el código ignore las que no necesite. Tres cookbooks hacen una segunda solicitud por un motivo real. Sugerencia de habilidades clasifica 182 habilidades en una sola solicitud y luego obtiene el texto completo de las tres mejores y las juzga de nuevo con esa evidencia mejor. Recuperación de estructura pregunta si cada salto de línea dividió una frase, combina las líneas en bloques a partir de esas respuestas y luego clasifica los bloques, que no existían hasta que la primera solicitud respondió. Clasificación jerárquica usa cada respuesta de Choice para decidir qué opciones ofrece la siguiente solicitud.

Consulta Cómo construir con TypeSafe para orientarte sobre cómo dividir un flujo de trabajo en juicios concretos.

Próximos pasos

Para ver cómo se componen en arquitecturas de sistema, ve a Patrones.