इवैल्स

blume eval आपके दस्तावेज़ों को एक टेस्ट सूट देता है — एक AI एजेंट केवल दस्तावेज़ीकरण का उपयोग करके आपके उपयोगकर्ताओं के प्रश्नों के उत्तर देता है, एक जज उन उत्तरों का मूल्यांकन करता है, और जब दस्तावेज़ उत्तर नहीं दे पाते तो CI विफल हो जाता है।

blume audit आपको बताता है कि क्रॉलर आपके दस्तावेज़ ढूँढ सकते हैं या नहीं। blume eval आपको बताता है कि क्या कोई वास्तव में उनका उपयोग कर सकता है: एक AI एजेंट आपके दस्तावेज़ीकरण को उसी तरह पढ़ता है जैसे कोई अजनबी पढ़ेगा, और उसके आधार पर उपयोगकर्ताओं के वास्तविक प्रश्नों के उत्तर देने का प्रयास करता है। जब दस्तावेज़ों में उत्तर स्पष्ट रूप से नहीं लिखा होता, तो रन विफल हो जाता है और उस पेज का नाम बताता है जिसमें यह उत्तर होना चाहिए।

blume eval

blume eval  4 question(s) · Claude Code

  ✔ install-node-version         pass  1.00  14.2s  $0.14
  ✔ custom-domain                pass  0.92  21.3s  $0.19
  ✖ deploy-vercel                fail  0.40  38.9s  $0.31
      missing: deployment: vercel() from blume/deploy
  ⊘ search-providers             skipped

  fix: content/docs/deployment.mdx  Docs could not answer: "How do I deploy to Vercel?" — missing: deployment: vercel() from blume/deploy

  2 passed · 1 failed · 1 skipped · 1m 42s · $0.64

यह कैसे काम करता है

प्रत्येक प्रश्न दो एजेंट सत्रों से होकर गुज़रता है। इनके लिए उस एजेंट CLI का उपयोग होता है जो आपके पास पहले से इंस्टॉल है — डिफ़ॉल्ट रूप से Claude Code, या --agent codex के साथ Codex। Blume न तो कोई API कुंजी रखता है और न ही स्वयं किसी मॉडल को कॉल करता है। --agent codex के साथ, दोनों सत्र Codex के shell, command और image टूल के बिना चलते हैं, और आपके किसी भी एनवायरनमेंट वेरिएबल को इनहेरिट नहीं करते।

1. रीडर केवल आपके दस्तावेज़ीकरण का उपयोग करके प्रश्न का उत्तर देता है। यह एक खाली डायरेक्टरी में चलता है, जहाँ इसके फ़ाइल, shell और वेब टूल अक्षम रहते हैं, और यह एक निजी MCP सर्वर से जुड़ा होता है जो आपके दस्तावेज़ उपलब्ध कराता है — ये वही search_docs/get_page टूल हैं जिनका उपयोग एक वास्तविक एजेंट आपकी डिप्लॉय की गई साइट पर करता है। यह आपकी रिपॉज़िटरी नहीं पढ़ सकता, इसलिए इसे दस्तावेज़ ठीक वैसे ही दिखते हैं जैसे किसी नए उपयोगकर्ता को: जो लिखा नहीं है, उसका अस्तित्व ही नहीं है।
2. जज बिना किसी टूल के, आपके द्वारा सूचीबद्ध तथ्यों के आधार पर उत्तर का मूल्यांकन करता है। दूसरे शब्दों में कही गई बात पास हो जाती है; कोई छूटा हुआ या गलत बताया गया तथ्य विफल होता है — और “दस्तावेज़ीकरण में यह नहीं बताया गया है” जैसा उत्तर भी विफल होता है।

MCP स्नैपशॉट सीधे आपके कंटेंट स्रोतों से बनाया जाता है, इसलिए पहले blume build चलाने की आवश्यकता नहीं है, और कुछ भी कहीं डिप्लॉय या अपलोड नहीं किया जाता।

जिस उत्तर की पुष्टि दस्तावेज़ों से नहीं होती, वह विफल होता है, भले ही एजेंट का पूर्व ज्ञान संयोग से सही हो — यही इसका उद्देश्य है। उपयोगकर्ताओं तक केवल आपके दस्तावेज़ ही पहुँचते हैं।

इवैल्स लिखना

प्रश्न प्रोजेक्ट रूट में evals.yaml में रखे जाते हैं। अपने मौजूदा दस्तावेज़ों के आधार पर किसी एजेंट से एक प्रारंभिक फ़ाइल का ड्राफ़्ट तैयार करवाने के लिए:

blume eval init

या इसे स्वयं लिखें:

questions:
  - id: install-node-version
    question: What is the minimum Node.js version required?
    expected:
      - Node 22.12 or newer
    routes: /docs/quickstart
  - id: deploy-vercel
    question: How do I deploy to Vercel?
    expected:
      - run blume build
      - "server features need deployment: vercel() from blume/deploy"
    routes:
      - /docs/deployment
  - id: search-providers
    question: Which search providers are supported?
    expected:
      - Orama is the default, with no hosted service
    severity: warning # a miss warns instead of failing CI
    skip: true # temporarily excluded, reported as skipped

• expected उन तथ्यों की सूची है जिनका सार एक सही उत्तर में होना चाहिए — जज दूसरे शब्दों में कही गई बात को स्वीकार करता है और विरोधाभासी बात को अस्वीकार करता है।
• routes उस पेज (या पेजों) का नाम बताता है जिसमें प्रश्न का उत्तर होना चाहिए। इससे रिपोर्ट में विफलता उस पेज की स्रोत फ़ाइल से जुड़ जाती है; यदि कोई संकेत अब किसी पेज से मेल नहीं खाता, तो उसे चुपचाप हटाया नहीं जाता, बल्कि उसके बारे में चेतावनी दी जाती है।
• severity: warning किसी प्रश्न को CI विफल किए बिना रिपोर्ट में बनाए रखता है; skip: true किसी प्रश्न को पूरी तरह बाहर कर देता है।

ऐसे प्रश्न लिखें जो आपके उपयोगकर्ता वास्तव में पूछते हैं — जैसे सपोर्ट थ्रेड, GitHub issues और ऑनबोर्डिंग कॉल में आने वाले प्रश्न। सबसे अच्छे इवैल्स आपके दस्तावेज़ों के किसी वादे (“ज़ीरो-कॉन्फ़िग डिप्लॉय”) को एक ऐसे प्रश्न में बदल देते हैं जो किसी PR के उस वादे को तोड़ते ही विफल हो जाता है।

CI को विफल करना

एग्ज़िट कोड ही निर्णायक होता है: एक भी प्रश्न विफल होने पर रन नॉन-ज़ीरो कोड के साथ समाप्त होता है। यदि एजेंट रन स्वयं विफल हो जाए — यानी रीडर या जज उत्तर का मूल्यांकन करने के बजाय त्रुटि के साथ रुक जाए — तो रिपोर्ट में run failed: दिखाई देता है। ऐसे में रिपोर्ट सुधार के लिए किसी दस्तावेज़ पेज का नाम बताने के बजाय आपकी evals फ़ाइल के उस प्रश्न की ओर इशारा करती है, क्योंकि दस्तावेज़ों का मूल्यांकन हुआ ही नहीं। यदि आप लंबित विफलताओं को धीरे-धीरे ठीक कर रहे हैं, तो --threshold इस शर्त को ढीला कर देता है — तब सभी प्रश्नों के बजाय उनका केवल एक निर्धारित अनुपात पास होना ज़रूरी होता है:

blume eval                    # every question must pass
blume eval --threshold 0.8    # at least 80% must pass
blume eval --json             # machine-readable report on stdout

JSON रिपोर्ट की diagnostics + summary संरचना वही है जो blume validate --json और blume audit --json की है। इसके साथ प्रति-प्रश्न परिणाम (उत्तर, स्कोर, छूटे हुए तथ्य, लागत) भी शामिल होते हैं।

चूँकि प्रत्येक प्रश्न के लिए दो मॉडल सत्र चलते हैं, इसलिए eval रन में वास्तविक पैसा और कुछ मिनट का समय लगता है — रन के दौरान प्रति-प्रश्न खर्च दिखाया जाता है। CI में blume eval को हर push पर चलाने के बजाय केवल दस्तावेज़ों में बदलाव होने पर चलाना बेहतर रहता है।

निष्कर्षों को ठीक करना

प्रत्येक विफलता में छूटे हुए तथ्यों और उस पेज का नाम होता है जिसमें ये तथ्य होने चाहिए। यदि आप पूरी रिपोर्ट एजेंट को सौंपना चाहते हैं, तो:

blume eval --fix

यह पूरी JSON रिपोर्ट एक फ़ाइल में लिखता है और एजेंट को इंटरैक्टिव मोड में एक प्रॉम्प्ट के साथ खोलता है। यह प्रॉम्प्ट एजेंट से एक-एक करके हर विफल प्रश्न पर यह काम करवाता है: बताया गया पेज पढ़ना, पेज की शैली में छूटे हुए तथ्य जोड़ना, और तब तक blume eval दोबारा चलाना जब तक सब कुछ पास न हो जाए। सत्र जानबूझकर इंटरैक्टिव रखा गया है, ताकि आप एजेंट की अपनी अनुमति प्रक्रिया के ज़रिए हर संपादन की समीक्षा कर सकें। एजेंट को यह निर्देश भी दिया जाता है कि वह सभी प्रश्न पास करवाने के लिए कभी भी कोई प्रश्न न हटाए और न ही अपेक्षित तथ्यों को कमज़ोर करे।

फ़्लैग

• --agent claude|codex — रीडर और जज को चलाने वाला एजेंट CLI। डिफ़ॉल्ट claude है।
• --file <path> — evals फ़ाइल। डिफ़ॉल्ट evals.yaml है।
• --threshold <0..1> — पास होने वाले प्रश्नों का न्यूनतम अनुपात, जिससे कम होने पर रन नॉन-ज़ीरो कोड के साथ समाप्त होता है। डिफ़ॉल्ट 1 है।
• --timeout <seconds> — प्रति प्रश्न रीडर की समय सीमा। डिफ़ॉल्ट 180 है।
• --json — रिपोर्ट को stdout पर JSON के रूप में आउटपुट करता है।
• --fix — रन विफल होने पर रिपोर्ट एजेंट को सौंपता है, ताकि वह इंटरैक्टिव रूप से दस्तावेज़ ठीक कर सके।
• --verbose — प्रत्येक विफलता के नीचे रीडर का पूरा उत्तर भी दिखाता है।