Evaluator SDK

एक मूल्यांकनकर्ता एक पूर्ण एजेंट सेशन प्राप्त करता है और गुणवत्ता संकेत लौटाता है जिनकी आपको परवाह है: संख्यात्मक स्कोर, प्रत्येक स्कोर के लिए एक व्याख्या, और एक वैकल्पिक सारांश। Failproof AI इन परिणामों को ट्रेस के साथ संग्रहीत करता है और एजेंट और वातावरण के पार उन्हें चार्ट करता है।

एक मूल्यांकनकर्ता सेट अप करें

Evaluator SDK इंस्टॉल करें

SDK और इसे चलाने के लिए उपयोग किए जाने वाले सर्वर को इंस्टॉल करें।

pip install failproofai-sdk uvicorn

स्कोर करने के लिए क्या परिभाषित करें

evaluator.py बनाएँ। यह उदाहरण जाँचता है कि क्या एक सेशन में कोई विफल टूल कॉल है।

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

इसे स्थानीय रूप से चलाएँ और परीक्षण करें

एक साझा टोकन सेट करें, मूल्यांकनकर्ता शुरू करें, और पुष्टि करें कि इसका health endpoint प्रतिक्रिया देता है।

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

एक अन्य टर्मिनल में:

curl http://127.0.0.1:8080/health

मूल्यांकनकर्ता को Failproof AI से कनेक्ट करें

मूल्यांकनकर्ता को एक HTTPS URL पर तैनात करें जो Failproof AI Cloud द्वारा पहुँचा जा सकता है।
EVALUATOR_ENDPOINT को उस URL के साथ कॉन्फ़िगर करें और EVALUATOR_TOKEN को मूल्यांकनकर्ता द्वारा उपयोग किए जाने वाले टोकन पर सेट करें। प्रबंधित Cloud के लिए, कनेक्शन कॉन्फ़िगर करने के लिए support@befailproof.ai से संपर्क करें।
एक मूल्यांकन चलाएँ और पुष्टि करें कि इसके स्कोर Failproof AI में दिखाई देते हैं।

Dashboard
CLI

Observe → Sessions के तहत एक पूर्ण सेशन खोलें और यदि यह स्वचालित रूप से मूल्यांकन नहीं किया गया था तो Run evaluation चुनें। सेशन के Evaluation पैनल में स्थिति, स्कोर, तर्क और सारांश की समीक्षा करें।एजेंट या वातावरण के पार स्कोर की तुलना करने के लिए Observe → Evaluations का उपयोग करें। विलंबता, लागत, टोकन और अन्य संख्यात्मक माप के लिए Observe → Metrics का उपयोग करें।पुष्टि करने के लिए एक सेशन के साथ शुरुआत करें कि मूल्यांकनकर्ता ने उस विशिष्ट रन के लिए अपेक्षित स्कोर कुंजी और उपयोगी तर्क लौटाए हैं।

एक सेशन विस्तार दृश्य जो इसके ट्रेस के बगल में मूल्यांकन स्कोर और तर्क दिखाता है।

एक बार जब व्यक्तिगत परिणाम सही दिखें, समय के साथ और एजेंट या वातावरण के पार उन स्कोर की तुलना करने के लिए मूल्यांकन डैशबोर्ड का उपयोग करें।

एक गुणवत्ता डैशबोर्ड जो समय के साथ मूल्यांकनकर्ता स्कोर चार्ट करता है।

एक स्वस्थ चार्ट को स्थिर स्कोर नाम का उपयोग करना चाहिए; एक कुंजी को पुनः नाम देना एक अलग श्रृंखला बनाता है।

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

एक self-hosted Cloud उदाहरण के लिए, जब तक EVALUATOR_ENDPOINT सर्वर प्रक्रिया पर सेट नहीं किया जाता तब तक स्वचालित मूल्यांकन अक्षम है। मूल्यांकनकर्ता पर्यावरण चर बदलने के बाद सर्वर को पुनः शुरू करें। सेवा GET /health, GET /config, POST /evaluate, और वैकल्पिक रूप से GET /evaluate/{job_id} को उजागर करती है। असमकालीन कार्य के लिए JobPending लौटाएँ और @app.job_lookup को पंजीकृत करें ताकि Failproof AI इसे पोल कर सके। जब एक टोकन कॉन्फ़िगर किया गया हो, तो health को छोड़कर सभी रूट को समान bearer token की आवश्यकता है जो Failproof AI EVALUATOR_TOKEN के रूप में भेजता है।

SDK प्रकार

प्रकार	फ़ील्ड
`AgentEvent`	`id`, `ts`, `event_type`, `payload`
`EvalRequest`	`schema_version`, `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `events`
`EvalResponse`	`scores`, `reasoning`, `summary`
`JobPending`	`job_id`, `next_poll_secs`
`EvaluatorConfig`	`inactivity_timeout_secs`, `default_poll_interval_secs`

Decorators और routes

Decorator	Route	आवश्यक
`@app.evaluator`	`POST /evaluate`	हाँ
`@app.job_lookup`	`GET /evaluate/{job_id}`	`JobPending` लौटाते समय
`@app.config`	`GET /config`	नहीं

SDK मूल्यांकन request bodies को 25 MiB पर सीमित करता है। अज्ञात request फ़ील्ड को अनदेखा किया जाता है ताकि सेवाएँ event contract के विकास के साथ संगत रहें।

असमकालीन कार्य लौटाएँ

JobPending का उपयोग करें जब मूल्यांकन एक request के भीतर समाप्त नहीं हो सकता है। job ID Failproof AI के लिए अपारदर्शी है और परिणाम एकत्र किए जाने या सर्वर timeout समाप्त होने तक आपकी सेवा द्वारा resolvable रहना चाहिए।

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,
    )

Polling cadence इस क्रम में चुना जाता है: JobPending.next_poll_secs, EvaluatorConfig.default_poll_interval_secs, फिर सर्वर का EVALUATOR_POLLING_INTERVAL_SECS। मान 1 सेकंड और 1 घंटे के बीच fixed हैं। सर्वर की डिफ़ॉल्ट wall-clock polling cap एक घंटा है।

Request और response फ़ील्ड

फ़ील्ड	प्रकार	नोट्स
`EvalRequest.schema_version`	`str`	वर्तमान में `"1"`।
`session_id`, `agent_id`, `environment`	`str`	सेशन identity और वातावरण।
`started_at`	`datetime`	पहली event का timestamp।
`ended_at`	`datetime \| None`	जब सेशन ने एक end event emit किया तो मौजूद है।
`events`	`list[AgentEvent]`	पूर्ण क्रमबद्ध event stream।
`AgentEvent.id`	`int`	Backend event row identifier।
`AgentEvent.ts`	`datetime`	Event timestamp।
`AgentEvent.event_type`	`str`	Event family जैसे `tool_use`।
`AgentEvent.payload`	`dict[str, Any]`	संपूर्ण event payload।
`EvalResponse.scores`	`dict[str, float] \| None`	मूल्यांकन में charted संख्यात्मक आयाम।
`EvalResponse.reasoning`	`dict[str, str] \| None`	Per-score व्याख्या; keys को `scores` को mirror करना चाहिए।
`EvalResponse.summary`	`str \| None`	समग्र मूल्यांकन narrative।

Server operator सेटिंग्स

स्वचालित मूल्यांकन deployment-wide है और जब EVALUATOR_ENDPOINT अनुपस्थित होता है तो अक्षम रहता है।

Variable	Default	उद्देश्य
`EVALUATOR_ENDPOINT`	unset	मूल्यांकनकर्ता सेवा का Base URL।
`EVALUATOR_TOKEN`	unset	Bearer token `Evaluator(token=...)` के साथ साझा किया जाता है।
`EVALUATOR_WORKERS`	`2`	समवर्ती dispatcher workers।
`EVALUATOR_CLAIM_BATCH`	`4`	Dispatcher pass प्रति दावा किए गए सेशन।
`EVALUATOR_POLLING_INTERVAL_SECS`	`10`	Fallback async polling cadence।
`EVALUATOR_REQUEST_TIMEOUT_MS`	`30000`	Per-request मूल्यांकनकर्ता timeout।
`EVALUATOR_MAX_ATTEMPTS`	`5`	Terminal failure से पहले delivery attempts।
`EVALUATOR_CONFIG_REFRESH_SECS`	`300`	`/config` के लिए refresh cadence।
`EVALUATOR_MAX_POLL_DURATION_SECS`	`3600`	अधिकतम wall-clock async polling time।

सर्वर यह भी restrict कर सकता है कि कौन सी organizations deployment-global मूल्यांकनकर्ता का उपयोग करती हैं। endpoint, token, retry, और organization-gate परिवर्तनों को operator configuration के रूप में मानें और उन्हें बदलने के बाद सर्वर को restart या roll करें।

सुरक्षा और संचालन

जब traffic एक trusted network boundary को पार करता है तो मूल्यांकनकर्ता को HTTPS के पीछे रखें।
एक non-empty bearer token कॉन्फ़िगर करें और इसे दोनों सेवाओं पर identical रखें।
टोकन या request payloads से पूर्ण sensitive prompts को log न करें।
समकालीन handlers को idempotent बनाएँ; retries एक request को दोहरा सकते हैं।
Production में process memory के बाहर असमकालीन job state को persist करें।
स्थिर स्कोर कुंजी लौटाएँ। एक कुंजी को पुनः नाम देना एक नई chart series बनाता है पुरानी को बदलने के बजाय।

SDK structured lifecycle logs emit करता है जैसे eval received, eval responded, job lookup, config returned, auth rejected, और handler exceptions। यह logging handlers कॉन्फ़िगर नहीं करता; host application की logging configuration का उपयोग करें।

Connect your agents

Reference

एक मूल्यांकनकर्ता सेट अप करें

मूल्यांकनकर्ता को Failproof AI से कनेक्ट करें

SDK प्रकार

Decorators और routes

असमकालीन कार्य लौटाएँ

Request और response फ़ील्ड

Server operator सेटिंग्स

सुरक्षा और संचालन

​एक मूल्यांकनकर्ता सेट अप करें

​मूल्यांकनकर्ता को Failproof AI से कनेक्ट करें

​SDK प्रकार

​Decorators और routes

​असमकालीन कार्य लौटाएँ

​Request और response फ़ील्ड

​Server operator सेटिंग्स

​सुरक्षा और संचालन

एक मूल्यांकनकर्ता सेट अप करें

मूल्यांकनकर्ता को Failproof AI से कनेक्ट करें

SDK प्रकार

Decorators और routes

असमकालीन कार्य लौटाएँ

Request और response फ़ील्ड

Server operator सेटिंग्स

सुरक्षा और संचालन