feat: add isolated Python module runtime

[TomCC7]

Contribution path

• Stacked on feat(damiao): support native macOS CAN transport #3465.

Problem

dimOS needs to run Python modules with dependency sets that conflict with the host environment while preserving normal typed streams, RPCs, skills, module references, lifecycle management, and restart behavior.

Solution

• Add IsolatedPythonModule, a host-side contract backed by a concrete subclass in a sibling Python project.
• Keep RPC definitions on the contract and forward calls through a unique internal runtime endpoint.
• Forward streams and injected module references to the isolated runtime.
• Support locked uv projects and Pixi-provided uv without installing runtime dependencies into the host environment.
• Add a runnable external module example and lifecycle, validation, RPC, restart, and shutdown coverage.

How to Test

uv run pytest dimos/core/test_isolated_python_module.py dimos/core/test_isolated_python_bootstrap.py dimos/core/test_isolated_python_end_to_end.py -q
uv run python examples/external_python_module/run.py

Validated on the #3465 base: 21 focused tests passed, targeted mypy passed, pre-commit passed, and the real subprocess example exited cleanly.

Checklist

• I have read and approved the CLA.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
dimensional	🟢 Ready	View Preview	Aug 15, 2026, 3:49 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[codecov]

Codecov Report

❌ Patch coverage is 80.39216% with 90 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
dimos/core/isolated_python_bootstrap.py	48.68%	35 Missing and 4 partials ⚠️
dimos/core/isolated_python_module.py	79.89%	22 Missing and 15 partials ⚠️
dimos/core/test_isolated_python_bootstrap.py	87.71%	7 Missing ⚠️
dimos/core/native_module.py	25.00%	6 Missing ⚠️
dimos/core/test_isolated_python_module.py	98.66%	1 Missing ⚠️

@@            Coverage Diff             @@
##             main    #3478      +/-   ##
==========================================
+ Coverage   74.05%   76.05%   +2.00%     
==========================================
  Files        1283     1229      -54     
  Lines      124704   119197    -5507     
  Branches    11141    11117      -24     
==========================================
- Hits        92349    90661    -1688     
+ Misses      29493    25440    -4053     
- Partials     2862     3096     +234     

Flag	Coverage Δ
OS-ubuntu-24.04-arm	70.47% <80.39%> (+0.03%)	⬆️
OS-ubuntu-latest	72.25% <80.39%> (+0.03%)	⬆️
Py-3.10	72.25% <80.39%> (+0.03%)	⬆️
Py-3.11	72.25% <80.39%> (+0.03%)	⬆️
Py-3.12	72.25% <80.39%> (+0.03%)	⬆️
Py-3.13	72.25% <80.39%> (+0.03%)	⬆️
Py-3.14	72.25% <80.39%> (+0.03%)	⬆️
Py-3.14t	72.25% <80.39%> (+0.03%)	⬆️
SelfHosted-Large	29.76% <30.06%> (+0.05%)	⬆️
SelfHosted-Linux	35.81% <30.06%> (-0.03%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
dimos/core/rpc_client.py	86.66% <100.00%> (+0.83%)	⬆️
dimos/core/test_isolated_python_end_to_end.py	100.00% <100.00%> (ø)
dimos/core/test_isolated_python_module.py	98.66% <98.66%> (ø)
dimos/core/native_module.py	74.70% <25.00%> (-1.39%)	⬇️
dimos/core/test_isolated_python_bootstrap.py	87.71% <87.71%> (ø)
dimos/core/isolated_python_module.py	79.89% <79.89%> (ø)
dimos/core/isolated_python_bootstrap.py	48.68% <48.68%> (ø)

... and 85 files with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[greptile-apps]

Too many files changed for review (139 files, 100 file limit).

Bypass the limit by tagging @greptile-apps to review.