# 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`](../../../skills/BRIDGE_SDK.md) — every current author contract is demonstrated in `server.py`.

The Rust sibling lives at [`scripts/sample-bridges/hello-rust/`](../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 `_hint`s, 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.

```bash
# (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

```bash
# 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.
