mlx-agent 0.9.0__tar.gz

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 (230) hide show
  1. mlx_agent-0.9.0/.gitignore +17 -0
  2. mlx_agent-0.9.0/LICENSE +21 -0
  3. mlx_agent-0.9.0/PKG-INFO +212 -0
  4. mlx_agent-0.9.0/README.md +191 -0
  5. mlx_agent-0.9.0/pyproject.toml +42 -0
  6. mlx_agent-0.9.0/src/mlx_agent/__init__.py +6 -0
  7. mlx_agent-0.9.0/src/mlx_agent/__main__.py +9 -0
  8. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/__init__.py +24 -0
  9. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/adapter_protocol.py +152 -0
  10. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/adapter_registry.py +300 -0
  11. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/adapters/__init__.py +1 -0
  12. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/adapters/animegen_mps.py +1242 -0
  13. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/adapters/fake.py +164 -0
  14. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/adapters/wan_mps.py +523 -0
  15. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/adaptive_study_models.py +415 -0
  16. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/adaptive_study_repository.py +1069 -0
  17. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/adaptive_study_service.py +810 -0
  18. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/adaptive_web_creation_repository.py +250 -0
  19. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/animegen_feasibility.py +596 -0
  20. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/animegen_pair_contract.py +6 -0
  21. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/artifacts.py +988 -0
  22. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/capabilities.py +82 -0
  23. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/character_benchmark_analysis.py +283 -0
  24. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/character_benchmark_models.py +264 -0
  25. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/character_benchmark_protocol.py +304 -0
  26. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/character_benchmark_repository.py +919 -0
  27. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/character_benchmark_service.py +1062 -0
  28. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/character_images.py +62 -0
  29. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/character_models.py +110 -0
  30. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/character_pack.py +177 -0
  31. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/character_repository.py +691 -0
  32. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/character_service.py +528 -0
  33. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/character_web_grant_repository.py +174 -0
  34. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/cli.py +2801 -0
  35. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/comparison.py +70 -0
  36. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/compilers/__init__.py +5 -0
  37. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/compilers/wan_curated.py +473 -0
  38. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/curated_ids.py +16 -0
  39. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/curated_metrics.py +86 -0
  40. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/curated_models.py +269 -0
  41. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/curated_source.py +468 -0
  42. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/curated_splits.py +279 -0
  43. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/curated_validation.py +557 -0
  44. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/database.py +6351 -0
  45. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/dataset_cli.py +1324 -0
  46. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/dataset_compiler.py +565 -0
  47. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/dataset_receipts.py +547 -0
  48. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/domain.py +249 -0
  49. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/evidence_service.py +525 -0
  50. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/feasibility.py +689 -0
  51. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/feasibility_models.py +300 -0
  52. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/feasibility_projection.py +531 -0
  53. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/feasibility_repository.py +900 -0
  54. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/feasibility_telemetry.py +128 -0
  55. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/host_canaries/__init__.py +29 -0
  56. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/host_canaries/wan_curated.py +1046 -0
  57. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/host_canaries/wan_qualification.py +1555 -0
  58. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/launcher.py +13 -0
  59. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/local_authority.py +689 -0
  60. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/normal_generation.py +161 -0
  61. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/operations.py +118 -0
  62. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/preference_optimizer.py +560 -0
  63. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/py.typed +0 -0
  64. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/queue_service.py +198 -0
  65. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/repositories.py +1293 -0
  66. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/review_service.py +545 -0
  67. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/reviews.py +452 -0
  68. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/runtime_identity.py +87 -0
  69. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/services.py +137 -0
  70. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/source_inventory.py +556 -0
  71. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/states.py +26 -0
  72. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/telemetry.py +54 -0
  73. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/trainer_protocol.py +855 -0
  74. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/trainers/__init__.py +106 -0
  75. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/trainers/fake.py +434 -0
  76. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/trainers/wan_batch.py +314 -0
  77. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/trainers/wan_branch_loader.py +623 -0
  78. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/trainers/wan_branch_runtime.py +916 -0
  79. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/trainers/wan_checkpoint.py +1642 -0
  80. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/trainers/wan_continuity.py +147 -0
  81. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/trainers/wan_diffusers_runtime.py +1289 -0
  82. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/trainers/wan_factory.py +1069 -0
  83. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/trainers/wan_mps.py +1442 -0
  84. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/trainers/wan_production_models.py +735 -0
  85. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/training_data.py +181 -0
  86. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/training_data_cli.py +66 -0
  87. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/training_dataset.py +206 -0
  88. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/training_media.py +586 -0
  89. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/training_models.py +1041 -0
  90. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/training_repository.py +1822 -0
  91. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/training_service.py +2759 -0
  92. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/validation_analysis.py +154 -0
  93. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/validation_models.py +263 -0
  94. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/validation_panel.py +151 -0
  95. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/validation_repository.py +641 -0
  96. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/validation_service.py +818 -0
  97. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/wan_pending.py +174 -0
  98. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/worker.py +525 -0
  99. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/worker_control.py +21 -0
  100. mlx_agent-0.9.0/src/mlx_agent/_lab/video_lab/worker_supervisor.py +327 -0
  101. mlx_agent-0.9.0/src/mlx_agent/adoption.py +870 -0
  102. mlx_agent-0.9.0/src/mlx_agent/atomicio.py +11 -0
  103. mlx_agent-0.9.0/src/mlx_agent/backend_install.py +255 -0
  104. mlx_agent-0.9.0/src/mlx_agent/backend_runner.py +63 -0
  105. mlx_agent-0.9.0/src/mlx_agent/backends.py +676 -0
  106. mlx_agent-0.9.0/src/mlx_agent/bench.py +445 -0
  107. mlx_agent-0.9.0/src/mlx_agent/blueprint.py +128 -0
  108. mlx_agent-0.9.0/src/mlx_agent/capture_platform.py +179 -0
  109. mlx_agent-0.9.0/src/mlx_agent/capture_volume.py +266 -0
  110. mlx_agent-0.9.0/src/mlx_agent/cli.py +2570 -0
  111. mlx_agent-0.9.0/src/mlx_agent/coding_capture_client.py +138 -0
  112. mlx_agent-0.9.0/src/mlx_agent/coding_capture_contracts.py +244 -0
  113. mlx_agent-0.9.0/src/mlx_agent/coding_capture_plugins.py +263 -0
  114. mlx_agent-0.9.0/src/mlx_agent/coding_capture_policy.py +121 -0
  115. mlx_agent-0.9.0/src/mlx_agent/coding_capture_process.py +179 -0
  116. mlx_agent-0.9.0/src/mlx_agent/coding_capture_storage.py +444 -0
  117. mlx_agent-0.9.0/src/mlx_agent/command_args.py +508 -0
  118. mlx_agent-0.9.0/src/mlx_agent/command_executor.py +74 -0
  119. mlx_agent-0.9.0/src/mlx_agent/compute.py +174 -0
  120. mlx_agent-0.9.0/src/mlx_agent/contextfit.py +87 -0
  121. mlx_agent-0.9.0/src/mlx_agent/contracts.py +98 -0
  122. mlx_agent-0.9.0/src/mlx_agent/convert.py +549 -0
  123. mlx_agent-0.9.0/src/mlx_agent/convert_queue.py +532 -0
  124. mlx_agent-0.9.0/src/mlx_agent/decide.py +145 -0
  125. mlx_agent-0.9.0/src/mlx_agent/decide_runner.py +31 -0
  126. mlx_agent-0.9.0/src/mlx_agent/describe.py +182 -0
  127. mlx_agent-0.9.0/src/mlx_agent/describe_runner.py +125 -0
  128. mlx_agent-0.9.0/src/mlx_agent/discovery.py +528 -0
  129. mlx_agent-0.9.0/src/mlx_agent/fetch_runner.py +64 -0
  130. mlx_agent-0.9.0/src/mlx_agent/fleet.py +277 -0
  131. mlx_agent-0.9.0/src/mlx_agent/fuse.py +213 -0
  132. mlx_agent-0.9.0/src/mlx_agent/generate.py +124 -0
  133. mlx_agent-0.9.0/src/mlx_agent/generate_runner.py +36 -0
  134. mlx_agent-0.9.0/src/mlx_agent/gguf.py +1038 -0
  135. mlx_agent-0.9.0/src/mlx_agent/gguf_runner.py +242 -0
  136. mlx_agent-0.9.0/src/mlx_agent/host.py +54 -0
  137. mlx_agent-0.9.0/src/mlx_agent/huggingface.py +683 -0
  138. mlx_agent-0.9.0/src/mlx_agent/installer.py +829 -0
  139. mlx_agent-0.9.0/src/mlx_agent/intake.py +387 -0
  140. mlx_agent-0.9.0/src/mlx_agent/intake_fetch.py +179 -0
  141. mlx_agent-0.9.0/src/mlx_agent/intake_source.py +106 -0
  142. mlx_agent-0.9.0/src/mlx_agent/interview.py +302 -0
  143. mlx_agent-0.9.0/src/mlx_agent/jit_serve.py +564 -0
  144. mlx_agent-0.9.0/src/mlx_agent/lab.py +146 -0
  145. mlx_agent-0.9.0/src/mlx_agent/lab_adoption.py +193 -0
  146. mlx_agent-0.9.0/src/mlx_agent/lab_studies.py +52 -0
  147. mlx_agent-0.9.0/src/mlx_agent/lab_workspace.py +246 -0
  148. mlx_agent-0.9.0/src/mlx_agent/lora.py +568 -0
  149. mlx_agent-0.9.0/src/mlx_agent/mcp_server.py +243 -0
  150. mlx_agent-0.9.0/src/mlx_agent/modality.py +283 -0
  151. mlx_agent-0.9.0/src/mlx_agent/model_doctor.py +502 -0
  152. mlx_agent-0.9.0/src/mlx_agent/models.py +184 -0
  153. mlx_agent-0.9.0/src/mlx_agent/music.py +90 -0
  154. mlx_agent-0.9.0/src/mlx_agent/music_requantize_runner.py +71 -0
  155. mlx_agent-0.9.0/src/mlx_agent/music_runner.py +89 -0
  156. mlx_agent-0.9.0/src/mlx_agent/port_analysis.py +181 -0
  157. mlx_agent-0.9.0/src/mlx_agent/port_plan.py +113 -0
  158. mlx_agent-0.9.0/src/mlx_agent/probe_assets.py +116 -0
  159. mlx_agent-0.9.0/src/mlx_agent/project_blueprint.py +257 -0
  160. mlx_agent-0.9.0/src/mlx_agent/providers.py +523 -0
  161. mlx_agent-0.9.0/src/mlx_agent/queue_bridge.py +139 -0
  162. mlx_agent-0.9.0/src/mlx_agent/queue_cli.py +190 -0
  163. mlx_agent-0.9.0/src/mlx_agent/research.py +502 -0
  164. mlx_agent-0.9.0/src/mlx_agent/resources/adapter-runtime.json +4 -0
  165. mlx_agent-0.9.0/src/mlx_agent/resources/backends/mflux.json +39 -0
  166. mlx_agent-0.9.0/src/mlx_agent/resources/backends/mflux.lock +1447 -0
  167. mlx_agent-0.9.0/src/mlx_agent/resources/backends/mlx-audio.json +176 -0
  168. mlx_agent-0.9.0/src/mlx_agent/resources/backends/mlx-audio.lock +1543 -0
  169. mlx_agent-0.9.0/src/mlx_agent/resources/backends/mlx-embeddings.json +50 -0
  170. mlx_agent-0.9.0/src/mlx_agent/resources/backends/mlx-embeddings.lock +1576 -0
  171. mlx_agent-0.9.0/src/mlx_agent/resources/backends/mlx-lm.json +123 -0
  172. mlx_agent-0.9.0/src/mlx_agent/resources/backends/mlx-video.json +27 -0
  173. mlx_agent-0.9.0/src/mlx_agent/resources/backends/mlx-video.lock +1635 -0
  174. mlx_agent-0.9.0/src/mlx_agent/resources/backends/mlx-vlm.json +356 -0
  175. mlx_agent-0.9.0/src/mlx_agent/resources/backends/mlx-vlm.lock +1495 -0
  176. mlx_agent-0.9.0/src/mlx_agent/resources/bench-community.json +4 -0
  177. mlx_agent-0.9.0/src/mlx_agent/resources/coding_capture/freeze.mjs +99 -0
  178. mlx_agent-0.9.0/src/mlx_agent/resources/coding_capture/legacy.mjs +77 -0
  179. mlx_agent-0.9.0/src/mlx_agent/resources/coding_capture/proxy.mjs +47 -0
  180. mlx_agent-0.9.0/src/mlx_agent/resources/coding_capture/rpc.mjs +54 -0
  181. mlx_agent-0.9.0/src/mlx_agent/resources/coding_capture/worker.mjs +36 -0
  182. mlx_agent-0.9.0/src/mlx_agent/resources/ports/mflux/qwen_image_21/__init__.py +5 -0
  183. mlx_agent-0.9.0/src/mlx_agent/resources/ports/mflux/qwen_image_21/convert.py +81 -0
  184. mlx_agent-0.9.0/src/mlx_agent/resources/ports/mflux/qwen_image_21/qwen_image_21.py +73 -0
  185. mlx_agent-0.9.0/src/mlx_agent/resources/ports/mlx-audio/audio8_asr_infinite/__init__.py +4 -0
  186. mlx_agent-0.9.0/src/mlx_agent/resources/ports/mlx-audio/audio8_asr_infinite/audio.py +96 -0
  187. mlx_agent-0.9.0/src/mlx_agent/resources/ports/mlx-audio/audio8_asr_infinite/audio8_asr_infinite.py +494 -0
  188. mlx_agent-0.9.0/src/mlx_agent/resources/ports/mlx-audio/audio8_asr_infinite/config.py +106 -0
  189. mlx_agent-0.9.0/src/mlx_agent/resources/ports/mlx-embeddings/laya/__init__.py +5 -0
  190. mlx_agent-0.9.0/src/mlx_agent/resources/ports/mlx-embeddings/laya/convert.py +94 -0
  191. mlx_agent-0.9.0/src/mlx_agent/resources/ports/mlx-embeddings/laya/laya.py +337 -0
  192. mlx_agent-0.9.0/src/mlx_agent/resources/ports/mlx-lm/deepseek_v4_dspark/__init__.py +1 -0
  193. mlx_agent-0.9.0/src/mlx_agent/resources/ports/mlx-lm/deepseek_v4_dspark/convert.py +311 -0
  194. mlx_agent-0.9.0/src/mlx_agent/resources/ports/mlx-video/t2v/__init__.py +6 -0
  195. mlx_agent-0.9.0/src/mlx_agent/resources/ports/mlx-video/t2v/convert.py +87 -0
  196. mlx_agent-0.9.0/src/mlx_agent/resources/ports/mlx-video/t2v/t2v.py +145 -0
  197. mlx_agent-0.9.0/src/mlx_agent/resources/ports/mlx-video/t2v/training.py +292 -0
  198. mlx_agent-0.9.0/src/mlx_agent/resources/ports/mlx-video/t2v/training_inputs.py +253 -0
  199. mlx_agent-0.9.0/src/mlx_agent/resources/references/model-families.md +35 -0
  200. mlx_agent-0.9.0/src/mlx_agent/resources/references/quantization.md +25 -0
  201. mlx_agent-0.9.0/src/mlx_agent/resources/references/troubleshooting.md +33 -0
  202. mlx_agent-0.9.0/src/mlx_agent/resources/serve-recipes.json +30 -0
  203. mlx_agent-0.9.0/src/mlx_agent/runtime_preference.py +142 -0
  204. mlx_agent-0.9.0/src/mlx_agent/scoring.py +194 -0
  205. mlx_agent-0.9.0/src/mlx_agent/serve.py +972 -0
  206. mlx_agent-0.9.0/src/mlx_agent/speak.py +161 -0
  207. mlx_agent-0.9.0/src/mlx_agent/speak_runner.py +73 -0
  208. mlx_agent-0.9.0/src/mlx_agent/strata_runtime.py +277 -0
  209. mlx_agent-0.9.0/src/mlx_agent/study_recipes.py +206 -0
  210. mlx_agent-0.9.0/src/mlx_agent/task_cli.py +92 -0
  211. mlx_agent-0.9.0/src/mlx_agent/task_contracts.py +313 -0
  212. mlx_agent-0.9.0/src/mlx_agent/task_identity.py +60 -0
  213. mlx_agent-0.9.0/src/mlx_agent/task_mp4_validator.py +46 -0
  214. mlx_agent-0.9.0/src/mlx_agent/task_png_validator.py +25 -0
  215. mlx_agent-0.9.0/src/mlx_agent/task_runtime.py +500 -0
  216. mlx_agent-0.9.0/src/mlx_agent/task_store.py +476 -0
  217. mlx_agent-0.9.0/src/mlx_agent/task_worker.py +19 -0
  218. mlx_agent-0.9.0/src/mlx_agent/taxonomy.py +266 -0
  219. mlx_agent-0.9.0/src/mlx_agent/training_artifacts.py +43 -0
  220. mlx_agent-0.9.0/src/mlx_agent/training_eval_runtime.py +31 -0
  221. mlx_agent-0.9.0/src/mlx_agent/training_evaluation.py +235 -0
  222. mlx_agent-0.9.0/src/mlx_agent/training_runner.py +30 -0
  223. mlx_agent-0.9.0/src/mlx_agent/transactions.py +1362 -0
  224. mlx_agent-0.9.0/src/mlx_agent/transcribe.py +107 -0
  225. mlx_agent-0.9.0/src/mlx_agent/transcribe_runner.py +66 -0
  226. mlx_agent-0.9.0/src/mlx_agent/verification.py +1163 -0
  227. mlx_agent-0.9.0/src/mlx_agent/video.py +182 -0
  228. mlx_agent-0.9.0/src/mlx_agent/video_runner.py +38 -0
  229. mlx_agent-0.9.0/src/mlx_agent/watch.py +206 -0
  230. mlx_agent-0.9.0/src/mlx_agent/wiring.py +353 -0
@@ -0,0 +1,17 @@
1
+ __pycache__/
2
+ *.pyc
3
+ .DS_Store
4
+ node_modules/
5
+ .worktrees/
6
+ .superpowers/
7
+ docs/superpowers/
8
+ .claude/
9
+ .cursor/
10
+ .code-review-graph/
11
+ docs/design/
12
+ data/
13
+
14
+ # Local Python environments and validation evidence
15
+ .venv/
16
+ .run/
17
+ .run-*.log
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sasan Sotoodehfar
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,212 @@
1
+ Metadata-Version: 2.5
2
+ Name: mlx-agent
3
+ Version: 0.9.0
4
+ Summary: Discover, verify and wire local MLX models on Apple Silicon
5
+ Project-URL: Homepage, https://cavi-ai.xyz
6
+ Project-URL: Repository, https://github.com/cavi-ai/mlx-agent
7
+ Project-URL: Changelog, https://github.com/cavi-ai/mlx-agent/blob/main/CHANGELOG.md
8
+ Author: Sasan Sotoodehfar
9
+ Maintainer: CAVI AI
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: apple-silicon,huggingface,local-models,mcp,mlx
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Environment :: Console
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Operating System :: MacOS
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
19
+ Requires-Python: >=3.9
20
+ Description-Content-Type: text/markdown
21
+
22
+ # mlx-agent
23
+
24
+ Discover, verify, and operate local MLX models on Apple Silicon for your coding
25
+ agent. mlx-agent ranks candidates for your memory budget, records local role
26
+ checks, measures served models, and writes reviewed connection configurations.
27
+
28
+ The Python core uses the standard library. Model execution needs a separately
29
+ installed runtime; optional backends have their own dependencies.
30
+
31
+ Current package version: **0.9.0**. These docs describe the current checkout;
32
+ published releases may contain earlier behavior.
33
+
34
+ ## Install
35
+
36
+ Choose your coding-agent host. Install its CLI first, then restart it after
37
+ adding mlx-agent. See [Installation](docs/mlx-agent/source/pages/introduction/installation.md)
38
+ for requirements and [provider lifecycle](docs/install/index.md) for project
39
+ scope, updates, removal, and recovery.
40
+
41
+ ### Claude Code
42
+
43
+ ```bash
44
+ claude plugin marketplace add cavi-ai/mlx-agent
45
+ claude plugin install mlx-agent@mlx-agent
46
+ ```
47
+
48
+ Run `/mlx-scout` after restarting.
49
+
50
+ ### Codex CLI
51
+
52
+ ```bash
53
+ codex plugin marketplace add cavi-ai/mlx-agent --ref v0.9.0
54
+ codex plugin add mlx-agent@mlx-agent
55
+ ```
56
+
57
+ Invoke `$mlx-agent:mlx-scout` after restarting. Codex does not support custom
58
+ slash commands.
59
+
60
+ ### Agy
61
+
62
+ ```bash
63
+ git clone --depth 1 --branch v0.9.0 https://github.com/cavi-ai/mlx-agent.git
64
+ agy plugin validate ./mlx-agent/providers/agy
65
+ agy plugin install ./mlx-agent/providers/agy
66
+ ```
67
+
68
+ Restart Agy, check `/skills`, and ask it to use `mlx-scout`.
69
+
70
+ ### OpenCode and portable skills
71
+
72
+ From a release checkout:
73
+
74
+ ```bash
75
+ git clone --depth 1 --branch v0.9.0 https://github.com/cavi-ai/mlx-agent.git
76
+ cd mlx-agent
77
+ python3 scripts/mlx-agent install opencode --scope user --dry-run --json
78
+ # Review the plan; copy data.preview.preview_hash.
79
+ python3 scripts/mlx-agent install opencode --scope user --confirm --preview-hash <preview-hash> --json
80
+ python3 scripts/mlx-agent doctor opencode --scope user --json
81
+ ```
82
+
83
+ Restart OpenCode and use `/mlx-scout`. For AgentSkills-compatible hosts, use
84
+ the same preview/confirm sequence with `agentskills`:
85
+
86
+ ```bash
87
+ python3 scripts/mlx-agent install agentskills --scope user --dry-run --json
88
+ python3 scripts/mlx-agent install agentskills --scope user --confirm --preview-hash <preview-hash> --json
89
+ ```
90
+
91
+ The installer copies a runtime into each installed portable skill. Move unowned
92
+ older `mlx-*` skill folders aside before the first managed install.
93
+
94
+ ### OpenClaw and Hermes Agent
95
+
96
+ From the same checkout, use the preview/confirm sequence with `openclaw` or
97
+ `hermes`:
98
+
99
+ ```bash
100
+ python3 scripts/mlx-agent install openclaw --scope user --dry-run --json
101
+ python3 scripts/mlx-agent install openclaw --scope user --confirm --preview-hash <preview-hash> --json
102
+ ```
103
+
104
+ Skills go to `$OPENCLAW_STATE_DIR/skills` (default `~/.openclaw/skills`) or
105
+ `$HERMES_HOME/skills` (default `~/.hermes/skills`). Start a new session and use
106
+ `/mlx-scout`.
107
+
108
+ ### Other MCP hosts
109
+
110
+ The `mlx-agent` package on PyPI carries the CLI and the MCP server. Add the
111
+ server to any MCP host's configuration:
112
+
113
+ ```json
114
+ {
115
+ "mcpServers": {
116
+ "mlx-agent": {"command": "uvx", "args": ["--from", "mlx-agent", "mlx-agent-mcp"]}
117
+ }
118
+ }
119
+ ```
120
+
121
+ Install the CLI with `uv tool install mlx-agent` or `pipx install mlx-agent`.
122
+ Provider installation copies the plugin files, so `mlx-agent install` runs from
123
+ a checkout.
124
+
125
+ ## First local model
126
+
127
+ From a checkout, inspect the host and find candidates:
128
+
129
+ ```bash
130
+ python3 scripts/mlx-agent inspect-host --json
131
+ python3 scripts/mlx-agent discover --role coding --limit 3 --json
132
+ ```
133
+
134
+ Review size, license, gating, runtime compatibility, and evidence. Discovery
135
+ does not download weights. Make the chosen model available with your runtime
136
+ or an explicitly confirmed [Intake](docs/mlx-agent/source/pages/lifecycle/intake.md)
137
+ download, then start its local server.
138
+
139
+ Intake can also list existing MLX conversions of a source model on the Hub.
140
+ Review these candidates before downloading or converting weights.
141
+
142
+ Follow [Your first local model](docs/mlx-agent/source/pages/introduction/quickstart.md)
143
+ to load weights, verify the shortlist, measure performance, and preview a
144
+ configuration. Keep the returned receipts for inspection and rollback.
145
+
146
+ ## What you can do
147
+
148
+ | Goal | Guide |
149
+ | --- | --- |
150
+ | Find models that fit a role and context budget | [Scout](docs/mlx-agent/source/pages/capabilities/scout.md) |
151
+ | Test candidates and retain evidence | [Adopt](docs/mlx-agent/source/pages/capabilities/adopt.md) |
152
+ | Apply or recover a connection configuration | [Wire](docs/mlx-agent/source/pages/capabilities/wire.md) |
153
+ | Measure an already-served model | [Bench](docs/mlx-agent/source/pages/capabilities/bench.md) |
154
+ | Research a domain or design a project | [Research](docs/mlx-agent/source/pages/capabilities/research.md) · [Blueprint](docs/mlx-agent/source/pages/capabilities/blueprint.md) |
155
+ | Download, quantize, and run model tasks | [Intake](docs/mlx-agent/source/pages/lifecycle/intake.md) · [Convert](docs/mlx-agent/source/pages/lifecycle/convert.md) · [Local inference](docs/mlx-agent/source/pages/lifecycle/local-inference.md) |
156
+ | Serve models with JIT loading and memory policy | [Serve](docs/mlx-agent/source/pages/lifecycle/serve.md) |
157
+ | Run controlled experiments and retain training evaluations | [Laboratory](docs/mlx-agent/source/pages/lifecycle/laboratory.md) |
158
+ | Train or fuse an adapter | [LoRA and fuse](docs/mlx-agent/source/pages/lifecycle/lora-and-fuse.md) |
159
+ | Route roles and inspect model health or changes | [Fleet](docs/mlx-agent/source/pages/lifecycle/fleet.md) · [Doctor](docs/mlx-agent/source/pages/lifecycle/doctor.md) · [Watch](docs/mlx-agent/source/pages/lifecycle/watch.md) |
160
+
161
+ ## Understand the evidence
162
+
163
+ Models retain a primary role and may also have `tool-use` membership. For
164
+ tool-use, metadata is not verification: recommendation requires a
165
+ schema-valid synthetic runtime tool call. The bounded probe supports Ollama and local
166
+ OpenAI-compatible LM Studio, `mlx_lm`, and LiteLLM servers.
167
+
168
+ Fit estimates and synthetic role probes help choose what to evaluate; they do
169
+ not establish production quality or reserve memory. See
170
+ [Evidence and sizing](docs/mlx-agent/source/pages/reference/evidence.md).
171
+
172
+ Configuration transactions and model job starts use reviewed preview hashes.
173
+ Explicit `intake fetch` downloads weights, and `backend install` installs
174
+ optional dependencies. Direct inference has a different execution contract.
175
+ Read the [security model](docs/mlx-agent/source/pages/security/model.md)
176
+ for confirmation, network, ownership, and recovery boundaries.
177
+
178
+ <!-- compatibility:begin -->
179
+ ## Provider support
180
+
181
+ First-class adapters are included for each provider below. The universal installer supports both user and project scopes.
182
+
183
+ | Provider | Package | Invoke |
184
+ | --- | --- | --- |
185
+ | [Claude Code](docs/install/claude.md) | Native plugin | `/mlx-scout`<br>`/mlx-adopt`<br>`/mlx-wire`<br>`/mlx-bench`<br>`/mlx-doctor`<br>`/mlx-watch`<br>`/mlx-fleet` |
186
+ | [Codex CLI](docs/install/codex.md) | Native plugin | `$mlx-agent:mlx-scout`<br>`$mlx-agent:mlx-adopt`<br>`$mlx-agent:mlx-wire`<br>`$mlx-agent:mlx-bench`<br>`$mlx-agent:mlx-doctor`<br>`$mlx-agent:mlx-watch`<br>`$mlx-agent:mlx-fleet` |
187
+ | [Agy](docs/install/agy.md) | Native plugin | `mlx-scout skill`<br>`mlx-adopt skill`<br>`mlx-wire skill`<br>`mlx-bench skill`<br>`mlx-doctor skill`<br>`mlx-watch skill`<br>`mlx-fleet skill` |
188
+ | [OpenCode](docs/install/opencode.md) | Native plugin | `/mlx-scout`<br>`/mlx-adopt`<br>`/mlx-wire`<br>`/mlx-bench`<br>`/mlx-doctor`<br>`/mlx-watch`<br>`/mlx-fleet` |
189
+ | [OpenClaw](docs/install/openclaw.md) | Native skills | `/mlx-scout`<br>`/mlx-adopt`<br>`/mlx-wire`<br>`/mlx-bench`<br>`/mlx-doctor`<br>`/mlx-watch`<br>`/mlx-fleet` |
190
+ | [Hermes Agent](docs/install/hermes.md) | Native skills | `/mlx-scout`<br>`/mlx-adopt`<br>`/mlx-wire`<br>`/mlx-bench`<br>`/mlx-doctor`<br>`/mlx-watch`<br>`/mlx-fleet` |
191
+ | [AgentSkills-compatible hosts](docs/install/index.md) | Portable skills | `mlx-scout skill`<br>`mlx-adopt skill`<br>`mlx-wire skill`<br>`mlx-bench skill`<br>`mlx-doctor skill`<br>`mlx-watch skill`<br>`mlx-fleet skill` |
192
+ <!-- compatibility:end -->
193
+
194
+ ## Documentation and contributing
195
+
196
+ The [documentation index](docs/README.md) links onboarding, workflows,
197
+ troubleshooting, references, and examples. Start with
198
+ [CLI](docs/mlx-agent/source/pages/reference/cli.md),
199
+ [Runtimes](docs/mlx-agent/source/pages/reference/runtimes.md), or
200
+ [Troubleshooting](docs/mlx-agent/source/pages/guides/troubleshooting.md).
201
+
202
+ See [Contributing](CONTRIBUTING.md) for local checks and
203
+ [Development](docs/mlx-agent/source/pages/guides/development.md) for adapters and
204
+ documentation builds. The opt-in release live smoke selects only direct local
205
+ Ollama, LM Studio, or `mlx_lm` backends.
206
+ LiteLLM is excluded from automatic live selection because it can route to remote or paid backends.
207
+
208
+ Versioned documentation comes from `docs/mlx-agent/source`. The
209
+ [consumer contract](docs/mlx-agent/CONSUMER.md) describes release artifacts;
210
+ editing source pages does not refresh an already published release.
211
+
212
+ Distributed under the [MIT License](LICENSE).
@@ -0,0 +1,191 @@
1
+ # mlx-agent
2
+
3
+ Discover, verify, and operate local MLX models on Apple Silicon for your coding
4
+ agent. mlx-agent ranks candidates for your memory budget, records local role
5
+ checks, measures served models, and writes reviewed connection configurations.
6
+
7
+ The Python core uses the standard library. Model execution needs a separately
8
+ installed runtime; optional backends have their own dependencies.
9
+
10
+ Current package version: **0.9.0**. These docs describe the current checkout;
11
+ published releases may contain earlier behavior.
12
+
13
+ ## Install
14
+
15
+ Choose your coding-agent host. Install its CLI first, then restart it after
16
+ adding mlx-agent. See [Installation](docs/mlx-agent/source/pages/introduction/installation.md)
17
+ for requirements and [provider lifecycle](docs/install/index.md) for project
18
+ scope, updates, removal, and recovery.
19
+
20
+ ### Claude Code
21
+
22
+ ```bash
23
+ claude plugin marketplace add cavi-ai/mlx-agent
24
+ claude plugin install mlx-agent@mlx-agent
25
+ ```
26
+
27
+ Run `/mlx-scout` after restarting.
28
+
29
+ ### Codex CLI
30
+
31
+ ```bash
32
+ codex plugin marketplace add cavi-ai/mlx-agent --ref v0.9.0
33
+ codex plugin add mlx-agent@mlx-agent
34
+ ```
35
+
36
+ Invoke `$mlx-agent:mlx-scout` after restarting. Codex does not support custom
37
+ slash commands.
38
+
39
+ ### Agy
40
+
41
+ ```bash
42
+ git clone --depth 1 --branch v0.9.0 https://github.com/cavi-ai/mlx-agent.git
43
+ agy plugin validate ./mlx-agent/providers/agy
44
+ agy plugin install ./mlx-agent/providers/agy
45
+ ```
46
+
47
+ Restart Agy, check `/skills`, and ask it to use `mlx-scout`.
48
+
49
+ ### OpenCode and portable skills
50
+
51
+ From a release checkout:
52
+
53
+ ```bash
54
+ git clone --depth 1 --branch v0.9.0 https://github.com/cavi-ai/mlx-agent.git
55
+ cd mlx-agent
56
+ python3 scripts/mlx-agent install opencode --scope user --dry-run --json
57
+ # Review the plan; copy data.preview.preview_hash.
58
+ python3 scripts/mlx-agent install opencode --scope user --confirm --preview-hash <preview-hash> --json
59
+ python3 scripts/mlx-agent doctor opencode --scope user --json
60
+ ```
61
+
62
+ Restart OpenCode and use `/mlx-scout`. For AgentSkills-compatible hosts, use
63
+ the same preview/confirm sequence with `agentskills`:
64
+
65
+ ```bash
66
+ python3 scripts/mlx-agent install agentskills --scope user --dry-run --json
67
+ python3 scripts/mlx-agent install agentskills --scope user --confirm --preview-hash <preview-hash> --json
68
+ ```
69
+
70
+ The installer copies a runtime into each installed portable skill. Move unowned
71
+ older `mlx-*` skill folders aside before the first managed install.
72
+
73
+ ### OpenClaw and Hermes Agent
74
+
75
+ From the same checkout, use the preview/confirm sequence with `openclaw` or
76
+ `hermes`:
77
+
78
+ ```bash
79
+ python3 scripts/mlx-agent install openclaw --scope user --dry-run --json
80
+ python3 scripts/mlx-agent install openclaw --scope user --confirm --preview-hash <preview-hash> --json
81
+ ```
82
+
83
+ Skills go to `$OPENCLAW_STATE_DIR/skills` (default `~/.openclaw/skills`) or
84
+ `$HERMES_HOME/skills` (default `~/.hermes/skills`). Start a new session and use
85
+ `/mlx-scout`.
86
+
87
+ ### Other MCP hosts
88
+
89
+ The `mlx-agent` package on PyPI carries the CLI and the MCP server. Add the
90
+ server to any MCP host's configuration:
91
+
92
+ ```json
93
+ {
94
+ "mcpServers": {
95
+ "mlx-agent": {"command": "uvx", "args": ["--from", "mlx-agent", "mlx-agent-mcp"]}
96
+ }
97
+ }
98
+ ```
99
+
100
+ Install the CLI with `uv tool install mlx-agent` or `pipx install mlx-agent`.
101
+ Provider installation copies the plugin files, so `mlx-agent install` runs from
102
+ a checkout.
103
+
104
+ ## First local model
105
+
106
+ From a checkout, inspect the host and find candidates:
107
+
108
+ ```bash
109
+ python3 scripts/mlx-agent inspect-host --json
110
+ python3 scripts/mlx-agent discover --role coding --limit 3 --json
111
+ ```
112
+
113
+ Review size, license, gating, runtime compatibility, and evidence. Discovery
114
+ does not download weights. Make the chosen model available with your runtime
115
+ or an explicitly confirmed [Intake](docs/mlx-agent/source/pages/lifecycle/intake.md)
116
+ download, then start its local server.
117
+
118
+ Intake can also list existing MLX conversions of a source model on the Hub.
119
+ Review these candidates before downloading or converting weights.
120
+
121
+ Follow [Your first local model](docs/mlx-agent/source/pages/introduction/quickstart.md)
122
+ to load weights, verify the shortlist, measure performance, and preview a
123
+ configuration. Keep the returned receipts for inspection and rollback.
124
+
125
+ ## What you can do
126
+
127
+ | Goal | Guide |
128
+ | --- | --- |
129
+ | Find models that fit a role and context budget | [Scout](docs/mlx-agent/source/pages/capabilities/scout.md) |
130
+ | Test candidates and retain evidence | [Adopt](docs/mlx-agent/source/pages/capabilities/adopt.md) |
131
+ | Apply or recover a connection configuration | [Wire](docs/mlx-agent/source/pages/capabilities/wire.md) |
132
+ | Measure an already-served model | [Bench](docs/mlx-agent/source/pages/capabilities/bench.md) |
133
+ | Research a domain or design a project | [Research](docs/mlx-agent/source/pages/capabilities/research.md) · [Blueprint](docs/mlx-agent/source/pages/capabilities/blueprint.md) |
134
+ | Download, quantize, and run model tasks | [Intake](docs/mlx-agent/source/pages/lifecycle/intake.md) · [Convert](docs/mlx-agent/source/pages/lifecycle/convert.md) · [Local inference](docs/mlx-agent/source/pages/lifecycle/local-inference.md) |
135
+ | Serve models with JIT loading and memory policy | [Serve](docs/mlx-agent/source/pages/lifecycle/serve.md) |
136
+ | Run controlled experiments and retain training evaluations | [Laboratory](docs/mlx-agent/source/pages/lifecycle/laboratory.md) |
137
+ | Train or fuse an adapter | [LoRA and fuse](docs/mlx-agent/source/pages/lifecycle/lora-and-fuse.md) |
138
+ | Route roles and inspect model health or changes | [Fleet](docs/mlx-agent/source/pages/lifecycle/fleet.md) · [Doctor](docs/mlx-agent/source/pages/lifecycle/doctor.md) · [Watch](docs/mlx-agent/source/pages/lifecycle/watch.md) |
139
+
140
+ ## Understand the evidence
141
+
142
+ Models retain a primary role and may also have `tool-use` membership. For
143
+ tool-use, metadata is not verification: recommendation requires a
144
+ schema-valid synthetic runtime tool call. The bounded probe supports Ollama and local
145
+ OpenAI-compatible LM Studio, `mlx_lm`, and LiteLLM servers.
146
+
147
+ Fit estimates and synthetic role probes help choose what to evaluate; they do
148
+ not establish production quality or reserve memory. See
149
+ [Evidence and sizing](docs/mlx-agent/source/pages/reference/evidence.md).
150
+
151
+ Configuration transactions and model job starts use reviewed preview hashes.
152
+ Explicit `intake fetch` downloads weights, and `backend install` installs
153
+ optional dependencies. Direct inference has a different execution contract.
154
+ Read the [security model](docs/mlx-agent/source/pages/security/model.md)
155
+ for confirmation, network, ownership, and recovery boundaries.
156
+
157
+ <!-- compatibility:begin -->
158
+ ## Provider support
159
+
160
+ First-class adapters are included for each provider below. The universal installer supports both user and project scopes.
161
+
162
+ | Provider | Package | Invoke |
163
+ | --- | --- | --- |
164
+ | [Claude Code](docs/install/claude.md) | Native plugin | `/mlx-scout`<br>`/mlx-adopt`<br>`/mlx-wire`<br>`/mlx-bench`<br>`/mlx-doctor`<br>`/mlx-watch`<br>`/mlx-fleet` |
165
+ | [Codex CLI](docs/install/codex.md) | Native plugin | `$mlx-agent:mlx-scout`<br>`$mlx-agent:mlx-adopt`<br>`$mlx-agent:mlx-wire`<br>`$mlx-agent:mlx-bench`<br>`$mlx-agent:mlx-doctor`<br>`$mlx-agent:mlx-watch`<br>`$mlx-agent:mlx-fleet` |
166
+ | [Agy](docs/install/agy.md) | Native plugin | `mlx-scout skill`<br>`mlx-adopt skill`<br>`mlx-wire skill`<br>`mlx-bench skill`<br>`mlx-doctor skill`<br>`mlx-watch skill`<br>`mlx-fleet skill` |
167
+ | [OpenCode](docs/install/opencode.md) | Native plugin | `/mlx-scout`<br>`/mlx-adopt`<br>`/mlx-wire`<br>`/mlx-bench`<br>`/mlx-doctor`<br>`/mlx-watch`<br>`/mlx-fleet` |
168
+ | [OpenClaw](docs/install/openclaw.md) | Native skills | `/mlx-scout`<br>`/mlx-adopt`<br>`/mlx-wire`<br>`/mlx-bench`<br>`/mlx-doctor`<br>`/mlx-watch`<br>`/mlx-fleet` |
169
+ | [Hermes Agent](docs/install/hermes.md) | Native skills | `/mlx-scout`<br>`/mlx-adopt`<br>`/mlx-wire`<br>`/mlx-bench`<br>`/mlx-doctor`<br>`/mlx-watch`<br>`/mlx-fleet` |
170
+ | [AgentSkills-compatible hosts](docs/install/index.md) | Portable skills | `mlx-scout skill`<br>`mlx-adopt skill`<br>`mlx-wire skill`<br>`mlx-bench skill`<br>`mlx-doctor skill`<br>`mlx-watch skill`<br>`mlx-fleet skill` |
171
+ <!-- compatibility:end -->
172
+
173
+ ## Documentation and contributing
174
+
175
+ The [documentation index](docs/README.md) links onboarding, workflows,
176
+ troubleshooting, references, and examples. Start with
177
+ [CLI](docs/mlx-agent/source/pages/reference/cli.md),
178
+ [Runtimes](docs/mlx-agent/source/pages/reference/runtimes.md), or
179
+ [Troubleshooting](docs/mlx-agent/source/pages/guides/troubleshooting.md).
180
+
181
+ See [Contributing](CONTRIBUTING.md) for local checks and
182
+ [Development](docs/mlx-agent/source/pages/guides/development.md) for adapters and
183
+ documentation builds. The opt-in release live smoke selects only direct local
184
+ Ollama, LM Studio, or `mlx_lm` backends.
185
+ LiteLLM is excluded from automatic live selection because it can route to remote or paid backends.
186
+
187
+ Versioned documentation comes from `docs/mlx-agent/source`. The
188
+ [consumer contract](docs/mlx-agent/CONSUMER.md) describes release artifacts;
189
+ editing source pages does not refresh an already published release.
190
+
191
+ Distributed under the [MIT License](LICENSE).
@@ -0,0 +1,42 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.27,<2"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "mlx-agent"
7
+ dynamic = ["version"]
8
+ description = "Discover, verify and wire local MLX models on Apple Silicon"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ requires-python = ">=3.9"
13
+ authors = [{ name = "Sasan Sotoodehfar" }]
14
+ maintainers = [{ name = "CAVI AI" }]
15
+ keywords = ["mlx", "apple-silicon", "mcp", "local-models", "huggingface"]
16
+ classifiers = [
17
+ "Development Status :: 4 - Beta",
18
+ "Environment :: Console",
19
+ "Intended Audience :: Developers",
20
+ "Operating System :: MacOS",
21
+ "Programming Language :: Python :: 3",
22
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
23
+ ]
24
+ dependencies = []
25
+
26
+ [project.urls]
27
+ Homepage = "https://cavi-ai.xyz"
28
+ Repository = "https://github.com/cavi-ai/mlx-agent"
29
+ Changelog = "https://github.com/cavi-ai/mlx-agent/blob/main/CHANGELOG.md"
30
+
31
+ [project.scripts]
32
+ mlx-agent = "mlx_agent.cli:main"
33
+ mlx-agent-mcp = "mlx_agent.mcp_server:main"
34
+
35
+ [tool.hatch.version]
36
+ path = "src/mlx_agent/__init__.py"
37
+
38
+ [tool.hatch.build.targets.sdist]
39
+ only-include = ["src/mlx_agent", "README.md", "LICENSE", "pyproject.toml"]
40
+
41
+ [tool.hatch.build.targets.wheel]
42
+ packages = ["src/mlx_agent"]
@@ -0,0 +1,6 @@
1
+ """Public API for the dependency-free MLX agent core."""
2
+
3
+ from .contracts import ResultEnvelope
4
+
5
+ __all__ = ["ResultEnvelope"]
6
+ __version__ = "0.9.0"
@@ -0,0 +1,9 @@
1
+ """Run the MLX agent core with ``python -m mlx_agent``."""
2
+
3
+ import sys
4
+
5
+ from .cli import main
6
+
7
+
8
+ if __name__ == "__main__":
9
+ sys.exit(main())
@@ -0,0 +1,24 @@
1
+ __version__ = "0.1.0"
2
+
3
+ from .curated_ids import curated_dataset_digest, structured_caption_digest
4
+ from .curated_models import (
5
+ CuratedDatasetManifestV1,
6
+ CuratedFrameV1,
7
+ CuratedSequenceV1,
8
+ DatasetSplitPolicyV1,
9
+ SequenceTransformRecipeV1,
10
+ StructuredCaptionV1,
11
+ render_caption_v1,
12
+ )
13
+
14
+ __all__ = (
15
+ "CuratedDatasetManifestV1",
16
+ "CuratedFrameV1",
17
+ "CuratedSequenceV1",
18
+ "DatasetSplitPolicyV1",
19
+ "SequenceTransformRecipeV1",
20
+ "StructuredCaptionV1",
21
+ "curated_dataset_digest",
22
+ "render_caption_v1",
23
+ "structured_caption_digest",
24
+ )
@@ -0,0 +1,152 @@
1
+ import json
2
+ import math
3
+ from collections.abc import Callable, Mapping, Sequence, Set
4
+ from dataclasses import dataclass
5
+ from enum import StrEnum
6
+ from pathlib import Path
7
+ from types import MappingProxyType
8
+ from typing import Protocol, runtime_checkable
9
+
10
+ from pydantic import Field, field_serializer, field_validator
11
+
12
+ from video_lab.capabilities import AdapterCapabilities
13
+ from video_lab.domain import FrozenModel, Manifest
14
+
15
+
16
+ class GenerationRequest(FrozenModel):
17
+ job_id: str
18
+ attempt_id: str
19
+ manifest: Manifest
20
+ scratch_root: Path
21
+
22
+
23
+ class GenerationProgress(FrozenModel):
24
+ phase: str
25
+ completed: int = Field(ge=0)
26
+ total: int = Field(gt=0)
27
+ message: str
28
+ elapsed_seconds: float = Field(ge=0)
29
+
30
+
31
+ class GenerationResult(FrozenModel):
32
+ video_path: Path
33
+ effective_manifest: Manifest
34
+ frame_count: int = Field(gt=0)
35
+ fps: int = Field(gt=0)
36
+ width: int = Field(gt=0)
37
+ height: int = Field(gt=0)
38
+ adapter_version: str
39
+ runtime_versions: Mapping[str, str]
40
+ adapter_telemetry: Mapping[str, object]
41
+
42
+ @field_validator("runtime_versions")
43
+ @classmethod
44
+ def freeze_runtime_versions(cls, value: Mapping[str, str]) -> Mapping[str, str]:
45
+ return MappingProxyType(dict(value))
46
+
47
+ @field_validator("adapter_telemetry")
48
+ @classmethod
49
+ def freeze_adapter_telemetry(cls, value: object) -> Mapping[str, object]:
50
+ frozen = _freeze_json(value)
51
+ if not isinstance(frozen, Mapping):
52
+ raise TypeError("adapter telemetry must be a mapping")
53
+ return frozen
54
+
55
+ @field_serializer("runtime_versions")
56
+ def serialize_runtime_versions(self, value: Mapping[str, str]) -> dict[str, str]:
57
+ return dict(value)
58
+
59
+ @field_serializer("adapter_telemetry")
60
+ def serialize_adapter_telemetry(self, value: Mapping[str, object]) -> dict[str, object]:
61
+ serialized = _serialize_json(value)
62
+ if not isinstance(serialized, dict):
63
+ raise TypeError("adapter telemetry must serialize to a mapping")
64
+ return serialized
65
+
66
+
67
+ def _freeze_json(value: object) -> object:
68
+ if isinstance(value, float) and not math.isfinite(value):
69
+ raise ValueError("unsupported non-finite JSON number")
70
+ if value is None or isinstance(value, str | int | float | bool):
71
+ return value
72
+ if isinstance(value, Mapping):
73
+ if not all(isinstance(key, str) for key in value):
74
+ raise TypeError("adapter telemetry mapping keys must be strings")
75
+ return MappingProxyType({key: _freeze_json(item) for key, item in value.items()})
76
+ if isinstance(value, Set):
77
+ frozen = tuple(_freeze_json(item) for item in value)
78
+ return tuple(sorted(frozen, key=_json_order))
79
+ if isinstance(value, Sequence) and not isinstance(value, str | bytes | bytearray):
80
+ return tuple(_freeze_json(item) for item in value)
81
+ raise TypeError(f"unsupported adapter telemetry value: {type(value).__name__}")
82
+
83
+
84
+ def _serialize_json(value: object) -> object:
85
+ if isinstance(value, float) and not math.isfinite(value):
86
+ raise ValueError("unsupported non-finite JSON number")
87
+ if isinstance(value, Mapping):
88
+ return {str(key): _serialize_json(item) for key, item in value.items()}
89
+ if isinstance(value, tuple):
90
+ return [_serialize_json(item) for item in value]
91
+ return value
92
+
93
+
94
+ def _json_order(value: object) -> str:
95
+ return json.dumps(_serialize_json(value), sort_keys=True)
96
+
97
+
98
+ class GenerationCancelled(Exception):
99
+ """Raised when generation is cancelled before artifact finalization."""
100
+
101
+
102
+ class AdapterExecutionError(Exception):
103
+ """Raised when an adapter cannot complete generation."""
104
+
105
+
106
+ ProgressCallback = Callable[[GenerationProgress], None]
107
+ CancellationCheck = Callable[[], bool]
108
+
109
+
110
+ class ProbePhase(StrEnum):
111
+ ENVIRONMENT = "environment"
112
+ METADATA = "metadata"
113
+ CACHE = "cache"
114
+ LOAD = "load"
115
+ GENERATE = "generate"
116
+
117
+
118
+ @dataclass(frozen=True)
119
+ class ProbeReport:
120
+ phase: ProbePhase | str
121
+ ok: bool
122
+ diagnostics: Mapping[str, object]
123
+
124
+
125
+ @dataclass(frozen=True)
126
+ class ProbeRequest:
127
+ generation: GenerationRequest
128
+ progress: ProgressCallback
129
+ cancelled: CancellationCheck
130
+
131
+
132
+ @runtime_checkable
133
+ class GenerationAdapter(Protocol):
134
+ adapter_id: str
135
+
136
+ def capabilities(self) -> AdapterCapabilities: ...
137
+
138
+ def probe(self) -> bool: ...
139
+
140
+ def generate(
141
+ self,
142
+ request: GenerationRequest,
143
+ progress: ProgressCallback,
144
+ cancelled: CancellationCheck,
145
+ ) -> GenerationResult: ...
146
+
147
+
148
+ @runtime_checkable
149
+ class StagedProbeAdapter(GenerationAdapter, Protocol):
150
+ def probe_phase(
151
+ self, phase: ProbePhase, request: ProbeRequest | None = None
152
+ ) -> ProbeReport: ...