{"id":43002655,"url":"https://github.com/mcp-tool-shop-org/venvkit","last_synced_at":"2026-02-26T19:26:12.130Z","repository":{"id":334679434,"uuid":"1142297859","full_name":"mcp-tool-shop-org/venvkit","owner":"mcp-tool-shop-org","description":"Python virtual environment diagnostic toolkit for Windows ML workflows","archived":false,"fork":false,"pushed_at":"2026-02-23T16:03:17.000Z","size":187,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-23T20:50:40.345Z","etag":null,"topics":["developer-tools","diagnostics","gpu","ml","python","virtual-environment","windows"],"latest_commit_sha":null,"homepage":"https://mcp-tool-shop-org.github.io/venvkit/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mcp-tool-shop-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["mcp-tool-shop"]}},"created_at":"2026-01-26T08:13:39.000Z","updated_at":"2026-02-23T16:03:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mcp-tool-shop-org/venvkit","commit_stats":null,"previous_names":["mcp-tool-shop/venvkit"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/mcp-tool-shop-org/venvkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcp-tool-shop-org%2Fvenvkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcp-tool-shop-org%2Fvenvkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcp-tool-shop-org%2Fvenvkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcp-tool-shop-org%2Fvenvkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mcp-tool-shop-org","download_url":"https://codeload.github.com/mcp-tool-shop-org/venvkit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcp-tool-shop-org%2Fvenvkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29868391,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T18:42:30.764Z","status":"ssl_error","status_checked_at":"2026-02-26T18:41:47.936Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["developer-tools","diagnostics","gpu","ml","python","virtual-environment","windows"],"created_at":"2026-01-31T04:10:07.542Z","updated_at":"2026-02-26T19:26:12.121Z","avatar_url":"https://github.com/mcp-tool-shop-org.png","language":"TypeScript","funding_links":["https://github.com/sponsors/mcp-tool-shop"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"README.md\"\u003eEnglish\u003c/a\u003e | \u003ca href=\"README.ja.md\"\u003e日本語\u003c/a\u003e | \u003ca href=\"README.zh.md\"\u003e中文\u003c/a\u003e | \u003ca href=\"README.es.md\"\u003eEspañol\u003c/a\u003e | \u003ca href=\"README.fr.md\"\u003eFrançais\u003c/a\u003e | \u003ca href=\"README.hi.md\"\u003eहिन्दी\u003c/a\u003e | \u003ca href=\"README.it.md\"\u003eItaliano\u003c/a\u003e | \u003ca href=\"README.pt-BR.md\"\u003ePortuguês (BR)\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/venvkit/readme.png\" alt=\"venvkit\" width=\"400\"\u003e\n\u003c/p\u003e\n\n# venvkit\n\n\u003e Part of [MCP Tool Shop](https://mcptoolshop.com)\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/mcp-tool-shop-org/venvkit/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/mcp-tool-shop-org/venvkit/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://mcp-tool-shop-org.github.io/venvkit/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Landing_Page-live-blue?style=flat-square\" alt=\"Landing Page\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@mcptoolshop/venvkit\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@mcptoolshop/venvkit?style=flat-square\u0026color=cb3837\" alt=\"npm version\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n**Python virtual environment diagnostic toolkit for Windows ML workflows.**\n\nScans your system for Python environments, diagnoses health issues (SSL, DLLs, ABI mismatches, path leakage), tracks task execution history, detects flaky tasks, and renders an ecosystem map.\n\n## 30-Second Quickstart\n\n```bash\ngit clone https://github.com/mcp-tool-shop-org/venvkit \u0026\u0026 cd venvkit\nnpm install \u0026\u0026 npm run build\nnode dist/map_cli.js --root C:\\projects --httpsProbe\n# Open .venvkit/venv-map.html in your browser\n```\n\n## Features\n\n- **doctorLite** - Fast health check for any Python interpreter\n  - SSL/TLS verification\n  - DLL load failures (common with PyTorch/CUDA)\n  - ABI mismatches (ARM vs x86)\n  - pip sanity checks\n  - User-site and PYTHONPATH leakage detection\n\n- **scanEnvPaths** - Discover all Python environments on your system\n  - Finds venvs, conda envs, pyenv versions, base interpreters\n  - Configurable depth and filtering\n\n- **mapRender** - Visualize your Python ecosystem\n  - Graph JSON output for programmatic use\n  - Mermaid diagrams for documentation\n  - Base interpreter grouping with blast radius analysis\n  - Task routing visualization\n\n- **runLog** - Track task execution history\n  - Append-only JSONL format\n  - Records which env ran what task\n  - Captures success/failure with error classification\n\n- **taskCluster** - Aggregate task runs by signature\n  - Flaky task detection (inconsistent pass/fail)\n  - Environment-dependent flake detection\n  - Failure hotspot identification\n  - Contagion analysis (shared root causes)\n\n## Installation\n\n```bash\nnpm install\nnpm run build\n```\n\n## CLI Usage\n\n```bash\n# Scan current directory and generate ecosystem map\nnode dist/map_cli.js\n\n# Scan specific directories\nnode dist/map_cli.js --root C:\\projects --root D:\\ml-experiments\n\n# Include task run history\nnode dist/map_cli.js --runlog .venvkit/runs.jsonl\n\n# Output options\nnode dist/map_cli.js --out ./output --minScore 50 --strict --httpsProbe\n```\n\n### CLI Options\n\n| Flag | Description |\n|------|-------------|\n| `--root, -r` | Directory to scan (can specify multiple) |\n| `--out` | Output directory (default: `.venvkit`) |\n| `--maxDepth` | Max directory depth to scan (default: 5) |\n| `--strict` | Enable strict mode checks |\n| `--httpsProbe` | Test HTTPS connectivity |\n| `--minScore` | Filter envs below this health score |\n| `--concurrency` | Parallel checks (default: CPU count) |\n| `--runlog` | Path to task run log (JSONL) |\n| `--no-tasks` | Skip task visualization |\n\n### Outputs\n\n| File | Description |\n|------|-------------|\n| `venv-map.json` | Full graph data (nodes, edges, summary) |\n| `venv-map.mmd` | Mermaid diagram source |\n| `venv-map.html` | Interactive viewer |\n| `reports.json` | Raw doctorLite reports |\n| `insights.json` | Actionable recommendations |\n\n## Programmatic Usage\n\n```typescript\nimport { doctorLite, scanEnvPaths, mapRender, readRunLog } from 'venvkit';\n\n// Check a specific Python\nconst report = await doctorLite({\n  pythonPath: 'C:\\\\project\\\\.venv\\\\Scripts\\\\python.exe',\n  requiredModules: ['torch', 'transformers'],\n  httpsProbe: true,\n});\n\nconsole.log(report.status); // 'good' | 'warn' | 'bad'\nconsole.log(report.score);  // 0-100\nconsole.log(report.findings); // Array of issues\n\n// Scan for all Python environments\nconst scan = await scanEnvPaths({\n  roots: ['C:\\\\projects'],\n  maxDepth: 5,\n});\n\n// Run doctorLite on all found environments\nconst reports = await Promise.all(\n  scan.pythonPaths.map(p =\u003e doctorLite({ pythonPath: p }))\n);\n\n// Load task execution history\nconst runs = await readRunLog('.venvkit/runs.jsonl');\n\n// Generate ecosystem visualization\nconst { graph, mermaid, insights } = mapRender(reports, runs, {\n  taskMode: 'clustered', // 'none' | 'runs' | 'clustered'\n  includeHotEdgeLabels: true,\n});\n```\n\n## Run Log Schema\n\nTrack task executions by appending events to a JSONL file:\n\n```typescript\nimport { appendRunLog, newRunId } from 'venvkit';\n\nawait appendRunLog('.venvkit/runs.jsonl', {\n  version: '1.0',\n  runId: newRunId(),\n  at: new Date().toISOString(),\n  task: {\n    name: 'train',\n    command: 'python train.py --epochs 10',\n    requirements: { packages: ['torch', 'transformers'] },\n  },\n  selected: {\n    pythonPath: 'C:\\\\project\\\\.venv\\\\Scripts\\\\python.exe',\n    score: 95,\n    status: 'good',\n  },\n  outcome: {\n    ok: true,\n    exitCode: 0,\n    durationMs: 45000,\n  },\n});\n```\n\n## Task Clustering\n\nWhen you have many task runs, venvkit clusters them by signature:\n\n```typescript\nimport { clusterRuns, isFlaky, getFailingEnvs } from 'venvkit';\n\nconst clusters = clusterRuns(runs);\n\nfor (const c of clusters) {\n  console.log(`${c.sig.name}: ${c.ok}/${c.runs} (${(c.successRate * 100).toFixed(0)}%)`);\n\n  if (isFlaky(c)) {\n    console.log(`  WARNING: Flaky task!`);\n    const badEnvs = getFailingEnvs(c, 3);\n    console.log(`  Failing most on: ${badEnvs.map(e =\u003e e.pythonPath).join(', ')}`);\n  }\n}\n```\n\n## Graph Schema\n\nThe `mapRender` output follows a stable JSON schema:\n\n```typescript\ntype GraphJSONv1 = {\n  version: '1.0';\n  generatedAt: string;\n  host: { os: string; arch: string; hostname: string };\n  summary: {\n    envCount: number;\n    baseCount: number;\n    taskCount: number;\n    healthy: number;\n    warning: number;\n    broken: number;\n    runsPassed: number;\n    runsFailed: number;\n    topIssues: Array\u003c{ code: string; count: number; hint: string }\u003e;\n  };\n  nodes: GraphNode[];\n  edges: GraphEdge[];\n};\n```\n\n### Node Types\n\n| Type | Description |\n|------|-------------|\n| `base` | Base Python interpreter (e.g., `C:\\Python311`) |\n| `venv` | Virtual environment |\n| `task` | Task signature (clustered runs) |\n\n### Edge Types\n\n| Type | Description |\n|------|-------------|\n| `USES_BASE` | venv → base relationship |\n| `ROUTES_TASK_TO` | task → env routing |\n| `FAILED_RUN` | task → env failure (dashed in Mermaid) |\n\n## Finding Codes\n\n| Code | Severity | Description |\n|------|----------|-------------|\n| `SSL_BROKEN` | bad | SSL module fails to import |\n| `CERT_STORE_FAIL` | warn | HTTPS certificate verification fails |\n| `DLL_LOAD_FAIL` | bad | Native extension DLL loading fails |\n| `ABI_MISMATCH` | bad | Binary incompatibility (ARM/x86) |\n| `PIP_MISSING` | warn | pip not available |\n| `PIP_CHECK_FAIL` | warn | Dependency conflicts detected |\n| `USER_SITE_LEAK` | warn | User site-packages enabled in venv |\n| `PYTHONPATH_INJECTED` | warn | PYTHONPATH environment variable set |\n| `ARCH_MISMATCH` | bad | 32-bit Python when 64-bit required |\n| `PYVENV_CFG_INVALID` | warn | Broken or missing pyvenv.cfg |\n\n## Development\n\n```bash\nnpm install\nnpm run typecheck  # Type check\nnpm run test       # Run tests\nnpm run build      # Build to dist/\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcp-tool-shop-org%2Fvenvkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmcp-tool-shop-org%2Fvenvkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcp-tool-shop-org%2Fvenvkit/lists"}