Evaluator sdk

​

title: “Evaluator SDK” description: “Costruisci un servizio che assegna punteggi alle sessioni di Failproof AI in modo sincrono o asincrono.” icon: “gauge”

​

Configura un evaluator

pip install failproofai-sdk uvicorn

import os
from failproofai.evaluator import Evaluator, EvalResponse

app = Evaluator(token=os.environ.get("EVALUATOR_TOKEN"))

@app.config
def config():
    return {"inactivity_timeout_secs": 1800}

@app.evaluator
def evaluate(req):
    tool_errors = sum(
        1 for item in req.events
        if item.event_type == "tool_result" and item.payload.get("error")
    )
    return EvalResponse(
        scores={"tool_reliability": 1.0 if tool_errors == 0 else 0.0},
        reasoning={"tool_reliability": f"{tool_errors} tool errors"},
    )

export EVALUATOR_TOKEN=<shared-token>
uvicorn evaluator:app --host 0.0.0.0 --port 8080

curl http://127.0.0.1:8080/health

​

Connetti l’evaluator a Failproof AI

1. Distribuisci l’evaluator a un URL HTTPS raggiungibile da Failproof AI Cloud.
2. Configura EVALUATOR_ENDPOINT con quell’URL e imposta EVALUATOR_TOKEN sullo stesso token utilizzato dall’evaluator. Per Cloud gestito, contatta support@befailproof.ai per configurare la connessione.
3. Esegui una valutazione e conferma che i suoi punteggi appaiono in Failproof AI.

• Dashboard
• CLI

Apri una sessione completata in Observe → Sessions e seleziona Run evaluation se non è stata valutata automaticamente. Rivedi lo stato, i punteggi, le motivazioni e il riepilogo nel pannello Evaluation della sessione.Utilizza Observe → Evaluations per confrontare i punteggi tra agenti o ambienti. Utilizza Observe → Metrics per latenza, costo, token e altre misurazioni numeriche.Inizia con una sessione per confermare che l’evaluator ha restituito le chiavi di punteggio previste e motivazioni utili per quella specifica esecuzione.Una volta che i risultati individuali appaiono corretti, utilizza il dashboard di valutazione per confrontare quei punteggi nel tempo e tra agenti o ambienti.Un grafico integro dovrebbe utilizzare nomi di punteggio stabili; modificare una chiave crea una serie separata.

fp evals --since 1h --score tool_reliability:0..1
fp evals --since 24h --aggregate

​

Tipi SDK

​

Decoratori e rotte

​

Restituisci lavoro asincrono

from failproofai.evaluator import EvalRequest, EvalResponse, Evaluator, JobPending

app = Evaluator(token="shared-secret")

@app.evaluator
def start(req: EvalRequest) -> JobPending:
    job_id = enqueue(req)
    return JobPending(job_id=job_id, next_poll_secs=30)

@app.job_lookup
def lookup(job_id: str):
    result = get_result(job_id)
    if result is None:
        return JobPending(job_id=job_id, next_poll_secs=30)
    return EvalResponse(
        scores=result.scores,
        reasoning=result.reasoning,
        summary=result.summary,
    )

​

Campi di richiesta e risposta

​

Impostazioni dell’operatore del server

​

Sicurezza e operazioni

• Metti l’evaluator dietro HTTPS quando il traffico attraversa un confine di rete attendibile.
• Configura un bearer token non vuoto e mantienilo identico su entrambi i servizi.
• Non registrare il token o i prompt sensibili completi dai payload delle richieste.
• Rendi gli handler sincroni idempotenti; i tentativi possono ripetere una richiesta.
• Persisti lo stato del lavoro asincrono al di fuori della memoria del processo in produzione.
• Restituisci chiavi di punteggio stabili. Rinominare una chiave crea una nuova serie di grafici piuttosto che modificare quella vecchia.