version: "1.0.1" 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

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.