GPU executor protocols — DIP boundary for GPU-bound work.
Two protocols, ISP-split: IGpuExecutor — does work (embed, generate, rerank) IGpuStatus — introspects backend (free VRAM, inflight, queued)
Closed ADTs cross the boundary: GpuRequest — what the caller wants done + declared :gpu/vram-mb budget GpuResponse — output payload + executor-id + duration-ms
Layering rationale: hive-mcp consumers (embedders, future rerankers, future local-LLM compression) depend on these protocols, never on a concrete backend. hive-weave.gpu admits requests against a VRAM budget BEFORE dispatching through gpu-execute!. New backends (ollama, llama.cpp, vLLM) extend the protocols; admission control + consumers stay closed (OCP).
CPPB mapping: Promote — GpuRequest is the ADT shape callers build up Pipeline — hive-weave.gpu/gpu-fork-join admits + dispatches Boundary — concrete IGpuExecutor impl performs IO
SOLID: SRP — IGpuExecutor does work; IGpuStatus introspects; admission lives in hive-weave OCP — new backends extend; consumers + admission untouched LSP — every executor returns the same Result shape (see schemas below) ISP — split work vs introspection so a probe-only sidecar (nvidia-smi) can satisfy IGpuStatus without claiming work-execution capability DIP — every consumer depends on these protocols, never on a record
GPU executor protocols — DIP boundary for GPU-bound work.
Two protocols, ISP-split:
IGpuExecutor — does work (embed, generate, rerank)
IGpuStatus — introspects backend (free VRAM, inflight, queued)
Closed ADTs cross the boundary:
GpuRequest — what the caller wants done + declared :gpu/vram-mb budget
GpuResponse — output payload + executor-id + duration-ms
Layering rationale:
hive-mcp consumers (embedders, future rerankers, future local-LLM
compression) depend on these protocols, never on a concrete backend.
hive-weave.gpu admits requests against a VRAM budget BEFORE dispatching
through gpu-execute!. New backends (ollama, llama.cpp, vLLM) extend the
protocols; admission control + consumers stay closed (OCP).
CPPB mapping:
Promote — GpuRequest is the ADT shape callers build up
Pipeline — hive-weave.gpu/gpu-fork-join admits + dispatches
Boundary — concrete IGpuExecutor impl performs IO
SOLID:
SRP — IGpuExecutor does work; IGpuStatus introspects; admission lives in hive-weave
OCP — new backends extend; consumers + admission untouched
LSP — every executor returns the same Result shape (see schemas below)
ISP — split work vs introspection so a probe-only sidecar (nvidia-smi)
can satisfy IGpuStatus without claiming work-execution capability
DIP — every consumer depends on these protocols, never on a recordExecutes GPU work. Concretions: ollama HTTP, llama.cpp, vLLM, raw CUDA.
Every method returns Result (ok/err) from hive-dsl.result. No exceptions cross the boundary; transport failures classify as :gpu/transport-failed, payload mismatches as :gpu/payload-invalid, etc.
Executes GPU work. Concretions: ollama HTTP, llama.cpp, vLLM, raw CUDA. Every method returns Result (ok/err) from hive-dsl.result. No exceptions cross the boundary; transport failures classify as :gpu/transport-failed, payload mismatches as :gpu/payload-invalid, etc.
(executor-capabilities this)Set of supported :gpu/op keywords, drawn from #{:embed :generate :rerank}. Pure introspection — no IO.
Set of supported :gpu/op keywords, drawn from #{:embed :generate :rerank}.
Pure introspection — no IO.(executor-id this)Stable keyword identifying this executor (e.g. :ollama, :llama-cpp). Used by callers for routing and by hive-weave admission for telemetry.
Stable keyword identifying this executor (e.g. :ollama, :llama-cpp). Used by callers for routing and by hive-weave admission for telemetry.
(gpu-execute! this request)Execute a GpuRequest. Returns Result<GpuResponse>. Implementations dispatch by (:gpu/op request) and MUST emit (err :gpu/unsupported-op ...) for ops outside executor-capabilities.
Execute a GpuRequest. Returns Result<GpuResponse>. Implementations dispatch by (:gpu/op request) and MUST emit (err :gpu/unsupported-op ...) for ops outside executor-capabilities.
Introspects a GPU backend's resource state. Sibling to IGpuExecutor; an nvidia-smi probe satisfies IGpuStatus without claiming IGpuExecutor.
ISP rationale: an admission scheduler reads status to decide; it does NOT need the ability to run work. A probe satisfies status; a concrete executor satisfies both (its status snapshot draws on its own counters).
Introspects a GPU backend's resource state. Sibling to IGpuExecutor; an nvidia-smi probe satisfies IGpuStatus without claiming IGpuExecutor. ISP rationale: an admission scheduler reads status to decide; it does NOT need the ability to run work. A probe satisfies status; a concrete executor satisfies both (its status snapshot draws on its own counters).
(gpu-status this)Snapshot of backend state. Returns Result<map> with at least: {:vram-free-mb long :vram-total-mb long :inflight long ; in-flight gpu-execute! calls :queued long ; admission-queued tasks :backend-id keyword} ; e.g. :nvidia-smi, :ollama Probes that cannot read all fields MAY return -1 for unknowns rather than err, so callers can distinguish 'unknown' from 'no driver'.
Snapshot of backend state. Returns Result<map> with at least:
{:vram-free-mb long
:vram-total-mb long
:inflight long ; in-flight gpu-execute! calls
:queued long ; admission-queued tasks
:backend-id keyword} ; e.g. :nvidia-smi, :ollama
Probes that cannot read all fields MAY return -1 for unknowns rather
than err, so callers can distinguish 'unknown' from 'no driver'.cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |