Returns a specification to start this module under a supervisor.

See Supervisor.

@spec ensure_initialised() :: :ok | {:error, term()}

Materialise the uv-managed venv and initialise the PythonX interpreter from the jido_gralkor-owned @pyproject_toml. Idempotent within a VM: a flag in :persistent_term short-circuits the second call so we never hit the NIF's "already been initialized" guard when more than one Gralkor.Python boots.

@spec install_async_runtime() :: :ok | {:error, term()}

Spin up a daemon-thread asyncio event loop and stash it on asyncio as _gralkor_loop plus a _gralkor_run(coro) helper that submits onto it.

Must run once per Pythonx interpreter, before any code that calls into graphiti via asyncio._gralkor_run. Idempotent — the second call is a no-op.

Why: Pythonx.eval creates a fresh event loop per asyncio.run call. AsyncFalkorDB (and any redis-async connection) binds its connections to the loop they were created on; reusing them on a different loop raises "Future attached to a different loop". The spike measured the alternative pattern (Step 6 in pythonx-spike/spike.exs) at ~56µs per call vs ~112µs for asyncio.run — and, crucially, it shares one loop across all calls so connection reuse works.

@spec reap_redislite_orphans((-> [integer()]), (integer() -> any())) ::
  :ok | {:error, term()}

SIGKILL every pid the listing function returns. Pure plumbing — accepts injected list/kill functions so the unit test doesn't have to spawn real redis processes.

@spec smoke_import_graphiti() :: :ok | {:error, term()}

Try to import graphiti_core via Pythonx; surface any failure as {:error, _}.

@spec smoke_import_provider_clients(atom()) :: :ok | {:error, term()}

Import the graphiti LLM, embedder, and reranker clients for provider. Returns {:error, {:unsupported_provider, provider}} for a provider the pool would refuse anyway.

@spec sweep_orphans_once((-> [integer()]), (integer() -> any())) :: :ok

Reap on the first sweep this VM performs, and nothing on any later one.

Only the first Gralkor.Python to boot runs before this VM has started a server of its own, so every later sweep would be aiming at a live server we own — a daemonised, init-reparented redis-server carries no evidence of which VM spawned it.