<p>🙋‍♂️ <strong>Claim: battle-tested idea, not AI-slop</strong>. I carefully designed the architecture and crafted the implementation mostly by myself (&gt;80%). AI assistance is present but mainly for creating unit tests and standalone utils.</p> <p>I just release <a href="https://github.com/namoshizun/Runsmith" rel="noopener noreferrer">Runsmith</a>, an Erlang/OTP style supervisor-tree framework for when your Python service/system is made of multiple long-running programs. </p> <h2> Brief Intro </h2> <p>Think of an ETL service with a data poller, a transformer, and a result notifier, each with its own lifecycle, failure modes, and recovery needs. Wiring this by hand with retry loops, watchdog threads, and scattered state flags brittle glue code that is hard to reason about.</p> <p>⚙️ Runsmith brings structure to this problem. Each unit becomes a worker with an explicit FSM lifecycle. A supervisor tree monitors every worker continuously — detecting stalls and timeouts, not just crashes — and confines restarts to the failed unit so the rest of the system keeps running.</p> <h2> Background story </h2> <p>The real origin story: I was building the backend for a safety-protection camera system at work. The camera is used in manufacturing plants so <u>no downtime is unacceptable</u>. The system has multiple processes all running together:</p> <ul> <li> <strong>Web app</strong>: serving the HTTP API and SSE streams</li> <li> <strong>Algorithm worker</strong>: running CV inference on incoming frames</li> <li> <strong>Camera controller</strong>: interacting with the camera device library and polling frames</li> <li> <strong>Background task</strong>: runner for scheduled jobs such as periodic data vacuuming</li> <li><strong>ONVIF service</strong></li> </ul> <p>Each one needed to run indefinitely and recover from failures without dragging the others down. The algorithm worker once stall mid-inference due to third-party driver failures. The FastAPI web app event loop once starved due to someone wrote bad sync code...</p> <p>My first version was a messy soup. Lots of state flags, retry logics, watchdogs and probes desperately trying to hold things together. It worked but hard to maintain and reason about.</p> <p>What I actually wanted was a framework where supervision is a first-class concept, fault isolation is structural rather than bolted on. More importantly, I really want an unified structure for modelling long-running stateful function units.</p> <p>So I built it. Runsmith is essentially what I wished had existed when I started that project 🤗</p> <h2> Fancy version of <code>supervisord</code>? </h2> <p>Nope 🙂‍↔️. Runsmith and supervisord solve different problems. supervisord is an OS-level process control daemon that manages external programs by PID and static config. Runsmith is an in-process, programmable Python library where the supervised unit is a typed worker with an explicit lifecycle.</p> <p>That gives a few advantages not present in supervisord:</p> <ul> <li> <strong>Rich concurrency models</strong>: beyond process-only orchestration, workers can run in threads or co-routines, or even custom execution backends.</li> <li> <strong>Fine-grained health probes</strong>: failure is not just an abnormal process exit, but a constraint violation that can be detected and recovered from.</li> <li> <strong>Supervisor-tree</strong>: Erlang/OTP style supervisor-tree for nested fault domains.</li> </ul>