Adom Desktop - Hello Sample Bridge (Python)

{
  "schema_version": 1,
  "type": "app",
  "slug": "adom-desktop-hello-python-bridge",
  "title": "Adom Desktop - Hello Sample Bridge (Python)",
  "brief": "Minimal third-party Adom Desktop bridge in ~80 lines of Python stdlib. Fork this as a starting point for your own bridge.",
  "version": "1.0.0",
  "tags": [],
  "license": "MIT",
  "sample_prompts": [
    {
      "label": "Install hello-python",
      "prompt": "Install the hello-python sample bridge from the wiki"
    },
    {
      "label": "Try the verbs",
      "prompt": "Run hellopy_ping and hellopy_echo to see how bridge verbs work"
    },
    {
      "label": "Fork to build my own",
      "prompt": "Get the hello-python source so I can fork it as my own bridge starter"
    }
  ],
  "install": {
    "binary_name": "adom-desktop-hello-python-bridge",
    "install_dir": "",
    "install_hint": "",
    "version_cmd": ""
  },
  "readme": "# Sample bridge: hello-python\n\n## What this is\n\n`hello-python` is a **minimal third-party bridge** for Adom Desktop, written in ~80 lines of Python stdlib. It exists so you can install one command, run two verbs, and have a complete mental model of what writing a bridge actually involves — before you commit to integrating your real tool (Altium, MATLAB, an oscilloscope, an inventory system, whatever).\n\nPair it with its twin [`hello-rust`](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-hello-rust-bridge) (same surface, different language) for a side-by-side comparison of the two implementation flavors Adom Desktop supports: `kind: \"python\"` (interpreted) vs. `kind: \"exe\"` (native single-binary).\n\nIf you're getting started, also read the [bridge SDK guide](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-bridges) for the `bridge.json` schema and packaging conventions.\n\n## Try it in 30 seconds\n\n```bash\n# 1. Install from the wiki (anonymous, no GitHub account needed)\nadom-desktop bridge_install '{\"manifestUrl\":\"https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/hello-python-bridge-manifest.json\"}'\n\n# 2. Ping it (auto-spawns the bridge process)\nadom-desktop hellopy_ping\n# → {\"success\":true,\"output\":\"Hello from the Python sample bridge v1.2.0!\",\"language\":\"python\",...}\n\n# 3. Echo something back\nadom-desktop hellopy_echo '{\"message\":\"world\"}'\n# → {\"success\":true,\"output\":\"echo (python): world\",\"echoed\":\"world\",\"language\":\"python\"}\n\n# 4. Confirm it's registered\nadom-desktop bridge_list   # look for \"hello-python\" with verbs hellopy_*\n\n# 5. Uninstall when done\nadom-desktop bridge_uninstall '{\"name\":\"hello-python\"}'\n```\n\nThe bridge process auto-spawns on the first `hellopy_*` call, listens on an OS-assigned ephemeral port (v1.8.31+ dynamic port allocation — no collision with any other bridge), and is killed cleanly on `bridge_uninstall` or app shutdown.\n\n## What's in the box\n\n```\nhello-python/\n├── bridge.json         ← manifest (verb prefixes, spawn config, platforms)\n├── BRIDGE_VERSION      ← semver, kept in sync with bridge.json\n├── server.py           ← ~80 lines, http.server.BaseHTTPRequestHandler\n└── README.md           ← lifecycle notes\n```\n\nThat's the entire bridge. No external pip dependencies — just the Python stdlib.\n\n## The two endpoints every bridge exposes\n\n| Endpoint | When | What it returns |\n|---|---|---|\n| `GET /status` | Adom Desktop polls this after spawn to confirm the bridge is alive | `{\"ok\": true, \"bridge\": \"hello-python\", \"version\": \"...\", \"uptimeSec\": N}` |\n| `POST /command` | Every CLI verb call routes through here | `{\"success\": bool, \"output\": ..., \"error\": ...}` (response shape is conventional, not enforced) |\n\n## How verb routing works\n\n1. `bridge.json` declares `verbPrefixes: [\"hellopy_\"]`\n2. Adom Desktop's registry records that `hellopy_*` belongs to this bridge\n3. When you type `adom-desktop hellopy_ping`, the Tauri runtime:\n   - Spawns `python server.py --port <ephemeral>` if not already running\n   - Polls `/status` until ready\n   - POSTs `{\"command\":\"hellopy_ping\",\"args\":{}}` to `/command`\n   - Streams the JSON response back through the CLI\n\n## The two verbs\n\n| Verb | Args | Returns |\n|---|---|---|\n| `hellopy_ping` | (none) | `{success, output, bridge, language: \"python\", version, uptimeSec, _hint}` |\n| `hellopy_echo` | `{\"message\": \"<str>\"}` | `{success, output, echoed, language: \"python\"}` |\n\nTry `adom-desktop status hellopy_ping` to see the AI-friendly help-map entry that drives Docker Claude usage.\n\n## Forking for your own bridge\n\nThe fastest way to get to a real bridge:\n\n```bash\n# 1. Get the source (anonymous — no GitHub account needed)\ncurl -O https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/hello-python-bridge.zip\nunzip hello-python-bridge.zip && cd hello-python\n\n# 2. Rename the bridge end-to-end\n#    - bridge.json: change \"name\", \"displayName\", \"verbPrefixes\", \"verbs\"\n#    - server.py:   change __version__, rename the if/elif command branches\n#    - BRIDGE_VERSION: reset to 0.1.0\n\n# 3. Replace the verb implementations with calls into your tool's SDK\n#    (Altium COM, MATLAB Engine, instrument SCPI, your REST API, etc.)\n\n# 4. Test locally without packaging:\npython server.py --port 8890   # in one terminal\nadom-desktop bridge_install '{\"manifestUrl\":\"file:///abs/path/to/your/bridge.json\"}'\n\n# 5. Package + ship — see the SDK guide\n```\n\nThe full source tree (with the dynamic-port v1.8.31 wiring intact) is at [`scripts/sample-bridges/hello-python/`](https://github.com/adom-inc/adom-desktop/tree/main/scripts/sample-bridges/hello-python) in the Adom Desktop repo, mirroring what `bridge_install` extracts to your cache dir.\n\n## When Python is the right choice\n\nPick `hello-python` (vs. the Rust flavor) when:\n\n- **Your tool has Python bindings.** KiCad, Fusion 360, OpenCV, NumPy ecosystem — Python is the natural shim.\n- **I/O-bound work.** REST calls, file walks, slow vendor SDKs — Python's overhead is invisible.\n- **Fast iteration.** No compile step. `Ctrl+S` then re-run.\n- **End users already have Python.** Engineers running Adom Desktop on a workstation typically have it.\n\nPick [`hello-rust`](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-hello-rust-bridge) when you need a single static binary, no runtime install, type safety, or CPU-bound performance.\n\n## License\n\nMIT. Fork freely, sell what you build on top.\n\n## See also\n\n- [Adom Desktop bridge SDK guide](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-bridges) — `bridge.json` schema, packaging, lifecycle\n- [`hello-rust`](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-hello-rust-bridge) — Rust port of this same surface\n- [Bridges registry](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-bridges-registry) — community-maintained list of installable bridges\n- [Reference bridges: KiCad, Fusion 360, Puppeteer](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-bridges-registry) — full-complexity production examples\n",
  "author": {
    "name": "Kyle Bergstedt",
    "email": "[email protected]"
  },
  "visibility": {
    "public": true
  },
  "hero": {
    "type": "image",
    "path": "hero-logo.png"
  },
  "discovery_triggers": [
    "hello world bridge",
    "sample bridge",
    "example bridge",
    "python bridge starter",
    "bridge template python",
    "how to write a bridge",
    "bridge starter kit",
    "hellopy"
  ],
  "discovery_pitch": null,
  "metadata": {},
  "created_at": "2026-05-28T05:28:42.608Z",
  "updated_at": "2026-06-21T12:35:38.658Z",
  "skills": [],
  "changelog": "Set descriptive title to the Adom Desktop - <name> naming convention for app-index consistency",
  "org": "adom"
}