speedy-utils 2.0.7__tar.gz → 3.0.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 (221) hide show
  1. speedy_utils-3.0.0/.agents/PRs/pcat-vscode-command-resolution.md +94 -0
  2. speedy_utils-3.0.0/.agents/plans/pcat-vscode-command-resolution.md +102 -0
  3. speedy_utils-3.0.0/.codex/skills/speedy-utils-core +1 -0
  4. speedy_utils-3.0.0/.github/skills/speedy-utils-core/SKILL.md +92 -0
  5. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/.gitignore +11 -0
  6. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/CLAUDE.md +13 -4
  7. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/PKG-INFO +157 -14
  8. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/README.md +144 -5
  9. speedy_utils-3.0.0/agents/PRs/parallel_llm_job.md +103 -0
  10. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/bumpversion.sh +54 -46
  11. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/debug/test_qwen3_generate.md +1 -1
  12. speedy_utils-3.0.0/docs/DELETED.md +34 -0
  13. speedy_utils-3.0.0/docs/DEPRECATIONS.md +71 -0
  14. speedy_utils-3.0.0/docs/JOB_CONTEXT.md +44 -0
  15. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/docs/MIGRATION_THINKING.md +3 -3
  16. speedy_utils-3.0.0/docs/MULTI_THREAD_HOOKS.md +94 -0
  17. speedy_utils-3.0.0/docs/PARALLEL_LLM_JOB.md +188 -0
  18. speedy_utils-3.0.0/docs/SHORTCUTS.md +13 -0
  19. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/examples/llm_public_api_example.ipynb +1 -1
  20. speedy_utils-3.0.0/examples/qwen3llm_usage_demo.ipynb +250 -0
  21. speedy_utils-3.0.0/install-tools.sh +87 -0
  22. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/pyproject.toml +12 -8
  23. speedy_utils-3.0.0/setup-skill.sh +6 -0
  24. speedy_utils-3.0.0/setup-speedy-utils.sh +202 -0
  25. speedy_utils-3.0.0/src/datasets_utils/_tokenizer.py +33 -0
  26. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/datasets_utils/convert_to_arrow.py +9 -1
  27. speedy_utils-3.0.0/src/datasets_utils/pcat/_assets.py +518 -0
  28. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/datasets_utils/pcat/_shared.py +540 -96
  29. speedy_utils-3.0.0/src/datasets_utils/pcat/cli.py +125 -0
  30. speedy_utils-3.0.0/src/datasets_utils/pcat/serve.py +1392 -0
  31. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/datasets_utils/viz_chat.py +66 -102
  32. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/llm_utils/__init__.py +8 -1
  33. speedy_utils-3.0.0/src/llm_utils/_traceback.py +30 -0
  34. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/llm_utils/chat_format/display.py +209 -72
  35. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/llm_utils/chat_format/transform.py +6 -4
  36. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/llm_utils/lm/__init__.py +6 -1
  37. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/llm_utils/lm/llm.py +632 -174
  38. speedy_utils-3.0.0/src/llm_utils/lm/llm_audio.py +258 -0
  39. speedy_utils-3.0.0/src/llm_utils/lm/llm_ds41.py +254 -0
  40. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/llm_utils/lm/llm_qwen3.py +85 -26
  41. speedy_utils-3.0.0/src/llm_utils/lm/llm_qwen38.py +142 -0
  42. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/llm_utils/lm/llm_signature.py +10 -18
  43. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/llm_utils/lm/lm_base.py +51 -46
  44. speedy_utils-3.0.0/src/llm_utils/lm/openai_memoize.py +253 -0
  45. speedy_utils-3.0.0/src/llm_utils/lm/ssh_tunnel.py +143 -0
  46. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/llm_utils/lm/utils.py +15 -2
  47. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/llm_utils/scripts/sp_chat.py +264 -123
  48. speedy_utils-3.0.0/src/llm_utils/utils.py +89 -0
  49. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/__imports.py +4 -38
  50. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/__init__.py +18 -20
  51. speedy_utils-3.0.0/src/speedy_utils/_indexed_llm_job.py +137 -0
  52. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/common/clock.py +3 -13
  53. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/common/exceptions.py +7 -0
  54. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/common/logger.py +6 -7
  55. speedy_utils-3.0.0/src/speedy_utils/common/mirror_path.py +193 -0
  56. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/common/notebook_utils.py +1 -6
  57. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/common/utils_cache.py +71 -148
  58. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/common/utils_error.py +19 -24
  59. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/common/utils_io.py +21 -16
  60. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/common/utils_misc.py +0 -6
  61. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/common/utils_print.py +8 -20
  62. speedy_utils-3.0.0/src/speedy_utils/job_context.py +137 -0
  63. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/multi_worker/_mp_backends.py +11 -56
  64. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/multi_worker/_multi_process.py +20 -13
  65. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/multi_worker/common.py +17 -39
  66. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/multi_worker/dataset_sharding.py +10 -1
  67. speedy_utils-3.0.0/src/speedy_utils/multi_worker/multi_process_ray.py +320 -0
  68. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/multi_worker/process.py +2 -0
  69. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/multi_worker/thread.py +230 -188
  70. speedy_utils-3.0.0/src/speedy_utils/parallel_llm_job.py +921 -0
  71. speedy_utils-3.0.0/src/speedy_utils/scripts/mpython.py +317 -0
  72. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/vision_utils/__init__.py +1 -0
  73. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/vision_utils/io_utils.py +71 -138
  74. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/vision_utils/plot.py +7 -62
  75. speedy_utils-3.0.0/tests/llm_utils/test_llm_audio.py +344 -0
  76. speedy_utils-3.0.0/tests/llm_utils/test_llm_bad_request_retry.py +52 -0
  77. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/llm_utils/test_llm_call_contract.py +228 -1
  78. speedy_utils-3.0.0/tests/llm_utils/test_llm_ds41.py +229 -0
  79. speedy_utils-3.0.0/tests/llm_utils/test_llm_helpers.py +78 -0
  80. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/llm_utils/test_llm_mixins.py +134 -17
  81. speedy_utils-3.0.0/tests/llm_utils/test_llm_qwen38.py +120 -0
  82. speedy_utils-3.0.0/tests/llm_utils/test_llm_wait_for_endpoint.py +196 -0
  83. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/llm_utils/test_openai_memoize_completion_cache.py +84 -0
  84. speedy_utils-3.0.0/tests/llm_utils/test_openai_proxy_localhost.py +34 -0
  85. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/llm_utils/test_public_api.py +101 -0
  86. speedy_utils-3.0.0/tests/llm_utils/test_sp_chat.py +301 -0
  87. speedy_utils-3.0.0/tests/llm_utils/test_ssh_tunnel.py +87 -0
  88. speedy_utils-3.0.0/tests/test_clean_traceback.py +21 -0
  89. speedy_utils-3.0.0/tests/test_common_examples.py +49 -0
  90. speedy_utils-3.0.0/tests/test_dataset_sharding.py +22 -0
  91. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/test_identify.py +21 -1
  92. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/test_import_time.py +7 -7
  93. speedy_utils-3.0.0/tests/test_job_context.py +53 -0
  94. speedy_utils-3.0.0/tests/test_llm_expected_errors.py +43 -0
  95. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/test_load_jsonl.py +70 -1
  96. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/test_memoize.py +59 -1
  97. speedy_utils-3.0.0/tests/test_mirror_path.py +33 -0
  98. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/test_mpython.py +89 -4
  99. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/test_multi_process.py +44 -0
  100. speedy_utils-3.0.0/tests/test_multi_process_ray.py +202 -0
  101. speedy_utils-3.0.0/tests/test_optional_deps.py +134 -0
  102. speedy_utils-3.0.0/tests/test_parallel_llm_job.py +629 -0
  103. speedy_utils-3.0.0/tests/test_pcat.py +1313 -0
  104. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/test_process_update.py +80 -5
  105. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/test_thread.py +115 -34
  106. speedy_utils-3.0.0/tests/test_vision_utils.py +125 -0
  107. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/test_viz_chat.py +29 -0
  108. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/uv.lock +101 -59
  109. speedy_utils-3.0.0/vscode-pcat/.gitignore +4 -0
  110. speedy_utils-3.0.0/vscode-pcat/.vscodeignore +5 -0
  111. speedy_utils-3.0.0/vscode-pcat/README.md +61 -0
  112. speedy_utils-3.0.0/vscode-pcat/package.json +144 -0
  113. speedy_utils-3.0.0/vscode-pcat/src/extension.ts +734 -0
  114. speedy_utils-3.0.0/vscode-pcat/tsconfig.json +26 -0
  115. speedy_utils-2.0.7/.codex +0 -0
  116. speedy_utils-2.0.7/.github/skills/caching-utilities/SKILL.md +0 -133
  117. speedy_utils-2.0.7/.github/skills/caching-utilities/examples/caching_example.py +0 -37
  118. speedy_utils-2.0.7/.github/skills/dataset-processing-multiprocessing/CONFIG_REFERENCE.md +0 -217
  119. speedy_utils-2.0.7/.github/skills/dataset-processing-multiprocessing/SKILL.md +0 -797
  120. speedy_utils-2.0.7/.github/skills/dataset-processing-multiprocessing/example_tokenize_pack.py +0 -323
  121. speedy_utils-2.0.7/.github/skills/edit-llm-inference-style/SKILL.md +0 -133
  122. speedy_utils-2.0.7/.github/skills/io-utilities/SKILL.md +0 -111
  123. speedy_utils-2.0.7/.github/skills/io-utilities/examples/io_example.py +0 -35
  124. speedy_utils-2.0.7/.github/skills/llm-integration/SKILL.md +0 -115
  125. speedy_utils-2.0.7/.github/skills/llm-integration/examples/llm_example.py +0 -27
  126. speedy_utils-2.0.7/.github/skills/make-vscode-happy/SKILL.md +0 -80
  127. speedy_utils-2.0.7/.github/skills/make-vscode-happy/references/diagnostic-playbook.md +0 -94
  128. speedy_utils-2.0.7/.github/skills/multi-threading-processing/SKILL.md +0 -486
  129. speedy_utils-2.0.7/.github/skills/ray-distributed-computing/SKILL.md +0 -704
  130. speedy_utils-2.0.7/.github/skills/skill-creation/SKILL.md +0 -516
  131. speedy_utils-2.0.7/.github/skills/vision-utilities/SKILL.md +0 -105
  132. speedy_utils-2.0.7/.github/skills/vision-utilities/examples/vision_example.py +0 -44
  133. speedy_utils-2.0.7/src/datasets_utils/pcat/cli.py +0 -146
  134. speedy_utils-2.0.7/src/llm_utils/_traceback.py +0 -235
  135. speedy_utils-2.0.7/src/llm_utils/lm/base_prompt_builder.py +0 -341
  136. speedy_utils-2.0.7/src/llm_utils/lm/openai_memoize.py +0 -429
  137. speedy_utils-2.0.7/src/llm_utils/utils.py +0 -42
  138. speedy_utils-2.0.7/src/speedy_utils/common/function_decorator.py +0 -57
  139. speedy_utils-2.0.7/src/speedy_utils/common/patcher.py +0 -72
  140. speedy_utils-2.0.7/src/speedy_utils/common/report_manager.py +0 -108
  141. speedy_utils-2.0.7/src/speedy_utils/scripts/mpython.py +0 -262
  142. speedy_utils-2.0.7/tests/import_time_report.py +0 -269
  143. speedy_utils-2.0.7/tests/llm_utils/test_openai_proxy_localhost.py +0 -29
  144. speedy_utils-2.0.7/tests/llm_utils/test_sp_chat.py +0 -198
  145. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/.githooks/pre-commit +0 -0
  146. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/.githooks/pre-push +0 -0
  147. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/.github/prompts/improveParallelErrorHandling.prompt.md +0 -0
  148. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/.github/workflows/publish.yml +0 -0
  149. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/.pre-commit-config.yaml +0 -0
  150. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/AGENTS.md +0 -0
  151. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/CODING_STYLE.md +0 -0
  152. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/debug/debug_generate_response.py +0 -0
  153. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/debug/debug_n_param.py +0 -0
  154. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/debug/debug_n_structure.py +0 -0
  155. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/debug/integration_test.py +0 -0
  156. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/debug/multi_thread.py +0 -0
  157. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/debug/test_decode_api.py +0 -0
  158. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/debug/test_endpoints.py +0 -0
  159. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/debug/test_generate.py +0 -0
  160. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/debug/test_generate_endpoint.py +0 -0
  161. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/debug/test_qwen3_generate.py +0 -0
  162. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/docs/GENERATE_QUICKREF.md +0 -0
  163. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/docs/PR_LIBRARY_ERROR_HANDLING_REFACTOR_PLAN.md +0 -0
  164. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/docs/TDD.md +0 -0
  165. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/docs/TOKENIZATION.md +0 -0
  166. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/docs/TOKENIZATION_IMPLEMENTATION.md +0 -0
  167. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/examples/generate_example.py +0 -0
  168. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/examples/model_specific_thinking_example.py +0 -0
  169. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/examples/tokenization_example.py +0 -0
  170. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/examples/vision_utils_example.py +0 -0
  171. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/experiments/exp1/dockerfile +0 -0
  172. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/experiments/exp1/run_in_docker.sh +0 -0
  173. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/notebooks/demo_multi_process.py +0 -0
  174. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/notebooks/llm_utils/llm_as_a_judge.ipynb +0 -0
  175. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/notebooks/test.ipynb +0 -0
  176. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/pyrightconfig.json +0 -0
  177. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/ruff.toml +0 -0
  178. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/scripts/bug_simple.py +0 -0
  179. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/scripts/debug_import_time.py +0 -0
  180. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/scripts/debug_multi_process.py +0 -0
  181. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/scripts/deploy.sh +0 -0
  182. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/scripts/imports.sh +0 -0
  183. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/scripts/install_hooks.sh +0 -0
  184. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/scripts/test.py +0 -0
  185. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/scripts/test_error_handling.py +0 -0
  186. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/scripts/test_import_time_vision.py +0 -0
  187. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/scripts/test_locals.py +0 -0
  188. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/scripts/test_ray_mp.py +0 -0
  189. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/setup.cfg +0 -0
  190. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/datasets_utils/__init__.py +0 -0
  191. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/datasets_utils/pcat/__init__.py +0 -0
  192. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/datasets_utils/pcat/hf_dataset.py +0 -0
  193. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/datasets_utils/pcat/jsonl.py +0 -0
  194. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/llm_utils/chat_format/__init__.py +0 -0
  195. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/llm_utils/chat_format/utils.py +0 -0
  196. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/llm_utils/lm/signature.py +0 -0
  197. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/common/__init__.py +0 -0
  198. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/multi_worker/__init__.py +0 -0
  199. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/multi_worker/_mp_progress.py +0 -0
  200. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/multi_worker/_mp_spawn.py +0 -0
  201. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/scripts/__init__.py +0 -0
  202. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/scripts/kill_mpython.py +0 -0
  203. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/scripts/openapi_client_codegen.py +0 -0
  204. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/speedy_utils/scripts/prefetch_large_model.py +0 -0
  205. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/src/vision_utils/README.md +0 -0
  206. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/import_all.py +0 -0
  207. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/llm_utils/test_llm_signature.py +0 -0
  208. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/sample_objects.py +0 -0
  209. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/test.py +0 -0
  210. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/test_logger.py +0 -0
  211. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/test_logger_format.py +0 -0
  212. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/test_memoize_typing.py +0 -0
  213. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/test_mp_no_main_guard.py +0 -0
  214. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/test_multi_thread.py +0 -0
  215. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/test_multithread_error_trace.py +0 -0
  216. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/test_prefetch_large_model.py +0 -0
  217. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/test_process.py +0 -0
  218. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/test_tokenization.py +0 -0
  219. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tests/test_utils_io.py +0 -0
  220. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tools/check_syntax.py +0 -0
  221. {speedy_utils-2.0.7 → speedy_utils-3.0.0}/tools/uv_test.sh +0 -0
@@ -0,0 +1,94 @@
1
+ # Problem Report: PCAT VS Code Command Resolution Fails Outside Interactive Shells
2
+
3
+ ## Summary
4
+
5
+ The PCAT VS Code extension opens `.jsonl` files and can launch `pcat` in the
6
+ integrated terminal, but preview actions can fail with:
7
+
8
+ ```text
9
+ PCAT preview failed: /bin/sh: 1: pcat: not found
10
+ ```
11
+
12
+ This is a shipped behavior bug in the extension, not a user configuration
13
+ mistake.
14
+
15
+ ## User-visible Symptom
16
+
17
+ - Opening a `.jsonl` file can show the PCAT custom editor as expected.
18
+ - Using `PCAT: Preview Plain Row` fails with `pcat: not found`.
19
+ - Interactive terminal launches may appear to work in the same workspace.
20
+
21
+ ## Reproduction
22
+
23
+ 1. Install the current `pcat-vscode` extension build.
24
+ 2. Leave `pcat.command` at its default value of `pcat`.
25
+ 3. Use a shell where `pcat` is defined only through interactive shell setup,
26
+ such as an alias in `.zshrc`.
27
+ 4. Open a `.jsonl` file and run `PCAT: Preview Plain Row`.
28
+ 5. Observe the failure notification.
29
+
30
+ ## Confirmed Evidence
31
+
32
+ Interactive shell resolution succeeds:
33
+
34
+ ```text
35
+ alias pcat='uvx --from /home/anhvth8/projects/speedy_utils pcat'
36
+ ```
37
+
38
+ The non-interactive shell used by the extension cannot resolve it:
39
+
40
+ ```text
41
+ /bin/sh: 32: source: not found
42
+ __PCAT_MISSING_IN_SH__
43
+ ```
44
+
45
+ ## Root Cause
46
+
47
+ The extension currently has two different execution paths:
48
+
49
+ - Interactive open uses the VS Code integrated terminal.
50
+ - Plain preview uses `child_process.exec(...)`.
51
+
52
+ The preview path inherits Node's default shell execution behavior, which uses a
53
+ non-interactive `/bin/sh` environment. That environment does not load the same
54
+ interactive shell aliases, functions, or PATH mutations that make `pcat`
55
+ available in the user's zsh terminal.
56
+
57
+ As a result, the extension is inconsistent:
58
+
59
+ - `pcat` can appear available in the integrated terminal.
60
+ - the same command string fails in preview mode.
61
+
62
+ ## Why This Is a Product Bug
63
+
64
+ - The default extension setting is `pcat.command = "pcat"`.
65
+ - In this environment, `pcat` is not a real executable on PATH for `/bin/sh`.
66
+ - The extension depends on shell-specific behavior without resolving or
67
+ validating the command.
68
+ - The extension does not fail early with actionable guidance.
69
+
70
+ ## Impact
71
+
72
+ - `.jsonl` custom-editor flows are unreliable.
73
+ - preview is broken in common remote and shell-customized setups.
74
+ - the extension currently depends on undocumented shell state.
75
+
76
+ ## Expected Behavior
77
+
78
+ The extension should either:
79
+
80
+ - resolve `pcat` in a shell-agnostic way before use, or
81
+ - require an explicit executable command and validate it clearly, or
82
+ - reuse one consistent execution strategy for both terminal and preview flows.
83
+
84
+ At minimum, preview and open actions must succeed or fail with the same command
85
+ resolution behavior.
86
+
87
+ ## Acceptance Criteria
88
+
89
+ - `PCAT: Preview Plain Row` works when `pcat.command` is configured to a valid
90
+ executable command.
91
+ - Default behavior does not silently rely on zsh aliases.
92
+ - When command resolution fails, the user sees an actionable error describing
93
+ how to set `pcat.command`.
94
+ - Interactive open and preview use the same command-resolution rules.
@@ -0,0 +1,102 @@
1
+ # Plan: Fix and Validate PCAT VS Code Command Resolution
2
+
3
+ Related problem report:
4
+
5
+ - `.agents/PRs/pcat-vscode-command-resolution.md`
6
+
7
+ ## Goal
8
+
9
+ Make the PCAT VS Code extension reliable in non-interactive environments,
10
+ especially for preview mode, and validate the fix against the problem report.
11
+
12
+ ## Working Hypothesis
13
+
14
+ The bug exists because preview uses `child_process.exec(...)` in a non-
15
+ interactive `/bin/sh` environment while interactive open uses the integrated
16
+ terminal. The fix should remove that mismatch and stop relying on shell aliases.
17
+
18
+ ## Fix Strategy
19
+
20
+ 1. Introduce explicit command resolution.
21
+
22
+ - Read `pcat.command` as a user-provided command string.
23
+ - Validate it before execution.
24
+ - If it is the default `pcat`, resolve whether a real executable exists.
25
+ - If not resolvable, show a clear error telling the user to set
26
+ `pcat.command` to something explicit such as:
27
+ - `uv run pcat`
28
+ - `uvx --from /home/anhvth8/projects/speedy_utils pcat`
29
+ - an absolute executable path
30
+
31
+ 2. Unify execution semantics.
32
+
33
+ - Ensure interactive open and plain preview use the same resolved command
34
+ model.
35
+ - Avoid depending on shell aliases, shell functions, or interactive rc files.
36
+ - Prefer spawning a command with explicit args over concatenating a shell
37
+ command string when practical.
38
+
39
+ 3. Improve failure reporting.
40
+
41
+ - Detect missing command resolution before invoking preview.
42
+ - Report the exact setting key to change: `pcat.command`.
43
+ - Include one working example command in the error.
44
+
45
+ 4. Keep the `.jsonl` custom editor behavior intact.
46
+
47
+ - Do not remove the current default custom-editor association.
48
+ - Do not regress `Open As Text` or integrated-terminal launch behavior.
49
+
50
+ ## Implementation Notes
51
+
52
+ - Replace shell-string execution for preview with a spawn-style path where the
53
+ command and args are separated.
54
+ - If `pcat.command` remains a free-form string, parse it once and reuse the
55
+ parsed command for both preview and integrated terminal launch.
56
+ - Consider adding a helper that returns a normalized `{ command, args }`
57
+ structure plus a user-facing diagnostic on failure.
58
+
59
+ ## Test Plan
60
+
61
+ ### Reproduction Test Against The Problem Report
62
+
63
+ 1. Install the fixed extension build.
64
+ 2. Configure no alias-dependent workaround in the extension itself.
65
+ 3. Use the same environment described in the problem report where `pcat` is
66
+ available only through interactive shell setup.
67
+ 4. Attempt preview.
68
+ 5. Verify one of these outcomes:
69
+ - preview succeeds with an explicit configured command, or
70
+ - the extension gives a clear configuration error instead of `/bin/sh: ... pcat: not found`.
71
+
72
+ ### Manual Behavior Tests
73
+
74
+ 1. Open a `.jsonl` file.
75
+ 2. Confirm the PCAT custom editor still opens by default.
76
+ 3. Confirm automatic terminal launch still works when enabled.
77
+ 4. Run `PCAT: Preview Plain Row`.
78
+ 5. Confirm the preview opens JSON content in a text editor tab.
79
+ 6. Use `PCAT: Reopen As Text Editor` and confirm raw text opens normally.
80
+
81
+ ### Negative Tests
82
+
83
+ 1. Set `pcat.command` to an invalid executable name.
84
+ 2. Run preview.
85
+ 3. Verify the error message references `pcat.command` and suggests a concrete
86
+ valid command.
87
+
88
+ ### Regression Tests
89
+
90
+ 1. Verify row index prompting still works for preview.
91
+ 2. Verify HF dataset split prompting still works where applicable.
92
+ 3. Verify the package still builds:
93
+ - `npm run compile`
94
+ - `npm run package`
95
+
96
+ ## Definition of Done
97
+
98
+ - The failure from the problem report is either fixed or converted into a clear,
99
+ actionable configuration error.
100
+ - Preview no longer depends on interactive shell aliases.
101
+ - Interactive open and preview follow the same command-resolution policy.
102
+ - The updated extension compiles, packages, and passes the manual checks above.
@@ -0,0 +1 @@
1
+ /home/anhvth8/projects/speedy_utils/.github/skills/speedy-utils-core
@@ -0,0 +1,92 @@
1
+ ---
2
+ name: "speedy-utils-core"
3
+ description: "Use when a simple for loop should be sped up with speedy_utils multi_thread or multi_process, or when the native OpenAI client should be wrapped with llm_utils.LLM or Qwen3LLM for a cleaner API. Focus only on these repo-specific surfaces."
4
+ ---
5
+
6
+ # Speedy Utils Core Skill
7
+
8
+ Use this skill only for changes involving:
9
+
10
+ - `speedy_utils.multi_worker.thread.multi_thread`
11
+ - `speedy_utils.multi_worker._multi_process.multi_process`
12
+ - `llm_utils.lm.llm.LLM`
13
+ - `llm_utils.lm.llm_qwen3.Qwen3LLM`
14
+
15
+ Reach for this skill in two common cases:
16
+
17
+ - a simple `for` loop should run faster with `multi_thread(...)` or `multi_process(...)`
18
+ - raw OpenAI client usage should be replaced with `LLM(...)` or `Qwen3LLM(...)` to make call sites cleaner and more consistent
19
+
20
+ Do not use this skill for caching, vision, dataset tooling, Ray, or generic repo cleanup outside those surfaces.
21
+
22
+ ## Working rules
23
+
24
+ - Prefer public APIs and current behavior over historical helper patterns.
25
+ - Keep changes small, direct, and easy to read.
26
+ - Follow Red -> Green -> Refactor for bug fixes.
27
+ - Add or update focused regression tests for behavior changes.
28
+ - Keep imports lazy when touching LLM or Qwen3 code paths.
29
+ - Do not introduce heavy top-level imports in package `__init__.py` files.
30
+
31
+ ## Repository-specific guidance
32
+
33
+ ### `multi_thread`
34
+
35
+ - Primary file: `src/speedy_utils/multi_worker/thread.py`
36
+ - Use `multi_thread` for managed thread-pool execution over an input iterable.
37
+ - Preserve support for batching, ordered results, progress reporting, timeouts, and error handling.
38
+ - `error_handler` is the active control surface. Treat `stop_on_error` as compatibility behavior only.
39
+ - `n_proc > 1` is a fan-out path layered on top of `multi_thread`; avoid duplicating process orchestration logic elsewhere.
40
+
41
+ ### `multi_process`
42
+
43
+ - Primary file: `src/speedy_utils/multi_worker/_multi_process.py`
44
+ - Public API returns a `list[Any]`.
45
+ - Respect the current normalization behavior around `num_procs`; do not assume auto-scaling unless the implementation explicitly does it.
46
+ - Keep fallback behavior across sequential, thread, and multiprocess execution paths coherent.
47
+ - Error handling and progress behavior should stay aligned with the thread utilities where practical.
48
+
49
+ ### `LLM`
50
+
51
+ - Primary file: `src/llm_utils/lm/llm.py`
52
+ - `LLM()` defaults to the chat path.
53
+ - `LLM.generate()` expects a string prompt and supports only `n=1`.
54
+ - `LLM.pydantic_parse()` is the structured-output path.
55
+ - `LLM(..., return_dict=True)` behavior must stay compatible with the normalized dict contract used in this repo.
56
+ - Avoid constructor regressions: legacy constructor keys are intentionally rejected.
57
+
58
+ ### `Qwen3LLM`
59
+
60
+ - Primary file: `src/llm_utils/lm/llm_qwen3.py`
61
+ - `Qwen3LLM.chat_completion()` returns an OpenAI-style chat message object.
62
+ - `complete_until()` returns continuation state, not a chat message.
63
+ - `complete_reasoning()` and `complete_content()` are staged helpers built on prefix completion.
64
+ - Keep tokenizer loading lazy and cached.
65
+ - Preserve reasoning/content split behavior and the assistant-prefix normalization flow.
66
+
67
+ ## Clean-code bar
68
+
69
+ - Prefer one obvious implementation path.
70
+ - Remove dead branches only when you can prove they are obsolete.
71
+ - Keep naming aligned with existing public APIs.
72
+ - Add short comments only where the control flow is genuinely non-obvious.
73
+ - Avoid broad refactors unless they directly reduce risk in the touched logic.
74
+
75
+ ## Validation
76
+
77
+ Run the smallest relevant checks after changes:
78
+
79
+ - `./tools/uv_test.sh <targeted_test>`
80
+ - `uv run python tools/check_syntax.py`
81
+ - `uv run ruff check .`
82
+
83
+ If import-time-sensitive files are touched, also run:
84
+
85
+ - `uv run python scripts/debug_import_time.py speedy_utils llm_utils vision_utils --max-total-sec 0.4 --top 12 --min-sec 0.01 --no-stdlib`
86
+
87
+ ## Examples of when to use this skill
88
+
89
+ - Fix a regression in `multi_thread` batching or error handling.
90
+ - Adjust `multi_process` backend behavior without changing unrelated utilities.
91
+ - Update `LLM` request/response behavior while preserving current public contracts.
92
+ - Modify `Qwen3LLM` staged reasoning/content generation without breaking lazy tokenizer loading.
@@ -125,5 +125,16 @@ dmypy.json
125
125
  edu_results.json
126
126
  .playwright-mcp
127
127
  .DS_Store
128
+ .AppleDouble
129
+ .LSOverride
130
+ .Trash-*/
131
+ Thumbs.db
132
+ Desktop.ini
133
+ .idea/
134
+ *.swp
135
+ *.swo
136
+ *~
137
+ *.tmp
138
+ *.temp
128
139
  .chainlit
129
140
  chainlit.md
@@ -6,7 +6,7 @@ This file provides guidance for working in this repository.
6
6
 
7
7
  ```bash
8
8
  # Install dependencies
9
- uv sync
9
+ uv sync --all-extras
10
10
 
11
11
  # Run tests
12
12
  ./tools/uv_test.sh -n 32
@@ -91,6 +91,13 @@ they are expensive enough to matter for import time:
91
91
  - `llm_utils.__init__` exports selected public classes and helpers directly.
92
92
  - `vision_utils` keeps plotting and image backends lazy inside function bodies.
93
93
 
94
+ The 0.400s budget is enforced by `.githooks/pre-commit` and measured with
95
+ `scripts/debug_import_time.py` (command above); heavy third-party imports stay
96
+ inside functions. `speedy_utils.parallel_llm_job` deliberately imports
97
+ `llm_utils` inside its methods because `speedy_utils.__init__` imports that
98
+ module: hoisting the import would pull the LLM stack into every
99
+ `import speedy_utils`.
100
+
94
101
  Do not add new top-level imports for heavy third-party libraries in public
95
102
  package `__init__.py` files unless you have rechecked import-time impact.
96
103
 
@@ -155,8 +162,9 @@ The wheel currently ships four packages from `src/`:
155
162
  - `LLM.pydantic_parse()` is the structured-output API.
156
163
  - `LLM(..., return_dict=True)` returns a normalized dict with `completion`, `message`, `messages`, and `parsed`.
157
164
  - `LLMSignature` defaults structured outputs to the signature's output model.
158
- - `Qwen3LLM.chat_completion()` returns an OpenAI-style `ChatCompletionMessage` with optional dynamic attrs such as `reasoning_content`, `usage`, and `call_count`.
165
+ - `Qwen3LLM.chat_completion()` returns an OpenAI-style `ChatCompletionMessage` with optional dynamic attrs such as `reasoning`, `usage`, and `call_count`.
159
166
  - `Qwen3LLM.complete_until()` returns a continuation-state object, not a `ChatCompletionMessage`.
167
+ - When adding model-specific `LLM` subclasses, keep them as thin shims unless behavior needs to change (no extra method overrides by default).
160
168
 
161
169
  ### `vision_utils`
162
170
 
@@ -171,9 +179,10 @@ Registered console scripts in `pyproject.toml`:
171
179
 
172
180
  - `mpython`
173
181
  - `kill-mpython`
174
- - `sp_chat`
182
+ - `sp_chat` (needs the `chat` extra)
175
183
  - `spu-prefetch-large-model`
176
184
  - `viz_chat`
185
+ - `pcat` (also `pcat-jsonl`, `pcat-hf-dataset`)
177
186
  - `openapi_client_codegen`
178
187
 
179
188
  ## Code Style
@@ -201,7 +210,7 @@ Current notable suppressions:
201
210
  | Rule | Why suppressed |
202
211
  |------|----------------|
203
212
  | `reportMissingImports` | Optional GPU and backend dependencies are not always installed |
204
- | `reportAttributeAccessIssue` | OpenAI response models and runtime message objects gain dynamic attrs such as `usage`, `reasoning_content`, and `call_count` |
213
+ | `reportAttributeAccessIssue` | OpenAI response models and runtime message objects gain dynamic attrs such as `usage`, `reasoning`, and `call_count` |
205
214
  | `reportUnsupportedDunderAll` | Some modules rely on broad export patterns that are noisy for pyright |
206
215
 
207
216
  ### Common annotation patterns in this repo
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: speedy-utils
3
- Version: 2.0.7
3
+ Version: 3.0.0
4
4
  Summary: Fast and easy-to-use package for data science
5
5
  Project-URL: Homepage, https://github.com/anhvth/speedy
6
6
  Project-URL: Repository, https://github.com/anhvth/speedy
@@ -19,22 +19,26 @@ Classifier: Programming Language :: Python :: 3.13
19
19
  Classifier: Programming Language :: Python :: 3.14
20
20
  Requires-Python: >=3.9
21
21
  Requires-Dist: cachetools
22
- Requires-Dist: chainlit>=2.0
23
- Requires-Dist: datasets
24
22
  Requires-Dist: dill
25
- Requires-Dist: fastcore
23
+ Requires-Dist: json-repair>=0.44.1
26
24
  Requires-Dist: loguru
27
- Requires-Dist: matplotlib
28
25
  Requires-Dist: numpy
29
26
  Requires-Dist: openai
30
- Requires-Dist: pandas
27
+ Requires-Dist: psutil
31
28
  Requires-Dist: pydantic
32
29
  Requires-Dist: rich>=14.3.1
33
30
  Requires-Dist: tabulate
34
31
  Requires-Dist: tqdm
35
- Requires-Dist: xxhash
32
+ Provides-Extra: chat
33
+ Requires-Dist: chainlit>=2.0; extra == 'chat'
34
+ Provides-Extra: datasets
35
+ Requires-Dist: datasets; extra == 'datasets'
36
+ Provides-Extra: pandas
37
+ Requires-Dist: pandas; extra == 'pandas'
38
+ Provides-Extra: plot
39
+ Requires-Dist: matplotlib; extra == 'plot'
36
40
  Provides-Extra: transformers
37
- Requires-Dist: transformers>=4.57.6; extra == 'transformers'
41
+ Requires-Dist: transformers>=4.57.3; extra == 'transformers'
38
42
  Description-Content-Type: text/markdown
39
43
 
40
44
  # Speedy Utils
@@ -67,6 +71,21 @@ pip install speedy-utils
67
71
  uv pip install speedy-utils
68
72
  ```
69
73
 
74
+ The core install covers caching, file I/O, parallel helpers, LLM wrappers, and
75
+ the CLIs. Optional features pull their own dependencies, and only the ones you
76
+ ask for:
77
+
78
+ | Extra | Install | Needed for |
79
+ |-------|---------|------------|
80
+ | `plot` | `pip install 'speedy-utils[plot]'` | `plot_images_notebook` (matplotlib) |
81
+ | `pandas` | `pip install 'speedy-utils[pandas]'` | CSV loading via `load_by_ext`, DataFrame inputs to `multi_thread` |
82
+ | `datasets` | `pip install 'speedy-utils[datasets]'` | HuggingFace dataset directories in `viz_chat`, `pcat`, and dataset sharding |
83
+ | `transformers` | `pip install 'speedy-utils[transformers]'` | `Qwen3LLM` tokenizer rendering, `viz_chat`, tokenized/SDD `pcat` views |
84
+ | `chat` | `pip install 'speedy-utils[chat]'` | `sp_chat` (Chainlit UI) |
85
+
86
+ The authoritative dependency list lives in [`pyproject.toml`](pyproject.toml)
87
+ under `[project.optional-dependencies]`.
88
+
70
89
  Install from source:
71
90
 
72
91
  ```bash
@@ -80,7 +99,19 @@ Local development:
80
99
  ```bash
81
100
  git clone https://github.com/anhvth/speedy_utils
82
101
  cd speedy_utils
83
- uv sync
102
+ uv sync --all-extras # optional extras are needed by parts of the test suite
103
+ ```
104
+
105
+ Install the repo's AI skill definitions locally:
106
+
107
+ ```bash
108
+ ./setup-skill.sh
109
+ ```
110
+
111
+ Or bootstrap them directly from GitHub:
112
+
113
+ ```bash
114
+ curl -fsSL https://raw.githubusercontent.com/anhvth/speedy_utils/master/setup-speedy-utils.sh | bash
84
115
  ```
85
116
 
86
117
  Upgrading from older split packages:
@@ -241,6 +272,9 @@ data = load_by_ext("data.csv")
241
272
  data = load_by_ext(["part1.jsonl", "part2.jsonl"])
242
273
  ```
243
274
 
275
+ CSV loading uses pandas, so it needs the `pandas` extra; JSON, JSONL, and
276
+ pickle paths are core.
277
+
244
278
  For streaming or compressed JSONL, use `fast_load_jsonl` directly:
245
279
 
246
280
  ```python
@@ -295,16 +329,23 @@ The installed console scripts are:
295
329
  | `sp_chat` | Launch a Chainlit chat UI for an OpenAI-compatible backend |
296
330
  | `spu-prefetch-large-model` | Read large model files into the OS page cache |
297
331
  | `viz_chat` | Inspect chat datasets from JSON, JSONL, folders, or HF saves |
332
+ | `pcat` | Interactive JSON/JSONL/HF-dataset viewer (TUI) |
298
333
  | `openapi_client_codegen` | Generate a sync client from an OpenAPI JSON spec |
299
334
 
300
335
  Examples:
301
336
 
302
337
  ```bash
303
338
  mpython -t 8 script.py
339
+
340
+ # Infer 24 workers from three nodes and eight GPUs per node. Each worker gets
341
+ # MP_ID/MP_TOTAL plus its node-local identity and CUDA_VISIBLE_DEVICES.
342
+ mpython --nodes h2-14,h2-15,h2-17 --gpus 0-7 --python /abs/venv/bin/python -- script.py
304
343
  kill-mpython
305
344
 
306
345
  sp_chat client=8000
307
346
  sp_chat client=http://10.0.0.3:8000/v1 port=5010 model=Qwen/Qwen2.5-7B-Instruct
347
+ # sp_chat needs the chat extra:
348
+ pip install 'speedy-utils[chat]'
308
349
 
309
350
  spu-prefetch-large-model /path/to/model -j 8
310
351
 
@@ -360,6 +401,66 @@ message = llm.chat_completion(
360
401
  )
361
402
  ```
362
403
 
404
+ ### Native audio with `AudioLLM`
405
+
406
+ `AudioLLM` subclasses `LLM` and sends native audio to an audio-capable chat
407
+ endpoint. Message lists preserve system prompts and conversation history:
408
+
409
+ ```python
410
+ from pathlib import Path
411
+ from llm_utils import AudioLLM
412
+
413
+ teacher = AudioLLM(client="http://localhost:8000/v1", model="your-audio-model")
414
+ message = teacher([
415
+ {"role": "system", "content": "Listen carefully to the conversation."},
416
+ {"role": "user", "content": [
417
+ {"type": "input_audio", "input_audio": {"path": "/absolute/input.wav"}},
418
+ {"type": "text", "text": "What do you hear?"},
419
+ ]},
420
+ ])
421
+ print(message.content)
422
+
423
+ # Convenience inputs: a client-local path, encoded file bytes, or a waveform.
424
+ message = teacher("What do you hear?", audio=Path("/absolute/input.wav"))
425
+ message = teacher("What do you hear?", audio=wav_bytes, audio_format="wav")
426
+ message = teacher("What do you hear?", audio=waveform, sample_rate=16000)
427
+ ```
428
+
429
+ Paths are read on the client and expand `~` and environment variables. The
430
+ server receives encoded audio, never the local path. Encoded bytes may also be
431
+ supplied in `input_audio.data` with `format`; WAV bytes are detected automatically.
432
+ Other byte formats require `audio_format` (or message `format`). Raw PCM bytes
433
+ are unsupported. Waveforms must be nonempty NumPy float arrays in [-1, 1] or
434
+ int16 arrays shaped `(frames,)` or `(frames, channels)`; they are encoded as
435
+ 16-bit WAV without resampling. File formats accepted locally are WAV, MP3,
436
+ FLAC, OGG, M4A, and AAC; endpoint support may be narrower. Existing encoded or
437
+ URL payloads pass through, and caller messages are never mutated.
438
+
439
+ For DashScope, supply its explicit client credentials:
440
+
441
+ ```python
442
+ import os
443
+ from openai import OpenAI
444
+
445
+ teacher = AudioLLM(
446
+ client=OpenAI(base_url=os.environ["DASHSCOPE_BASE_URL"],
447
+ api_key=os.environ["DASHSCOPE_API_KEY"]),
448
+ model="qwen3.8-omni-flash", temperature=0.5, cache=False,
449
+ )
450
+ message = teacher("What do you hear?", audio="input.wav")
451
+ print(message.content, teacher.last_usage)
452
+ ```
453
+
454
+ DashScope hostnames are detected automatically; private gateways can set
455
+ `audio_provider="dashscope"`. DashScope uses audio Data URIs and streaming
456
+ internally, returning the same `ChatCompletionMessage` as a regular `LLM` call.
457
+ `return_dict=True` retains the aggregated completion and usage. Its streaming
458
+ transport disables caching and does not support `response_model`; request JSON
459
+ text and validate it locally. Explicit `stream=True` returns normal SDK chunks.
460
+ Other endpoints inherit `LLM` caching and structured parsing where supported.
461
+ `generate()` remains the inherited text-only legacy completions API; audio is
462
+ supported through chat calls, never by a transcription proxy.
463
+
363
464
  ### Structured output with Pydantic
364
465
 
365
466
  ```python
@@ -446,8 +547,20 @@ llm = LLM(
446
547
  llm = LLM(client=8000, model="llama-3")
447
548
  llm = LLM(client="http://localhost:8000/v1", model="llama-3")
448
549
  llm = LLM(client=[8000, 8001, 8002], model="llama-3")
550
+ llm = LLM(client="h1-31:8000", model="llama-3")
551
+ llm = LLM(client=["h1-31:8000", "h2-14:8100"], model="llama-3")
449
552
  ```
450
553
 
554
+ An integer means a local port. An HTTP(S) URL is used directly. A bare
555
+ `HOST:PORT` string is treated as an SSH host or alias plus its remote service
556
+ port; Speedy Utils creates a loopback-only SSH forward and reuses it for the
557
+ life of the Python process. Lists may mix all three forms.
558
+
559
+ For large checkpointed jobs, subclass `ParallelLLMJob` and implement only the
560
+ per-item domain logic. It provides persistent process/thread workers, lazy LLM
561
+ pools, exact-size JSONL output, and atomic resume state; see
562
+ [`docs/PARALLEL_LLM_JOB.md`](docs/PARALLEL_LLM_JOB.md).
563
+
451
564
  ### Caching and history inspection
452
565
 
453
566
  ```python
@@ -492,14 +605,14 @@ Standard chat path:
492
605
  from llm_utils import Qwen3LLM
493
606
 
494
607
  llm = Qwen3LLM(client=8000)
495
- message = llm.chat_completion(
608
+ message = llm(
496
609
  [{"role": "user", "content": "Solve x^2 + 2x + 1 = 0"}],
497
610
  thinking_max_tokens=32,
498
611
  content_max_tokens=128,
499
612
  )
500
613
 
501
614
  print(message.content)
502
- print(getattr(message, "reasoning_content", None))
615
+ print(getattr(message, "reasoning", None))
503
616
  print(getattr(message, "call_count", None))
504
617
  ```
505
618
 
@@ -548,16 +661,45 @@ Supported inputs:
548
661
  - Folders of JSON files
549
662
  - tokenized datasets when `--tokenizer` is provided
550
663
 
664
+ `viz_chat` renders chat templates with a HuggingFace tokenizer, so it needs the
665
+ `transformers` extra; HuggingFace dataset directories also need the `datasets`
666
+ extra. See [Installation](#installation).
667
+
551
668
  Examples:
552
669
 
553
670
  ```bash
554
671
  viz_chat data/my_dataset
555
672
  viz_chat data/conversations.jsonl
556
- viz_chat data/sharegpt.jsonl --format sharegpt
673
+ viz_chat data/sharegpt.jsonl --count 5
557
674
  viz_chat data/tokenized_dataset/ --tokenizer Qwen/Qwen3-8B
558
675
  viz_chat data/with_tools.jsonl --show-tools
559
676
  ```
560
677
 
678
+ ### `pcat` — Interactive JSON/JSONL/HF-dataset viewer
679
+
680
+ Install once:
681
+
682
+ ```bash
683
+ uv tool install git+https://github.com/anhvth/speedy_utils
684
+ # add HuggingFace dataset / tokenized-row support:
685
+ uv tool install 'speedy-utils[datasets,transformers]'
686
+ ```
687
+
688
+ Then use the installed executable:
689
+
690
+ ```bash
691
+ pcat data/file.jsonl
692
+ pcat data/tokenized-sdd --serve --no-browser
693
+ pcat data/dataset-dict --split validation --serve --no-browser
694
+ ```
695
+
696
+ Hugging Face `Dataset` and `DatasetDict` directories saved with
697
+ `save_to_disk()` are loaded with `datasets.load_from_disk()`. Arrow files stay
698
+ memory-mapped and rows are read by index; `pcat` does not materialize the full
699
+ dataset. `DatasetDict` defaults to its `train` split and accepts `--split` for
700
+ another split. Tokenized SDD rows with `student_ids`, `teacher_ids`, and
701
+ `response_ids` use the existing tokenizer-aware SDD view in `--serve` mode.
702
+
561
703
  ## Vision Utils
562
704
 
563
705
  `vision_utils` exports:
@@ -589,7 +731,8 @@ first_image = images[paths[0]]
589
731
  ### Notebook plotting
590
732
 
591
733
  `plot_images_notebook()` accepts NumPy arrays, PyTorch tensors, lists, or tuples
592
- of image arrays. If you loaded images with `read_images*`, pass the values.
734
+ of image arrays. If you loaded images with `read_images*`, pass the values. It
735
+ needs the `plot` extra (matplotlib).
593
736
 
594
737
  ```python
595
738
  from vision_utils import plot_images_notebook, read_images