ग्राउंड ट्रुथ्स: AI एजेंट्स को हक़ीक़त से जोड़ना

इस पोस्ट में दिए गए आंकड़े प्रकाशन के समय (जनवरी 2026) की सिस्टम स्थिति दर्शाते हैं। मौजूदा आंकड़ों के लिए हमारा टीम पेज देखें।

AI एजेंट असाधारण रूप से सक्षम हैं। वे तर्क कर सकते हैं, संश्लेषित कर सकते हैं, और जनरेट कर सकते हैं। लेकिन उनमें एक बुनियादी कमज़ोरी है: वे चीज़ें गढ़ लेते हैं। बदनीयती से नहीं, बल्कि पूरे भरोसे के साथ। कोई एजेंट ऐसे API पैरामीटर गढ़ सकता है जो मौजूद ही नहीं हैं, ऐसे कॉन्फ़िगरेशन का हवाला दे सकता है जो कभी परिभाषित ही नहीं हुए, या अपने ट्रेनिंग डेटा से ऐसे पैटर्न लागू कर सकता है जो आपके असली आर्किटेक्चर के विरुद्ध जाते हैं।

मानक उपाय है “एजेंट को ज़्यादा कॉन्टेक्स्ट दो।” लेकिन कॉन्टेक्स्ट भी परस्पर विरोधाभासी हो सकता है। डॉक्यूमेंटेशन इम्प्लीमेंटेशन से भटक जाता है। कमेंट झूठ बोलते हैं। यहां तक कि आशय समझे बिना पढ़ने पर कोड भी गुमराह कर सकता है।

हमें कुछ ज़्यादा स्पष्ट चाहिए था। कुछ ऐसा जिसे नज़रअंदाज़ या ग़लत तरीक़े से समझा न जा सके। कुछ ऐसा जो एजेंट को सत्यापन योग्य हक़ीक़त से जोड़े रखे।

हम इन्हें ग्राउंड ट्रुथ्स कहते हैं।

ग्राउंड ट्रुथ क्या है?

ग्राउंड ट्रुथ तथ्य का एक स्पष्ट, वर्ज़न्ड कथन है जिसका एजेंट को सम्मान करना ही होता है। यह डॉक्यूमेंटेशन नहीं है। यह कोई कमेंट नहीं है। यह सिस्टम में एक प्रथम-श्रेणी इकाई है, जिसमें शामिल है:

• एक यूनीक आइडेंटिफ़ायर (जैसे GT-MAG-015 या GT-MAG-036)
• एक लाइफ़साइकल स्टेटस (current, tentative, या deprecated)
• एक स्कोप (प्लेटफ़ॉर्म-व्यापी, पैकेज-विशिष्ट, या डोमेन-बद्ध)
• साक्ष्य (फ़ाइल पथ, URL, या रेफ़रेंस जो कथन को साबित करते हैं)
• एजेंट गाइडेंस (स्पष्ट do/avoid निर्देश)

यह रहा हमारे Maguyva कोड इंटेलिजेंस प्लेटफ़ॉर्म का एक उदाहरण:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

यह गद्य नहीं है। यह एक अनुबंध है। जब कोई एजेंट इस ग्राउंड ट्रुथ का सामना करता है, तो वह जानता है:

1. डिफ़ॉल्ट डिटरमिनिस्टिक है (खाली परिणाम, अस्पष्ट अनुमान नहीं)
2. परिभाषित व्यवहार वाले विशिष्ट पैरामीटर मौजूद हैं (find_similar, exact_match)
3. साक्ष्य विशिष्ट फ़ाइलों में मौजूद है जिसे सत्यापित किया जा सकता है
4. कथन एक विशिष्ट तारीख़ को सत्यापित किया गया था

ग्राउंड ट्रुथ रजिस्ट्री की शारीरिक बनावट

ग्राउंड ट्रुथ ai_assets/reference/ground_truths.yaml के अंतर्गत YAML रजिस्ट्री में रहते हैं। हर पैकेज या डोमेन की अपनी रजिस्ट्री हो सकती है। संरचना यह है:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

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

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

एजेंट ग्राउंड ट्रुथ तक कैसे पहुंचते हैं

ग्राउंड ट्रुथ कई चैनल के ज़रिए एक्सपोज़ किए जाते हैं:

1. रेंडर्ड डॉक्यूमेंटेशन

orkestra sync कमांड YAML रजिस्ट्री को पढ़ने योग्य मार्कडाउन में बदल देता है:

uv run orkestra sync

यह GROUND_TRUTHS.md फ़ाइलें जनरेट करता है जो एजेंट कॉन्टेक्स्ट में शामिल होती हैं। रेंडर्ड आउटपुट कथनों को स्टेटस और श्रेणी के हिसाब से समूहित करता है:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. CLI सर्च

शेल एक्सेस वाले एजेंट ग्राउंड ट्रुथ को प्रोग्रामेटिक रूप से सर्च कर सकते हैं:

uv run orkestra context ground-truths search "embedding"
uv run orkestra context ground-truths search --tag security
uv run orkestra context ground-truths list --status current

सर्च फ़ंक्शन कई फ़ील्ड में वेटेड रेलेवेंस के साथ मैच स्कोर करता है:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. कॉन्टेक्स्ट कम्पोज़िशन

जब एजेंट YAML परिभाषाओं से रेंडर किए जाते हैं, तो उनका कॉन्टेक्स्ट ग्राउंड ट्रुथ रजिस्ट्री का हवाला दे सकता है:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

इससे यह सुनिश्चित होता है कि एजेंट का काम शुरू करने से पहले प्रासंगिक ग्राउंड ट्रुथ लोड हो चुके हों।

ग्राउंड ट्रुथ की श्रेणियां

हमारी रजिस्ट्री में देखने पर, ग्राउंड ट्रुथ कई पैटर्न में समूहित हो जाते हैं:

प्रोडक्ट सिद्धांत

यह प्रोडक्ट क्या है और क्या नहीं, इस पर सीमाएं:

“Maguyva उपयोगकर्ता रिपॉज़िटरी के संबंध में केवल-पठनीय (read-only) है; एकमात्र ऐसा एसेट जिसे दोबारा नहीं बनाया जा सकता, वह है पेड एम्बेडिंग कैश।” (GT-MAG-001)

आर्किटेक्चर सीमाएं

ज़िम्मेदारियां कहां रहती हैं और क्यों:

“पाइपलाइन और Maguyva की सीमाएं जानबूझकर बनाई गई हैं: पाइपलाइन पुनः उपयोग योग्य है, Maguyva कोड-विशिष्ट लॉजिक रखता है, और CQRS स्टेज राइट्स को सर्वर रीड्स से अलग करता है।” (GT-MAG-006)

एंटी-हैलुसिनेशन नियम

स्पष्ट अधिदेश जो टूल कॉन्ट्रैक्ट को अनुमानित के बजाय डिटरमिनिस्टिक बनाए रखते हैं:

“फ़ज़ी सिंबल मैचिंग find_similar=true के ज़रिए ऑप्ट-इन है। डिफ़ॉल्ट व्यवहार अस्तित्वहीन सिंबल के लिए खाली परिणाम लौटाता है; exact_match=true सख़्त मैचिंग लागू करता है और सभी फ़ज़ी फ़ॉलबैक बंद कर देता है।” (GT-MAG-015)

क्वालिटी गेट

ऐसे मानदंड जिन्हें बनाए रखना ज़रूरी है:

“साझा इन्फ़्रास्ट्रक्चर (post_filters.py, रिलेशनशिप एक्सट्रैक्टर, साझा हैंडलर) में बदलावों को कमिट से पहले फ़ुल मैनिफ़ेस्ट जनरेशन के ज़रिए सभी सपोर्टेड भाषाओं के विरुद्ध वैलिडेट किया जाना ज़रूरी है। साझा कोड के लिए सिर्फ़ एक भाषा में वैलिडेशन पर्याप्त नहीं है।” (GT-MAG-036)

कोड पैटर्न

इम्प्लीमेंटेशन आवश्यकताएं:

“एसिंक कॉन्टेक्स्ट में CPU-बाउंड काम के लिए asyncio.to_thread() का उपयोग करें; डिप्रीकेटेड loop.run_in_executor() पैटर्न का उपयोग नए कोड में नहीं होना चाहिए।” (GT-MAG-018)

ग्राउंड ट्रुथ का लाइफ़साइकल

ग्राउंड ट्रुथ स्थिर नहीं होते। वे एक परिभाषित लाइफ़साइकल के ज़रिए विकसित होते हैं:

Tentative (अस्थायी)

मूल्यांकन के दौर से गुज़र रहा एक प्रस्तावित सत्य। कथन दर्ज कर लिया गया है लेकिन बदल सकता है:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Current (मौजूदा)

एक सत्यापित सत्य जिसका एजेंट को सम्मान करना ज़रूरी है। साक्ष्य को वैलिडेट किया जा चुका है:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Deprecated (अप्रचलित)

एक ऐसा सत्य जो अब लागू नहीं होता। इसे ऐतिहासिक संदर्भ के लिए रखा गया है, साथ ही यह इशारा भी कि इसकी जगह क्या आया:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

सिर्फ़ डॉक्यूमेंटेशन क्यों नहीं?

डॉक्यूमेंटेशन एक अलग मक़सद पूरा करता है। यह समझाता है। यह सिखाता है। यह अस्पष्ट हो सकता है, “आमतौर पर” या “सामान्यतः” जैसे क्वालिफ़ायर का उपयोग कर सकता है।

ग्राउंड ट्रुथ अस्पष्ट नहीं हो सकते। ये दावे हैं। या तो ये लागू होते हैं या नहीं होते।

यह फ़र्क़ देखें:

डॉक्यूमेंटेशन: “जब कोई सिंबल नहीं मिलता तो API आमतौर पर खाली परिणाम लौटाता है, हालांकि कुछ कॉन्फ़िगरेशन में फ़ज़ी मैचिंग एनेबल हो सकती है।”

ग्राउंड ट्रुथ: “डिफ़ॉल्ट व्यवहार अस्तित्वहीन सिंबल के लिए खाली परिणाम लौटाता है; exact_match=true सख़्त मैचिंग लागू करता है और सभी फ़ज़ी फ़ॉलबैक बंद कर देता है।”

पहला इंसानों के लिए सिस्टम सीखने में मददगार है। दूसरा फ़ैसले लेते समय एजेंट के लिए कार्रवाई-योग्य है।

एजेंट गाइडेंस: करें और बचें

कुछ ग्राउंड ट्रुथ में स्पष्ट एजेंट गाइडेंस शामिल होती है:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

इससे अस्पष्टता ख़त्म हो जाती है। इसे पढ़ने वाला एजेंट सिर्फ़ यह नहीं जानता कि क्या सच है, बल्कि यह भी जानता है कि वह सत्य किन कार्रवाइयों का संकेत देता है।

सत्यापन और रखरखाव

ग्राउंड ट्रुथ को रखरखाव की ज़रूरत होती है। हम ट्रैक करते हैं:

• last_verified: कब किसी ने पुष्टि की कि कथन अब भी लागू होता है
• evidence: वे फ़ाइलें जो कथन को साबित करती हैं (अस्तित्व के लिए जांची जा सकती हैं)
• source: सत्य की उत्पत्ति कहां से हुई (CLI निरीक्षण, आर्किटेक्चर समीक्षा, इंसिडेंट के बाद की सीख)

पुरानी पड़ चुकी सत्यापन तारीख़ों या टूटे साक्ष्य लिंक वाला कोई ग्राउंड ट्रुथ जांच का संकेत है। या तो सत्य अब भी वैध है और उसे दोबारा सत्यापित करने की ज़रूरत है, या हक़ीक़त बदल चुकी है और सत्य को अपडेट करने की ज़रूरत है।

प्रोडक्शन से असली उदाहरण

सुरक्षा सीमा

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

यह ग्राउंड ट्रुथ ऐसे “सुरक्षा सुधारों” की एक पूरी श्रेणी को रोकता है जो भ्रमित होकर प्रोडक्ट को तोड़ देते।

एक्सट्रैक्शन-टाइम सटीकता

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

यह एक तकलीफ़देह अनुभव से आया। एजेंट फ़ेल हो रहे लैंग्वेज पैक को सिर्फ़ वैलिडेटर-ओनली फ़िल्टर जोड़कर पैच कर देते थे, जिससे टेस्ट हार्नेस ज़्यादा ग्रीन दिखने लगता था, जबकि लाइव Maguyva एक्सट्रैक्टर अब भी ग़लत एज उत्सर्जित कर रहा होता था। यह नियम फ़िक्स को वापस असली पथ में ले जाने पर मजबूर करता है: YAML कॉन्फ़िग, क्वेरी, या हैंडलर।

मल्टी-टियर फ़िल्टरिंग

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

यह एजेंट को ग़लत जगह फ़िल्टर जोड़ने से रोकता है, एक आम ग़लती जिसने सटीकता में रिग्रेशन पैदा किया था।

ऑर्केस्ट्रेशन सिस्टम के साथ इंटीग्रेशन

ग्राउंड ट्रुथ एक व्यापक कॉन्टेक्स्ट सिस्टम की एक लेयर हैं:

1. आर्किटेक्चरल डिसीज़न (ADR) - दर्ज करते हैं कि हमने अप्रोच A को B पर क्यों चुना
2. ग्राउंड ट्रुथ - बताते हैं कि अभी निश्चित रूप से क्या सच है
3. डोमेन पैटर्न - बताते हैं कि चीज़ें सही तरीक़े से कैसे करें
4. एंटी-पैटर्न - बताते हैं कि क्या टालना चाहिए और क्यों

सिस्टम में काम करने वाले किसी एजेंट के पास चारों तक पहुंच होती है। ग्राउंड ट्रुथ तथ्यात्मक आधार देते हैं, जबकि डिसीज़न इतिहास समझाते हैं, पैटर्न इम्प्लीमेंटेशन में मार्गदर्शन करते हैं, और एंटी-पैटर्न ख़तरों के प्रति आगाह करते हैं।

प्रभाव मापना

ग्राउंड ट्रुथ लाने के बाद से, हमने देखा है:

• “हैलुसिनेटेड फ़िक्स को फ़िक्स करने” के चक्र कम हुए
• जब तथ्य स्पष्ट होते हैं तो एजेंट का फ़ैसला ज़्यादा भरोसेमंद होता है
• बेहतर PR समीक्षाएं क्योंकि अपेक्षाएं स्पष्ट हैं
• नए एजेंट (और इंसानों) के लिए घटा हुआ ऑनबोर्डिंग समय

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

शुरुआत कैसे करें

अपने सिस्टम में एक ग्राउंड ट्रुथ जोड़ने के लिए:

1. अपने पैकेज की ai_assets/reference/ डायरेक्टरी में एक ground_truths.yaml बनाएं
2. मेटाडेटा और रेंडर कॉन्फ़िगरेशन परिभाषित करें
3. स्कीमा का पालन करते हुए कथन जोड़ें
4. डॉक्यूमेंटेशन जनरेट करने के लिए uv run orkestra sync चलाएं
5. एजेंट कॉन्टेक्स्ट कम्पोज़िशन में रजिस्ट्री शामिल करें

उन तथ्यों से शुरू करें जो सबसे ज़्यादा भ्रम पैदा करते हैं, या उन सीमाओं से जिनका सबसे ज़्यादा उल्लंघन होता है। यही आपके सबसे मूल्यवान ग्राउंड ट्रुथ हैं।

निष्कर्ष

AI एजेंट हैलुसिनेट करेंगे। यह उनकी प्रकृति है। लेकिन हम ऐसे वातावरण बना सकते हैं जहां हैलुसिनेशन को सीमित किया जाए, जहां कुछ तथ्य गैर-परक्राम्य हों, जहां एजेंट अपनी धारणाओं को सत्यापित हक़ीक़त के विरुद्ध जांच सकें।

ग्राउंड ट्रुथ कोई मुकम्मल समाधान नहीं हैं। उन्हें रखरखाव की ज़रूरत होती है। वे पुराने पड़ सकते हैं। वे डेवलपमेंट प्रक्रिया में ओवरहेड जोड़ते हैं।

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

विकल्प है एजेंट के पूरे भरोसे के साथ ग़लतियां करते रहने और इंसानों के उन्हें सुधारते रहने का अंतहीन चक्र। ग्राउंड ट्रुथ सुधारों को स्पष्ट और टिकाऊ बनाकर उस चक्र को तोड़ते हैं।

आपके एजेंट यह जानने के हक़दार हैं कि क्या सच है। उन्हें बताएं।