Python उपकरण और IPython रनटाइम

यह दस्तावेज़ packages/coding-agent में वर्तमान Python निष्पादन स्टैक का वर्णन करता है। इसमें उपकरण व्यवहार, कर्नेल/गेटवे लाइफ़साइकिल, एनवायरनमेंट हैंडलिंग, निष्पादन सेमेंटिक्स, आउटपुट रेंडरिंग और परिचालन विफलता मोड शामिल हैं।

दायरा और मुख्य फ़ाइलें

• उपकरण सतह: src/tools/python.ts
• सेशन/प्रति-कॉल कर्नेल ऑर्केस्ट्रेशन: src/ipy/executor.ts
• कर्नेल प्रोटोकॉल + गेटवे इंटीग्रेशन: src/ipy/kernel.ts
• साझा लोकल गेटवे समन्वयक: src/ipy/gateway-coordinator.ts
• उपयोगकर्ता-ट्रिगर Python रन के लिए इंटरएक्टिव-मोड रेंडरर: src/modes/components/python-execution.ts
• रनटाइम/एनव फ़िल्टरिंग और Python रेज़ोल्यूशन: src/ipy/runtime.ts

Python उपकरण क्या है

python उपकरण एक या अधिक Python सेल को Jupyter Kernel Gateway-समर्थित कर्नेल के माध्यम से निष्पादित करता है (प्रति सेल सीधे python -c स्पॉन करके नहीं)।

उपकरण पैरामीटर:

{
  cells: Array<{ code: string; title?: string }>;
  timeout?: number; // सेकंड, 1..600 तक क्लैंप, डिफ़ॉल्ट 30
  cwd?: string;
  reset?: boolean; // केवल पहले सेल से पहले कर्नेल रीसेट करें
}

उपकरण एक सेशन के लिए concurrency = "exclusive" है, इसलिए कॉल ओवरलैप नहीं होते।

गेटवे लाइफ़साइकिल

मोड

दो गेटवे पथ हैं:

1. बाहरी गेटवे (PI_PYTHON_GATEWAY_URL सेट होने पर)

   • कॉन्फ़िगर किए गए URL का सीधे उपयोग करता है।
   • PI_PYTHON_GATEWAY_TOKEN के साथ वैकल्पिक ऑथ।
   • कोई लोकल गेटवे प्रक्रिया स्पॉन या प्रबंधित नहीं की जाती।

2. लोकल साझा गेटवे (डिफ़ॉल्ट पथ)

   • ~/.xcsh/agent/python-gateway के अंतर्गत समन्वित एकल साझा प्रक्रिया का उपयोग करता है।
   • मेटाडेटा फ़ाइल: gateway.json
   • लॉक फ़ाइल: gateway.lock
   • स्पॉन कमांड:
     • python -m kernel_gateway
     • 127.0.0.1:<allocated-port> से बाइंड
     • स्टार्टअप हेल्थ चेक: GET /api/kernelspecs

लोकल साझा गेटवे समन्वय

acquireSharedGateway():

• हार्टबीट के साथ फ़ाइल लॉक (gateway.lock) लेता है।
• यदि PID जीवित है और हेल्थ चेक पास होता है तो gateway.json पुनः उपयोग करता है।
• आवश्यकता पड़ने पर पुरानी जानकारी/PID साफ़ करता है।
• जब कोई स्वस्थ गेटवे मौजूद नहीं होता तो नया गेटवे शुरू करता है।

releaseSharedGateway() वर्तमान में एक no-op है (कर्नेल शटडाउन साझा गेटवे को बंद नहीं करता)।

shutdownSharedGateway() साझा प्रक्रिया को स्पष्ट रूप से समाप्त करता है और गेटवे मेटाडेटा साफ़ करता है।

महत्वपूर्ण बाधा

python.sharedGateway=false को कर्नेल स्टार्ट पर अस्वीकार किया जाता है:

• त्रुटि: Shared Python gateway required; local gateways are disabled
• प्रति-प्रक्रिया गैर-साझा लोकल गेटवे मोड उपलब्ध नहीं है।

कर्नेल लाइफ़साइकिल

प्रत्येक निष्पादन चयनित गेटवे पर POST /api/kernels के माध्यम से बनाए गए कर्नेल का उपयोग करता है।

कर्नेल स्टार्टअप अनुक्रम:

1. उपलब्धता जाँच (checkPythonKernelAvailability)
2. कर्नेल बनाएँ (/api/kernels)
3. वेबसॉकेट खोलें (/api/kernels/:id/channels)
4. कर्नेल एनव आरंभ करें (cwd, एनव वेरिएबल, sys.path)
5. PYTHON_PRELUDE निष्पादित करें
6. एक्सटेंशन मॉड्यूल लोड करें:
   • उपयोगकर्ता: ~/.xcsh/agent/modules/*.py
   • प्रोजेक्ट: <cwd>/.xcsh/modules/*.py (समान-नाम उपयोगकर्ता मॉड्यूल को ओवरराइड करता है)

कर्नेल शटडाउन:

• DELETE /api/kernels/:id के माध्यम से रिमोट कर्नेल हटाता है
• वेबसॉकेट बंद करता है
• साझा गेटवे रिलीज़ हुक कॉल करता है (आज no-op)

सेशन पर्सिस्टेंस सेमेंटिक्स

python.kernelMode कर्नेल पुनः उपयोग को नियंत्रित करता है:

• session (डिफ़ॉल्ट)

  • सेशन आइडेंटिटी + cwd द्वारा कुंजीबद्ध कर्नेल सेशन पुनः उपयोग करता है।
  • निष्पादन एक क्यू के माध्यम से प्रति सेशन क्रमबद्ध है।
  • निष्क्रिय सेशन 5 मिनट बाद बाहर कर दिए जाते हैं।
  • अधिकतम 4 सेशन; ओवरफ़्लो पर सबसे पुराना बाहर किया जाता है।
  • हार्टबीट चेक मृत कर्नेल का पता लगाते हैं।
  • एक बार ऑटो-रीस्टार्ट की अनुमति; बार-बार क्रैश => कठोर विफलता।

• per-call

  • प्रत्येक निष्पादन अनुरोध के लिए एक नया कर्नेल बनाता है।
  • अनुरोध के बाद कर्नेल बंद करता है।
  • क्रॉस-कॉल स्टेट पर्सिस्टेंस नहीं।

एकल उपकरण कॉल में मल्टी-सेल व्यवहार

उस उपकरण कॉल के लिए सेल उसी कर्नेल इंस्टेंस में क्रमिक रूप से चलते हैं।

यदि कोई मध्यवर्ती सेल विफल होता है:

• पहले के सेल की स्थिति मेमोरी में बनी रहती है।
• उपकरण एक लक्षित त्रुटि लौटाता है जो बताती है कि कौन सा सेल विफल हुआ।
• बाद के सेल निष्पादित नहीं होते।

reset=true केवल उस कॉल में पहले सेल निष्पादन पर लागू होता है।

एनवायरनमेंट फ़िल्टरिंग और रनटाइम रेज़ोल्यूशन

गेटवे/कर्नेल रनटाइम लॉन्च करने से पहले एनवायरनमेंट फ़िल्टर किया जाता है:

• अनुमति सूची में PATH, HOME, लोकेल वेरिएबल, VIRTUAL_ENV, PYTHONPATH आदि जैसे मुख्य वेरिएबल शामिल हैं।
• अनुमति-उपसर्ग: LC_, XDG_, PI_
• अस्वीकृति सूची सामान्य API कुंजियाँ हटाती है (OpenAI/Anthropic/Gemini/आदि)

रनटाइम चयन क्रम:

1. सक्रिय/स्थित venv (VIRTUAL_ENV, फिर <cwd>/.venv, <cwd>/venv)
2. ~/.xcsh/python-env पर प्रबंधित venv
3. PATH पर python या python3

जब कोई venv चुना जाता है, तो उसका bin/Scripts पथ PATH में आगे जोड़ा जाता है।

Python के अंदर कर्नेल एनव आरंभीकरण भी:

• os.chdir(cwd)
• प्रदान किए गए एनव मैप को os.environ में इंजेक्ट करता है
• सुनिश्चित करता है कि cwd sys.path में है

उपकरण उपलब्धता और मोड चयन

python.toolMode (डिफ़ॉल्ट both) + वैकल्पिक PI_PY ओवरराइड एक्सपोज़र को नियंत्रित करता है:

• ipy-only
• bash-only
• both

PI_PY स्वीकृत मान:

• 0 / bash -> bash-only
• 1 / py -> ipy-only
• mix / both -> both

यदि Python प्रीफ़्लाइट विफल होता है, तो उस सेशन के लिए उपकरण निर्माण bash-only तक डिग्रेड हो जाता है।

निष्पादन प्रवाह और रद्दीकरण/टाइमआउट

उपकरण-स्तर टाइमआउट

python उपकरण टाइमआउट सेकंड में है, डिफ़ॉल्ट 30, 1..600 तक क्लैंप।

उपकरण इन्हें मिलाता है:

• कॉलर अबॉर्ट सिग्नल
• टाइमआउट अबॉर्ट सिग्नल

AbortSignal.any(...) के साथ।

कर्नेल निष्पादन रद्दीकरण

अबॉर्ट/टाइमआउट पर:

• निष्पादन रद्द के रूप में चिह्नित किया जाता है।
• REST (POST /interrupt) और कंट्रोल-चैनल interrupt_request के माध्यम से कर्नेल इंटरप्ट का प्रयास किया जाता है।
• परिणाम में cancelled=true शामिल है।
• टाइमआउट पथ आउटपुट को Command timed out after <n> seconds के रूप में एनोटेट करता है।

stdin व्यवहार

इंटरएक्टिव stdin समर्थित नहीं है।

यदि कर्नेल input_request उत्सर्जित करता है:

• उपकरण stdinRequested=true रिकॉर्ड करता है
• व्याख्यात्मक टेक्स्ट उत्सर्जित करता है
• खाली input_reply भेजता है
• निष्पादन को एग्ज़ीक्यूटर परत पर विफलता के रूप में माना जाता है

आउटपुट कैप्चर और रेंडरिंग

कैप्चर किए गए आउटपुट वर्ग

कर्नेल संदेशों से:

• stream -> सादा टेक्स्ट खंड
• display_data/execute_result -> रिच डिस्प्ले हैंडलिंग
• error -> ट्रेसबैक टेक्स्ट
• कस्टम MIME application/x-xcsh-status -> संरचित स्टेटस इवेंट

डिस्प्ले MIME प्राथमिकता:

1. text/markdown
2. text/plain
3. text/html (बेसिक मार्कडाउन में परिवर्तित)

इसके अतिरिक्त संरचित आउटपुट के रूप में कैप्चर किया गया:

• application/json -> JSON ट्री डेटा
• image/png -> छवि पेलोड
• application/x-xcsh-status -> स्टेटस इवेंट

स्टोरेज और ट्रंकेशन

आउटपुट OutputSink के माध्यम से स्ट्रीम किया जाता है और आर्टिफ़ैक्ट स्टोरेज में सहेजा जा सकता है।

उपकरण परिणामों में ट्रंकेशन मेटाडेटा और पूर्ण आउटपुट पुनर्प्राप्ति के लिए artifact://<id> शामिल हो सकता है।

रेंडरर व्यवहार

• उपकरण रेंडरर (python.ts):
  • प्रति-सेल स्टेटस के साथ कोड-सेल ब्लॉक दिखाता है
  • संक्षिप्त पूर्वावलोकन डिफ़ॉल्ट 10 पंक्तियाँ
  • पूर्ण आउटपुट और समृद्ध स्टेटस विवरण के लिए विस्तारित मोड का समर्थन करता है
• इंटरएक्टिव रेंडरर (python-execution.ts):
  • TUI में उपयोगकर्ता-ट्रिगर Python निष्पादन के लिए उपयोग किया जाता है
  • संक्षिप्त पूर्वावलोकन डिफ़ॉल्ट 20 पंक्तियाँ
  • डिस्प्ले सुरक्षा के लिए बहुत लंबी व्यक्तिगत पंक्तियों को 4000 वर्णों तक क्लैंप करता है
  • रद्दीकरण/त्रुटि/ट्रंकेशन नोटिस दिखाता है

बाहरी गेटवे समर्थन

सेट करें:

export PI_PYTHON_GATEWAY_URL="http://127.0.0.1:8888"
# वैकल्पिक:
export PI_PYTHON_GATEWAY_TOKEN="..."

लोकल साझा गेटवे से व्यवहार अंतर:

• कोई लोकल गेटवे लॉक/जानकारी फ़ाइलें नहीं
• कोई लोकल प्रक्रिया स्पॉन/समाप्ति नहीं
• हेल्थ चेक और कर्नेल CRUD बाहरी एंडपॉइंट के विरुद्ध चलते हैं
• ऑथ विफलताएँ स्पष्ट टोकन मार्गदर्शन के साथ प्रदर्शित की जाती हैं

परिचालन समस्या निवारण (वर्तमान विफलता मोड)

• Python उपकरण उपलब्ध नहीं

  • python.toolMode / PI_PY जाँचें।
  • यदि प्रीफ़्लाइट विफल होता है, तो रनटाइम bash-only पर फ़ॉलबैक करता है।

• कर्नेल उपलब्धता त्रुटियाँ

  • लोकल मोड के लिए रेज़ॉल्व किए गए Python रनटाइम में kernel_gateway और ipykernel दोनों इम्पोर्ट योग्य होने चाहिए।

  • इंस्टॉल करें:

    python -m pip install jupyter_kernel_gateway ipykernel

• python.sharedGateway=false से स्टार्टअप विफलता

  • यह वर्तमान कार्यान्वयन के साथ अपेक्षित है।

• बाहरी गेटवे ऑथ/पहुँच विफलताएँ

  • 401/403 -> PI_PYTHON_GATEWAY_TOKEN सेट करें।
  • टाइमआउट/अनुपलब्ध -> URL/नेटवर्क और गेटवे हेल्थ सत्यापित करें।

• निष्पादन रुकता है फिर टाइमआउट होता है

  • यदि वर्कलोड वैध है तो उपकरण timeout बढ़ाएँ (अधिकतम 600s)।
  • अटके कोड के लिए, रद्दीकरण कर्नेल इंटरप्ट ट्रिगर करता है लेकिन उपयोगकर्ता कोड को अभी भी रिफ़ैक्टर करने की आवश्यकता हो सकती है।

• Python कोड में stdin/input प्रॉम्प्ट

  • input() इस रनटाइम पथ में इंटरएक्टिव रूप से समर्थित नहीं है; डेटा प्रोग्रामेटिक रूप से पास करें।

• संसाधन समाप्ति (EMFILE / बहुत अधिक खुली फ़ाइलें)

  • सेशन मैनेजर साझा-गेटवे पुनर्प्राप्ति ट्रिगर करता है (सेशन टियरडाउन + साझा गेटवे रीस्टार्ट)।

• कार्यशील निर्देशिका त्रुटियाँ

  • उपकरण निष्पादन से पहले सत्यापित करता है कि cwd मौजूद है और एक निर्देशिका है।

प्रासंगिक एनवायरनमेंट वेरिएबल

• PI_PY — उपकरण एक्सपोज़र ओवरराइड (ऊपर दिया गया bash-only/ipy-only/both मैपिंग)
• PI_PYTHON_GATEWAY_URL — बाहरी गेटवे का उपयोग करें
• PI_PYTHON_GATEWAY_TOKEN — वैकल्पिक बाहरी गेटवे ऑथ टोकन
• PI_PYTHON_SKIP_CHECK=1 — Python प्रीफ़्लाइट/वार्म चेक बाईपास करें
• PI_PYTHON_IPC_TRACE=1 — कर्नेल IPC भेजने/प्राप्त करने के ट्रेस लॉग करें
• PI_DEBUG_STARTUP=1 — स्टार्टअप-स्टेज डीबग मार्कर उत्सर्जित करें