Decisions

Decisions serve per le domande che ti poni continuamente sullo stesso tipo di testo: quale team deve gestire questo ticket, quanto è arrabbiato questo cliente, questa email chiede un rimborso? Incolla il testo, scrivi le domande e ogni risposta torna nella forma che hai definito: una delle tue opzioni, un livello della tua scala oppure un valore tra falso e vero. Ottieni risposte su cui agire, non paragrafi da leggere.

Le risposte a scelta e a punteggio mostrano quanto è sicuro il modello e come si distribuisce la probabilità tra le tue opzioni, così capisci al volo se la risposta era netta o in bilico. Decisions funziona con Jev 1.13 di TypeSafe AI, un modello decisionale: invece di scrivere testo, risponde alle tue domande nelle forme che definisci tu.

Dimostrazione · 1:32 Decisions, with Jev Video in inglese, registrato nell'app reale

Tipi di domanda

Decisions si trova in Apps, nella scheda con la scritta Classify, score and check text with structured questions. Una decisione può contenere più domande sullo stesso testo e ogni domanda è di uno di questi tre tipi:

Prendere una decisione

1. Avvia una nuova decisione

   Vai su Apps e scegli Decisions. La pagina elenca le tue decisioni passate; seleziona New decision.

2. Incolla il testo

   In TEXT, incolla ciò che vuoi controllare: un ticket di assistenza, una recensione, un’email, l’invio di un modulo.

3. Aggiungi le domande

   In QUESTIONS, aggiungi una domanda con Choice, Score o True / false.

   • Choice. Scrivi la domanda, ad esempio Which team should handle this? (quale team deve occuparsene?). Dai un nome a ogni opzione e descrivi When it applies. Add option aggiunge un’altra opzione.
   • Score. Scrivi la domanda, ad esempio How frustrated is the customer? (quanto è irritato il cliente?). Descrivi ogni livello, dal più basso al più alto. Add level aggiunge un livello e le frecce su e giù li riordinano.
   • True / false. Scrivi l’affermazione, ad esempio The customer is threatening to cancel (il cliente minaccia di disdire). Se vuoi, compila i Criteria, valutati da 0 (falso) a 1 (vero): TRUE per quando l’affermazione è vera (Mentions a prior attempt or ticket, cioè cita un tentativo o un ticket precedente) e FALSE per quando non lo è.
4. Controlla il modello

   Il pannello MODEL mostra il modello che risponderà. Il predefinito è Jev 1.13 di TypeSafe AI.

5. Eseguila

   Seleziona Run decision. Le risposte compaiono nel pannello ANSWERS. Per provare una formulazione diversa, modifica il testo o le domande e seleziona Run again.

Esempio: smistare un ticket di assistenza

È l’esecuzione che vedi nella registrazione qui sopra. Il team di assistenza di Northwind riceve un messaggio come questo da una cliente, Marta (la sua coperta in merino non è mai arrivata, è il secondo ordine che va perso e sta pensando di disdire l’abbonamento):

Hi, I ordered a merino throw (order NW-4471) and it still hasn't arrived.
This is the second order from you that has gone missing. I'm seriously
thinking about cancelling my membership. - Marta

Tre domande su questo messaggio:

Ogni risposta si traduce in un’azione: il ticket va nella coda delle spedizioni, mentre il punteggio di irritazione e il segnale di disdetta lo contrassegnano per una risposta rapida e attenta, prima che Marta se ne vada.

Leggere le risposte

• Choice. L’opzione scelta dal modello, con un livello di confidenza come 100% confidence, e la probabilità di ogni opzione sotto forma di barra con una percentuale. Le barre mostrano quanto era in bilico la risposta: una divisione quasi alla pari tra due opzioni merita un controllo umano, un vincitore netto di solito no.
• Score. Il livello in cui è finito il testo, un punteggio sulla tua scala come 1.9 / 2, un livello di confidenza come 79% confidence e la probabilità di ogni livello. Il punteggio può cadere tra due livelli, quindi è utile sia per ordinare sia per etichettare.
• True / false. Un valore tra 0 e 1 su una barra che va da False a True. Più è vicino a 1, più l’affermazione è chiaramente vera; più è vicino a 0, più è chiaramente falsa.

Decisioni salvate

Ogni decisione viene salvata con il suo testo, le sue domande e le sue risposte. La pagina Decisions elenca le decisioni che hai preso in una tabella con le colonne Text, Model, Status e Created, e New decision ne avvia un’altra.

Una decisione salvata registra esattamente cosa è stato chiesto e cosa è stato risposto: utile quando, in seguito, qualcuno chiede perché un ticket è finito proprio lì.

Guardrail e accesso

Le decisioni seguono le stesse regole del workspace che valgono per la chat:

• Guardrail. I guardrail del tuo workspace controllano il testo e ogni domanda e descrizione prima che il modello li veda. A seconda di come sono configurati, i dati sensibili vengono oscurati oppure l’esecuzione viene bloccata.
• Accesso ai modelli e residenza dei dati. Le impostazioni di accesso ai modelli e di residenza dei dati del tuo workspace si applicano a Jev come a qualsiasi altro modello. Se lo escludono per te, non puoi eseguire una decisione con questo modello.

Dall’API

Decisions ha i suoi endpoint REST, così puoi porre le stesse domande su ogni nuovo ticket, recensione o email dal tuo codice. Tutti i percorsi sono relativi a https://api.stickyprompts.com/api/v1 e ogni richiesta invia la tua chiave API come bearer token nell’header Authorization. Non hai mai usato l’API? Parti dall’Avvio rapido.

La chiave ha bisogno di queste autorizzazioni (nell’editor delle chiavi dell’app si chiamano Decision Get, Decision Manage e Decision Delete):

• decision_get: elencare i modelli decisionali, elencare e leggere le tue decisioni
• decision_manage: eseguire una decisione
• decision_delete: eliminare una decisione

Decisions non è disponibile come strumento MCP; usa gli endpoint REST.

Elencare i modelli decisionali

Restituisce i modelli decisionali come array JSON (abbreviato):

[
  {
    "ID": 1,
    "name": "Jev 1.13",
    "selectable": true
  }
]

Passa l’ID del modello come decision_model_id. Ogni modello ha anche version, powered_by, description e default. Come per i modelli di chat, selectable: false significa che le regole di accesso ai modelli o di residenza dei dati del tuo workspace bloccano il modello per te, e restriction_reason ne spiega il motivo. Gli esempi qui sotto usano 1, l’ID che Jev 1.13 aveva quando è stata scritta questa pagina; recuperalo ogni volta invece di inserirlo fisso nel codice.

Eseguire una decisione

Esegue la decisione in modo sincrono (la chiamata restituisce il risultato quando le risposte sono pronte) e la salva insieme alle tue altre decisioni.

Ogni domanda ha un type, le sue instructions (la domanda o l’affermazione) e i suoi criteria:

Questa richiesta pone una domanda a scelta e una domanda vero / falso:

curl -X POST https://api.stickyprompts.com/api/v1/decision \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision_model_id": 1,
    "state": "My parcel never arrived and the tracking link is broken. Second time this month!",
    "questions": {
      "team": {
        "type": "choice",
        "instructions": "Which team should handle this?",
        "criteria": {
          "billing": "Payments and refunds",
          "shipping": "Delivery and tracking"
        }
      },
      "urgent": {
        "type": "noul",
        "instructions": "The customer needs a fast reply"
      }
    }
  }'

import os
import requests

BASE = "https://api.stickyprompts.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"}

r = requests.post(
    f"{BASE}/decision",
    headers=HEADERS,
    json={
        "decision_model_id": 1,
        "state": "My parcel never arrived and the tracking link is broken. Second time this month!",
        "questions": {
            "team": {
                "type": "choice",
                "instructions": "Which team should handle this?",
                "criteria": {
                    "billing": "Payments and refunds",
                    "shipping": "Delivery and tracking",
                },
            },
            "urgent": {
                "type": "noul",
                "instructions": "The customer needs a fast reply",
            },
        },
    },
)
r.raise_for_status()
decision = r.json()
if decision["status"] != "done":
    raise RuntimeError(decision["error"])
answers = decision["answers"]
print(answers["team"]["choice"], answers["urgent"]["noul"])

const BASE = "https://api.stickyprompts.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.STICKY_API_KEY}` };

const res = await fetch(`${BASE}/decision`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    decision_model_id: 1,
    state: "My parcel never arrived and the tracking link is broken. Second time this month!",
    questions: {
      team: {
        type: "choice",
        instructions: "Which team should handle this?",
        criteria: {
          billing: "Payments and refunds",
          shipping: "Delivery and tracking",
        },
      },
      urgent: {
        type: "noul",
        instructions: "The customer needs a fast reply",
      },
    },
  }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const decision = await res.json();
if (decision.status !== "done") throw new Error(decision.error);
console.log(decision.answers.team.choice, decision.answers.urgent.noul);

La risposta è un 201 con la decisione salvata. Ecco una versione abbreviata, con un ID e uno slug di esempio:

{
  "ID": 27,
  "slug": "q4m8x2kd",
  "decision_model_id": 1,
  "state": "My parcel never arrived and the tracking link is broken. Second time this month!",
  "status": "done",
  "error": "",
  "answers": {
    "team": {
      "type": "choice",
      "choice": "shipping",
      "confidence": 1,
      "probabilities": { "billing": 0, "shipping": 1 }
    },
    "urgent": {
      "type": "noul",
      "noul": 0.87
    }
  }
}

La risposta restituisce anche questions così come sono state inviate al modello (dopo un eventuale oscuramento da parte dei guardrail), il decision_model incorporato e resolved_model, la versione esatta del modello che ha risposto.

Domande a punteggio

Una domanda a punteggio invia i suoi livelli come array, a partire dal più basso:

{
  "frustration": {
    "type": "score",
    "instructions": "How frustrated is the customer?",
    "criteria": ["Calm", "Frustrated but civil", "Angry, ready to leave"]
  }
}

La risposta contiene lo score, una confidence, una legend che associa ogni numero di livello alla tua descrizione e le probabilities di ogni livello, indicizzate per numero di livello. La struttura è questa (valori di esempio):

{
  "frustration": {
    "type": "score",
    "score": 1,
    "confidence": 1,
    "legend": { "0": "Calm", "1": "Frustrated but civil", "2": "Angry, ready to leave" },
    "probabilities": { "0": 0, "1": 1, "2": 0 }
  }
}

Quando una decisione non riesce

• 400: manca state, una domanda non è valida (senza instructions, una choice o uno score senza criteria, criteri noul con chiavi diverse da true e false, oppure un type sconosciuto), oppure decision_model_id non corrisponde a nessun modello.
• 400 con un code: un guardrail ha bloccato il testo o una domanda.
• 403: le regole di accesso ai modelli del tuo workspace limitano il modello.
• 429: è stata raggiunta la quota del workspace o il limite del piano. Vedi Errori, paginazione e quote.

Elencare, leggere ed eliminare le decisioni

Elenca le tue decisioni, dalla più recente. Supporta page e size, più status (processing, done o error) per filtrare. Il totale è nell’header X-Total-Count: vedi paginazione.

Una decisione per ID o slug, con il suo testo, le domande e le risposte. Una decisione che non esiste o non è tua restituisce 404 {"error":"Decision not found"}.

Elimina una decisione tramite il suo ID numerico. Restituisce 204, anche quando non trova nulla.

Idee

• Smista i ticket. Una domanda Choice con i tuoi team come opzioni manda ogni ticket nella coda giusta.
• Valuta il tono delle recensioni. Una domanda Score da Insoddisfatto a Entusiasta trasforma una pila di recensioni in un numero che puoi ordinare e rappresentare in un grafico.
• Controlla una condizione in email e moduli. Un’affermazione True / false come L’email chiede un rimborso o Il modulo contiene un numero d’ordine segnala quelli su cui bisogna intervenire.
• Chiedi tutte e tre le cose insieme. Una sola decisione può smistare, valutare e controllare lo stesso testo, come nell’esempio qui sopra.

Pagine correlate