Structure the tech specs directory (#836)

Tech spec some subdirectories for different languages

docs/tech-specs/hi/structured-diag-service.hi.md

@@ -0,0 +1,281 @@
+---
+layout: default
+title: "स्ट्रक्चर्ड डेटा डायग्नोस्टिक सर्विस टेक्निकल स्पेसिफिकेशन"
+parent: "Hindi (Beta)"
+---
+
+# स्ट्रक्चर्ड डेटा डायग्नोस्टिक सर्विस टेक्निकल स्पेसिफिकेशन
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## अवलोकन
+
+यह स्पेसिफिकेशन ट्रस्टग्राफ के भीतर संरचित डेटा का निदान और विश्लेषण करने के लिए एक नए इनवोकेबल सर्विस का वर्णन करता है। यह सर्विस मौजूदा `tg-load-structured-data` कमांड-लाइन टूल से कार्यक्षमता निकालती है और इसे एक अनुरोध/प्रतिक्रिया सेवा के रूप में प्रस्तुत करती है, जिससे डेटा प्रकार का पता लगाने और विवरण पीढ़ी क्षमताओं तक प्रोग्रामेटिक पहुंच सक्षम होती है।
+
+यह सेवा तीन प्राथमिक कार्यों का समर्थन करती है:
+
+1. **डेटा टाइप डिटेक्शन**: यह निर्धारित करने के लिए कि इसका प्रारूप क्या है (CSV, JSON, या XML), एक डेटा नमूने का विश्लेषण करें।
+2. **डिस्क्रिप्टर जेनरेशन**: दिए गए डेटा नमूने और प्रकार के लिए एक ट्रस्टग्राफ संरचित डेटा विवरण उत्पन्न करें।
+3. **संयुक्त निदान**: अनुक्रम में डेटा प्रकार का पता लगाने और विवरण पीढ़ी दोनों करें।
+
+## लक्ष्य
+
+**डेटा विश्लेषण का मॉड्यूलरकरण**: CLI से डेटा निदान तर्क को पुन: प्रयोज्य सेवा घटकों में निकालें।
+**प्रोग्रामेटिक एक्सेस सक्षम करें**: डेटा विश्लेषण क्षमताओं तक API-आधारित पहुंच प्रदान करें।
+**एकाधिक डेटा प्रारूपों का समर्थन करें**: CSV, JSON और XML डेटा प्रारूपों को लगातार संभालें।
+**सटीक विवरण उत्पन्न करें**: संरचित डेटा विवरण उत्पन्न करें जो स्रोत डेटा को ट्रस्टग्राफ स्कीमा से सटीक रूप से मैप करते हैं।
+**पिछला संगतता बनाए रखें**: सुनिश्चित करें कि मौजूदा CLI कार्यक्षमता जारी रहती है।
+**सेवा रचना को सक्षम करें**: अन्य सेवाओं को डेटा निदान क्षमताओं का लाभ उठाने दें।
+**परीक्षण क्षमता में सुधार करें**: बेहतर परीक्षण के लिए CLI इंटरफ़ेस से व्यावसायिक तर्क को अलग करें।
+**स्ट्रीमिंग विश्लेषण का समर्थन करें**: संपूर्ण फ़ाइलों को लोड किए बिना डेटा नमूनों का विश्लेषण सक्षम करें।
+
+## पृष्ठभूमि
+
+वर्तमान में, `tg-load-structured-data` कमांड संरचित डेटा का विश्लेषण करने और विवरण उत्पन्न करने के लिए व्यापक कार्यक्षमता प्रदान करता है। हालाँकि, यह कार्यक्षमता CLI इंटरफ़ेस से दृढ़ता से जुड़ी हुई है, जो इसकी पुन: प्रयोज्यता को सीमित करती है।
+
+वर्तमान सीमाएँ शामिल हैं:
+CLI कोड में एम्बेडेड डेटा निदान तर्क।
+डेटा प्रकार का पता लगाने और विवरण पीढ़ी तक कोई प्रोग्रामेटिक पहुंच नहीं।
+अन्य सेवाओं में निदान क्षमताओं को एकीकृत करना मुश्किल है।
+डेटा विश्लेषण वर्कफ़्लो को संयोजित करने की सीमित क्षमता।
+
+यह स्पेसिफिकेशन इन कमियों को एक समर्पित संरचित डेटा निदान सेवा बनाकर संबोधित करता है। इन क्षमताओं को एक सेवा के रूप में उजागर करके, ट्रस्टग्राफ:
+अन्य सेवाओं को डेटा का प्रोग्रामेटिक रूप से विश्लेषण करने में सक्षम बनाता है।
+अधिक जटिल डेटा प्रसंस्करण पाइपलाइन का समर्थन करता है।
+बाहरी प्रणालियों के साथ एकीकरण को सुविधाजनक बनाता है।
+चिंताओं के अलगाव के माध्यम से रखरखाव में सुधार करता है।
+
+## तकनीकी डिजाइन
+
+### आर्किटेक्चर
+
+संरचित डेटा निदान सेवा के लिए निम्नलिखित तकनीकी घटकों की आवश्यकता होती है:
+
+1. **डायग्नोस्टिक सर्विस प्रोसेसर**
+   आने वाले निदान अनुरोधों को संभालता है।
+   डेटा प्रकार का पता लगाने और विवरण पीढ़ी का समन्वय करता है।
+   निदान परिणामों के साथ संरचित प्रतिक्रियाएँ लौटाता है।
+
+   मॉड्यूल: `trustgraph-flow/trustgraph/diagnosis/structured_data/service.py`
+
+2. **डेटा टाइप डिटेक्टर**
+   डेटा प्रारूप (CSV, JSON, XML) की पहचान करने के लिए एल्गोरिथम का उपयोग करता है।
+   पता लगाए गए प्रारूप और आत्मविश्वास स्कोर लौटाता है।
+   पता लगाए गए प्रारूप और आत्मविश्वास स्कोर वापस करता है।
+
+   मॉड्यूल: `trustgraph-flow/trustgraph/diagnosis/structured_data/type_detector.py`
+
+3. **डिस्क्रिप्टर जेनरेटर**
+   विवरण उत्पन्न करने के लिए प्रॉम्प्ट सेवा का उपयोग करता है।
+   प्रारूप-विशिष्ट प्रॉम्प्ट (diagnose-csv, diagnose-json, diagnose-xml) को लागू करता है।
+   डेटा फ़ील्ड को प्रॉम्प्ट प्रतिक्रियाओं के माध्यम से ट्रस्टग्राफ स्कीमा फ़ील्ड में मैप करता है।
+
+   मॉड्यूल: `trustgraph-flow/trustgraph/diagnosis/structured_data/descriptor_generator.py`
+
+### डेटा मॉडल
+
+#### StructuredDataDiagnosisRequest
+
+संरचित डेटा निदान कार्यों के लिए अनुरोध संदेश:
+
+```python
+class StructuredDataDiagnosisRequest:
+    operation: str  # "detect-type", "generate-descriptor", or "diagnose"
+    sample: str     # Data sample to analyze (text content)
+    type: Optional[str]  # Data type (csv, json, xml) - required for generate-descriptor
+    schema_name: Optional[str]  # Target schema name for descriptor generation
+    options: Dict[str, Any]  # Additional options (e.g., delimiter for CSV)
+```
+
+#### संरचित डेटा निदान प्रतिक्रिया
+
+निदान परिणामों को शामिल करने वाला प्रतिक्रिया संदेश:
+
+```python
+class StructuredDataDiagnosisResponse:
+    operation: str  # The operation that was performed
+    detected_type: Optional[str]  # Detected data type (for detect-type/diagnose)
+    confidence: Optional[float]  # Confidence score for type detection
+    descriptor: Optional[Dict]  # Generated descriptor (for generate-descriptor/diagnose)
+    error: Optional[str]  # Error message if operation failed
+    metadata: Dict[str, Any]  # Additional metadata (e.g., field count, sample records)
+```
+
+#### विवरण संरचना
+
+उत्पन्न विवरण मौजूदा संरचित डेटा विवरण प्रारूप का पालन करता है:
+
+```json
+{
+  "format": {
+    "type": "csv",
+    "encoding": "utf-8",
+    "options": {
+      "delimiter": ",",
+      "has_header": true
+    }
+  },
+  "mappings": [
+    {
+      "source_field": "customer_id",
+      "target_field": "id",
+      "transforms": [
+        {"type": "trim"}
+      ]
+    }
+  ],
+  "output": {
+    "schema_name": "customer",
+    "options": {
+      "batch_size": 1000,
+      "confidence": 0.9
+    }
+  }
+}
+```
+
+### सेवा इंटरफ़ेस
+
+यह सेवा अनुरोध/प्रतिक्रिया पैटर्न के माध्यम से निम्नलिखित कार्यों को प्रदान करेगी:
+
+1. **टाइप डिटेक्शन ऑपरेशन**
+   इनपुट: डेटा नमूना
+   प्रसंस्करण: एल्गोरिथम डिटेक्शन का उपयोग करके डेटा संरचना का विश्लेषण करें
+   आउटपुट: पता लगाए गए प्रकार के साथ आत्मविश्वास स्कोर
+
+2. **डिस्क्रिप्टर जनरेशन ऑपरेशन**
+   इनपुट: डेटा नमूना, प्रकार, लक्षित स्कीमा नाम
+   प्रसंस्करण:
+     प्रारूप-विशिष्ट प्रॉम्प्ट आईडी (diagnose-csv, diagnose-json, या diagnose-xml) के साथ प्रॉम्प्ट सेवा को कॉल करें
+     डेटा नमूना और उपलब्ध स्कीमा को प्रॉम्प्ट में पास करें
+     प्रॉम्प्ट प्रतिक्रिया से उत्पन्न डिस्क्रिप्टर प्राप्त करें
+   आउटपुट: संरचित डेटा डिस्क्रिप्टर
+
+3. **संयुक्त निदान ऑपरेशन**
+   इनपुट: डेटा नमूना, वैकल्पिक स्कीमा नाम
+   प्रसंस्करण:
+     पहले एल्गोरिथम डिटेक्शन का उपयोग करके प्रारूप की पहचान करें
+     पता लगाए गए प्रकार के आधार पर उपयुक्त प्रारूप-विशिष्ट प्रॉम्प्ट का चयन करें
+     डिस्क्रिप्टर उत्पन्न करने के लिए प्रॉम्प्ट सेवा को कॉल करें
+   आउटपुट: पता लगाए गए प्रकार और डिस्क्रिप्टर दोनों
+
+### कार्यान्वयन विवरण
+
+यह सेवा TrustGraph सेवा सम्मेलनों का पालन करेगी:
+
+1. **सेवा पंजीकरण**
+   `structured-diag` सेवा प्रकार के रूप में पंजीकृत करें
+   मानक अनुरोध/प्रतिक्रिया विषयों का उपयोग करें
+   FlowProcessor बेस क्लास को लागू करें
+   प्रॉम्प्ट सेवा के साथ इंटरैक्शन के लिए PromptClientSpec को पंजीकृत करें
+
+2. **कॉन्फ़िगरेशन प्रबंधन**
+   कॉन्फ़िग सेवा के माध्यम से स्कीमा कॉन्फ़िगरेशन तक पहुंचें
+   प्रदर्शन के लिए स्कीमा को कैश करें
+   गतिशील रूप से कॉन्फ़िगरेशन अपडेट को संभालें
+
+3. **प्रॉम्प्ट एकीकरण**
+   मौजूदा प्रॉम्प्ट सेवा बुनियादी ढांचे का उपयोग करें
+   प्रारूप-विशिष्ट प्रॉम्प्ट आईडी के साथ प्रॉम्प्ट सेवा को कॉल करें:
+     `diagnose-csv`: CSV डेटा विश्लेषण के लिए
+     `diagnose-json`: JSON डेटा विश्लेषण के लिए
+     `diagnose-xml`: XML डेटा विश्लेषण के लिए
+   प्रॉम्प्ट सेवा में कॉन्फ़िगर किए गए हैं, सेवा में हार्ड-कोडेड नहीं हैं
+   स्कीमा और डेटा नमूने को प्रॉम्प्ट चर के रूप में पास करें
+   डिस्क्रिप्टर निकालने के लिए प्रॉम्प्ट प्रतिक्रियाओं को पार्स करें
+
+4. **त्रुटि प्रबंधन**
+   इनपुट डेटा नमूनों को मान्य करें
+   वर्णनात्मक त्रुटि संदेश प्रदान करें
+   खराब डेटा को शालीनता से संभालें
+   प्रॉम्प्ट सेवा विफलताओं को संभालें
+
+5. **डेटा नमूनाकरण**
+   कॉन्फ़िगर करने योग्य नमूना आकारों को संसाधित करें
+   अधूरी रिकॉर्ड को उचित रूप से संभालें
+   नमूनाकरण स्थिरता बनाए रखें
+
+### एपीआई एकीकरण
+
+यह सेवा मौजूदा TrustGraph एपीआई के साथ एकीकृत होगी:
+
+संशोधित घटक:
+`tg-load-structured-data` CLI - निदान कार्यों के लिए नई सेवा का उपयोग करने के लिए रिफैक्टर किया गया
+फ्लो एपीआई - संरचित डेटा निदान अनुरोधों का समर्थन करने के लिए विस्तारित
+
+नए सेवा एंडपॉइंट:
+`/api/v1/flow/{flow}/diagnose/structured-data` - निदान अनुरोधों के लिए वेबसॉकेट एंडपॉइंट
+`/api/v1/diagnose/structured-data` - सिंक्रोनस निदान के लिए REST एंडपॉइंट
+
+### संदेश प्रवाह
+
+```
+Client → Gateway → Structured Diag Service → Config Service (for schemas)
+                                           ↓
+                                    Type Detector (algorithmic)
+                                           ↓
+                                    Prompt Service (diagnose-csv/json/xml)
+                                           ↓
+                                 Descriptor Generator (parses prompt response)
+                                           ↓
+Client ← Gateway ← Structured Diag Service (response)
+```
+
+## सुरक्षा संबंधी विचार
+
+इंजेक्शन हमलों को रोकने के लिए इनपुट सत्यापन
+DoS को रोकने के लिए डेटा नमूनों पर आकार सीमाएं
+उत्पन्न विवरणों का सैनिटाइजेशन
+मौजूदा ट्रस्टग्राफ प्रमाणीकरण के माध्यम से एक्सेस नियंत्रण
+
+## प्रदर्शन संबंधी विचार
+
+कॉन्फ़िगरेशन सेवा कॉल को कम करने के लिए स्कीमा परिभाषाओं को कैश करें
+उत्तरदायी प्रदर्शन बनाए रखने के लिए नमूना आकारों को सीमित करें
+बड़े डेटा नमूनों के लिए स्ट्रीमिंग प्रोसेसिंग का उपयोग करें
+लंबे समय तक चलने वाले विश्लेषणों के लिए टाइमआउट तंत्र लागू करें
+
+## परीक्षण रणनीति
+
+1. **इकाई परीक्षण**
+   विभिन्न डेटा प्रारूपों के लिए प्रकार का पता लगाना
+   विवरण पीढ़ी की सटीकता
+   त्रुटि हैंडलिंग परिदृश्य
+
+2. **एकीकरण परीक्षण**
+   सेवा अनुरोध/प्रतिक्रिया प्रवाह
+   स्कीमा पुनर्प्राप्ति और कैशिंग
+   CLI एकीकरण
+
+3. **प्रदर्शन परीक्षण**
+   बड़े नमूने प्रसंस्करण
+   समवर्ती अनुरोध हैंडलिंग
+   लोड के तहत मेमोरी उपयोग
+
+## माइग्रेशन योजना
+
+1. **चरण 1**: मुख्य कार्यक्षमता के साथ सेवा लागू करें
+2. **चरण 2**: CLI को सेवा का उपयोग करने के लिए रिफैक्टर करें (पिछड़ी संगतता बनाए रखें)
+3. **चरण 3**: REST API एंडपॉइंट जोड़ें
+4. **चरण 4**: एम्बेडेड CLI लॉजिक को अप्रचलित करें (सूचना अवधि के साथ)
+
+## समयरेखा
+
+सप्ताह 1-2: मुख्य सेवा और प्रकार का पता लगाना लागू करें
+सप्ताह 3-4: विवरण पीढ़ी और एकीकरण जोड़ें
+सप्ताह 5: परीक्षण और दस्तावेज़ीकरण
+सप्ताह 6: CLI रिफैक्टरिंग और माइग्रेशन
+
+## खुले प्रश्न
+
+क्या सेवा को अतिरिक्त डेटा प्रारूपों (जैसे, Parquet, Avro) का समर्थन करना चाहिए?
+विश्लेषण के लिए अधिकतम नमूना आकार क्या होना चाहिए?
+क्या निदान परिणाम बार-बार अनुरोधों के लिए कैश किए जाने चाहिए?
+सेवा को मल्टी-स्कीमा परिदृश्यों को कैसे संभालना चाहिए?
+क्या प्रॉम्प्ट आईडी सेवा के लिए कॉन्फ़िगर करने योग्य पैरामीटर होने चाहिए?
+
+## संदर्भ
+
+[स्ट्रक्चर्ड डेटा डिस्क्रिप्टर विनिर्देश](structured-data-descriptor.md)
+[स्ट्रक्चर्ड डेटा लोडिंग दस्तावेज़](structured-data.md)
+`tg-load-structured-data` कार्यान्वयन: `trustgraph-cli/trustgraph/cli/load_structured_data.py`