# ग्राफ संदर्भ तकनीकी विनिर्देश

## अवलोकन

यह विनिर्देश ट्रस्टग्राफ के मुख्य ग्राफ प्रिमिटिव में किए गए परिवर्तनों का वर्णन करता है ताकि
यह RDF 1.2 के अनुरूप हो और RDF डेटासेट के पूर्ण अर्थों का समर्थन कर सके। यह 2.x रिलीज़ श्रृंखला के लिए एक महत्वपूर्ण बदलाव है।

### संस्करण

- **2.0**: प्रारंभिक अपनाने वाला रिलीज़। मुख्य विशेषताएं उपलब्ध हैं, लेकिन यह पूरी तरह से
  उत्पादन के लिए तैयार नहीं हो सकता है।
- **2.1 / 2.2**: उत्पादन रिलीज़। स्थिरता और पूर्णता की पुष्टि की गई है।

परिपक्वता में लचीलापन जानबूझकर रखा गया है - प्रारंभिक अपनाने वाले नई
क्षमताओं तक पहुंच सकते हैं, भले ही सभी विशेषताएं उत्पादन के लिए पूरी तरह से तैयार न हों।

## लक्ष्य

इस कार्य के प्राथमिक लक्ष्य तथ्यों/कथनों के बारे में मेटाडेटा को सक्षम करना हैं:

- **टेम्पोरल जानकारी**: तथ्यों को समय मेटाडेटा से जोड़ना
  - जब किसी तथ्य को सत्य माना गया था
  - जब कोई तथ्य सत्य हो गया
  - जब किसी तथ्य को गलत साबित किया गया

- **उत्पत्ति/स्रोत**: यह ट्रैक करना कि कौन से स्रोत किसी तथ्य का समर्थन करते हैं
  - "यह तथ्य स्रोत X द्वारा समर्थित था"
  - तथ्यों को उनके मूल दस्तावेजों से जोड़ना

- **सत्यता/विश्वसनीयता**: सत्य के बारे में दावे रिकॉर्ड करना
  - "व्यक्ति P ने कहा कि यह सत्य था"
  - "व्यक्ति Q का दावा है कि यह गलत है"
  - विश्वास स्कोरिंग और संघर्ष का पता लगाने को सक्षम करना

**परिकल्पना**: पुन:पुनर्बलन (RDF-स्टार / उद्धृत ट्रिपल) वह प्रमुख तंत्र है
इन परिणामों को प्राप्त करने के लिए, क्योंकि सभी को कथनों के बारे में कथन करने की आवश्यकता होती है।

## पृष्ठभूमि

"यह तथ्य (एलिस बॉब को जानती है) 15 जनवरी, 2024 को खोजा गया था" या
"स्रोत X दावे (Y कारण Z है) का समर्थन करता है" को व्यक्त करने के लिए, आपको एक किनारे
का संदर्भ देना होगा जिसे आप कथनों के बारे में बात कर सकते हैं। मानक ट्रिपल इसका समर्थन नहीं करते हैं।

### वर्तमान सीमाएं

`trustgraph-base/trustgraph/schema/core/primitives.py` में वर्तमान `Value` वर्ग:
- URI नोड (`is_uri=True`)
- शाब्दिक मान (`is_uri=False`)

`type` फ़ील्ड मौजूद है, लेकिन इसका उपयोग XSD डेटा प्रकारों को दर्शाने के लिए नहीं किया जाता है।

## तकनीकी डिज़ाइन

### समर्थित RDF विशेषताएं

#### मुख्य विशेषताएं (पुन:पुनर्बलन लक्ष्यों से संबंधित)

ये विशेषताएं अस्थायी, उत्पत्ति और सत्यता लक्ष्यों से सीधे संबंधित हैं:

1. **RDF 1.2 उद्धृत ट्रिपल (RDF-स्टार)**
   - किनारे जो अन्य किनारों की ओर इशारा करते हैं
   - एक ट्रिपल एक ट्रिपल के विषय या वस्तु दोनों के रूप में दिखाई दे सकता है
   - कथनों के बारे में कथन सक्षम करें (पुन:पुनर्बलन)
   - व्यक्तिगत तथ्यों को एनोटेट करने का मुख्य तंत्र

2. **RDF डेटासेट / नामित ग्राफ**
   - एक डेटासेट के भीतर कई नामित ग्राफ का समर्थन
   - प्रत्येक ग्राफ को एक IRI द्वारा पहचाना जाता है
   - ट्रिपल (s, p, o) से क्वाड (s, p, o, g) में बदलाव
   - एक डिफ़ॉल्ट ग्राफ प्लस शून्य या अधिक नामित ग्राफ शामिल हैं
   - ग्राफ IRI कथनों में एक विषय हो सकता है, उदाहरण के लिए:
     ```
     <graph-source-A> <discoveredOn> "2024-01-15"
     <graph-source-A> <hasVeracity> "उच्च"
     ```
   - ध्यान दें: नामित ग्राफ पुन:पुनर्बलन से अलग विशेषता है। उनके
     कथन एनोटेशन (विभाजन, एक्सेस नियंत्रण, डेटासेट संगठन) से परे उपयोग हैं
     और इसे एक अलग क्षमता के रूप में माना जाना चाहिए।

3. **रिक्त नोड** (सीमित समर्थन)
   - वैश्विक URI के बिना अनाम नोड
   - बाहरी RDF डेटा लोड करते समय संगतता के लिए समर्थित
   - **सीमित स्थिति**: लोडिंग के बाद स्थिर पहचान की कोई गारंटी नहीं
   - वाइल्डकार्ड प्रश्नों के माध्यम से उनका पता लगाएं (कनेक्शन से मिलान करें, आईडी से नहीं)
   - यह पहली श्रेणी की विशेषता नहीं है - सटीक रिक्त नोड हैंडलिंग पर भरोसा न करें।

#### अवसरवादी सुधार (2.0 ब्रेकिंग परिवर्तन)

ये विशेषताएं पुन:पुनर्बलन लक्ष्यों से सीधे संबंधित नहीं हैं, लेकिन
महत्वपूर्ण सुधार हैं जिन्हें ब्रेकिंग परिवर्तनों के दौरान शामिल किया जाना चाहिए:

4. **शाब्दिक डेटा प्रकार**
   - XSD डेटा प्रकारों के लिए `type` फ़ील्ड का ठीक से उपयोग करें
   - उदाहरण: xsd:string, xsd:integer, xsd:dateTime, आदि।
   - वर्तमान सीमा को ठीक करता है: तिथियों या पूर्णांकों को ठीक से दर्शाया नहीं जा सकता है।

5. **भाषा टैग**
   - स्ट्रिंग शाब्दिक पर भाषा विशेषताओं का समर्थन
   - ध्यान दें: एक शाब्दिक में या तो एक भाषा टैग होता है या एक डेटा प्रकार, दोनों नहीं
     (rdf:langString को छोड़कर)
   - AI/बहुभाषी उपयोग के मामलों के लिए महत्वपूर्ण।

### डेटा मॉडल

#### टर्म (नाम बदलकर वैल्यू)

`Value` वर्ग को बेहतर ढंग से RDF शब्दावली को दर्शाने के लिए `Term` में बदल दिया जाएगा।
इस नामकरण का दो उद्देश्य हैं:
1. यह नामकरण RDF अवधारणाओं के साथ संरेखित होता है (एक "टर्म" एक IRI, शाब्दिक,
   रिक्त नोड या उद्धृत ट्रिपल हो सकता है - केवल एक "मान" नहीं)।
2. यह ब्रेकिंग परिवर्तन इंटरफ़ेस पर कोड समीक्षा को मजबूर करता है - कोई भी कोड जो अभी भी
   `Value` को संदर्भित करता है, वह स्पष्ट रूप से टूटा हुआ है और इसे अपडेट करने की आवश्यकता है।

एक टर्म का प्रतिनिधित्व किया जा सकता है:

- **IRI/URI**: एक नामित नोड/संसाधन
- **रिक्त नोड**: स्थानीय दायरे वाला एक अनाम नोड
- **शाब्दिक**: एक डेटा मान जिसमें या तो:
  - एक डेटा प्रकार (XSD प्रकार), या
  - एक भाषा टैग
- **उद्धृत ट्रिपल**: एक ट्रिपल का उपयोग एक टर्म के रूप में किया जाता है (RDF 1.2)

##### चुनी गई दृष्टिकोण: एकल वर्ग जिसमें प्रकार विभेदक है

सीरियलाइज़ेशन आवश्यकताएं संरचना को चलाती हैं - वायर प्रारूप में एक प्रकार विभेदक की आवश्यकता होती है
चाहे पायथन प्रतिनिधित्व कुछ भी हो। एक एकल वर्ग जिसमें एक प्रकार फ़ील्ड प्राकृतिक है
और वर्तमान `Value` पैटर्न के साथ संरेखित है।

एकल-अक्षर प्रकार कोड कॉम्पैक्ट सीरियलाइज़ेशन प्रदान करते हैं:

```python
from dataclasses import dataclass

# टर्म प्रकार स्थिरांक
IRI = "i"      # IRI/URI नोड
BLANK = "b"    # रिक्त नोड
LITERAL = "l"  # शाब्दिक मान
TRIPLE = "t"   # उद्धृत ट्रिपल (RDF-स्टार)

@dataclass
class Term:
    type: str = ""  # इनमें से एक: IRI, BLANK, LITERAL, TRIPLE

    # IRI टर्म के लिए (type == IRI)
    iri: str = ""

    # रिक्त नोड के लिए (type == BLANK)
    id: str = ""

    # शाब्दिक के लिए (type == LITERAL)
    value: str = ""
    datatype: str = ""   # XSD डेटा प्रकार URI (भाषा के साथ परस्पर अनन्य)
    language: str = ""   # भाषा टैग (डेटा प्रकार के साथ परस्पर अनन्य)

    # उद्धृत ट्रिपल के लिए (type == TRIPLE)
    triple: "Triple | None" = None
```

उपयोग के उदाहरण:

```python
# IRI टर्म
node = Term(type=IRI, iri="http://example.org/Alice")

# डेटा प्रकार के साथ शाब्दिक
age = Term(type=LITERAL, value="42", datatype="xsd:integer")

# भाषा टैग के साथ शाब्दिक
label = Term(type=LITERAL, value="नमस्ते", language="en")

# रिक्त नोड
anon = Term(type=BLANK, id="_:b1")

# उद्धृत ट्रिपल (कथन के बारे में कथन)
inner = Triple(
    s=Term(type=IRI, iri="http://example.org/Alice"),
    p=Term(type=IRI, iri="http://example.org/knows"),
    o=Term(type=IRI, iri="http://example.org/Bob"),
)
reified = Term(type=TRIPLE, triple=inner)
```

##### विचार किए गए विकल्प

**विकल्प B: विशिष्ट वर्गों का संघ** (`Term = IRI | BlankNode | Literal | QuotedTriple`)
- अस्वीकृत: सीरियलाइज़ेशन को अभी भी एक प्रकार विभेदक की आवश्यकता होगी, जो जटिलता जोड़ता है।

**विकल्प C: बेस क्लास जिसमें सबक्लासेस हैं**
- अस्वीकृत: समान सीरियलाइज़ेशन समस्या, साथ ही डेटा क्लास इनहेरिटेंस की जटिलताएं।

#### ट्रिपल / क्वाड

`Triple` वर्ग में एक वैकल्पिक ग्राफ फ़ील्ड है ताकि यह क्वाड बन जाए:

```python
@dataclass
class Triple:
    s: Term | None = None    # विषय
    p: Term | None = None    # विधेय
    o: Term | None = None    # वस्तु
    g: str | None = None     # ग्राफ नाम (IRI), None = डिफ़ॉल्ट ग्राफ
```

डिज़ाइन निर्णय:
- **फ़ील्ड नाम**: स्थिरता के लिए `g` को `s`, `p`, `o` के साथ
- **वैकल्पिक**: `None` का मतलब डिफ़ॉल्ट ग्राफ (अनटैग)
- **प्रकार**: पूर्ण `Term` तंत्र की आवश्यकता नहीं होने के कारण, केवल एक स्ट्रिंग (IRI)
  - ग्राफ नाम हमेशा IRI होते हैं
  - ग्राफ नाम के रूप में रिक्त नोड को खारिज कर दिया गया (बहुत भ्रमित करने वाला)

ध्यान दें: `Triple` वर्ग का नाम `Quad` होने पर भी `Triple` रहता है।
यह अपव्यय से बचाता है और "ट्रिपल" अभी भी सामान्य शब्दावली है। ग्राफ संदर्भ
यह दर्शाता है कि ट्रिपल कहाँ स्थित है।

### उम्मीदवार क्वेरी पैटर्न

वर्तमान क्वेरी इंजन S, P, O टर्म के संयोजनों को स्वीकार करता है। उद्धृत
ट्रिपल के साथ, एक ट्रिपल स्वयं उन स्थितियों में एक मान्य टर्म बन जाता है। नीचे
उम्मीदवार क्वेरी पैटर्न दिए गए हैं जो मूल लक्ष्यों का समर्थन करते हैं।

#### ग्राफ पैरामीटर अर्थशास्त्र

पिछड़ी संगतता के लिए SPARQL सम्मेलनों का पालन करना:

- **`g` छोड़ा गया / None**: केवल डिफ़ॉल्ट ग्राफ क्वेरी करें
- **`g` = विशिष्ट IRI**: केवल उस नामित ग्राफ को क्वेरी करें
- **`g` = वाइल्डकार्ड / `*`**: सभी ग्राफों में क्वेरी करें (SPARQL के बराबर
  `GRAPH ?g { ... }`)

यह सरल क्वेरी को सरल रखता है और नामित ग्राफ क्वेरी को वैकल्पिक बनाता है।

क्रॉस-ग्राफ क्वेरी (g=वाइल्डकार्ड) पूरी तरह से समर्थित हैं। Cassandra स्कीमा
समर्पित तालिकाओं को शामिल करता है (SPOG, POSG, OSPG) जहां g एक क्लस्टरिंग कॉलम है
विभिन्न ग्राफों में कुशल क्वेरी सक्षम करने के लिए पार्टीशन कुंजी नहीं है।

#### टेम्पोरल क्वेरी

**एक निश्चित तिथि के बाद खोजे गए सभी तथ्यों का पता लगाएं:**
```
S: ?                                    # कोई भी उद्धृत ट्रिपल
P: <discoveredOn>
O: > "2024-01-15"^^xsd:date             # तिथि तुलना
```

**पता लगाएं कि किसी विशिष्ट तथ्य को कब सत्य माना गया था:**
```
S: << <एलिस> <जानता है> <बॉब> >>          # विषय के रूप में उद्धृत ट्रिपल
P: <believedTrueFrom>
O: ?                                    # तिथि लौटाता है
```

**उन तथ्यों का पता लगाएं जिन्हें गलत माना गया था:**
```
S: ?                                    # कोई भी उद्धृत ट्रिपल
P: <discoveredFalseOn>
O: ?                                    # कोई भी मान (अस्तित्व)
```

#### उत्पत्ति क्वेरी

**किसी विशिष्ट स्रोत द्वारा समर्थित सभी तथ्यों का पता लगाएं:**
```
S: ?                                    # कोई भी उद्धृत ट्रिपल
P: <supportedBy>
O: <source:document-123>
```

**पता करें कि कौन से स्रोत किसी विशिष्ट तथ्य का समर्थन करते हैं:**
```
S: << <ड्रगए> <उपचार करता है> <बीमारीबी> >>    # विषय के रूप में उद्धृत ट्रिपल
P: <supportedBy>
O: ?                                    # स्रोत IRI लौटाता है
```

#### सत्यता क्वेरी

**उन दावों का पता लगाएं जिन्हें किसी व्यक्ति ने सत्य के रूप में चिह्नित किया था:**
```
S: ?                                    # कोई भी उद्धृत ट्रिपल
P: <assertedTrueBy>
O: <person:Alice>
```

**विरोधाभासी दावों का पता लगाएं (एक ही तथ्य, अलग-अलग सत्यता):**
```
# पहली क्वेरी: सत्य माने गए तथ्य
S: ?
P: <assertedTrueBy>
O: ?

# दूसरी क्वेरी: झूठे माने गए तथ्य
S: ?
P: <assertedFalseBy>
O: ?

# एप्लिकेशन तर्क: विषयों के चौराहे का पता लगाएं
```

**उस विश्वास स्कोर का पता लगाएं जो थ्रेसहोल्ड से नीचे है:**
```
S: ?                                    # कोई भी उद्धृत ट्रिपल
P: <trustScore>
O: < 0.5                                # संख्यात्मक तुलना
```

### आर्किटेक्चर

कई घटकों में महत्वपूर्ण परिवर्तन आवश्यक हैं:

#### यह भंडार (trustgraph)

- **स्कीमा प्रिमिटिव** (`trustgraph-base/trustgraph/schema/core/primitives.py`)
  - वैल्यू → टर्म का नाम बदलें
  - नए टर्म संरचना में प्रकार विभेदक
  - ग्राफ संदर्भ के लिए ट्रिपल में `g`
- **नाम बदलें**: `Value` क्लास का नाम बदलकर `Term` कर दिया जाएगा। यह
  ~78 फ़ाइलों को कोडबेस में प्रभावित करता है। नामकरण एक मजबूर करने वाला कारक के रूप में कार्य करता है:
  `Value` का उपयोग करने वाला कोई भी कोड तुरंत पहचानने योग्य है और इसे 2.0
  संगतता के लिए समीक्षा/अपडेट करने की आवश्यकता है।

सुरक्षा विचार
नामित ग्राफ एक सुरक्षा सुविधा नहीं हैं। उपयोगकर्ता और संग्रह सुरक्षा सीमाएँ हैं।
नामित ग्राफ डेटा संगठन और पुन:पुनर्बलन समर्थन के लिए पूरी तरह से हैं।

प्रदर्शन विचार
- उद्धृत ट्रिपल नेस्टिंग गहराई जोड़ते हैं - यह क्वेरी प्रदर्शन को प्रभावित कर सकता है
- कुशल ग्राफ-स्कोप वाली क्वेरी के लिए नामित ग्राफ इंडेक्सिंग रणनीतियाँ आवश्यक हैं
- क्वाड स्टोरेज को कुशलतापूर्वक समायोजित करने के लिए Cassandra स्कीमा डिज़ाइन
  आवश्यक होगा।

वेक्टर स्टोर सीमा
वेक्टर स्टोर हमेशा केवल IRIs को संदर्भित करते हैं:
- कभी भी किनारे (उद्धृत ट्रिपल)
- कभी भी शाब्दिक मान
- कभी भी रिक्त नोड
यह वेक्टर स्टोर को सरल रखता है - यह नामित संस्थाओं की सिमेंटिक समानता को संभालता है।
ग्राफ संरचना, पुन:पुनर्बलन और मेटाडेटा संबंध को संभालता है। उद्धृत ट्रिपल और
नामित ग्राफ वेक्टर संचालन को जटिल नहीं बनाते हैं।

परीक्षण रणनीति
मौजूदा परीक्षण रणनीति का उपयोग करें। चूंकि यह एक ब्रेकिंग रिलीज़ है, इसलिए नए
संरचनाओं का परीक्षण करने के लिए एंड-टू-एंड परीक्षण सूट पर ध्यान केंद्रित करें ताकि यह सत्यापित किया जा सके कि
वे सभी घटकों में सही ढंग से काम करते हैं।

प्रवासन योजना
- 2.0 एक ब्रेकिंग रिलीज़ है; कोई पिछड़ा संगतता की आवश्यकता नहीं है
- मौजूदा डेटा को नए स्कीमा में माइग्रेट करने की आवश्यकता हो सकती है (अंतिम डिज़ाइन के आधार पर TBD)
- मौजूदा ट्रिपल को बदलने के लिए माइग्रेशन टूल पर विचार करें

खुले प्रश्न
- **रिक्त नोड**: सीमित समर्थन की पुष्टि की गई है। एक स्कोलेम रणनीति पर निर्णय लेने
  हो सकता है (लोडिंग पर IRI उत्पन्न करें, या रिक्त नोड ID को संरक्षित करें)।
- **क्वेरी सिंटैक्स**: उद्धृत ट्रिपल को क्वेरी में निर्दिष्ट करने के लिए ठोस सिंटैक्स क्या है?
  क्वेरी API को परिभाषित करने की आवश्यकता है।
- ~~**विधेय शब्दावली**~~: हल किया गया। किसी भी वैध RDF विधेय की अनुमति है,
  जिसमें कस्टम उपयोगकर्ता-परिभाषित भी शामिल हैं। RDF वैधता के बारे में बहुत कम धारणाएं।
  रणनीति: जब तक बिल्कुल आवश्यक न हो, कुछ भी लॉक न करें।
- ~~**वेक्टर स्टोर प्रभाव**~~: हल किया गया। वेक्टर स्टोर हमेशा केवल IRIs को संदर्भित करते हैं
  - कभी भी किनारे, शाब्दिक, या रिक्त नोड। उद्धृत ट्रिपल और
  पुन:पुनर्बलन वेक्टर स्टोर को प्रभावित नहीं करते हैं।
- ~~**नामित ग्राफ अर्थशास्त्र**~~: हल किया गया। क्वेरी डिफ़ॉल्ट में डिफ़ॉल्ट ग्राफ
  (पिछड़ी संगत SPARQL व्यवहार)। नामित ग्राफ या सभी ग्राफों को क्वेरी करने के लिए
  एक स्पष्ट ग्राफ पैरामीटर की आवश्यकता होती है।

संदर्भ
- [RDF 1.2 अवधारणाएँ](https://www.w3.org/TR/rdf12-concepts/)
- [RDF-स्टार और SPARQL-स्टार](https://w3c.github.io/rdf-star/)
- [RDF डेटासेट](https://www.w3.org/TR/rdf11-concepts/#section-dataset)