Sweepy डेवलपर संदर्भ
Sweepy एक छोटे Python प्रोजेक्ट के रूप में चलता है जिसका इंजन सपाट है। यह पेज हर पाइपलाइन चरण को उस मॉड्यूल से मिलाता है जो उसे चलाता है, ताकि आप जान सकें कि बदलाव कहाँ करना है।
किसके लिए है
यह पेज पढ़ें अगर आप Sweepy का कोड बदलने या नया जॉब स्रोत जोड़ने की सोच रहे हैं। समीक्षक इसे pull request को समझने के लिए इस्तेमाल कर सकते हैं। यह केवल आंतरिक बातें कवर करता है: मॉड्यूल, डिपेंडेंसी और Python संस्करण।
अगर आप स्वीप चलाना चाहते हैं, तो यह पेज छोड़ दें। इंस्टॉलेशन से शुरू करें।
पाइपलाइन चरण और मॉड्यूल
swee.py पाँच चरण क्रम से चलाता है। टर्मिनल हर चरण को [1/5] से [5/5] तक छापता है।
| चरण | मॉड्यूल | यह क्या करता है |
|---|---|---|
| 1. प्रोफ़ाइल लोडिंग | engine/config.py | आपकी YAML प्रोफ़ाइल लोड और सत्यापित करता है। उसी मॉड्यूल का विज़ार्ड उसे लिखता है। |
| 2. भूमिकाएँ खोजना | engine/discovery.py | python-jobspy के ज़रिए एग्रीगेटर फ़ीड से पूछताछ करता है और हर प्लेटफ़ॉर्म को वर्गीकृत करता है। |
| 2. भूमिकाएँ खोजना | engine/sources/ | सार्वजनिक endpoint से Greenhouse, Ashby, Lever, Workable और Built In NYC बोर्ड लाता है। |
| 2. डुप्लिकेट हटाना | swee.py | एग्रीगेटर और स्रोत नतीजों को हर जॉब लिंक के लिए एक कार्ड में मिलाता है। |
| 3. URL सत्यापित करना | engine/validator.py | HTTP HEAD अनुरोध और GET fallback से हर लिंक जाँचता है। यह मृत पोस्टिंग हटाता है। |
| 4. रिज़्यूमे के सामने स्कोरिंग | engine/scorer.py | पोस्टिंग और रिज़्यूमे के शब्द निकालता है, फिर आवश्यकताओं और कीवर्ड पर मेल स्कोर करता है। यह उन पोस्टिंग को चिह्नित करता है जो लिखित उत्तर माँगती हैं। |
| 5. रिज़्यूमे ट्रैक भेजना | engine/enrich.py | सबसे अधिक शब्द मेल वाला ट्रैक चुनता है और उसी का बैज रंग लगाता है। |
| 5. कार्ड समृद्ध करना | engine/enrich.py | कार्ड सारांश, वेतन पंक्तियाँ और अनुकूलित टिप टेक्स्ट बनाता है। |
| 5. डिफ़ॉल्ट कार्ड PDF | engine/report.py | कार्ड लेआउट रेंडर करता है, डिफ़ॉल्ट रूप से प्रति पेज छह कार्ड, और पेज संख्या लौटाता है। |
| 5. लेगेसी तालिका PDF | engine/pdf_builder.py | जब आपकी प्रोफ़ाइल report.style: legacy सेट करे, तब तालिका लेआउट रेंडर करता है। |
| 5. डेटा निर्यात | engine/exporter.py | CSV और JSON फ़ाइलें लिखता है। अनुरोध पर PNG पेज छवियाँ बनाता है। |
| 5. जॉब ट्रैकिंग | engine/tracking.py | ट्रैकिंग कॉलम जोड़ता है और पिछले निर्यात पढ़ता है ताकि आपके भरे मान लौटकर आएँ। |
engine/session.py stateful Model Context Protocol (MCP) फ़्लो के लिए कार्ड स्टोर रखता है। यह कार्ड को एक thread-safe मैप में रखता है, जिसकी कुंजी हर जॉब लिंक का स्थिर hash होती है।
बदलाव कहाँ करें
| आप क्या बदलना चाहते हैं | यहाँ से शुरू करें |
|---|---|
| कोई जॉब स्रोत या उसका endpoint | engine/sources/, साथ में data/sources/ में सीड सूची |
| मिलान कैसे स्कोर होते हैं | engine/scorer.py |
| कार्ड क्या दिखाता है | engine/enrich.py, फिर engine/report.py |
| लिंक कैसे जाँचे जाते हैं | engine/validator.py |
| कोई कमांड-लाइन फ़्लैग | swee.py |
| कोई MCP टूल | server.py |
server.py वही इंजन मॉड्यूल import करता है जो कमांड-लाइन टूल करता है। किसी भी इंजन बदलाव के बाद MCP रास्ता जाँचें, क्योंकि एक सुधार दोनों प्रवेश बिंदुओं पर असर डालता है।
मॉड्यूल संदर्भ
प्रवेश बिंदु
| मॉड्यूल | उद्देश्य |
|---|---|
swee.py | पाँच-चरणीय पाइपलाइन के लिए मुख्य ऑर्केस्ट्रेटर और argparse कमांड-लाइन प्रवेश बिंदु। |
server.py | Model Context Protocol (stdio) सर्वर जो इंजन टूल AI सहायकों को देता है। |
इंजन मॉड्यूल
| मॉड्यूल | उद्देश्य |
|---|---|
engine/config.py | इंटरैक्टिव विज़ार्ड के साथ YAML लोडिंग और सत्यापन। |
engine/discovery.py | python-jobspy और नियतात्मक स्रोतों के लिए स्क्रैपर ऑर्केस्ट्रेशन, Applicant Tracking System (ATS) पहचान और डुप्लिकेट हटाना। |
engine/validator.py | soft-404 पहचान के साथ लिंक uptime जाँच। असत्यापनीय लिंक रन में रहते हैं। |
engine/scorer.py | रिज़्यूमे शब्द निकालना, प्रतिशत मिलान, टैगिंग और प्रति-ट्रैक स्कोरिंग। |
engine/enrich.py | सारांश, वेतन, ट्रैक रूटिंग और अनुकूलित टिप के लिए कार्ड समृद्धि। |
engine/session.py | stateful MCP फ़्लो के लिए स्थिर ID वाला thread-safe कार्ड स्टोर। |
engine/report.py | डिफ़ॉल्ट कार्ड-लेआउट PDF। |
engine/pdf_builder.py | report.style: legacy के लिए लेगेसी तालिका-लेआउट PDF। |
engine/exporter.py | CSV और JSON निर्यात, साथ में रिपोर्ट PDF का PNG रूपांतरण। |
engine/tracking.py | ट्रैकिंग कॉलम और पिछले निर्यात का carry-over पठन। |
engine/docx.py | python-docx और reportlab से DOCX से PDF रूपांतरण, साथ में Microsoft Word fallback। |
engine/documents.py | --convert और MCP कन्वर्टर के लिए दस्तावेज़ dispatch, DOCX, DOC, टेक्स्ट, Markdown और PDF सहित। |
engine/logging.py | logs/ के अंतर्गत वैकल्पिक डीबग लॉग। |
engine/cache.py | क्वेरी और इंजन सेट पर कुंजीबद्ध SQLite स्क्रैप कैश, एक घंटे की आयु के साथ। |
engine/circuit_breaker.py | लगातार स्रोत त्रुटियाँ गिनता है और cooldown के दौरान कॉल रोकता है। |
engine/engine_defaults.py | साझा डिफ़ॉल्ट साइट सूचियाँ और इंजन सेटिंग, चक्र से बचने के लिए import-मुक्त रखी गईं। |
engine/engines.py | वैकल्पिक hirehunt, openroles, apify और jobdrop इंजन के लिए अडैप्टर रजिस्ट्री और इंस्टॉलर। |
engine/history.py | पहले रिपोर्ट की गई पोस्टिंग का स्थायी रिकॉर्ड। रोज़ाना स्वीप केवल नई भूमिकाएँ रिपोर्ट करता है। |
engine/normalize.py | कच्ची इंजन पंक्तियों को साझा पोस्टिंग कॉलम में सामान्य करता है। |
engine/salary.py | जब बोर्ड संरचित वेतन न दे, तब पोस्टिंग टेक्स्ट से वेतन निकालना। |
engine/sweep_config.py | साझा इंजन डिफ़ॉल्ट को प्रोफ़ाइल सेटिंग पर लागू करता है। |
engine/updater.py | चेकआउट के लिए Git-आधारित अपडेट जाँच और डिपेंडेंसी पुनःस्थापन। |
नियतात्मक स्रोत
| मॉड्यूल | उद्देश्य |
|---|---|
engine/sources/__init__.py | फ़ेचर निर्यात और data/sources/ से सीड सूची लोडिंग। |
engine/sources/_common.py | HTTP हेडर, पद नाम की पूर्व-छँटाई और HTML-से-टेक्स्ट रूपांतरण के साझा helpers। |
engine/sources/greenhouse.py | Greenhouse जॉब बोर्ड फ़ेचर। |
engine/sources/ashby.py | Ashby जॉब बोर्ड फ़ेचर। |
engine/sources/lever.py | Lever पोस्टिंग फ़ेचर। |
engine/sources/workable.py | Workable widget API फ़ेचर। |
engine/sources/builtinnyc.py | Built In NYC श्रेणी स्क्रैपर। |
इंजन अडैप्टर
| मॉड्यूल | उद्देश्य |
|---|---|
engine/adapters/__init__.py | रजिस्ट्री जो हर इंजन नाम को उसके अडैप्टर से मिलाती है। |
engine/adapters/base.py | ScraperAdapter आधार क्लास, साझा User-Agent हेडर और परिणाम-आकार helpers। |
engine/adapters/jobspy_adapter.py | LinkedIn, Indeed, Glassdoor और ZipRecruiter के लिए python-jobspy एग्रीगेटर अडैप्टर। |
engine/adapters/ats_adapter.py | engine/sources/ के नियतात्मक ATS फ़ेचर पर अडैप्टर। |
engine/adapters/hirehunt_adapter.py | वैकल्पिक hirehunt इंजन अडैप्टर। |
engine/adapters/openroles_adapter.py | वैकल्पिक openroles इंजन अडैप्टर। |
engine/adapters/apify_adapter.py | वैकल्पिक Apify actor अडैप्टर। |
engine/adapters/jobdrop_adapter.py | वैकल्पिक jobdrop इंजन अडैप्टर। |
डेटा, स्क्रिप्ट और टेस्ट
| पथ | उद्देश्य |
|---|---|
data/sources/*.txt | बोर्ड, कंपनियों, संगठनों और श्रेणियों के लिए सीड सूचियाँ। |
scripts/make_sample.py | docs/ में रखी नमूना रिपोर्ट का बिल्डर। |
tests/ | pytest सूट, हर क्षेत्र के लिए एक फ़ाइल: adapters, config, documents, docx, engines, enrich, history, logging और report। बाकी फ़ाइलें salary, scorer, server, session, sources, swee, tracking, updater और validator कवर करती हैं। |
जब आप discovery.py, exporter.py या pdf_builder.py बदलें, तब एक समर्पित टेस्ट फ़ाइल जोड़ें। फ़ाइल tests/ में रखें।
डिपेंडेंसी
रनटाइम पैकेज requirements.txt से आते हैं। नीचे के संस्करण उसी फ़ाइल से मेल खाते हैं।
| पैकेज | संस्करण | Sweepy के लिए यह क्या करता है |
|---|---|---|
reportlab | 5.0.1 | क्लिक करने योग्य लिंक के साथ स्टाइल की गई PDF रिपोर्ट बनाता है। |
pymupdf | 1.28.2 | रिज़्यूमे PDF से टेक्स्ट निकालता है और PNG निर्यात बनाता है। |
python-docx | 1.2.0 | .docx रिज़्यूमे पढ़ता है और Word के बिना DOCX टेक्स्ट से PDF बनाता है। |
requests | 2.32.5 | ATS endpoint तक पहुँचता है और हर जॉब लिंक का जीवंत जवाब जाँचता है। |
beautifulsoup4 | 4.15.0 | Greenhouse, Lever, Workable और Built In NYC स्रोतों का HTML पार्स करता है। |
pyyaml | 6.0.3 | YAML प्रोफ़ाइल पढ़ता और लिखता है। |
questionary | 2.1.1 | इंटरैक्टिव विज़ार्ड के प्रश्न चलाता है। |
prompt-toolkit | 3.0.53 | विज़ार्ड का इंटरैक्टिव टेक्स्ट इनपुट चलाता है। |
python-jobspy | 1.2.0 | बिना API क्रेडेंशियल के LinkedIn, Indeed, Glassdoor और ZipRecruiter स्क्रैप करता है। |
pandas | 2.2.3 | पोस्टिंग को व्यवस्थित करता है और CSV तथा JSON निर्यात बनाता है। |
mcp | 1.30.0 | Model Context Protocol सर्वर चलाता है। |
anyio | 4.12.1 | असिंक्रोनस MCP ट्रांसपोर्ट चलाता है। |
requirements.txt एक वैकल्पिक पैकेज भी सूचीबद्ध करती है। जब Word से PDF बनना चाहिए, तब docx2pdf को कमेंट से मुक्त करें।
docx2pdf(0.5.2, वैकल्पिक) Windows पर Microsoft Word के ज़रिए DOCX को PDF में रेंडर करता है। जब भी मशीन पर Microsoft Word हो, Sweepy उसे बुलाता है।
mcp जान-बूझकर 1.x पर रहता है। 2.x SDK केवल 2026-07-28 प्रोटोकॉल युग की सेवा करता है। जो क्लाइंट server/discover जाँचकर फिर initialize handshake पर लौट आता है, उसे -32022 त्रुटि मिलती है। VS Code Copilot वही fallback अपनाता है।
pandas जान-बूझकर 2.x पर रहता है। Pandas 3.x के लिए Python 3.11 या नया चाहिए, और CI मैट्रिक्स अब भी Python 3.10 जाँचता है।
डेवलपमेंट पैकेज (requirements-dev.txt)
| पैकेज | संस्करण | यह क्या करता है |
|---|---|---|
pytest | 9.1.1 | tests/ में टेस्ट सूट चलाता है। |
pytest-cov | 7.1.0 | swee.py, server.py और engine/scorer.py का कवरेज बताता है। |
ruff | 0.17.0 | कोड लिंट करता है और import क्रम में लगाता है। |
tomli | 2.2.1 | Python 3.10 टेस्ट रन के लिए tomllib देता है। |
pip install -r requirements.txt
pip install -r requirements-dev.txt
ruff check .
pytest -q
आवश्यकताएँ और समर्थित Python संस्करण
| मद | विवरण |
|---|---|
| Python न्यूनतम | Sweepy के लिए Python 3.10 या नया चाहिए और हर मॉड्यूल में 3.10 सिंटैक्स लक्षित करता है। |
| परीक्षित सीमा | .github/workflows/ci.yml का CI वर्कफ़्लो Ubuntu पर Python 3.10, 3.11 और 3.12 चलाता है। |
| लिंट लक्ष्य | pyproject.toml ruff के लिए target-version = "py310" सेट करता है। केवल-नया construct लिंट जॉब विफल कर देता है। |
| पंक्ति लंबाई | Ruff 100-अक्षर की पंक्ति सीमा लागू करता है और E501 अनदेखा करता है। |
| CI चरण | जॉब दोनों requirements फ़ाइलें इंस्टॉल करता है और pytest से पहले ruff check . चलाता है। |
pyproject.toml में requires-python = ">=3.10" घोषित है, इसलिए pip इंस्टॉल के समय पुराना इंटरप्रेटर अस्वीकार कर देता है। CI मैट्रिक्स और ruff लक्ष्य परीक्षित सीमा तय करते हैं। Python 3.13 व्यवहार में काम करता है, पर उस सीमा से बाहर रहता है।
जब पहले से बना wheel न हो, तब pymupdf पैकेज सोर्स से कंपाइल हो सकता है। डिपेंडेंसी इंस्टॉल करने से पहले Microsoft C++ Build Tools इंस्टॉल करें और "Desktop development with C++" वर्कलोड चुनें।
रिपॉज़िटरी लेआउट
swee.py CLI प्रवेश बिंदु और स्वीप ऑर्केस्ट्रेटर
server.py stdio पर MCP सर्वर
engine/ पाइपलाइन मॉड्यूल
engine/sources/ नियतात्मक ATS फ़ेचर
engine/adapters/ एग्रीगेटर और वैकल्पिक इंजन अडैप्टर
data/sources/ हर फ़ेचर के लिए सीड सूचियाँ
profiles/ YAML खोज प्रोफ़ाइल
results/ बनाए गए PDF, CSV, JSON और PNG फ़ाइलें
logs/ वैकल्पिक डीबग लॉग
styles/ दस्तावेज़ों के लिए Vale स्टाइल नियम
tests/ pytest सूट
जब आप server.py में किसी टूल का signature बदलें, तब उसी कमिट में MCP टूल संदर्भ अपडेट करें।