python-bridge

name	python-bridge
description	Native Python execution via the local Python bridge. Use when the user asks about running Python locally, setting up the Python bridge, LibreOffice conversion, or troubleshooting Python connectivity.
compatibility	Python tools always work via in-browser Pyodide. The native bridge is optional and requires a local bridge process running on the user's machine.
metadata	{"tool-name":"python_run","docs":"docs/python-bridge-contract.md"}

Python Bridge

The Python bridge gives Pi access to native Python on the user's machine. It is an opt-in capability that upgrades the default in-browser Pyodide runtime.

Pyodide (default) vs Native bridge

	Pyodide (default)	Native bridge
Setup	None — works out of the box	Requires local bridge process
Packages	Pure-Python only (numpy, pandas, scipy via micropip)	Full ecosystem (C extensions, ML libs, etc.)
Filesystem	No local filesystem access	Full local filesystem
LibreOffice	Not available	Available (libreoffice_convert tool)
Long scripts	WebAssembly limits	No limits

Prefer Pyodide unless the task requires native-only capabilities.

How to set it up

1. Start the bridge

npx pi-for-excel-python-bridge

This defaults to real execution mode on https://localhost:3340.

Options:

• --install-missing — auto-install Python/LibreOffice via Homebrew (macOS)
• PYTHON_BRIDGE_MODE=stub — safe simulated mode
• PYTHON_BRIDGE_TOKEN=your-secret — require auth token
• PYTHON_BRIDGE_PYTHON_BIN=python3.12 — specify Python binary

Requirements:

• python3 must be on PATH (or set PYTHON_BRIDGE_PYTHON_BIN)
• LibreOffice (soffice) is optional — only needed for libreoffice_convert

2. Configure in Pi (optional)

The default URL (https://localhost:3340) works automatically. Override if needed:

/experimental python-bridge-url <url>
/experimental python-bridge-token <token>

Or use: /extensions → Connections → Python bridge

3. First execution

The first time Python runs through the native bridge, Pi will ask for explicit user confirmation (one-time per bridge URL).

Tools

• python_run — execute a Python snippet, inspect stdout/stderr/result
• python_transform_range — read Excel range → run Python → write result back (single tool call)
• libreoffice_convert — convert files between formats (xlsx ↔ csv ↔ pdf) — bridge-only

When the bridge is not running

python_run and python_transform_range fall back to Pyodide automatically. Only libreoffice_convert strictly requires the bridge.

Security

• Loopback-only (localhost)
• Origin allowlist
• Optional bearer token auth
• Python runs with -I isolation flag
• Code/input/output size limits
• Timeout enforcement

Troubleshooting

• Falls back to Pyodide unexpectedly — the bridge process isn't running. Start it with npx pi-for-excel-python-bridge.
• Import errors on Pyodide — the package likely has C extensions. Set up the native bridge.
• LibreOffice convert fails — ensure soffice is on PATH. Install with brew install --cask libreoffice (macOS).
• CORS/cert errors — visit https://localhost:3340 in your browser and accept the certificate.