नोटबुक टूल रनटाइम आंतरिक संरचना

यह दस्तावेज़ वर्तमान notebook टूल के कार्यान्वयन और कर्नेल-समर्थित Python रनटाइम के साथ उसके संबंध का वर्णन करता है।

महत्वपूर्ण अंतर: notebook एक JSON नोटबुक संपादक है, न कि नोटबुक एक्जीक्यूटर। यह .ipynb सेल सोर्स को सीधे संपादित करता है; यह Python कर्नेल को प्रारंभ नहीं करता और न ही उससे संवाद करता है।

कार्यान्वयन फ़ाइलें

• src/tools/notebook.ts
• src/ipy/executor.ts
• src/ipy/kernel.ts
• src/session/streaming-output.ts
• src/tools/python.ts

1) रनटाइम सीमा: संपादन बनाम एक्जीक्यूशन

notebook टूल (src/tools/notebook.ts)

• .ipynb फ़ाइल पर action: edit | insert | delete का समर्थन करता है।
• सेशन CWD के सापेक्ष पथ को रिज़ॉल्व करता है (resolveToCwd)।
• नोटबुक JSON लोड करता है, cells एरे को मान्य करता है, cell_index सीमाओं को मान्य करता है।
• मेमोरी में सोर्स एडिट्स लागू करता है और JSON.stringify(notebook, null, 1) के साथ पूरा नोटबुक JSON वापस लिखता है।
• पाठ्य सारांश + संरचित details (action, cellIndex, cellType, totalCells, cellSource) लौटाता है।

इस टूल में कोई कर्नेल लाइफसाइकल मौजूद नहीं है:

• कोई गेटवे अधिग्रहण नहीं
• कोई कर्नेल सेशन ID नहीं
• कोई execute_request नहीं
• कर्नेल चैनलों से कोई स्ट्रीम चंक्स नहीं
• कोई रिच डिस्प्ले कैप्चर नहीं (image/png, JSON display, status MIME)

नोटबुक-जैसा एक्जीक्यूशन पथ (src/tools/python.ts + src/ipy/*)

जब एजेंट को सेल-स्टाइल Python कोड चलाने की आवश्यकता होती है (अनुक्रमिक सेल, स्थायी अवस्था, रिच डिस्प्ले), तो वह python टूल के माध्यम से जाता है, न कि notebook के।

वह पथ वहाँ है जहाँ कर्नेल मोड्स, restart/cancel व्यवहार, चंक स्ट्रीमिंग और आउटपुट आर्टिफैक्ट ट्रंकेशन रहते हैं।

2) नोटबुक सेल हैंडलिंग सेमेंटिक्स (notebook टूल)

सोर्स नॉर्मलाइज़ेशन

content को न्यूलाइन संरक्षण के साथ source: string[] में विभाजित किया जाता है:

• प्रत्येक गैर-अंतिम पंक्ति अनुगामी \n रखती है
• अंतिम पंक्ति में कोई जबरन अनुगामी न्यूलाइन नहीं होती

यह नोटबुक JSON परंपराओं को प्रतिबिंबित करता है और बाद के संपादनों पर अनपेक्षित पंक्ति संयोजन से बचाता है।

एक्शन व्यवहार

• edit
  • cells[cell_index].source को बदलता है
  • मौजूदा cell_type को संरक्षित रखता है
• insert
  • [0..cellCount] पर सम्मिलित करता है
  • cell_type डिफ़ॉल्ट रूप से code होता है
  • कोड सेल execution_count: null और outputs: [] के साथ आरंभ होते हैं
  • मार्कडाउन सेल केवल metadata + source के साथ आरंभ होते हैं
• delete
  • cells[cell_index] को हटाता है
  • रेंडरर पूर्वावलोकन के लिए details में हटाए गए source को लौटाता है

त्रुटि सतहें

निम्नलिखित के लिए हार्ड विफलताएँ थ्रो की जाती हैं:

• नोटबुक फ़ाइल अनुपस्थित होने पर
• अमान्य JSON
• अनुपस्थित/गैर-एरे cells
• रेंज से बाहर का इंडेक्स (insert और non-insert के लिए अलग-अलग वैध रेंज होते हैं)
• edit/insert के लिए content अनुपस्थित होने पर

ये अपस्ट्रीम Error: टूल प्रतिक्रियाएँ बनती हैं; रेंडरर नोटबुक पथ + स्वरूपित त्रुटि पाठ का उपयोग करता है।

3) कर्नेल सेशन सेमेंटिक्स (जहाँ वे वास्तव में मौजूद हैं)

कर्नेल सेमेंटिक्स executePython / PythonKernel में कार्यान्वित हैं और python टूल पर लागू होते हैं।

मोड्स

PythonKernelMode:

• session (डिफ़ॉल्ट)
  • कर्नेल kernelSessions मैप में कैश्ड होते हैं
  • अधिकतम 4 सेशन; ओवरफ्लो पर सबसे पुराना बाहर निकाला जाता है
  • हर 30 सेकंड में idle/dead क्लीनअप, 5 मिनट बाद टाइमआउट
  • प्रति-सेशन क्यू एक्जीक्यूशन को सीरियलाइज़ करता है (session.queue)
• per-call
  • अनुरोध के लिए कर्नेल बनाता है
  • एक्जीक्यूट करता है
  • finally में हमेशा कर्नेल बंद करता है

रीसेट व्यवहार

python टूल केवल मल्टी-सेल कॉल की पहली सेल के लिए reset पास करता है; बाद की सेल हमेशा reset: false के साथ चलती हैं।

कर्नेल की मृत्यु / रीस्टार्ट / रिट्री

सेशन मोड में (withKernelSession):

• मृत कर्नेल का पता हार्टबीट (kernel.isAlive() हर 5 सेकंड में जाँच) या एक्जीक्यूट विफलता से चलता है।
• पूर्व-रन मृत अवस्था restartKernelSession को ट्रिगर करती है।
• एक्जीक्यूट-टाइम क्रैश पथ एक बार पुनः प्रयास करता है: कर्नेल रीस्टार्ट करता है, हैंडलर पुनः चलाता है।
• उसी सेशन में restartCount > 1 से Python kernel restarted too many times in this session थ्रो होता है।

स्टार्टअप रिट्री व्यवहार:

• शेयर्ड गेटवे कर्नेल निर्माण HTTP 5xx के साथ SharedGatewayCreateError पर एक बार पुनः प्रयास करता है।

संसाधन समाप्ति पुनर्प्राप्ति:

• EMFILE/ENFILE/“Too many open files” शैली की विफलताओं का पता लगाता है
• ट्रैक किए गए सेशन साफ़ करता है
• shutdownSharedGateway() को कॉल करता है
• कर्नेल सेशन निर्माण एक बार पुनः प्रयास करता है

4) एनवायरनमेंट/सेशन वेरिएबल इंजेक्शन

कर्नेल स्टार्टअप को executor से वैकल्पिक env मैप मिलता है:

• PI_SESSION_FILE (सेशन स्टेट फ़ाइल पथ)
• ARTIFACTS (आर्टिफैक्ट डायरेक्टरी)

PythonKernel.#initializeKernelEnvironment(...) फिर कर्नेल के अंदर init स्क्रिप्ट चलाता है:

• os.chdir(cwd)
• os.environ में env एंट्रियाँ इंजेक्ट करता है
• अनुपस्थित होने पर cwd को sys.path के आगे जोड़ता है

निहितार्थ:

• प्रस्तावना हेल्पर जो सेशन या आर्टिफैक्ट संदर्भ पढ़ते हैं, वे Python प्रोसेस स्टेट में इन env vars पर निर्भर करते हैं।

5) स्ट्रीमिंग/चंक और डिस्प्ले हैंडलिंग (कर्नेल-समर्थित पथ)

कर्नेल क्लाइंट प्रत्येक एक्जीक्यूशन के लिए Jupyter प्रोटोकॉल संदेशों को प्रोसेस करता है:

• stream -> onChunk को टेक्स्ट चंक
• execute_result / display_data ->
  • MIME प्राथमिकता द्वारा चुना गया डिस्प्ले टेक्स्ट: text/markdown > text/plain > रूपांतरित text/html
  • संरचित आउटपुट अलग से कैप्चर किए जाते हैं:
    • application/json -> { type: "json" }
    • image/png -> { type: "image" }
    • application/x-xcsh-status -> { type: "status" } (कोई टेक्स्ट उत्सर्जन नहीं)
• error -> ट्रेसबैक टेक्स्ट चंक स्ट्रीम में पुश + संरचित त्रुटि मेटाडेटा
• input_request -> stdin चेतावनी टेक्स्ट उत्सर्जित करता है, खाली input_reply भेजता है, stdin अनुरोधित चिह्नित करता है
• पूर्णता execute_reply और कर्नेल status=idle दोनों की प्रतीक्षा करती है

रद्दीकरण/टाइमआउट:

• abort सिग्नल interrupt() को ट्रिगर करता है (REST /interrupt + control-channel interrupt_request)
• परिणाम cancelled=true चिह्नित करता है
• टाइमआउट पथ आउटपुट को Command timed out after <n> seconds के साथ एनोटेट करता है

6) ट्रंकेशन और आर्टिफैक्ट व्यवहार

src/session/streaming-output.ts में OutputSink का उपयोग कर्नेल एक्जीक्यूशन पथों (executeWithKernel) द्वारा किया जाता है:

• प्रत्येक चंक को सैनिटाइज़ करता है (sanitizeText)
• कुल/आउटपुट पंक्तियाँ और बाइट्स ट्रैक करता है
• वैकल्पिक आर्टिफैक्ट स्पिल फ़ाइल (artifactPath, artifactId)
• जब इन-मेमोरी बफर सीमा से अधिक हो जाता है (DEFAULT_MAX_BYTES जब तक ओवरराइड न हो):
  • ट्रंकेटेड चिह्नित करता है
  • मेमोरी में टेल बाइट्स रखता है (UTF-8 सुरक्षित सीमा)
  • आर्टिफैक्ट सिंक में पूरी स्ट्रीम स्पिल कर सकता है

dump() लौटाता है:

• दृश्यमान आउटपुट टेक्स्ट (संभवतः टेल-ट्रंकेटेड)
• ट्रंकेशन फ्लैग + काउंट
• आर्टिफैक्ट ID (artifact://<id> संदर्भों के लिए)

python टूल इस मेटाडेटा को परिणाम ट्रंकेशन सूचनाओं और TUI चेतावनियों में परिवर्तित करता है।

notebook टूल OutputSink का उपयोग नहीं करता; इसमें कोई स्ट्रीम/आर्टिफैक्ट ट्रंकेशन पाइपलाइन नहीं है क्योंकि यह कोड एक्जीक्यूट नहीं करता।

7) रेंडरर अनुमान और स्वरूपण

नोटबुक रेंडरर (notebookToolRenderer)

• कॉल व्यू: action + नोटबुक पथ + cell/type मेटाडेटा के साथ स्टेटस लाइन
• परिणाम व्यू:
  • details से प्राप्त सफलता सारांश
  • cellSource को renderCodeCell के माध्यम से रेंडर किया गया
  • मार्कडाउन सेल markdown लैंग्वेज हिंट सेट करते हैं; अन्य सेल में कोई स्पष्ट लैंग्वेज ओवरराइड नहीं
  • संक्षिप्त कोड पूर्वावलोकन सीमा PREVIEW_LIMITS.COLLAPSED_LINES * 2 है
  • शेयर्ड रेंडर विकल्पों के माध्यम से विस्तारित मोड का समर्थन करता है
  • width + expanded state द्वारा कीड रेंडर कैश का उपयोग करता है

त्रुटि रेंडरिंग अनुमान:

• यदि पहली टेक्स्ट सामग्री Error: से शुरू होती है, तो रेंडरर नोटबुक त्रुटि ब्लॉक के रूप में स्वरूपित करता है।

Python रेंडरर (वास्तविक एक्जीक्यूशन आउटपुट के लिए)

कर्नेल-समर्थित एक्जीक्यूशन रेंडरिंग की अपेक्षाएँ:

• प्रति-सेल स्टेटस ट्रांजिशन (pending/running/complete/error)
• वैकल्पिक संरचित स्टेटस इवेंट अनुभाग
• वैकल्पिक JSON आउटपुट ट्री
• ट्रंकेशन चेतावनियाँ + वैकल्पिक artifact://<id> पॉइंटर

यह रेंडरर व्यवहार notebook JSON संपादन परिणामों से असंबंधित है, सिवाय इसके कि दोनों शेयर्ड TUI प्रिमिटिव का पुनः उपयोग करते हैं।

8) सादे Python टूल व्यवहार से विचलन

यदि “सादे Python टूल” का अर्थ python एक्जीक्यूशन पथ है:

• python कर्नेल में कोड एक्जीक्यूट करता है, मोड द्वारा स्टेट बनाए रखता है, चंक स्ट्रीम करता है, रिच डिस्प्ले कैप्चर करता है, interrupt/timeout संभालता है, और आउटपुट ट्रंकेशन/आर्टिफैक्ट का समर्थन करता है।
• notebook केवल निर्धारित नोटबुक JSON म्यूटेशन करता है; कोई एक्जीक्यूशन नहीं, कोई कर्नेल स्टेट नहीं, कोई चंक स्ट्रीम नहीं, कोई डिस्प्ले आउटपुट नहीं, कोई आर्टिफैक्ट पाइपलाइन नहीं।

यदि किसी वर्कफ़्लो को दोनों की आवश्यकता है:

1. notebook के साथ नोटबुक सोर्स संपादित करें
2. कोड सेल को python के माध्यम से एक्जीक्यूट करें (कोड को मैन्युअल रूप से पास करके), notebook के माध्यम से नहीं

वर्तमान कार्यान्वयन एक एकल टूल प्रदान नहीं करता जो .ipynb को म्यूटेट करे और कर्नेल संदर्भ के माध्यम से नोटबुक सेल एक्जीक्यूट भी करे।