app

hello-python - sample bridge (Python)

Public Made by Adom

by adom

Minimal third-party Adom Desktop bridge in ~80 lines of Python stdlib. Fork this as a starting point for your own bridge.

Overview Files Skills Discover Packages Releases Dependencies Issues Breadcrumbs Pull Requests Activity
hello-python-bridge / README.md
Download

Hello sample bridge — Python flavor

One of two parallel reference bridges for the Adom Desktop bridge SDK. The Python flavor is a complete working bridge in ~140 lines of stdlib — no pip install, no virtualenv, no external dependencies. Fork this when Python is the natural fit (vendor SDKs with Python bindings: Altium Designer scripting, MATLAB Engine, KiCad's pcbnew, instrument vendor wrappers like pyvisa, etc.). Kept in lock-step with skills/BRIDGE_SDK.md — every current author contract is demonstrated in server.py.

The Rust sibling lives at scripts/sample-bridges/hello-rust/ — same surface, different verb prefix (hellors_ vs hellopy_). Both use port: 0 (v1.8.31+ dynamic OS-assigned ports), so they can be installed simultaneously with no port-collision worry.

What it does

Three verbs:

  • hellopy_ping → returns {"success": true, "output": "Hello from the Python sample bridge v1.3.0!", "language": "python", ...}
  • hellopy_echo with {"message": "..."} → echoes the message back as "echo (python): <msg>"
  • hellopy_describe → the self-doc catalog AD renders in its Verbs tab (one entry per verb, with hint/related/pitfalls)

It also demonstrates the current author contracts you should copy: loopback bind via ADOM_BIND_HOST, the self-reported status-chip LED, rich _hints, caller-provenance logging (it prints which AI thread + container drove each call), and a throttled _reportIssues line inviting bug reports.

How it gets installed end-to-end

Relay calls (from a cloud container / galliaApril) each need --ai-thread "<your thread name>" — AD refuses a relayed command with no caller identity (errorCode: caller_identity_required). Shown on the first line; add it to every relayed call. A LOCAL adom-desktop-cli.exe on the same PC as AD does not need it.

# (from galliaApril, or any machine with adom-desktop CLI on PATH)
adom-desktop --ai-thread "my-thread" bridge_install '{"manifestUrl":"https://wiki.adom.inc/api/v1/pages/adom-desktop-hello-python-bridge/files/adom-bridge-hello-python-manifest.json"}'

# Confirm it's loaded
adom-desktop --ai-thread "my-thread" bridge_list
# → "hello-python" appears alongside the bundled bridges

# Call a verb
adom-desktop --ai-thread "my-thread" hellopy_ping
adom-desktop --ai-thread "my-thread" hellopy_echo '{"message":"world"}'

# Uninstall when done
adom-desktop --ai-thread "my-thread" bridge_uninstall '{"name":"hello-python"}'

Anatomy

File Purpose
bridge.json Required manifest. Declares name, version, spawn config, verb prefixes.
BRIDGE_VERSION Convenience version line (kept in sync with bridge.json's version).
server.py The bridge runtime. Spawned by Adom Desktop on first verb call.

Why pick Python over Rust for your bridge

  • Vendor has Python bindings. KiCad's pcbnew, Autodesk Fusion 360's add-in API, MATLAB Engine, NI-VISA, etc. all have first-class Python.
  • No build step. Edit server.py, restart the bridge, done. Zero compile latency during development.
  • Shorter for I/O-bound work. Spawning subprocesses, parsing files, talking to HTTP services — Python's stdlib gets you there in fewer lines.

Why pick Rust over Python (see hello-rust)

  • Single static binary. No Python install on the user's machine, no version conflicts, no pip install step. The bridge is one self-contained .exe.
  • CPU-bound work. Heavy parsing, image processing, encoding/decoding — Rust is dramatically faster.
  • Static typing + strict error handling. Catches a class of bugs at compile time that Python only hits at runtime.

What's NOT here (intentionally)

  • No node_modules / __pycache__ — keep your bridge zip small.
  • No vendor-specific dependencies — server.py uses stdlib only so it runs on any Python 3.8+.
  • No platform-specific code — the same bridge runs on Windows, macOS, Linux.

For a real bridge (e.g. one that drives Altium Designer), you'd add:

  • Vendor SDK imports / COM/AppleScript calls in server.py
  • Handler modules in handlers/ subdirectory (see plugins/kicad/handlers/ for the pattern)
  • A requirements.txt if you need third-party deps (Adom Desktop runs pip install on first launch — see the SDK guide for the lifecycle)
  • If your bridge calls AD back (the loopback direct API), FORWARD the X-Adom-Caller-Thread/-Container/-Reason headers it received and add X-Adom-Caller-Delegate: hello-python, so the delegation chain survives (BRIDGE_SDK.md "Caller provenance"). This sample only reads + logs them; it never calls AD back.
  • A skills pkg (USER docs) published separately from the runtime zip — the two-artifact layout in the SDK. This sample ships runtime-only.

Shipping a new version

# 1. Bump BRIDGE_VERSION + bridge.json's "version" field
# 2. Package + upload to wiki
bash scripts/release-bridge.sh hello-python

# 3. Tell installed clients to refresh
adom-desktop refresh_bridges

That's the entire ship cycle — no Adom Desktop installer rebuild, no CLI rebuild, no GUI restart.