Local API Server Lifecycle Management#

When the mineru CLI converts documents without a pre-existing server (--api-url is not provided), it automatically spawns a temporary mineru-api process, waits for it to become healthy, uses it for all parsing tasks, and then tears it down. The full lifecycle is managed by two classes in mineru/cli/api_client.py: LocalAPIServer (one-shot) and ReusableLocalAPIServer (singleton wrapper for the Gradio UI).

Startup Sequencing#

LocalAPIServer.start() performs startup in this order:

1. Port allocation — find_free_port() binds 127.0.0.1:0 to get a guaranteed-free ephemeral port. The server is always bound to loopback only.
2. Launch mode selection — get_effective_local_api_launch_mode() resolves to subprocess (default) or spawn. spawn is forced when MINERU_LMDEPLOY_DEVICE is in the MINERU_SPAWN_DEVICE_LIST (currently ["ascend"]), and can be overridden via MINERU_LOCAL_API_LAUNCH_MODE.
3. Environment construction — _build_local_api_server_env() sets MINERU_API_OUTPUT_ROOT, MINERU_API_MAX_CONCURRENT_REQUESTS, MINERU_API_DISABLE_ACCESS_LOG=1, and conditionally MINERU_API_SHUTDOWN_ON_STDIN_EOF=1 (non-Windows subprocess mode only).
4. Process launch:
   • subprocess mode: Spawns python -m mineru.cli.fast_api --host 127.0.0.1 --port <port> [extra_args] via subprocess.Popen with start_new_session=True (POSIX) or CREATE_NEW_PROCESS_GROUP (Windows) 1.
   • spawn mode: Uses multiprocessing.get_context("spawn").Process targeting _run_local_api_via_spawn(), which calls os.setsid() then imports and calls fast_api.main directly. Limited to Linux only 2.
5. atexit registration — atexit.register(self.stop) is called once after the process is launched, guaranteeing cleanup even on unhandled exit 3.

In run_orchestrated_cli, the CLI waits for readiness before submitting any task: it creates a LocalAPIServer, calls start(), then awaits wait_for_local_api_ready() before planning or submitting any parse tasks.

Health Checks#

wait_for_local_api_ready() polls GET /health every 1 second 4 until one of three outcomes:

The startup timeout defaults to 300 seconds and is configurable via MINERU_LOCAL_API_STARTUP_TIMEOUT_SECONDS (minimum 1.0 s) 5.

validate_server_health_payload() enforces two conditions before any traffic is sent:

• status == "healthy" (server task manager is running)
• protocol_version == API_PROTOCOL_VERSION (currently 2) — a version mismatch raises a hard error, not a warning 6.

Shutdown Conditions and Sequencing#

LocalAPIServer.stop() is called from the finally block in run_orchestrated_cli 7 and also via atexit. It delegates to stop_managed_process() (subprocess mode) or _stop_spawn_managed_process() (spawn mode), with a 10-second shutdown timeout (LOCAL_API_SHUTDOWN_TIMEOUT_SECONDS) 8.

subprocess mode shutdown sequence#

1. If MINERU_API_SHUTDOWN_ON_STDIN_EOF=1 was set (non-Windows only): close the process's stdin pipe and wait up to 10 s for graceful exit.
2. If still running: send SIGTERM to the entire process group (os.killpg) and wait up to 10 s.
3. If still running: send SIGKILL and wait up to 10 s. A warning is logged if the process still hasn't exited.
4. On Windows, taskkill /PID /T (graceful) or /F (forceful) replaces the POSIX signals 9.

After the process stops, _cleanup_temp_dir() removes the temporary directory with up to 8 retries at 0.25-second intervals (LOCAL_API_CLEANUP_RETRIES, LOCAL_API_CLEANUP_RETRY_INTERVAL_SECONDS) 10. If all retries fail, a warning is logged with the path for manual cleanup.

The atexit handler is unregistered inside stop() to prevent double-invocation 11.

ReusableLocalAPIServer (Gradio UI)#

The Gradio UI holds a module-level ReusableLocalAPIServer singleton (_gradio_local_api_server). Unlike the CLI's one-shot LocalAPIServer, this wrapper:

• ensure_started() checks if an existing server process is still running; if not, it stops the dead instance and starts a fresh one. Thread-safe via an internal threading.Lock.
• configure() updates extra_cli_args; if the process is already dead, it calls stop() and clears the reference so the next ensure_started() re-launches cleanly.

The Gradio path is not triggered when --api-url is provided (the local process is never started in that case).

Key Constants and Environment Variables#