इवैल्स

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

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

blume eval

blume eval  4 question(s) · Codex

  ✔ install-node-version         pass  1.00  14.2s
  ✔ custom-domain                pass  0.92  21.3s
  ✖ deploy-vercel                fail  0.40  38.9s
      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

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

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

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.19 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 को विफल करना

एग्ज़िट कोड ही निर्णायक होता है: एक भी प्रश्न विफल होने पर रन नॉन-ज़ीरो कोड के साथ समाप्त होता है, सिवाय severity: warning वाले प्रश्न के — उसकी चूक को चेतावनी के रूप में रिपोर्ट किया जाता है और उसे न तो इस शर्त में और न ही --threshold में कभी विफलता के रूप में गिना जाता है। यदि एजेंट रन स्वयं विफल हो जाए — यानी रीडर या जज उत्तर का मूल्यांकन करने के बजाय त्रुटि के साथ रुक जाए — तो रिपोर्ट में 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 की है। इसके साथ प्रति-प्रश्न परिणाम (उत्तर, स्कोर, छूटे हुए तथ्य, और Claude Code के साथ, लागत) भी शामिल होते हैं।

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

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

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

blume eval --fix

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

फ़्लैग

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