@qvac/inference 0.18.2 → 0.19.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (396) hide show
  1. package/NOTICE +69 -36
  2. package/README.md +1 -5
  3. package/dist/api/assess-model-fit.d.ts +16 -0
  4. package/dist/api/assess-model-fit.js +27 -0
  5. package/dist/api/audio-gen.d.ts +4 -4
  6. package/dist/api/audio-gen.js +17 -6
  7. package/dist/api/completion-stream.d.ts +1 -1
  8. package/dist/api/completion-stream.js +1 -1
  9. package/dist/api/delete-cache.d.ts +7 -1
  10. package/dist/api/delete-cache.js +11 -1
  11. package/dist/api/download-asset.d.ts +1 -1
  12. package/dist/api/download-asset.js +2 -2
  13. package/dist/api/finetune.js +1 -1
  14. package/dist/api/get-loaded-model-info.d.ts +6 -10
  15. package/dist/api/get-loaded-model-info.js +6 -10
  16. package/dist/api/heartbeat.d.ts +5 -22
  17. package/dist/api/heartbeat.js +6 -23
  18. package/dist/api/index.d.ts +36 -35
  19. package/dist/api/index.js +35 -35
  20. package/dist/api/load-model.d.ts +5 -1
  21. package/dist/api/load-model.js +3 -5
  22. package/dist/api/logging-stream-registry.js +1 -1
  23. package/dist/api/resume.d.ts +0 -3
  24. package/dist/api/resume.js +0 -3
  25. package/dist/api/subscribe-logs.js +1 -1
  26. package/dist/api/suspend.d.ts +0 -4
  27. package/dist/api/suspend.js +0 -4
  28. package/dist/api/translate.d.ts +3 -1
  29. package/dist/api/translate.js +16 -8
  30. package/dist/api/unload-model.js +3 -5
  31. package/dist/api/video-request.d.ts +207 -0
  32. package/dist/api/video-request.js +18 -0
  33. package/dist/api/video.d.ts +22 -2
  34. package/dist/api/video.js +25 -15
  35. package/dist/api/vla-helpers.d.ts +1 -2
  36. package/dist/api/vla-helpers.js +1 -2
  37. package/dist/api/vla.js +1 -1
  38. package/dist/api/world-result.d.ts +71 -0
  39. package/dist/api/world-result.js +293 -0
  40. package/dist/api/world.d.ts +143 -0
  41. package/dist/api/world.js +71 -0
  42. package/dist/config/resolve-config.d.ts +1 -1
  43. package/dist/config/resolve-config.js +1 -1
  44. package/dist/constants/index.d.ts +2 -2
  45. package/dist/constants/index.js +2 -2
  46. package/dist/dispatch.js +15 -28
  47. package/dist/errors/index.d.ts +35 -31
  48. package/dist/errors/index.js +66 -56
  49. package/dist/handlers/assess-model-fit.d.ts +10 -0
  50. package/dist/handlers/assess-model-fit.js +75 -0
  51. package/dist/handlers/cancelHandler.js +1 -1
  52. package/dist/handlers/completion-orchestrate.js +1 -1
  53. package/dist/handlers/delete-cache.js +3 -0
  54. package/dist/handlers/download-asset.js +6 -5
  55. package/dist/handlers/finetune.js +1 -1
  56. package/dist/handlers/get-loaded-model-info.js +0 -12
  57. package/dist/handlers/get-model-info.js +1 -1
  58. package/dist/handlers/get-system-resources.js +8 -0
  59. package/dist/handlers/load-model/download-manager.d.ts +1 -1
  60. package/dist/handlers/load-model/download-stats.d.ts +3 -3
  61. package/dist/handlers/load-model/download-stats.js +5 -5
  62. package/dist/handlers/load-model/handler.js +6 -8
  63. package/dist/handlers/load-model/http-verify.d.ts +20 -0
  64. package/dist/handlers/load-model/http-verify.js +54 -0
  65. package/dist/handlers/load-model/http.d.ts +12 -2
  66. package/dist/handlers/load-model/http.js +119 -230
  67. package/dist/handlers/load-model/hyperdrive.d.ts +1 -1
  68. package/dist/handlers/load-model/hyperdrive.js +1 -1
  69. package/dist/handlers/load-model/index.d.ts +2 -2
  70. package/dist/handlers/load-model/index.js +2 -2
  71. package/dist/handlers/load-model/registry-companion-set.d.ts +1 -1
  72. package/dist/handlers/load-model/registry-companion-set.js +1 -1
  73. package/dist/handlers/load-model/registry-download-utils.d.ts +3 -3
  74. package/dist/handlers/load-model/registry-download-utils.js +2 -2
  75. package/dist/handlers/load-model/registry.d.ts +2 -2
  76. package/dist/handlers/load-model/registry.js +4 -4
  77. package/dist/handlers/load-model/resolve-session.d.ts +8 -1
  78. package/dist/handlers/load-model/resolve-session.js +12 -9
  79. package/dist/handlers/load-model/resolve.d.ts +4 -4
  80. package/dist/handlers/load-model/resolve.js +18 -16
  81. package/dist/handlers/load-model/safe-fetch.d.ts +44 -0
  82. package/dist/handlers/load-model/safe-fetch.js +143 -0
  83. package/dist/handlers/load-model/types.d.ts +9 -0
  84. package/dist/handlers/plugin-dispatch.js +1 -4
  85. package/dist/handlers/plugin-invoke.js +1 -4
  86. package/dist/handlers/types.d.ts +0 -2
  87. package/dist/handlers/unload-model.js +1 -4
  88. package/dist/index.d.ts +1 -1
  89. package/dist/index.js +1 -1
  90. package/dist/logging/addon.d.ts +1 -1
  91. package/dist/logging/addon.js +1 -1
  92. package/dist/logging/index.d.ts +5 -5
  93. package/dist/logging/index.js +4 -4
  94. package/dist/logging/logger.d.ts +1 -1
  95. package/dist/logging/logger.js +2 -2
  96. package/dist/models/registry/index.d.ts +1 -1
  97. package/dist/models/registry/index.js +2 -2
  98. package/dist/models/registry/models.d.ts +250 -0
  99. package/dist/models/registry/models.js +2071 -1806
  100. package/dist/models/registry/resource-profiles.d.ts +18 -0
  101. package/dist/models/registry/resource-profiles.js +4934 -0
  102. package/dist/plugins/builtin/audiogen-ggml/config.d.ts +14 -0
  103. package/dist/plugins/builtin/audiogen-ggml/config.js +23 -0
  104. package/dist/plugins/builtin/audiogen-ggml/ops/audio-gen-stream.js +47 -5
  105. package/dist/plugins/builtin/audiogen-ggml/plugin.d.ts +134 -4
  106. package/dist/plugins/builtin/audiogen-ggml/plugin.js +47 -28
  107. package/dist/plugins/builtin/bci-whispercpp-transcription/plugin.d.ts +1 -1
  108. package/dist/plugins/builtin/bci-whispercpp-transcription/plugin.js +3 -3
  109. package/dist/plugins/builtin/ggml-classification/plugin.js +1 -1
  110. package/dist/plugins/builtin/ggml-ocr/plugin.js +2 -2
  111. package/dist/plugins/builtin/ggml-vla/plugin.d.ts +1 -1
  112. package/dist/plugins/builtin/ggml-vla/plugin.js +3 -3
  113. package/dist/plugins/builtin/index.d.ts +12 -12
  114. package/dist/plugins/builtin/index.js +12 -12
  115. package/dist/plugins/builtin/llamacpp-completion/ops/batch-completion-stream.js +2 -2
  116. package/dist/plugins/builtin/llamacpp-completion/ops/completion-stats.d.ts +1 -0
  117. package/dist/plugins/builtin/llamacpp-completion/ops/completion-stats.js +3 -0
  118. package/dist/plugins/builtin/llamacpp-completion/ops/completion-stream.js +37 -26
  119. package/dist/plugins/builtin/llamacpp-completion/ops/context-overflow.d.ts +12 -11
  120. package/dist/plugins/builtin/llamacpp-completion/ops/context-overflow.js +133 -41
  121. package/dist/plugins/builtin/llamacpp-completion/ops/kv-cache-session.d.ts +15 -4
  122. package/dist/plugins/builtin/llamacpp-completion/ops/kv-cache-session.js +79 -17
  123. package/dist/plugins/builtin/llamacpp-completion/plugin.d.ts +22 -8
  124. package/dist/plugins/builtin/llamacpp-completion/plugin.js +10 -13
  125. package/dist/plugins/builtin/llamacpp-embedding/plugin.d.ts +4 -0
  126. package/dist/plugins/builtin/llamacpp-embedding/plugin.js +13 -2
  127. package/dist/plugins/builtin/nmtcpp-translation/plugin.js +2 -2
  128. package/dist/plugins/builtin/parakeet-transcription/plugin.d.ts +2 -2
  129. package/dist/plugins/builtin/parakeet-transcription/plugin.js +3 -3
  130. package/dist/plugins/builtin/sdcpp-generation/ops/upscale.js +1 -1
  131. package/dist/plugins/builtin/sdcpp-generation/ops/video.js +32 -2
  132. package/dist/plugins/builtin/sdcpp-generation/ops/world.d.ts +126 -0
  133. package/dist/plugins/builtin/sdcpp-generation/ops/world.js +820 -0
  134. package/dist/plugins/builtin/sdcpp-generation/plugin.d.ts +153 -4
  135. package/dist/plugins/builtin/sdcpp-generation/plugin.js +134 -13
  136. package/dist/plugins/builtin/tts-ggml/ops/text-to-speech-stream.js +1 -1
  137. package/dist/plugins/builtin/tts-ggml/ops/text-to-speech.js +1 -1
  138. package/dist/plugins/builtin/tts-ggml/plugin.js +2 -2
  139. package/dist/plugins/builtin/whispercpp-transcription/plugin.d.ts +2 -2
  140. package/dist/plugins/builtin/whispercpp-transcription/plugin.js +3 -3
  141. package/dist/plugins/index.d.ts +1 -1
  142. package/dist/plugins/index.js +2 -2
  143. package/dist/plugins/ops/kv-cache-utils.js +1 -1
  144. package/dist/plugins/ops/load-model.js +1 -1
  145. package/dist/plugins/ops/transcribe.js +2 -2
  146. package/dist/plugins/ops/translate.js +4 -12
  147. package/dist/plugins/ops/unload-model.js +19 -21
  148. package/dist/plugins/registry.d.ts +1 -0
  149. package/dist/plugins/registry.js +12 -0
  150. package/dist/profiling/aggregator.d.ts +1 -1
  151. package/dist/profiling/aggregator.js +1 -1
  152. package/dist/profiling/controller.d.ts +1 -1
  153. package/dist/profiling/controller.js +2 -2
  154. package/dist/profiling/envelope.d.ts +0 -1
  155. package/dist/profiling/envelope.js +0 -10
  156. package/dist/profiling/events.d.ts +2 -3
  157. package/dist/profiling/events.js +2 -9
  158. package/dist/profiling/exporters.d.ts +1 -1
  159. package/dist/profiling/exporters.js +3 -3
  160. package/dist/profiling/index.d.ts +13 -14
  161. package/dist/profiling/index.js +12 -13
  162. package/dist/profiling/operation-metrics.d.ts +1 -1
  163. package/dist/profiling/operation-metrics.js +35 -2
  164. package/dist/profiling/operation-wrappers.js +12 -15
  165. package/dist/profiling/profiler.d.ts +1 -2
  166. package/dist/profiling/profiler.js +7 -26
  167. package/dist/profiling/types.d.ts +1 -1
  168. package/dist/rag/handler.js +1 -1
  169. package/dist/rag/handlers/close-workspace.js +1 -1
  170. package/dist/rag/handlers/delete-embeddings.js +1 -1
  171. package/dist/rag/handlers/delete-workspace.js +2 -6
  172. package/dist/rag/handlers/ingest.js +1 -1
  173. package/dist/rag/handlers/list-workspaces.d.ts +1 -1
  174. package/dist/rag/handlers/list-workspaces.js +1 -1
  175. package/dist/rag/handlers/reindex.js +1 -1
  176. package/dist/rag/handlers/save-embeddings.js +1 -1
  177. package/dist/rag/handlers/search.js +1 -1
  178. package/dist/rag/index.d.ts +11 -11
  179. package/dist/rag/index.js +11 -11
  180. package/dist/rag/rag-workspace-manager.d.ts +4 -2
  181. package/dist/rag/rag-workspace-manager.js +268 -15
  182. package/dist/registry.js +8 -58
  183. package/dist/resources/collector.d.ts +3 -1
  184. package/dist/resources/collector.js +91 -9
  185. package/dist/resources/instance.d.ts +1 -1
  186. package/dist/resources/instance.js +1 -1
  187. package/dist/resources/model-fit/assess.d.ts +36 -0
  188. package/dist/resources/model-fit/assess.js +679 -0
  189. package/dist/resources/model-fit/calibration/darwin-arm64.d.ts +8 -0
  190. package/dist/resources/model-fit/calibration/darwin-arm64.js +36 -0
  191. package/dist/resources/model-fit/calibration/darwin-x64.d.ts +8 -0
  192. package/dist/resources/model-fit/calibration/darwin-x64.js +38 -0
  193. package/dist/resources/model-fit/calibration/fit.d.ts +73 -0
  194. package/dist/resources/model-fit/calibration/fit.js +152 -0
  195. package/dist/resources/model-fit/calibration/index.d.ts +37 -0
  196. package/dist/resources/model-fit/calibration/index.js +75 -0
  197. package/dist/resources/model-fit/calibration/linux-arm64.d.ts +8 -0
  198. package/dist/resources/model-fit/calibration/linux-arm64.js +38 -0
  199. package/dist/resources/model-fit/calibration/linux-x64-vulkan.d.ts +8 -0
  200. package/dist/resources/model-fit/calibration/linux-x64-vulkan.js +39 -0
  201. package/dist/resources/model-fit/calibration/linux-x64.d.ts +8 -0
  202. package/dist/resources/model-fit/calibration/linux-x64.js +38 -0
  203. package/dist/resources/model-fit/calibration/win32-x64-vulkan-shared.d.ts +8 -0
  204. package/dist/resources/model-fit/calibration/win32-x64-vulkan-shared.js +39 -0
  205. package/dist/resources/model-fit/calibration/win32-x64-vulkan.d.ts +8 -0
  206. package/dist/resources/model-fit/calibration/win32-x64-vulkan.js +36 -0
  207. package/dist/resources/model-fit/calibration/win32-x64.d.ts +8 -0
  208. package/dist/resources/model-fit/calibration/win32-x64.js +38 -0
  209. package/dist/resources/model-fit/estimators/llm.d.ts +46 -0
  210. package/dist/resources/model-fit/estimators/llm.js +222 -0
  211. package/dist/resources/model-fit/estimators/whisper.d.ts +10 -0
  212. package/dist/resources/model-fit/estimators/whisper.js +77 -0
  213. package/dist/resources/model-fit/floor.d.ts +31 -0
  214. package/dist/resources/model-fit/floor.js +65 -0
  215. package/dist/resources/model-fit/types.d.ts +120 -0
  216. package/dist/resources/model-fit/types.js +1 -0
  217. package/dist/resources/native.d.ts +1 -1
  218. package/dist/resources/native.js +15 -0
  219. package/dist/resources/normalize.d.ts +1 -1
  220. package/dist/resources/types.d.ts +14 -0
  221. package/dist/runtime/index.d.ts +5 -5
  222. package/dist/runtime/index.js +2 -2
  223. package/dist/runtime/lifecycle.js +5 -7
  224. package/dist/runtime/model-registry.d.ts +0 -14
  225. package/dist/runtime/model-registry.js +17 -40
  226. package/dist/runtime/registry-client.js +1 -1
  227. package/dist/runtime/request-context.d.ts +3 -3
  228. package/dist/runtime/request-context.js +13 -1
  229. package/dist/runtime/request-registry.d.ts +1 -1
  230. package/dist/runtime/request-registry.js +4 -5
  231. package/dist/runtime/state.d.ts +1 -1
  232. package/dist/runtime/state.js +18 -3
  233. package/dist/schemas/assess-model-fit.d.ts +311 -0
  234. package/dist/schemas/assess-model-fit.js +182 -0
  235. package/dist/schemas/audio-gen.d.ts +437 -7
  236. package/dist/schemas/audio-gen.js +131 -19
  237. package/dist/schemas/batch-completion-stream.d.ts +5 -2
  238. package/dist/schemas/batch-completion-stream.js +3 -3
  239. package/dist/schemas/bci-config.js +73 -27
  240. package/dist/schemas/bci.d.ts +3 -3
  241. package/dist/schemas/bci.js +5 -5
  242. package/dist/schemas/cancel.d.ts +5 -0
  243. package/dist/schemas/cancel.js +1 -0
  244. package/dist/schemas/classification.js +13 -6
  245. package/dist/schemas/common.d.ts +695 -335
  246. package/dist/schemas/common.js +33 -31
  247. package/dist/schemas/completion-event.d.ts +5 -2
  248. package/dist/schemas/completion-event.js +2 -1
  249. package/dist/schemas/completion-stream.d.ts +3 -5
  250. package/dist/schemas/completion-stream.js +4 -8
  251. package/dist/schemas/config.d.ts +640 -18
  252. package/dist/schemas/config.js +50 -8
  253. package/dist/schemas/download-asset.d.ts +19 -1
  254. package/dist/schemas/download-asset.js +20 -4
  255. package/dist/schemas/engine-addon-map.d.ts +1 -1
  256. package/dist/schemas/engine-addon-map.js +3 -3
  257. package/dist/schemas/error.d.ts +2 -2
  258. package/dist/schemas/error.js +2 -2
  259. package/dist/schemas/errors.d.ts +2 -6
  260. package/dist/schemas/errors.js +30 -40
  261. package/dist/schemas/heartbeat.d.ts +10 -0
  262. package/dist/schemas/heartbeat.js +8 -0
  263. package/dist/schemas/index.d.ts +46 -44
  264. package/dist/schemas/index.js +45 -43
  265. package/dist/schemas/llamacpp-config.d.ts +32 -10
  266. package/dist/schemas/llamacpp-config.js +11 -8
  267. package/dist/schemas/load-model.d.ts +2902 -1857
  268. package/dist/schemas/load-model.js +52 -52
  269. package/dist/schemas/mcp-adapter.d.ts +1 -1
  270. package/dist/schemas/model-config-schemas.d.ts +2354 -0
  271. package/dist/schemas/model-config-schemas.js +46 -0
  272. package/dist/schemas/model-info.d.ts +10 -20
  273. package/dist/schemas/model-info.js +4 -25
  274. package/dist/schemas/model-ops.d.ts +3 -1
  275. package/dist/schemas/model-ops.js +7 -2
  276. package/dist/schemas/model-resource-profile.d.ts +109 -0
  277. package/dist/schemas/model-resource-profile.js +83 -0
  278. package/dist/schemas/model-src-utils.d.ts +1 -0
  279. package/dist/schemas/model-src-utils.js +33 -13
  280. package/dist/schemas/ocr.js +48 -13
  281. package/dist/schemas/path-validation.js +8 -2
  282. package/dist/schemas/plugin.d.ts +23 -10
  283. package/dist/schemas/plugin.js +11 -0
  284. package/dist/schemas/profiling.d.ts +138 -43
  285. package/dist/schemas/profiling.js +1 -22
  286. package/dist/schemas/rag.js +1 -1
  287. package/dist/schemas/registry.js +1 -1
  288. package/dist/schemas/reload-config.d.ts +0 -2
  289. package/dist/schemas/reload-config.js +2 -3
  290. package/dist/schemas/sdcpp-config.d.ts +344 -4
  291. package/dist/schemas/sdcpp-config.js +504 -17
  292. package/dist/schemas/system-resources.d.ts +138 -0
  293. package/dist/schemas/system-resources.js +3 -1
  294. package/dist/schemas/text-to-speech.js +183 -76
  295. package/dist/schemas/transcription-config.js +253 -85
  296. package/dist/schemas/transcription.d.ts +3 -3
  297. package/dist/schemas/translate.d.ts +2 -2
  298. package/dist/schemas/translate.js +1 -1
  299. package/dist/schemas/translation-config.js +53 -25
  300. package/dist/schemas/vla.d.ts +1 -1
  301. package/dist/selection.d.ts +1 -5
  302. package/dist/selection.js +2 -6
  303. package/dist/surface.d.ts +1 -1
  304. package/dist/utils/addon-responses.d.ts +1 -0
  305. package/dist/utils/aggregate-events.d.ts +1 -1
  306. package/dist/utils/aggregate-events.js +2 -2
  307. package/dist/utils/archive.js +2 -2
  308. package/dist/utils/audio-input.js +1 -1
  309. package/dist/utils/cache/auto-history.d.ts +1 -1
  310. package/dist/utils/cache/auto-history.js +1 -1
  311. package/dist/utils/cache/paths.js +5 -5
  312. package/dist/utils/completion-normalizer.js +1 -1
  313. package/dist/utils/gguf-tensor-extractor.js +1 -1
  314. package/dist/utils/image-dimensions.d.ts +26 -0
  315. package/dist/utils/image-dimensions.js +46 -0
  316. package/dist/utils/index.d.ts +13 -10
  317. package/dist/utils/index.js +13 -10
  318. package/dist/utils/mcp-adapter.d.ts +1 -1
  319. package/dist/utils/mcp-adapter.js +1 -1
  320. package/dist/utils/path-sanitize.d.ts +7 -0
  321. package/dist/utils/path-sanitize.js +36 -0
  322. package/dist/utils/path-security.d.ts +0 -7
  323. package/dist/utils/path-security.js +1 -36
  324. package/dist/utils/shard-utils.js +3 -3
  325. package/dist/utils/tool-integration.js +1 -1
  326. package/dist/utils/tools/dialect.js +1 -1
  327. package/dist/utils/tools/index.d.ts +2 -2
  328. package/dist/utils/tools/index.js +2 -2
  329. package/dist/utils/tools/parser.js +8 -8
  330. package/dist/utils/tools/parsers/dsml.d.ts +1 -1
  331. package/dist/utils/tools/parsers/dsml.js +1 -1
  332. package/dist/utils/tools/parsers/gemma4native.d.ts +1 -1
  333. package/dist/utils/tools/parsers/gemma4native.js +1 -1
  334. package/dist/utils/tools/parsers/harmony.d.ts +1 -1
  335. package/dist/utils/tools/parsers/harmony.js +1 -1
  336. package/dist/utils/tools/parsers/hermes.d.ts +1 -1
  337. package/dist/utils/tools/parsers/hermes.js +1 -1
  338. package/dist/utils/tools/parsers/json.d.ts +1 -1
  339. package/dist/utils/tools/parsers/json.js +1 -1
  340. package/dist/utils/tools/parsers/pythonic.d.ts +1 -1
  341. package/dist/utils/tools/parsers/pythonic.js +1 -1
  342. package/dist/utils/tools/parsers/qwen35.d.ts +1 -1
  343. package/dist/utils/tools/parsers/qwen35.js +3 -3
  344. package/dist/utils/url-security.d.ts +17 -0
  345. package/dist/utils/url-security.js +75 -0
  346. package/package.json +31 -26
  347. package/dist/api/provide.d.ts +0 -23
  348. package/dist/api/provide.js +0 -32
  349. package/dist/api/stop-provider.d.ts +0 -20
  350. package/dist/api/stop-provider.js +0 -30
  351. package/dist/p2p/cancel-delegated.d.ts +0 -3
  352. package/dist/p2p/cancel-delegated.js +0 -64
  353. package/dist/p2p/completion-stream-delegated.d.ts +0 -4
  354. package/dist/p2p/completion-stream-delegated.js +0 -51
  355. package/dist/p2p/delegate-client.d.ts +0 -9
  356. package/dist/p2p/delegate-client.js +0 -219
  357. package/dist/p2p/delegate-connect-diagnostics.d.ts +0 -8
  358. package/dist/p2p/delegate-connect-diagnostics.js +0 -38
  359. package/dist/p2p/delegate-transport.d.ts +0 -18
  360. package/dist/p2p/delegate-transport.js +0 -237
  361. package/dist/p2p/error-handlers.d.ts +0 -4
  362. package/dist/p2p/error-handlers.js +0 -31
  363. package/dist/p2p/handle-request.d.ts +0 -2
  364. package/dist/p2p/handle-request.js +0 -171
  365. package/dist/p2p/handler-utils.d.ts +0 -19
  366. package/dist/p2p/handler-utils.js +0 -180
  367. package/dist/p2p/heartbeat-delegated.d.ts +0 -3
  368. package/dist/p2p/heartbeat-delegated.js +0 -32
  369. package/dist/p2p/load-model-delegated.d.ts +0 -6
  370. package/dist/p2p/load-model-delegated.js +0 -132
  371. package/dist/p2p/progress-throttle.d.ts +0 -7
  372. package/dist/p2p/progress-throttle.js +0 -47
  373. package/dist/p2p/provideHandler/connection.d.ts +0 -2
  374. package/dist/p2p/provideHandler/connection.js +0 -38
  375. package/dist/p2p/provideHandler/handler.d.ts +0 -2
  376. package/dist/p2p/provideHandler/handler.js +0 -66
  377. package/dist/p2p/provideHandler/proxy.d.ts +0 -2
  378. package/dist/p2p/provideHandler/proxy.js +0 -24
  379. package/dist/p2p/provideHandler.d.ts +0 -1
  380. package/dist/p2p/provideHandler.js +0 -2
  381. package/dist/p2p/rpc-utils.d.ts +0 -4
  382. package/dist/p2p/rpc-utils.js +0 -8
  383. package/dist/p2p/stopProvideHandler.d.ts +0 -2
  384. package/dist/p2p/stopProvideHandler.js +0 -29
  385. package/dist/p2p/swarm.d.ts +0 -9
  386. package/dist/p2p/swarm.js +0 -103
  387. package/dist/p2p/transport-selector.d.ts +0 -2
  388. package/dist/p2p/transport-selector.js +0 -18
  389. package/dist/p2p/unload-model-delegated.d.ts +0 -2
  390. package/dist/p2p/unload-model-delegated.js +0 -31
  391. package/dist/profiling/delegation-profiler.d.ts +0 -31
  392. package/dist/profiling/delegation-profiler.js +0 -155
  393. package/dist/schemas/delegate.d.ts +0 -29
  394. package/dist/schemas/delegate.js +0 -40
  395. package/dist/schemas/provide.d.ts +0 -50
  396. package/dist/schemas/provide.js +0 -32
@@ -0,0 +1,38 @@
1
+ /**
2
+ * win32-x64 coefficients.
3
+ *
4
+ * Generated by `scripts/calibrate-model-fit.ts`; see `METHODOLOGY.md` next
5
+ * to this file for how the numbers are derived and validated.
6
+ */
7
+ export const WIN32_X64_CALIBRATION = {
8
+ weightUpperCoeff: 1.01,
9
+ workingPeakBytes: {
10
+ lower: 0,
11
+ upper: 10587341
12
+ },
13
+ fixedOverheadBytes: {
14
+ lower: 55193195,
15
+ upper: 134358525
16
+ },
17
+ computeBufferBytesPerToken: {
18
+ lower: 0,
19
+ upper: 0
20
+ },
21
+ audioWindowBytes: {
22
+ lower: 0,
23
+ upper: 0
24
+ },
25
+ audioStreamingBytes: {
26
+ lower: 0,
27
+ upper: 0
28
+ },
29
+ validated: true,
30
+ notes: [
31
+ "weights were loaded with load_mode 'none' so RSS counted them in full at load; a mapped weight set keeps at most the artifact size resident, so weightUpperCoeff remains an upper bound for the default mmap load"
32
+ ],
33
+ measuredAt: '2026-09-03',
34
+ measuredOn: {
35
+ backend: 'cpu',
36
+ kvElementBytes: 2
37
+ }
38
+ };
@@ -0,0 +1,46 @@
1
+ import type { GgufFacts } from '../../../schemas/model-resource-profile.js';
2
+ import type { ByteRange, EstimatorInput, EstimatorResult } from '../types.js';
3
+ export declare const LLM_ESTIMATOR_VERSION = "llm-v1";
4
+ export declare const LLAMA_WEIGHTS_ASSUMPTION = "weights are counted at full artifact size; llama.cpp maps them by default, so those pages are file-backed and evictable rather than anonymous RAM";
5
+ /**
6
+ * Estimates memory for a llama.cpp completion or embedding model from catalog
7
+ * metadata alone.
8
+ *
9
+ * Weights come from the artifact size; the KV cache is computed from the
10
+ * transformer shape and the requested context. The estimate is a range, not a
11
+ * number, because two things are genuinely undetermined before load: the
12
+ * backend the engine will pick (which sets the default KV-cache type) and, for
13
+ * some architectures, which blocks hold a full cache.
14
+ */
15
+ export declare function estimateLlm(input: EstimatorInput): EstimatorResult;
16
+ /** A KV-cache element width range, with the reason it is that range. */
17
+ export interface KvElementWidth {
18
+ bytes: ByteRange;
19
+ assumption: string;
20
+ }
21
+ /**
22
+ * Picks the KV-cache element width range for this model on this device.
23
+ *
24
+ * Exported because the calibration harness has to subtract the cache the engine
25
+ * *actually* allocated before it can fit the remaining overhead. Hard-coding a
26
+ * width there would skew the fit by roughly 2× on a GPU backend — and because
27
+ * the error scales with context, it would corrupt the per-token slope rather
28
+ * than shifting the intercept. Sharing this rule keeps the two in step.
29
+ *
30
+ * @returns Lower/upper bytes per cache element, and the assumption that choice
31
+ * rests on. Side-effect free so the harness can call it without an
32
+ * assumptions array.
33
+ */
34
+ export declare function kvElementBytes(facts: GgufFacts, hasGpu: boolean): KvElementWidth;
35
+ /**
36
+ * KV-cache bytes at one fixed element width, clamped to the trained context.
37
+ *
38
+ * Exported for the calibration harness, which must subtract the cache the
39
+ * engine actually allocated using the exact accounting the estimator uses —
40
+ * a hand-rolled copy drifted once already (no sliding-window branch, `ceil`
41
+ * where the estimator bounds with `floor`, no SSM state). A non-degenerate
42
+ * range means part of the layout is engine-owned, so the allocation cannot be
43
+ * known from the file alone and the model is unsuitable for calibration; the
44
+ * harness aborts on it rather than guessing.
45
+ */
46
+ export declare function kvCacheBytesForWidth(facts: GgufFacts, contextTokens: number, bytesPerElement: number): ByteRange;
@@ -0,0 +1,222 @@
1
+ export const LLM_ESTIMATOR_VERSION = 'llm-v1';
2
+ /**
3
+ * KV-cache element widths, in bytes per element.
4
+ *
5
+ * `f16` is the CPU default. On a Metal/Vulkan GPU backend with flash attention
6
+ * on — the SDK's own defaults — `llm-llamacpp` defaults the cache to `q8_0`
7
+ * instead (`addon/src/model-interface/LoadFitNormalization.cpp`, QVAC-21318),
8
+ * which is why the bound is a range rather than a number. `q8_0` packs 32
9
+ * elements into a 34-byte block.
10
+ */
11
+ const F16_BYTES_PER_ELEMENT = 2;
12
+ const Q8_0_BYTES_PER_ELEMENT = 34 / 32;
13
+ /** Recurrent/SSM state is kept in f32. */
14
+ const SSM_STATE_BYTES_PER_ELEMENT = 4;
15
+ /**
16
+ * Architectures that disable flash attention, so the GPU `q8_0` KV default
17
+ * never applies and the cache stays `f16` on every backend.
18
+ */
19
+ function disablesFlashAttention(architecture) {
20
+ return architecture.startsWith('bitnet');
21
+ }
22
+ // Shared with the computed floor so a mixed set carries one weights assumption, not two.
23
+ export const LLAMA_WEIGHTS_ASSUMPTION = 'weights are counted at full artifact size; llama.cpp maps them by default, so those pages are file-backed and evictable rather than anonymous RAM';
24
+ /**
25
+ * Estimates memory for a llama.cpp completion or embedding model from catalog
26
+ * metadata alone.
27
+ *
28
+ * Weights come from the artifact size; the KV cache is computed from the
29
+ * transformer shape and the requested context. The estimate is a range, not a
30
+ * number, because two things are genuinely undetermined before load: the
31
+ * backend the engine will pick (which sets the default KV-cache type) and, for
32
+ * some architectures, which blocks hold a full cache.
33
+ */
34
+ export function estimateLlm(input) {
35
+ const { profile, workload, calibration, extraArtifactBytes, hasGpu } = input;
36
+ if (workload.kind !== 'llm') {
37
+ return {
38
+ kind: 'unknown',
39
+ estimatorVersion: LLM_ESTIMATOR_VERSION,
40
+ reasons: [`workload kind '${workload.kind}' is not supported by ${LLM_ESTIMATOR_VERSION}`]
41
+ };
42
+ }
43
+ const facts = profile.ggufFacts;
44
+ if (!facts) {
45
+ return {
46
+ kind: 'unknown',
47
+ estimatorVersion: LLM_ESTIMATOR_VERSION,
48
+ reasons: ['no GGUF metadata for this model in the catalog, so the KV cache cannot be sized']
49
+ };
50
+ }
51
+ const assumptions = [];
52
+ const reasons = [];
53
+ // Weights: mapped at file size by default, so artifact bytes are the floor.
54
+ // The upper coefficient covers the allocator's copy-on-write and alignment
55
+ // slack measured during calibration.
56
+ const artifactBytes = profile.artifactBytes + extraArtifactBytes;
57
+ assumptions.push(LLAMA_WEIGHTS_ASSUMPTION);
58
+ if (extraArtifactBytes > 0) {
59
+ assumptions.push('companion artifacts passed in `artifacts` are counted at full size');
60
+ }
61
+ // Context: never more than the model was trained for — llama.cpp clamps.
62
+ let contextTokens = workload.contextTokens;
63
+ if (contextTokens > facts.contextLength) {
64
+ assumptions.push(`requested ${workload.contextTokens} tokens exceeds the trained context of ${facts.contextLength}; clamped to the trained context`);
65
+ contextTokens = facts.contextLength;
66
+ }
67
+ const element = kvElementBytes(facts, hasGpu);
68
+ assumptions.push(element.assumption);
69
+ const kv = kvCacheBytes(facts, contextTokens, element.bytes, assumptions, reasons);
70
+ // llama.cpp builds the context at load — KV cache, engine overhead, compute
71
+ // buffers — so all of it is resident for the model's lifetime. Parking any of
72
+ // it in `working` would let `sequential` count only the largest. What a
73
+ // completion adds on top is released afterwards, so that part is `working`.
74
+ const persistent = {
75
+ lower: Math.ceil(artifactBytes +
76
+ kv.lower +
77
+ calibration.fixedOverheadBytes.lower +
78
+ calibration.computeBufferBytesPerToken.lower * contextTokens),
79
+ upper: Math.ceil(artifactBytes * calibration.weightUpperCoeff +
80
+ kv.upper +
81
+ calibration.fixedOverheadBytes.upper +
82
+ calibration.computeBufferBytesPerToken.upper * contextTokens)
83
+ };
84
+ assumptions.push('the KV cache, engine overhead and compute buffers count as resident for the model’s whole lifetime; llama.cpp allocates them when the model loads, not per operation');
85
+ if (calibration.workingPeakBytes && calibration.workingPeakBytes.upper > 0) {
86
+ assumptions.push('one operation is assumed in flight per model; the working peak is what a single completion was measured to add on top of the resident cost');
87
+ }
88
+ assumptions.push('default KV-cache types are assumed; an explicit `cache-type-k`/`cache-type-v` in `modelConfig` is not expressible in a workload and would change these numbers');
89
+ return {
90
+ kind: 'estimate',
91
+ estimatorVersion: LLM_ESTIMATOR_VERSION,
92
+ persistent,
93
+ working: {
94
+ lower: calibration.workingPeakBytes?.lower ?? 0,
95
+ upper: calibration.workingPeakBytes?.upper ?? 0
96
+ },
97
+ reasons,
98
+ assumptions
99
+ };
100
+ }
101
+ /**
102
+ * Picks the KV-cache element width range for this model on this device.
103
+ *
104
+ * Exported because the calibration harness has to subtract the cache the engine
105
+ * *actually* allocated before it can fit the remaining overhead. Hard-coding a
106
+ * width there would skew the fit by roughly 2× on a GPU backend — and because
107
+ * the error scales with context, it would corrupt the per-token slope rather
108
+ * than shifting the intercept. Sharing this rule keeps the two in step.
109
+ *
110
+ * @returns Lower/upper bytes per cache element, and the assumption that choice
111
+ * rests on. Side-effect free so the harness can call it without an
112
+ * assumptions array.
113
+ */
114
+ export function kvElementBytes(facts, hasGpu) {
115
+ if (disablesFlashAttention(facts.architecture)) {
116
+ return {
117
+ bytes: { lower: F16_BYTES_PER_ELEMENT, upper: F16_BYTES_PER_ELEMENT },
118
+ assumption: `${facts.architecture} loads with flash attention off, so the KV cache stays f16 on every backend`
119
+ };
120
+ }
121
+ if (hasGpu) {
122
+ return {
123
+ bytes: { lower: Q8_0_BYTES_PER_ELEMENT, upper: F16_BYTES_PER_ELEMENT },
124
+ assumption: 'a GPU is present, so the engine may default the KV cache to q8_0 (lower bound) or keep f16 on a CPU or OpenCL backend (upper bound)'
125
+ };
126
+ }
127
+ return {
128
+ bytes: { lower: F16_BYTES_PER_ELEMENT, upper: F16_BYTES_PER_ELEMENT },
129
+ assumption: 'no GPU reported, so the CPU f16 KV-cache default applies'
130
+ };
131
+ }
132
+ /**
133
+ * KV-cache bytes at one fixed element width, clamped to the trained context.
134
+ *
135
+ * Exported for the calibration harness, which must subtract the cache the
136
+ * engine actually allocated using the exact accounting the estimator uses —
137
+ * a hand-rolled copy drifted once already (no sliding-window branch, `ceil`
138
+ * where the estimator bounds with `floor`, no SSM state). A non-degenerate
139
+ * range means part of the layout is engine-owned, so the allocation cannot be
140
+ * known from the file alone and the model is unsuitable for calibration; the
141
+ * harness aborts on it rather than guessing.
142
+ */
143
+ export function kvCacheBytesForWidth(facts, contextTokens, bytesPerElement) {
144
+ const tokens = Math.min(contextTokens, facts.contextLength);
145
+ return kvCacheBytes(facts, tokens, { lower: bytesPerElement, upper: bytesPerElement }, [], []);
146
+ }
147
+ /**
148
+ * Sizes the KV cache for the requested context.
149
+ *
150
+ * Three cases, in order of how much the file actually tells us:
151
+ *
152
+ * 1. **Per-layer classes** — the file describes attention per block, so the
153
+ * cache is summed exactly, with sliding-window blocks capped at their window.
154
+ * 2. **Hybrid attention/recurrent** — `full_attention_interval` says how many
155
+ * blocks hold a cache at all; the rest hold a fixed-size SSM state. Which
156
+ * blocks are which is engine-owned, so the count is bounded, not fixed.
157
+ * 3. **Flat** — every block holds the same cache. When the file declares a
158
+ * sliding window but no per-layer pattern, the pattern lives in the engine:
159
+ * the bound then spans "every block windowed" to "every block full", which is
160
+ * wide on purpose.
161
+ */
162
+ function kvCacheBytes(facts, contextTokens, elementBytes, assumptions, reasons) {
163
+ if (facts.kvLayerClasses && facts.kvLayerClasses.length > 0) {
164
+ reasons.push('KV cache summed per layer class from the file’s per-block attention metadata');
165
+ return {
166
+ lower: layerClassBytes(facts.kvLayerClasses, facts, contextTokens, elementBytes.lower),
167
+ upper: layerClassBytes(facts.kvLayerClasses, facts, contextTokens, elementBytes.upper)
168
+ };
169
+ }
170
+ const perBlockPerToken = facts.headCountKv * (facts.keyLength + facts.valueLength);
171
+ if (facts.fullAttentionInterval && facts.fullAttentionInterval > 1) {
172
+ const interval = facts.fullAttentionInterval;
173
+ const fullBlocksLower = Math.floor(facts.blockCount / interval);
174
+ const fullBlocksUpper = Math.ceil(facts.blockCount / interval);
175
+ const ssm = ssmStateBytes(facts, facts.blockCount - fullBlocksLower);
176
+ assumptions.push(`${facts.architecture} keeps full attention every ${interval} blocks; the remaining blocks hold a fixed-size recurrent state instead of a KV cache, and which blocks are which is engine-owned`);
177
+ reasons.push(`KV cache sized for ${fullBlocksLower}–${fullBlocksUpper} of ${facts.blockCount} blocks (hybrid attention)`);
178
+ return {
179
+ lower: fullBlocksLower * perBlockPerToken * contextTokens * elementBytes.lower + ssm,
180
+ upper: fullBlocksUpper * perBlockPerToken * contextTokens * elementBytes.upper + ssm
181
+ };
182
+ }
183
+ if (facts.slidingWindow) {
184
+ const windowedTokens = Math.min(contextTokens, facts.slidingWindow);
185
+ assumptions.push(`${facts.architecture} uses sliding-window attention with a ${facts.slidingWindow}-token window, but the file does not say which blocks are windowed; the bound spans every block windowed to every block full`);
186
+ reasons.push('sliding-window layer pattern is engine-owned, so the KV bound is wide');
187
+ return {
188
+ lower: facts.blockCount * perBlockPerToken * windowedTokens * elementBytes.lower,
189
+ upper: facts.blockCount * perBlockPerToken * contextTokens * elementBytes.upper
190
+ };
191
+ }
192
+ reasons.push(`KV cache sized for all ${facts.blockCount} blocks at ${contextTokens} tokens`);
193
+ return {
194
+ lower: facts.blockCount * perBlockPerToken * contextTokens * elementBytes.lower,
195
+ upper: facts.blockCount * perBlockPerToken * contextTokens * elementBytes.upper
196
+ };
197
+ }
198
+ function layerClassBytes(classes, facts, contextTokens, elementBytes) {
199
+ let total = 0;
200
+ for (const layerClass of classes) {
201
+ const tokens = layerClass.windowed && facts.slidingWindow
202
+ ? Math.min(contextTokens, facts.slidingWindow)
203
+ : contextTokens;
204
+ total +=
205
+ layerClass.count *
206
+ layerClass.headCountKv *
207
+ (layerClass.keyLength + layerClass.valueLength) *
208
+ tokens *
209
+ elementBytes;
210
+ }
211
+ return total;
212
+ }
213
+ /**
214
+ * Fixed recurrent state for the blocks of a hybrid model that hold no KV cache:
215
+ * the SSM state plus its convolution window, per block.
216
+ */
217
+ function ssmStateBytes(facts, recurrentBlocks) {
218
+ if (!facts.ssmInnerSize || !facts.ssmStateSize || recurrentBlocks <= 0)
219
+ return 0;
220
+ const perBlock = facts.ssmInnerSize * facts.ssmStateSize + facts.ssmInnerSize * (facts.ssmConvKernel ?? 0);
221
+ return recurrentBlocks * perBlock * SSM_STATE_BYTES_PER_ELEMENT;
222
+ }
@@ -0,0 +1,10 @@
1
+ import type { EstimatorInput, EstimatorResult } from '../types.js';
2
+ export declare const WHISPER_ESTIMATOR_VERSION = "whisper-v1";
3
+ /**
4
+ * Estimates memory for a whisper.cpp transcription model.
5
+ *
6
+ * Whisper's encoder work is fixed by its 30 s window rather than by a growing
7
+ * cache, so the shape is simpler than the LLM case: resident weights plus a
8
+ * working peak that scales with the window the caller feeds it.
9
+ */
10
+ export declare function estimateWhisper(input: EstimatorInput): EstimatorResult;
@@ -0,0 +1,77 @@
1
+ export const WHISPER_ESTIMATOR_VERSION = 'whisper-v1';
2
+ /** Whisper's own default window, and therefore the calibration anchor. */
3
+ const CALIBRATION_WINDOW_MS = 30_000;
4
+ /**
5
+ * Estimates memory for a whisper.cpp transcription model.
6
+ *
7
+ * Whisper's encoder work is fixed by its 30 s window rather than by a growing
8
+ * cache, so the shape is simpler than the LLM case: resident weights plus a
9
+ * working peak that scales with the window the caller feeds it.
10
+ */
11
+ export function estimateWhisper(input) {
12
+ const { profile, workload, calibration, extraArtifactBytes } = input;
13
+ if (workload.kind !== 'audio') {
14
+ return {
15
+ kind: 'unknown',
16
+ estimatorVersion: WHISPER_ESTIMATOR_VERSION,
17
+ reasons: [`workload kind '${workload.kind}' is not supported by ${WHISPER_ESTIMATOR_VERSION}`]
18
+ };
19
+ }
20
+ // A zero here is an unmeasured placeholder, not a measurement: the harness
21
+ // writes `{ lower: 0, upper: 0 }` until its whisper pass has run. Consuming
22
+ // it would return a confident estimate whose entire audio working memory is
23
+ // zero — the same failure shape as a mis-subtracted KV cache.
24
+ if (calibration.audioWindowBytes.upper <= 0) {
25
+ return {
26
+ kind: 'unknown',
27
+ estimatorVersion: WHISPER_ESTIMATOR_VERSION,
28
+ reasons: [
29
+ 'the audio window coefficient for this platform has not been measured, so an audio estimate cannot be defended'
30
+ ]
31
+ };
32
+ }
33
+ if (workload.streaming && calibration.audioStreamingBytes.upper <= 0) {
34
+ return {
35
+ kind: 'unknown',
36
+ estimatorVersion: WHISPER_ESTIMATOR_VERSION,
37
+ reasons: [
38
+ 'the streaming-session coefficient for this platform has not been measured, so a streaming audio estimate cannot be defended'
39
+ ]
40
+ };
41
+ }
42
+ const assumptions = [];
43
+ const reasons = [];
44
+ const artifactBytes = profile.artifactBytes + extraArtifactBytes;
45
+ const persistent = {
46
+ lower: artifactBytes,
47
+ upper: Math.ceil(artifactBytes * calibration.weightUpperCoeff)
48
+ };
49
+ if (extraArtifactBytes > 0) {
50
+ assumptions.push('companion artifacts passed in `artifacts` (e.g. a VAD model) are counted at full size');
51
+ }
52
+ const windows = workload.windowMs / CALIBRATION_WINDOW_MS;
53
+ const batch = workload.batch ?? 1;
54
+ const streamingLower = workload.streaming ? calibration.audioStreamingBytes.lower : 0;
55
+ const streamingUpper = workload.streaming ? calibration.audioStreamingBytes.upper : 0;
56
+ const working = {
57
+ lower: calibration.fixedOverheadBytes.lower +
58
+ calibration.audioWindowBytes.lower * windows * batch +
59
+ streamingLower,
60
+ upper: calibration.fixedOverheadBytes.upper +
61
+ calibration.audioWindowBytes.upper * windows * batch +
62
+ streamingUpper
63
+ };
64
+ reasons.push(`working memory scaled from the calibrated 30 s window to ${Math.round(workload.windowMs)} ms${batch > 1 ? ` × ${batch} concurrent windows` : ''}`);
65
+ assumptions.push('the audio window scales working memory linearly from the engine’s 30 s default; longer windows are chunked by the engine rather than held whole');
66
+ if (workload.streaming) {
67
+ assumptions.push('a streaming session is assumed to keep one calibrated stream buffer resident');
68
+ }
69
+ return {
70
+ kind: 'estimate',
71
+ estimatorVersion: WHISPER_ESTIMATOR_VERSION,
72
+ persistent,
73
+ working: { lower: Math.ceil(working.lower), upper: Math.ceil(working.upper) },
74
+ reasons,
75
+ assumptions
76
+ };
77
+ }
@@ -0,0 +1,31 @@
1
+ import type { ModelFitWorkload } from '../../schemas/assess-model-fit.js';
2
+ import type { ModelResourceProfile } from '../../schemas/model-resource-profile.js';
3
+ export declare const FLOOR_VERSION = "floor-v1";
4
+ export interface FloorInput {
5
+ profile: ModelResourceProfile;
6
+ workload: ModelFitWorkload;
7
+ /** Artifact bytes of companion constants the caller passed alongside. */
8
+ extraArtifactBytes: number;
9
+ }
10
+ /** A lower bound with no upper bound, and how it was assembled. */
11
+ export interface FloorResult {
12
+ bytes: number;
13
+ reasons: readonly string[];
14
+ assumptions: readonly string[];
15
+ }
16
+ /**
17
+ * The smallest resident footprint the catalog facts prove, with no coefficient
18
+ * measured anywhere: artifact bytes, plus the KV cache for a llama.cpp model at
19
+ * the cheapest element width the engine can default to.
20
+ *
21
+ * Every term a calibrated estimate adds on top — weight slack, engine overhead,
22
+ * compute buffers, a completion's working peak — is non-negative, so a floor
23
+ * with all of them at zero is unconditionally valid on any platform and any
24
+ * backend. It can therefore refuse a model (`likely-too-large` when even the
25
+ * floor is over budget) but never confirm one: how far above the floor the real
26
+ * load lands is exactly what calibration exists to measure.
27
+ *
28
+ * This is the zero-fetch gate. It reads nothing but the catalog and stays the
29
+ * fallback wherever no calibration or engine projection is available.
30
+ */
31
+ export declare function computeFloor(input: FloorInput): FloorResult;
@@ -0,0 +1,65 @@
1
+ import { LLAMA_WEIGHTS_ASSUMPTION, kvCacheBytesForWidth, kvElementBytes } from './estimators/llm.js';
2
+ export const FLOOR_VERSION = 'floor-v1';
3
+ /**
4
+ * Engines whose load builds a KV cache the file sizes exactly, so the floor can
5
+ * count it. Every other engine's working memory is engine-owned and unsized
6
+ * here; the floor for those is the weights alone.
7
+ */
8
+ const KV_CACHE_ENGINES = new Set(['llamacpp-completion', 'llamacpp-embedding']);
9
+ /**
10
+ * The smallest resident footprint the catalog facts prove, with no coefficient
11
+ * measured anywhere: artifact bytes, plus the KV cache for a llama.cpp model at
12
+ * the cheapest element width the engine can default to.
13
+ *
14
+ * Every term a calibrated estimate adds on top — weight slack, engine overhead,
15
+ * compute buffers, a completion's working peak — is non-negative, so a floor
16
+ * with all of them at zero is unconditionally valid on any platform and any
17
+ * backend. It can therefore refuse a model (`likely-too-large` when even the
18
+ * floor is over budget) but never confirm one: how far above the floor the real
19
+ * load lands is exactly what calibration exists to measure.
20
+ *
21
+ * This is the zero-fetch gate. It reads nothing but the catalog and stays the
22
+ * fallback wherever no calibration or engine projection is available.
23
+ */
24
+ export function computeFloor(input) {
25
+ const { profile, workload, extraArtifactBytes } = input;
26
+ const reasons = [];
27
+ const assumptions = [
28
+ KV_CACHE_ENGINES.has(profile.engine)
29
+ ? LLAMA_WEIGHTS_ASSUMPTION
30
+ : 'weights are counted at full artifact size; whatever the engine maps or copies, the file has to be resident to run',
31
+ 'the floor omits engine overhead, compute buffers and working memory, all of which are non-negative, so it cannot overstate the cost — and says nothing about how much more the load needs'
32
+ ];
33
+ const artifactBytes = profile.artifactBytes + extraArtifactBytes;
34
+ if (extraArtifactBytes > 0) {
35
+ assumptions.push('companion artifacts passed in `artifacts` are counted at full size');
36
+ }
37
+ if (!KV_CACHE_ENGINES.has(profile.engine)) {
38
+ reasons.push(`the floor for engine '${profile.engine}' counts weights only; its working memory is engine-owned and not sized here`);
39
+ return { bytes: artifactBytes, reasons, assumptions };
40
+ }
41
+ if (workload.kind !== 'llm') {
42
+ reasons.push(`workload kind '${workload.kind}' carries no context for a llama.cpp model, so the floor counts weights only`);
43
+ return { bytes: artifactBytes, reasons, assumptions };
44
+ }
45
+ const facts = profile.ggufFacts;
46
+ if (!facts) {
47
+ reasons.push('no GGUF metadata for this model in the catalog, so the floor counts weights only');
48
+ return { bytes: artifactBytes, reasons, assumptions };
49
+ }
50
+ let contextTokens = workload.contextTokens;
51
+ if (contextTokens > facts.contextLength) {
52
+ assumptions.push(`requested ${workload.contextTokens} tokens exceeds the trained context of ${facts.contextLength}; clamped to the trained context`);
53
+ contextTokens = facts.contextLength;
54
+ }
55
+ // The narrowest default the engine can pick on any backend, so the floor
56
+ // holds whether the model lands on a GPU (q8_0 with flash attention) or on
57
+ // the CPU (f16). Architectures that disable flash attention stay f16 anyway.
58
+ const element = kvElementBytes(facts, true).bytes.lower;
59
+ const kv = kvCacheBytesForWidth(facts, contextTokens, element).lower;
60
+ assumptions.push(element < 2
61
+ ? 'the KV cache is floored at the q8_0 element width, the narrowest default the engine picks on any backend; a CPU load allocates an f16 cache above it'
62
+ : `${facts.architecture} loads with flash attention off, so the KV cache is floored at f16 on every backend`, 'default KV-cache types are assumed; an explicit `cache-type-k`/`cache-type-v` in `modelConfig` is not expressible in a workload and would change these numbers');
63
+ reasons.push(`KV cache floored for ${contextTokens} tokens at the narrowest default element width`);
64
+ return { bytes: Math.ceil(artifactBytes + kv), reasons, assumptions };
65
+ }
@@ -0,0 +1,120 @@
1
+ import type { ModelFitWorkload } from '../../schemas/assess-model-fit.js';
2
+ import type { ModelResourceProfile } from '../../schemas/model-resource-profile.js';
3
+ /** A memory bound. `lower` is the optimistic end, `upper` the conservative one. */
4
+ export interface ByteRange {
5
+ lower: number;
6
+ upper: number;
7
+ }
8
+ /**
9
+ * Platforms a calibration fixture can cover. A platform absent from the shipped
10
+ * fixtures assesses as `unknown`: an uncalibrated formula is not evidence.
11
+ */
12
+ export type ModelFitPlatform = 'darwin-arm64' | 'darwin-x64' | 'linux-arm64' | 'linux-x64' | 'win32-x64' | 'win32-arm64' | 'android-arm64' | 'ios-arm64';
13
+ /**
14
+ * Measured coefficients for one platform. Derived by the calibration harness
15
+ * (`scripts/calibrate-model-fit.ts`) from real loads, then committed.
16
+ *
17
+ * @property weightUpperCoeff - Multiplier on `artifactBytes` for resident
18
+ * weights at the conservative end. The lower end is always 1.0: llama.cpp
19
+ * maps weights, so the file size is the floor.
20
+ * @property fixedOverheadBytes - Runtime cost that does not scale with the
21
+ * workload: engine context, backend buffers, tokenizer.
22
+ * @property computeBufferBytesPerToken - Compute/graph buffers that scale with
23
+ * the context the caller asks for.
24
+ * @property audioWindowBytes - Whisper-family working memory for one 30 s
25
+ * window, the engine's own default window.
26
+ * @property audioStreamingBytes - Extra resident cost of a streaming session.
27
+ * @property validated - False while coefficients are provisional. An
28
+ * unvalidated platform assesses as `unknown`, exactly like a missing one.
29
+ * @property measuredOn - What the harness observed while measuring. Recorded
30
+ * because these coefficients are keyed by platform alone, while the buffers
31
+ * they measure are allocated by the backend: a `linux-x64` fixture measured on
32
+ * CUDA is being applied to CPU-only hosts too. Stating each fixture's scope
33
+ * keeps that visible, and means the key could later gain a backend dimension
34
+ * without re-measuring anything. Absent on a placeholder, which measured
35
+ * nothing.
36
+ */
37
+ export interface PlatformCalibration {
38
+ weightUpperCoeff: number;
39
+ fixedOverheadBytes: ByteRange;
40
+ computeBufferBytesPerToken: ByteRange;
41
+ /**
42
+ * Transient peak one operation adds on top of the resident cost — a few MiB
43
+ * on most platforms, 73 MiB on darwin-x64. Optional: fixtures measured
44
+ * before the harness sampled generation contribute nothing, as they do now.
45
+ */
46
+ workingPeakBytes?: ByteRange;
47
+ audioWindowBytes: ByteRange;
48
+ audioStreamingBytes: ByteRange;
49
+ validated: boolean;
50
+ measuredAt?: string;
51
+ measuredOn?: CalibrationProvenance;
52
+ notes?: readonly string[];
53
+ }
54
+ /**
55
+ * The measurement conditions behind one set of coefficients.
56
+ *
57
+ * @property backend - Best-effort label for the backend in play during the run,
58
+ * inferred from the GPU drivers the resource collector reported: `metal`,
59
+ * `vulkan`, `cuda`, `rocm`, or `cpu`.
60
+ * @property device - GPU name, when one was reported.
61
+ * @property kvElementBytes - Bytes per KV-cache element the residuals were
62
+ * computed against. The single most useful number here: subtract the wrong
63
+ * width and the fit is wrong, so recording it makes a bad run auditable after
64
+ * the fact.
65
+ */
66
+ export interface CalibrationProvenance {
67
+ backend: string;
68
+ device?: string;
69
+ kvElementBytes: number;
70
+ }
71
+ export interface CalibrationFixture {
72
+ schemaVersion: 1;
73
+ platforms: Partial<Record<ModelFitPlatform, PlatformCalibration>>;
74
+ /**
75
+ * GPU-resident coefficients, keyed `<platform>:<backend>`. Separate from
76
+ * `platforms` because those describe CPU-resident execution in system RAM,
77
+ * and because one platform can run several backends whose buffers differ.
78
+ */
79
+ gpuPlatforms?: Readonly<Record<string, PlatformCalibration>>;
80
+ /**
81
+ * Integrated-GPU coefficients, keyed the same way. A third map because the
82
+ * buffers are the backend's, as in `gpuPlatforms`, but come out of system
83
+ * RAM, as in `platforms`. Measured by the harness's `--igpu` pass.
84
+ */
85
+ sharedGpuPlatforms?: Readonly<Record<string, PlatformCalibration>>;
86
+ }
87
+ /** What an estimator is handed for one candidate. */
88
+ export interface EstimatorInput {
89
+ profile: ModelResourceProfile;
90
+ workload: ModelFitWorkload;
91
+ /** Artifact bytes of companion constants the caller passed alongside. */
92
+ extraArtifactBytes: number;
93
+ calibration: PlatformCalibration;
94
+ /**
95
+ * Whether the device reports a GPU. Used only to decide which KV-cache type
96
+ * the engine would default to — never as a memory budget, since GPU memory
97
+ * metrics are `unverified`-scoped by design.
98
+ */
99
+ hasGpu: boolean;
100
+ }
101
+ /**
102
+ * An estimate, or a refusal to estimate.
103
+ *
104
+ * `persistent` stays resident for the model's whole lifetime; `working` is the
105
+ * temporary peak of one operation. Aggregation treats them differently, which
106
+ * is what makes `sequential` cheaper than `concurrent`.
107
+ */
108
+ export type EstimatorResult = {
109
+ kind: 'estimate';
110
+ estimatorVersion: string;
111
+ persistent: ByteRange;
112
+ working: ByteRange;
113
+ reasons: readonly string[];
114
+ assumptions: readonly string[];
115
+ } | {
116
+ kind: 'unknown';
117
+ estimatorVersion: string;
118
+ reasons: readonly string[];
119
+ assumptions?: readonly string[];
120
+ };
@@ -0,0 +1 @@
1
+ export {};
@@ -1,2 +1,2 @@
1
- import type { ResourceCollectorDependencies } from '../resources/types.js';
1
+ import type { ResourceCollectorDependencies } from './types.js';
2
2
  export declare const nativeResourceCollectorDependencies: ResourceCollectorDependencies;
@@ -1,3 +1,4 @@
1
+ import os from 'bare-os';
1
2
  import { randomUUID } from 'bare-crypto';
2
3
  // Load independently so one unavailable native addon cannot disable the other collector.
3
4
  const [cpuModule, gpuModule] = await Promise.allSettled([
@@ -13,9 +14,12 @@ const cpuArchitectures = cpuModule.status === 'fulfilled'
13
14
  const gpuTypes = gpuModule.status === 'fulfilled'
14
15
  ? supportedEnumValues(gpuModule.value.default.constants.gpuType, gpuModule.value.default.constants.gpuType.UNKNOWN)
15
16
  : [];
17
+ // `availableMemory()` reports the constrained memory on iOS.
18
+ const reportsProcessAllowance = os.platform() === 'ios';
16
19
  export const nativeResourceCollectorDependencies = {
17
20
  cpuArchitectures,
18
21
  gpuTypes,
22
+ platform: os.platform(),
19
23
  createCPUInfo() {
20
24
  if (cpuModule.status !== 'fulfilled')
21
25
  return undefined;
@@ -31,5 +35,16 @@ export const nativeResourceCollectorDependencies = {
31
35
  },
32
36
  now() {
33
37
  return Date.now();
38
+ },
39
+ sampleProcessMemory() {
40
+ // A throw here is a sampling failure, not a platform gap: let it reach the
41
+ // collector so the metric reports `failed` rather than `unavailable`.
42
+ const usage = os.memoryUsage();
43
+ const available = reportsProcessAllowance ? os.availableMemory() : 0;
44
+ return {
45
+ usedBytes: usage && usage.rss > 0 ? usage.rss : undefined,
46
+ // Zero states no headroom, which is not a budget.
47
+ availableBytes: available > 0 ? available : undefined
48
+ };
34
49
  }
35
50
  };
@@ -1,4 +1,4 @@
1
- import type { ResourceMetric, ResourceProvenance } from '../resources/types.js';
1
+ import type { ResourceMetric, ResourceProvenance } from './types.js';
2
2
  export declare function unavailableMetric<T>(reason?: string): ResourceMetric<T>;
3
3
  export declare function unverifiedMetric<T>(reason?: string): ResourceMetric<T>;
4
4
  export declare function failedMetric<T>(reason: string): ResourceMetric<T>;