readme2demo — आपकी README से सत्यापित ट्यूटोरियल और डेमो वीडियो

_{▶ readme2demo अपना स्वयं का ट्यूटोरियल उत्पन्न कर रहा है: एक AI एजेंट इस रिपॉजिटरी की README को एक सैंडबॉक्स में चलाता है, एक ताज़ा कंटेनर प्रत्येक चरण को दोहराता है, फिर डेमो प्रस्तुत किया जाता है। पूर्ण self-run आउटपुट examples/readme2demo में · दूसरे प्रोजेक्ट के विरुद्ध चलाएँ examples/toolhive में।}

AI-सत्यापित ट्यूटोरियल और डेमो वीडियो जनरेटर। इसे किसी रिपॉजिटरी पर इंगित करें। एक AI एजेंट README पढ़ता है और वास्तव में इसे एक कठोर Docker सैंडबॉक्स के अंदर चलाता है। केवल जब एक क्लीन-रूम रिप्ले सफल होता है, तब यह एक डेमो वीडियो (VHS) प्रस्तुत करता है और ट्यूटोरियल, चरण-दर-चरण मार्गदर्शिका और समस्या निवारण दस्तावेज़ प्रकाशित करता है।

मूल्य यह नहीं है कि "AI एक ट्यूटोरियल लिखता है" — बल्कि यह है कि ट्यूटोरियल दो बार चला, इससे पहले कि आप इसे देखें।

इसे क्रियाशील देखें: सत्यापित उदाहरण रन ब्राउज़ करें — वास्तविक ट्यूटोरियल, चरण-दर-चरण मार्गदर्शिकाएँ और डेमो वीडियो, प्रत्येक को प्रकाशन से पहले एक साफ कंटेनर में स्वतंत्र रूप से दोहराया गया।

यह कैसे काम करता है

repo URL → ingest/plan → agent run (in Docker) → normalize transcript
        → distill minimal path → VERIFY replay in fresh container
        → generate tutorial.md + troubleshooting.md → render VHS video

पूर्ण आर्किटेक्चर के लिए architecture/README.md देखें।

आवश्यकताएँ

• Python ≥ 3.10, Docker
• प्रमाणीकरण, इनमें से एक:
  • आपकी Claude सदस्यता (कोई API कुंजी नहीं): एक स्थानीय Claude Code स्थापना। प्लानर/डिस्टिलर/ट्यूटोरियल पास आपकी सदस्यता पर --llm-backend claude-cli (claude -p) के माध्यम से चलते हैं, और सैंडबॉक्स में एजेंट CLAUDE_CODE_OAUTH_TOKEN से प्रमाणित होता है (एक बनाएँ: claude setup-token)। स्व-होस्टेड, एकल-ऑपरेटर रन के लिए आपके अपने रिपॉजिटरी के विरुद्ध पूरी तरह से समर्थित — Pro/Max योजनाओं में एक मासिक Agent SDK क्रेडिट शामिल है जो claude -p को कवर करता है।
  • ANTHROPIC_API_KEY — मीटर्ड API बिलिंग; स्केल और समवर्तीता के लिए सर्वोत्तम, और यदि आप readme2demo को दूसरों के लिए सेवा के रूप में होस्ट करते हैं तो आवश्यक (Anthropic की शर्तों के अनुसार, सदस्यता प्रमाणीकरण एक मल्टी-टेनेंट उत्पाद को संचालित नहीं कर सकता — ROADMAP.md देखें)। claude-code के बजाय OpenHands इंजन पर Claude मॉडल के साथ सैंडबॉक्स्ड एजेंट चलाने के लिए --anthropic [मॉडल] जोड़ें।
  • Google Gemini (--gemini [मॉडल]): एक एकल GEMINI_API_KEY पूरे सत्र को Claude से दूर चलाता है — प्लानर/डिस्टिलर/ट्यूटोरियल पास Gemini का उपयोग करते हैं और सैंडबॉक्स्ड एजेंट OpenHands इंजन पर चलता है (Gemini पर भी)। कोई मॉडल नाम निर्मित नहीं है (Google पुराने मॉडलों को हार्ड 404 के साथ हटा देता है): प्रति रन नाम दें () या एक बार निर्यात करें। एक्स्ट्रा इंस्टॉल करें: ।

# अपनी Claude सदस्यता पर चलाएँ (कोई API कुंजी नहीं) — स्व-होस्टेड रन के लिए समर्थित
claude setup-token        # इंटरैक्टिव: ब्राउज़र में अनुमोदन करें, फिर COPY करें
                          # sk-ant-oat01-... टोकन जो यह प्रिंट करता है ($(...)) का उपयोग न करें)
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
readme2demo run <repo-url> --llm-backend claude-cli

# मीटर्ड API बिलिंग पर चलाएँ (स्केल, समवर्तीता, या दूसरों के लिए होस्टिंग)
export ANTHROPIC_API_KEY=sk-ant-...
readme2demo run <repo-url>              # --llm-backend auto api चुनता है

# पूरा सत्र Google Gemini पर चलाएँ (OpenHands एजेंट + Gemini पास)
pip install 'readme2demo[gemini]'
docker build -t readme2demo/openhands:latest images/openhands   # एक बार: OpenHands सैंडबॉक्स छवि
export GEMINI_API_KEY=...
readme2demo run <repo-url> --gemini gemini-3.5-flash   # मॉडल प्रति रन नामित
export GEMINI_MODEL=gemini-3.5-flash                   # ...या एक बार सेट करें, फिर:
readme2demo run <repo-url> --gemini                    # बेयर फ्लैग GEMINI_MODEL पढ़ता है

# पूरा सत्र OpenAI पर चलाएँ (OpenHands एजेंट + OpenAI पास)
pip install 'readme2demo[openai]'
export OPENAI_API_KEY=sk-...
readme2demo run <repo-url> --openai gpt-5.1            # या एक बार OPENAI_MODEL निर्यात करें

# API बिलिंग पर Claude मॉडल के साथ OpenHands एजेंट चलाएँ
export ANTHROPIC_API_KEY=sk-ant-...
readme2demo run <repo-url> --anthropic                 # डिफ़ॉल्ट रूप से कॉन्फ़िग मॉडल का उपयोग करता है

स्थापना

pip install -e ".[dev]"
docker build -t readme2demo/base:latest images/base/
docker build -t readme2demo/openhands:latest images/openhands/   # केवल --engine openhands / --gemini / --openai / --anthropic के लिए

उपयोग

readme2demo run https://github.com/example/tool
readme2demo run -gr https://github.com/example/tool             # समान, फ्लैग के माध्यम से
readme2demo run -s my_guide.md                                  # केवल-गाइड: कोई repo नहीं, आपकी गाइड स्व-निहित है
readme2demo run -gr https://github.com/example/tool -s my_guide.md   # दोनों: आपकी गाइड सब कुछ चलाती है
readme2demo run https://github.com/example/tool --gemini gemini-3.5-flash  # Google Gemini पर चलाएँ (GEMINI_API_KEY की आवश्यकता है; OpenHands एजेंट का उपयोग करता है; बेयर --gemini GEMINI_MODEL पढ़ता है)
readme2demo run https://github.com/example/tool --openai gpt-5.1           # OpenAI पर चलाएँ (OPENAI_API_KEY की आवश्यकता है; OpenHands एजेंट का उपयोग करता है; बेयर --openai OPENAI_MODEL पढ़ता है)
readme2demo run https://github.com/example/tool --anthropic                # ANTHROPIC_API_KEY पर Claude मॉडल के साथ OpenHands एजेंट
readme2demo run https://github.com/example/tool --allow-docker-socket  # उन टूल के लिए जो कंटेनर प्रबंधित करते हैं (सुरक्षा समझौता: सैंडबॉक्स अलगाव को भेदता है — केवल विश्वसनीय रिपॉजिटरी)
readme2demo run https://github.com/example/tool --skip-video --budget-usd 3
readme2demo resume runs/tool-20260702-... --from-stage render
readme2demo report runs/tool-20260702-...

रिपॉजिटरी वैकल्पिक है: इसे स्थितीय रूप से या -gr/--github-repo के साथ पास करें, -s/--step-by-step के साथ एक गाइड प्रदान करें, या दोनों। कम से कम एक आवश्यक है। केवल गाइड के साथ, कोई repo क्लोन नहीं किया जाता — गाइड स्व-निहित होनी चाहिए (एक प्रकाशित पैकेज स्थापित करें, या एक स्पष्ट चरण के रूप में अपनी ज़रूरत की चीज़ें क्लोन करें); ताज़ा-कंटेनर रिप्ले अभी भी प्रत्येक कमांड को सत्यापित करता है।

आउटपुट runs/<run-id>/ में आते हैं: tutorial.md, step_by_step.md, troubleshooting.md, commands.sh, demo.tape, demo.mp4, demo.gif, साथ ही manifest.json जिसमें चरण स्थितियाँ और कुल लागत है।

GitHub Action — CI में अपनी README सत्यापित करें

जब आपकी README काम करना बंद कर दे तो लाल X प्राप्त करें। repo-root कम्पोज़िट एक्शन अपने स्वयं के पिन किए गए चेकआउट से readme2demo स्थापित करता है, सैंडबॉक्स इमेज बनाता है, आपकी repo के URL के विरुद्ध पूरी पाइपलाइन चलाता है, और जब ताज़ा-कंटेनर रिप्ले सफल नहीं होता है तो चेक को विफल कर देता है:

name: readme-check
on:
  push:
    branches: [main]        # url मोड डिफ़ॉल्ट ब्रांच HEAD का परीक्षण करता है — नीचे चेतावनी देखें
    paths: ["README.md"]
  schedule:
    - cron: "0 6 * * 1"     # साप्ताहिक: अपरिवर्तित README के नीचे बदलती दुनिया को पकड़ें

permissions:
  contents: read

jobs:
  verify-readme:
    runs-on: ubuntu-latest
    steps:
      - uses: alphacrack/readme2demo@main   # रिलीज़ होने पर एक टैग या SHA पिन करें
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          skip-video: "true"

⚠ केवल URL मोड — यह अभी तक PR हेड्स को सत्यापित नहीं करता है। एक्शन repo-url के रिमोट डिफ़ॉल्ट ब्रांच HEAD को क्लोन करता है (डिफ़ॉल्ट: वर्कफ़्लो चलाने वाली रिपॉजिटरी); इंजेशन केवल https URL स्वीकार करता है, --depth 1, कोई ref पिनिंग नहीं। pull_request पर यह बेस ब्रांच की README का परीक्षण करेगा — PR की नहीं — इसलिए इसे PR पर प्री-मर्ज फैसले की उम्मीद में न लगाएं। जब तक #74 (स्थानीय-पथ इंजेशन) नहीं आता, तब तक डिफ़ॉल्ट ब्रांच पर on: push और एक क्रोन ईमानदार ट्रिगर हैं; वास्तविक PR-हेड सत्यापन के लिए repo-path इनपुट इसके साथ आता है।

लागत: प्रत्येक रन आपके ANTHROPIC_API_KEY पर वास्तविक एजेंट धन खर्च करता है — आमतौर पर कुछ डॉलर, budget-usd (डिफ़ॉल्ट "5"; यदि अधिक हो तो रन रद्द हो जाता है) द्वारा हार्ड-कैप किया गया। paths: फ़िल्टर और एक क्रोन खर्च को README परिवर्तन के अनुपात में रखता है, और skip-video: "true" वॉल-क्लॉक समय कम करता है (रेंडर में वैसे भी कोई API धन खर्च नहीं होता)।

चेक दो अलग-अलग तरीकों से विफल होता है, जिनका नाम स्टेप लॉग में दिया गया है: README टूटा (पाइपलाइन पूरी हुई, क्लीन-रूम रिप्ले विफल — readme2demo report --json के माध्यम से पता चला, क्योंकि readme2demo run जानबूझकर एक पूर्ण लेकिन असत्यापित रन पर 0 से बाहर निकलता है) और एक्शन इंफ्रा टूटा (गैर-शून्य पाइपलाइन निकास: प्रीफ़्लाइट, बजट, Docker)। आउटपुट: verified ("true"/"false") और run-dir; tutorial.md, step_by_step.md, verify.log (और जब वीडियो चालू हो तो demo.gif) readme2demo-run कलाकृति के रूप में अपलोड होते हैं।

step_by_step.md — वीडियो का स्रोत

डेमो वीडियो हमेशा step_by_step.md से बनाया जाता है: इसके चरणों को पार्स किया जाता है, और प्रत्येक डेमो-सुरक्षित, ग्राउंडेड कमांड वीडियो में एक टाइप किए गए कमांड के रूप में बन जाता है, जिसमें चरण शीर्षक ऑन-स्क्रीन टिप्पणी के रूप में दिखाया जाता है। यह तीन तरीकों से अस्तित्व में आता है, प्राथमिकता क्रम में:

1. आप एक पास करते हैं: readme2demo run <url> -s my_guide.md — क्लोन में आधिकारिक गाइड के रूप में इंजेक्ट; प्लानर और एजेंट इसका अनुसरण करते हैं, वीडियो इसे चलाता है। <url> यहाँ वैकल्पिक है: readme2demo run -s my_guide.md एक खाली सैंडबॉक्स के विरुद्ध केवल-गाइड चलाता है।
2. रिपॉजिटरी एक भेजती है (step_by_step.md / step-by-step.md रूट या docs/ पर, कोई भी केस): समान उपचार, स्वचालित रूप से।
3. कोई मौजूद नहीं है: पाइपलाइन एक विस्तृत step_by_step.md उत्पन्न करती है — सत्यापित commands.sh से प्रत्येक कमांड एक क्रमांकित चरण के रूप में वास्तविक कैप्चर किए गए आउटपुट के साथ — फिर उससे वीडियो बनाती है। रिपॉजिटरी में वापस योगदान करने के लिए तैयार।

सेटअप चरण (क्लोन, इंस्टॉल, बिल्ड) गाइड में दस्तावेज़ित हैं लेकिन वीडियो से बाहर रखे गए हैं — यह सत्यापित, पहले से बनाए गए वर्कट्री के विरुद्ध चलता है, जो लाभ दिखाता है।

प्रत्येक ट्यूटोरियल में एक सत्यापन बैज होता है: ✅ Verified on <date> · image <digest> · commit <sha> — या एक जोरदार ⚠ UNVERIFIED यदि रिप्ले सफल नहीं हुआ। असत्यापित आउटपुट कभी भी चुपचाप प्रकाशित नहीं किया जाता है।

कॉन्फ़िगरेशन

CLI फ्लैग > readme2demo.toml > डिफ़ॉल्ट:

engine = "claude-code"      # या "openhands"
model = "claude-sonnet-5"   # प्लानर/डिस्टिलर/ट्यूटोरियल पास
max_turns = 60
budget_usd = 5.0
base_image = "readme2demo/base:latest"
skip_video = false

विकास

python -m pytest tests/ -q            # 175 यूनिट परीक्षण, किसी docker/नेटवर्क की आवश्यकता नहीं
ruff check src/ tests/               # शुद्धता लिंट (CI से मेल खाता है)
python -m pytest -m integration      # docker + API कुंजियों की आवश्यकता है (अभी तक कोई नहीं)

सुरक्षा मॉडल

READMEs अविश्वसनीय कोड हैं। एजेंट एक कठोर कंटेनर के अंदर चलता है (cap-drop ALL, no-new-privileges, memory/cpu/pids limits, non-root) — वह कंटेनर अनुमति सीमा है। ज्ञात MVP व्यापार-बंद: API कुंजी सैंडबॉक्स में प्रवेश करती है; एक समर्पित निम्न-सीमा कुंजी का उपयोग करें। एक होस्ट-साइड कुंजी-इंजेक्टिंग एग्रेस प्रॉक्सी की योजना बनाई गई है (माइलस्टोन 4)।

पूर्ण खतरा मॉडल और निजी भेद्यता रिपोर्टिंग: SECURITY.md।

परियोजना और समुदाय

• उदाहरण — प्रमाण के रूप में प्रतिबद्ध सत्यापित आउटपुट
• रोडमैप — यह कहाँ जा रहा है (खोजपूर्ण होस्टेड/SaaS दिशा सहित)
• योगदान — एकमात्र गैर-परक्राम्य नियम, और कैसे सेटअप करें
• सुरक्षा नीति · आचार संहिता
• आर्किटेक्चर — चरण सीमाएँ और आरेख

MIT लाइसेंस प्राप्त। CLI और सत्यापन पाइपलाइन मुफ्त और खुला स्रोत हैं, और रहेंगे।

योगदानकर्ता

readme2demo में योगदान देने वाले सभी लोगों को एक बड़ा धन्यवाद!