RFC: @tywrapped ecosystem - curated Python library wrappers for npm #168
Conversation
Proposes a curated ecosystem of pre-wrapped Python libraries published to npm under the @tywrapped organization. Key proposals: - Governance: Central org with trusted maintainers, Open Collective funding - Versioning: Mirror upstream, compound version for tywrap patches - Quality: Two-badge system (quality tier + support breadth) - Runtime: Auto-detection with explicit override option - Breaking changes: Mirror upstream directly, transparent pass-through Seeking community feedback on this direction before implementation. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
📝 WalkthroughWalkthroughA comprehensive RFC document was added outlining the Tywrapped ecosystem vision, defining pre-wrapped Python libraries for JavaScript/TypeScript developers. The document covers governance, naming conventions, versioning, CI/CD pipelines, runtime selection, initial launch libraries, and phased implementation steps. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
|
@CodeRabbit help |
ChatThere are 3 ways to chat with CodeRabbit:
CodeRabbit commands
Other keywords and placeholders
CodeRabbit configuration file (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
In `@docs/plans/2026-01-22-tywrapped-ecosystem-vision.md`:
- Line 330: The emphasized line "**Recommended approach: JSON passthrough**"
triggers MD036; replace the emphasis with a proper Markdown heading (e.g.,
change it to a level-3 heading like "### Recommended approach: JSON
passthrough") so the line is a heading rather than emphasized text and satisfies
the MD036 rule.
- Around line 198-201: The fenced code block containing "@tywrapped/numpy" (and
the other fenced blocks showing runtime/quality lines) lacks blank lines before
and after, triggering MD031; edit each fenced block (e.g., the block with
"@tywrapped/numpy" and the similar blocks around the other occurrences) to
ensure there is exactly one blank line above the opening ``` and one blank line
below the closing ``` so each fenced code block is separated from surrounding
text.
- Around line 153-165: Add language identifiers to the fenced code blocks that
triggered markdownlint MD040 (e.g., the block containing the numbered pipeline
with arrows "1. Trigger (Dependabot or tywrap release) … 6. Publish to npm" and
the other flagged fences), replacing opening triple backticks (```) with a
language-specific fence such as ```text or ```bash or ```typescript as
appropriate so each fence includes a language token; apply the same change to
the other flagged blocks referenced in the comment (the fences at the other
noted locations) to satisfy MD040.
- Around line 355-376: Add blank lines before and after each heading (e.g.,
"Phase 1: Foundation", "Phase 2: Template & Tooling", etc.) to satisfy MD022,
and convert all ordered list prefixes to "1." so Markdown auto-numbers (for
example, change "1., 2., 3." to "1." for items under each phase such as the
items under "Phase 1: Foundation" and "Phase 2: Template & Tooling"); ensure the
heading/section blocks and their lists have a single blank line separating them
from surrounding text so MD029 is resolved.
📜 Review details
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (1)
docs/plans/2026-01-22-tywrapped-ecosystem-vision.md
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: bbopen
Repo: bbopen/tywrap PR: 127
File: runtime/python_bridge.py:99-123
Timestamp: 2026-01-19T21:49:05.612Z
Learning: In the tywrap repository, TYWRAP_REQUEST_MAX_BYTES uses strict integer parsing that rejects values with trailing characters (e.g., "1024abc"). This differs from TYWRAP_CODEC_MAX_BYTES, which uses tolerant/best-effort parsing that accepts numeric prefixes. The strict policy for REQUEST_MAX_BYTES ensures explicit integer values and consistent parse behavior across Node/Python implementations.
📚 Learning: 2026-01-19T21:14:40.872Z
Learnt from: bbopen
Repo: bbopen/tywrap PR: 127
File: src/runtime/bridge-core.ts:260-263
Timestamp: 2026-01-19T21:14:40.872Z
Learning: In `src/runtime/bridge-core.ts` and similar hot request/response loop implementations in the tywrap repository, avoid adding extra defensive validation (e.g., runtime shape checks on error payloads) in tight loops unless the protocol boundary is untrusted or there's a concrete bug report. The Python bridge protocol is controlled and validated via tests, so defensive checks would add unnecessary branching overhead without meaningful benefit.
Applied to files:
docs/plans/2026-01-22-tywrapped-ecosystem-vision.md
🪛 markdownlint-cli2 (0.18.1)
docs/plans/2026-01-22-tywrapped-ecosystem-vision.md
153-153: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
198-198: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
198-198: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
223-223: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
305-305: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
318-318: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
330-330: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
355-355: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
361-361: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
362-362: Ordered list item prefix
Expected: 1; Actual: 5; Style: 1/2/3
(MD029, ol-prefix)
363-363: Ordered list item prefix
Expected: 2; Actual: 6; Style: 1/2/3
(MD029, ol-prefix)
364-364: Ordered list item prefix
Expected: 3; Actual: 7; Style: 1/2/3
(MD029, ol-prefix)
366-366: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
367-367: Ordered list item prefix
Expected: 1; Actual: 8; Style: 1/2/3
(MD029, ol-prefix)
368-368: Ordered list item prefix
Expected: 2; Actual: 9; Style: 1/2/3
(MD029, ol-prefix)
369-369: Ordered list item prefix
Expected: 3; Actual: 10; Style: 1/2/3
(MD029, ol-prefix)
371-371: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
372-372: Ordered list item prefix
Expected: 1; Actual: 11; Style: 1/2/3
(MD029, ol-prefix)
373-373: Ordered list item prefix
Expected: 2; Actual: 12; Style: 1/2/3
(MD029, ol-prefix)
374-374: Ordered list item prefix
Expected: 3; Actual: 13; Style: 1/2/3
(MD029, ol-prefix)
376-376: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
| ``` | ||
| 1. Trigger (Dependabot or tywrap release) | ||
| ↓ | ||
| 2. CI regenerates wrappers | ||
| ↓ | ||
| 3. Run test suite (based on health tier) | ||
| ↓ | ||
| 4. If tests pass → Create PR / request approval | ||
| ↓ | ||
| 5. Library maintainer reviews/approves | ||
| ↓ | ||
| 6. Publish to npm | ||
| ``` |
There was a problem hiding this comment.
Add language identifiers to fenced code blocks.
markdownlint reports MD040 on these fences; add a language (e.g., text, bash, typescript) to each to satisfy linting.
✅ Example fix pattern
-```
+```text
1. Trigger (Dependabot or tywrap release)
↓
2. CI regenerates wrappers
↓
3. Run test suite (based on health tier)
↓
4. If tests pass → Create PR / request approval
↓
5. Library maintainer reviews/approves
↓
6. Publish to npm
-```
+```Also applies to: 198-201, 223-226, 305-315, 318-323
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
153-153: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In `@docs/plans/2026-01-22-tywrapped-ecosystem-vision.md` around lines 153 - 165,
Add language identifiers to the fenced code blocks that triggered markdownlint
MD040 (e.g., the block containing the numbered pipeline with arrows "1. Trigger
(Dependabot or tywrap release) … 6. Publish to npm" and the other flagged
fences), replacing opening triple backticks (```) with a language-specific fence
such as ```text or ```bash or ```typescript as appropriate so each fence
includes a language token; apply the same change to the other flagged blocks
referenced in the comment (the fences at the other noted locations) to satisfy
MD040.
| ``` | ||
| @tywrapped/numpy | ||
| Quality: 🥇 Gold | Support: upstream (1.24+) | Runtimes: node, browser | ||
| ``` |
There was a problem hiding this comment.
Add blank lines around fenced code blocks.
markdownlint reports MD031; ensure a blank line before and after each fenced block for consistent Markdown rendering.
Also applies to: 223-226, 318-323
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
198-198: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
198-198: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In `@docs/plans/2026-01-22-tywrapped-ecosystem-vision.md` around lines 198 - 201,
The fenced code block containing "@tywrapped/numpy" (and the other fenced blocks
showing runtime/quality lines) lacks blank lines before and after, triggering
MD031; edit each fenced block (e.g., the block with "@tywrapped/numpy" and the
similar blocks around the other occurrences) to ensure there is exactly one
blank line above the opening ``` and one blank line below the closing ``` so
each fenced code block is separated from surrounding text.
|
|
||
| ### Adding node-calls-python Support | ||
|
|
||
| **Recommended approach: JSON passthrough** |
There was a problem hiding this comment.
Avoid using emphasis as a heading.
MD036 flags this line; replace the emphasized line with a proper heading level (e.g., ### Recommended approach: JSON passthrough).
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
330-330: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🤖 Prompt for AI Agents
In `@docs/plans/2026-01-22-tywrapped-ecosystem-vision.md` at line 330, The
emphasized line "**Recommended approach: JSON passthrough**" triggers MD036;
replace the emphasis with a proper Markdown heading (e.g., change it to a
level-3 heading like "### Recommended approach: JSON passthrough") so the line
is a heading rather than emphasized text and satisfies the MD036 rule.
| ### Phase 1: Foundation (before launch) | ||
| 1. Register "tywrapped" trademark | ||
| 2. Set up GitHub org (`tywrapped`) and npm org (`@tywrapped`) | ||
| 3. Create Open Collective account | ||
| 4. Secure domain (tywrapped.org or similar) | ||
|
|
||
| ### Phase 2: Template & Tooling | ||
| 5. Create template repository with standardized CI/CD | ||
| 6. Build badge generation tooling for health indicators | ||
| 7. Document governance charter and contribution guidelines | ||
|
|
||
| ### Phase 3: Proof of Concept | ||
| 8. Build `@tywrapped/numpy` as first package | ||
| 9. Validate CI/CD pipeline with real upstream updates | ||
| 10. Gather feedback, iterate on template | ||
|
|
||
| ### Phase 4: Expansion | ||
| 11. Add 2-3 more high-priority packages (scipy, scikit-learn) | ||
| 12. Recruit initial maintainers | ||
| 13. Announce publicly, begin community building | ||
|
|
||
| ### Optional (parallel track) |
There was a problem hiding this comment.
Normalize heading spacing and ordered list numbering.
MD022/MD029 indicate missing blank lines around headings and non-1/2/3 list prefixes. Add blank lines around headings and use 1. for all ordered list items so Markdown auto-numbers.
✅ Example fix pattern
-### Phase 1: Foundation (before launch)
-1. Register "tywrapped" trademark
-2. Set up GitHub org (`tywrapped`) and npm org (`@tywrapped`)
-3. Create Open Collective account
-4. Secure domain (tywrapped.org or similar)
+### Phase 1: Foundation (before launch)
+
+1. Register "tywrapped" trademark
+1. Set up GitHub org (`tywrapped`) and npm org (`@tywrapped`)
+1. Create Open Collective account
+1. Secure domain (tywrapped.org or similar)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### Phase 1: Foundation (before launch) | |
| 1. Register "tywrapped" trademark | |
| 2. Set up GitHub org (`tywrapped`) and npm org (`@tywrapped`) | |
| 3. Create Open Collective account | |
| 4. Secure domain (tywrapped.org or similar) | |
| ### Phase 2: Template & Tooling | |
| 5. Create template repository with standardized CI/CD | |
| 6. Build badge generation tooling for health indicators | |
| 7. Document governance charter and contribution guidelines | |
| ### Phase 3: Proof of Concept | |
| 8. Build `@tywrapped/numpy` as first package | |
| 9. Validate CI/CD pipeline with real upstream updates | |
| 10. Gather feedback, iterate on template | |
| ### Phase 4: Expansion | |
| 11. Add 2-3 more high-priority packages (scipy, scikit-learn) | |
| 12. Recruit initial maintainers | |
| 13. Announce publicly, begin community building | |
| ### Optional (parallel track) | |
| ### Phase 1: Foundation (before launch) | |
| 1. Register "tywrapped" trademark | |
| 1. Set up GitHub org (`tywrapped`) and npm org (`@tywrapped`) | |
| 1. Create Open Collective account | |
| 1. Secure domain (tywrapped.org or similar) | |
| ### Phase 2: Template & Tooling | |
| 1. Create template repository with standardized CI/CD | |
| 1. Build badge generation tooling for health indicators | |
| 1. Document governance charter and contribution guidelines | |
| ### Phase 3: Proof of Concept | |
| 1. Build `@tywrapped/numpy` as first package | |
| 1. Validate CI/CD pipeline with real upstream updates | |
| 1. Gather feedback, iterate on template | |
| ### Phase 4: Expansion | |
| 1. Add 2-3 more high-priority packages (scipy, scikit-learn) | |
| 1. Recruit initial maintainers | |
| 1. Announce publicly, begin community building | |
| ### Optional (parallel track) |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
355-355: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
361-361: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
362-362: Ordered list item prefix
Expected: 1; Actual: 5; Style: 1/2/3
(MD029, ol-prefix)
363-363: Ordered list item prefix
Expected: 2; Actual: 6; Style: 1/2/3
(MD029, ol-prefix)
364-364: Ordered list item prefix
Expected: 3; Actual: 7; Style: 1/2/3
(MD029, ol-prefix)
366-366: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
367-367: Ordered list item prefix
Expected: 1; Actual: 8; Style: 1/2/3
(MD029, ol-prefix)
368-368: Ordered list item prefix
Expected: 2; Actual: 9; Style: 1/2/3
(MD029, ol-prefix)
369-369: Ordered list item prefix
Expected: 3; Actual: 10; Style: 1/2/3
(MD029, ol-prefix)
371-371: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
372-372: Ordered list item prefix
Expected: 1; Actual: 11; Style: 1/2/3
(MD029, ol-prefix)
373-373: Ordered list item prefix
Expected: 2; Actual: 12; Style: 1/2/3
(MD029, ol-prefix)
374-374: Ordered list item prefix
Expected: 3; Actual: 13; Style: 1/2/3
(MD029, ol-prefix)
376-376: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
🤖 Prompt for AI Agents
In `@docs/plans/2026-01-22-tywrapped-ecosystem-vision.md` around lines 355 - 376,
Add blank lines before and after each heading (e.g., "Phase 1: Foundation",
"Phase 2: Template & Tooling", etc.) to satisfy MD022, and convert all ordered
list prefixes to "1." so Markdown auto-numbers (for example, change "1., 2., 3."
to "1." for items under each phase such as the items under "Phase 1: Foundation"
and "Phase 2: Template & Tooling"); ensure the heading/section blocks and their
lists have a single blank line separating them from surrounding text so MD029 is
resolved.
Summary
This RFC proposes creating a curated ecosystem of pre-wrapped Python libraries published to npm under the
@tywrappedorganization, making world-class Python libraries accessible to JavaScript/TypeScript developers.Motivation
JS/TS developers who need PyTorch, NumPy, SciPy, or scikit-learn currently must either learn Python, use inferior JS alternatives, or set up tywrap themselves. This RFC proposes ready-to-use
npm install @tywrapped/numpypackages.Key Proposals
Governance
@tywrappedorg on npm and GitHubVersioning
@tywrapped/numpy@1.26.0@tywrapped/numpy@1.26.0-tywrap.1Quality Indicators
Two separate badges:
Runtime
setRuntime(new InProcessBridge())Breaking Changes
Mirror upstream directly. No buffering or parallel support periods. Users accept upstream's upgrade path.
Initial Launch Libraries
Open for Discussion
Full RFC
See docs/plans/2026-01-22-tywrapped-ecosystem-vision.md for the complete design document.
🤖 Generated with Claude Code