speedy-utils 2.0.2__tar.gz → 2.0.5__tar.gz

{speedy_utils-2.0.2 → speedy_utils-2.0.5}/.githooks/pre-commit

@@ -1,13 +1,5 @@
 #!/usr/bin/env python3
-"""
-Pre-commit hook to ensure import time is under 0.4 seconds.
-
-This enforces the project's performance requirement that speedy_utils
-must import quickly (< 0.4s). This is critical for user experience.
-
-Strategy: Use lazy imports for heavy modules (torch, ray, matplotlib, pandas)
-inside functions that need them, not at module level.
-"""
+"""Pre-commit hook to enforce import-time budgets with actionable output."""
 
 import os
 import subprocess
@@ -73,57 +65,39 @@ def _build_env() -> dict[str, str]:
     return env
 
 
-def check_import_time(module: str) -> tuple[bool, float, str]:
-    """Check import time for a module. Returns (passed, time_seconds)."""
-    code = f"import time; start=time.perf_counter(); import {module}; print(time.perf_counter()-start)"
+def _helper_script() -> Path:
+    return _REPO_ROOT / "scripts" / "debug_import_time.py"
+
+
+def main() -> int:
+    """Run import-time checks through the shared helper script."""
+    print("Checking import times... (max: {:.1f}s)".format(MAX_IMPORT_TIME))
+
+    helper = _helper_script()
     result = subprocess.run(
-        [_PYTHON, "-c", code],
-        capture_output=True,
-        text=True,
+        [
+            _PYTHON,
+            str(helper),
+            "--max-total-sec",
+            str(MAX_IMPORT_TIME),
+            "--min-sec",
+            "0.01",
+            "--top",
+            "12",
+            "--no-stdlib",
+            "--quiet-success",
+            *MODULES,
+        ],
         env=_build_env(),
         cwd=str(_REPO_ROOT),
     )
-    if result.returncode != 0:
-        err = (result.stderr or result.stdout or "").strip()
-        return False, -1, err
-    try:
-        import_time = float(result.stdout.strip())
-        return import_time <= MAX_IMPORT_TIME, import_time, ""
-    except ValueError:
-        err = (result.stderr or result.stdout or "").strip()
-        return False, -1, err
 
+    if result.returncode != 0:
+        print("\nImport time check failed.")
+        print("Rerun the helper above after moving heavy imports into function scope")
+        print("or a lazy __getattr__ export to pinpoint the slow path.")
 
-def main() -> int:
-    """Run import time checks."""
-    failed = False
-
-    print("Checking import times... (max: {:.1f}s)".format(MAX_IMPORT_TIME))
-
-    for module in MODULES:
-        passed, import_time, err = check_import_time(module)
-
-        if import_time < 0:
-            print(f"  {module}: FAILED - import error")
-            if err:
-                last_line = err.splitlines()[-1]
-                print(f"    ↳ {last_line}")
-            failed = True
-        elif passed:
-            print(f"  {module}: {import_time:.3f}s")
-        else:
-            print(f"  {module}: FAILED - {import_time:.3f}s exceeds {MAX_IMPORT_TIME:.1f}s")
-            failed = True
-
-    if failed:
-        print("\nImport time check failed! To fix:")
-        print("  1. Use lazy imports for heavy modules inside functions")
-        print("  2. Move heavy imports to function scope, not module level")
-        print("  3. Use the _LazyModule pattern from __imports.py")
-        print("\nHeavy modules to lazy-load: torch, ray, matplotlib, pandas")
-        return 1
-
-    return 0
+    return result.returncode
 
 
 if __name__ == "__main__":

speedy_utils-2.0.5/.github/skills/make-vscode-happy/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: 'make-vscode-happy'
+description: 'Reduce VS Code Python red squiggles to zero in this repository. Use when Pylance or pyright reports errors, when tools/check_syntax.py fails, or when a change should leave VS Code diagnostics clean.'
+argument-hint: 'Optional file path, module name, or failing area to fix'
+---
+
+# Make VS Code Happy
+
+Use this skill when the goal is to make VS Code and Pylance happy in this
+repository by driving Python diagnostics to zero with the repo's existing
+checker: `tools/check_syntax.py`.
+
+## When to Use
+
+Use this skill when you need to:
+- Fix Python red squiggles in VS Code.
+- Reconcile Pylance diagnostics with command-line validation.
+- Clean up pyright issues before committing.
+- Verify that a targeted change did not leave new diagnostics behind.
+
+## Primary Checker
+
+The authoritative checker for this repo is:
+
+```bash
+uv run python tools/check_syntax.py
+```
+
+Useful variants:
+
+```bash
+uv run python tools/check_syntax.py --file src/llm_utils/lm/llm_qwen3.py
+uv run python tools/check_syntax.py --include tests
+uv run python tools/check_syntax.py --json
+```
+
+This script mirrors the diagnostics VS Code Pylance shows for the repository's
+`pyrightconfig.json`.
+
+## Procedure
+
+1. Pick scope first.
+   - If the request names a file, start with `--file` for that file.
+   - If the issue sounds cross-cutting or unclear, run the full check first.
+2. Read diagnostics and group them by root cause instead of fixing them one by
+   one in isolation.
+3. Fix the real source of the type error.
+   - Prefer correcting annotations, overloads, return types, and control flow.
+   - Use repo-approved ignores only when the code is intentionally dynamic.
+4. Re-run the smallest relevant check after each edit.
+5. Before concluding, run the broader validation needed for the scope.
+   - If you touched one file, re-run that file and then a full check if the
+     change affects shared APIs.
+   - If you changed common utilities, package exports, or typing helpers, run
+     the full check.
+6. If the fix changes imports in public packages, protect the import-time
+   budget as well.
+
+## Decision Points
+
+- Single-file symptom vs shared typing pattern:
+  Start narrow for local regressions; go broad if the same diagnostic appears in
+  multiple files or stems from a shared helper.
+- True bug vs accepted dynamic pattern:
+  Prefer a real type fix first. Only use a targeted ignore when the repository
+  already treats that pattern as intentionally dynamic.
+- Typing fix vs performance regression:
+  Do not fix types by introducing heavy top-level imports in `__init__.py` or
+  other import-sensitive modules.
+
+## Completion Criteria
+
+- `tools/check_syntax.py` reports zero relevant errors for the changed scope.
+- Touched files do not introduce new warnings unless the user accepted them.
+- The fix matches repository typing conventions.
+- No eager heavy imports were added just to satisfy typing.
+
+## References
+
+- [Diagnostic playbook](./references/diagnostic-playbook.md)

speedy_utils-2.0.5/.github/skills/make-vscode-happy/references/diagnostic-playbook.md

@@ -0,0 +1,94 @@
+# Diagnostic Playbook
+
+This reference supports the `make-vscode-happy` skill for the `speedy_utils`
+repository.
+
+## Repo Rules That Matter
+
+- Use `uv run python tools/check_syntax.py` as the source of truth for Python
+  diagnostics.
+- Fix root causes instead of masking errors with broad ignores.
+- Keep public package import time under `0.4s`.
+- Do not introduce heavy top-level imports such as `torch`, `pandas`,
+  `matplotlib`, or `IPython` in `__init__.py` files.
+
+## Fast Triage
+
+### If the prompt names a specific file
+
+Run:
+
+```bash
+uv run python tools/check_syntax.py --file path/to/file.py
+```
+
+Then fix the reported issue and re-run the same command.
+
+### If the prompt is vague or broad
+
+Run:
+
+```bash
+uv run python tools/check_syntax.py
+```
+
+If the change touches tests or test helpers, consider:
+
+```bash
+uv run python tools/check_syntax.py --include tests
+```
+
+## Common Fix Patterns In This Repo
+
+### Overload ordering
+
+Put the `Awaitable[...]` overload before the generic non-awaitable overload to
+avoid overlapping-overload diagnostics.
+
+### Dynamic Pydantic-style attributes
+
+When the code intentionally sets attributes not declared in the model schema,
+use a narrow ignore such as:
+
+```python
+# type: ignore[attr-defined]
+```
+
+Do not apply it broadly if a better annotation is possible.
+
+### `tqdm` annotations
+
+Use the string literal form in annotations:
+
+```python
+"tqdm"
+```
+
+### Lazy exports
+
+For names loaded through `__getattr__`, follow the existing lazy-export pattern
+instead of forcing eager imports for type convenience.
+
+### `__all__` with heavy lazy names
+
+Do not add heavy lazy names to `__all__`, because star imports will defeat lazy
+loading and hurt import time.
+
+## When a Typing Fix Touches Imports
+
+If you changed imports in a public package, especially `speedy_utils`,
+`llm_utils`, or `vision_utils`, run:
+
+```bash
+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
+```
+
+Use that output to move heavy imports behind lazy boundaries if needed.
+
+## Definition of Done
+
+- Targeted diagnostics are gone.
+- Shared changes were validated with a broader repo check.
+- The fix preserves existing lazy-import and typing conventions.
+- VS Code should agree with command-line output because the checker mirrors
+  Pylance behavior for this repository.

{speedy_utils-2.0.2 → speedy_utils-2.0.5}/.gitignore

@@ -125,4 +125,5 @@ dmypy.json
 edu_results.json
 .playwright-mcp
 .DS_Store
-.chainlit
+.chainlit
+chainlit.md

speedy_utils-2.0.5/CLAUDE.md

@@ -0,0 +1,201 @@
+# CLAUDE.md
+
+This file provides guidance for working in this repository.
+
+## Development Commands
+
+```bash
+# Install dependencies
+uv sync
+
+# Run tests
+./tools/uv_test.sh -n 32
+
+# Run a single test file
+./tools/uv_test.sh tests/test_thread.py
+
+# Run with verbose output
+./tools/uv_test.sh -v
+
+# Check import time for the exported packages
+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
+
+# Lint and format
+uv run ruff check .
+uv run ruff format .
+
+# Pyright / Pylance parity check
+uv run python tools/check_syntax.py
+
+# Bump version (runs tests, then commits and pushes)
+./bumpversion.sh patch  # or minor / major
+
+# Deploy to PyPI (requires PYPI_API_TOKEN)
+./scripts/deploy.sh
+```
+
+## Performance Requirement: Import Time < 0.4s
+
+The repository hook budget is `0.4s` for the exported packages checked by
+`.githooks/pre-commit`:
+
+- `speedy_utils`
+- `llm_utils`
+- `vision_utils`
+
+Use the shared helper when import time regresses:
+
+```bash
+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
+```
+
+Current code structure keeps the budget by avoiding heavy external imports at
+module import time.
+
+### What to keep lazy
+
+These imports are intentionally kept behind helpers or function scope because
+they are expensive enough to matter for import time:
+
+- `torch`
+- `pandas`
+- `matplotlib`
+- `IPython`
+- tokenizer-loading code in `Qwen3LLM`
+
+### How the current code does it
+
+- `speedy_utils.__init__` imports lightweight internal modules directly.
+- heavy external helpers live in `speedy_utils.__imports`.
+- `llm_utils.__init__` exports selected public classes and helpers directly.
+- `vision_utils` keeps plotting and image backends lazy inside function bodies.
+
+Do not add new top-level imports for heavy third-party libraries in public
+package `__init__.py` files unless you have rechecked import-time impact.
+
+### Hook vs test budget
+
+The pre-commit hook is stricter than the regression test:
+
+- `.githooks/pre-commit` enforces `0.4s`
+- `tests/test_import_time.py` currently guards `speedy_utils` at `1.0s`
+
+Treat the hook budget as the real policy.
+
+## Architecture
+
+### Package Structure
+
+The wheel currently ships four packages from `src/`:
+
+- `speedy_utils`: caching, file I/O, formatting, timing, and parallel helpers
+- `llm_utils`: OpenAI-compatible LLM wrappers, memoized clients, chat-format helpers
+- `vision_utils`: image loading, notebook plotting, and mmap-backed image datasets
+- `datasets_utils`: dataset inspection helpers such as `viz_chat`
+
+### Important Modules
+
+- `src/speedy_utils/common/utils_cache.py`
+  - `memoize`, `imemoize`, `identify`
+  - default disk cache root: `~/.cache/speedy_cache`
+- `src/speedy_utils/common/utils_io.py`
+  - `load_jsonl`, `fast_load_jsonl`, `load_json_or_pickle`, `load_by_ext`
+- `src/speedy_utils/multi_worker/thread.py`
+  - `multi_thread`
+- `src/speedy_utils/multi_worker/_multi_process.py`
+  - `multi_process`
+- `src/llm_utils/lm/llm.py`
+  - `LLM.chat_completion`, `LLM.generate`, `LLM.pydantic_parse`, `LLM.inspect_history`
+- `src/llm_utils/lm/llm_signature.py`
+  - `LLMSignature`
+- `src/llm_utils/lm/llm_qwen3.py`
+  - `Qwen3LLM`, `complete_until`, `complete_reasoning`, `complete_content`
+- `src/vision_utils/io_utils.py`
+  - `read_images`, `read_images_cpu`, `read_images_gpu`, `ImageMmap`, `ImageMmapDynamic`
+- `src/vision_utils/plot.py`
+  - `plot_images_notebook`
+- `src/datasets_utils/viz_chat.py`
+  - dataset and conversation inspection CLI
+
+## Public API Notes
+
+### `speedy_utils`
+
+- `memoize` supports sync and async functions.
+- `load_json_or_pickle` is for `.json` and pickle-like files.
+- use `load_jsonl` or `fast_load_jsonl` for JSONL.
+- `multi_process(num_procs=None)` currently normalizes to `1`; it does not auto-pick a process count.
+
+### `llm_utils`
+
+- `LLM()` defaults to the chat path.
+- `LLM.generate()` uses the completions API and returns a `CompletionChoice`-like object.
+- `LLM.generate()` expects a string prompt and only supports `n=1`.
+- `LLM.pydantic_parse()` is the structured-output API.
+- `LLM(..., return_dict=True)` returns a normalized dict with `completion`, `message`, `messages`, and `parsed`.
+- `LLMSignature` defaults structured outputs to the signature's output model.
+- `Qwen3LLM.chat_completion()` returns an OpenAI-style `ChatCompletionMessage` with optional dynamic attrs such as `reasoning_content`, `usage`, and `call_count`.
+- `Qwen3LLM.complete_until()` returns a continuation-state object, not a `ChatCompletionMessage`.
+
+### `vision_utils`
+
+- `read_images*()` returns `dict[path, ndarray | None]`.
+- `plot_images_notebook()` expects arrays/tensors or lists/tuples of arrays.
+- if you loaded images with `read_images*()`, pass `list(images.values())` to the plotter.
+- `ImageMmap` and `ImageMmapDynamic` take image-path sequences and build cache files as needed.
+
+## CLI Tools
+
+Registered console scripts in `pyproject.toml`:
+
+- `mpython`
+- `kill-mpython`
+- `sp_chat`
+- `spu-prefetch-large-model`
+- `viz_chat`
+- `openapi_client_codegen`
+
+## Code Style
+
+- Line length: `88`
+- Quote style: double quotes
+- Ruff is the formatter and linter
+- Avoid unnecessary wrappers and ceremony; see `CODING_STYLE.md`
+- Keep public docs/examples aligned with tests and current implementation, not with historical helper scripts
+
+## Type Checking with Pyright
+
+Use:
+
+```bash
+uv run python tools/check_syntax.py
+```
+
+This mirrors what VS Code Pylance reports for the configured project files.
+
+### pyright config (`pyrightconfig.json`)
+
+Current notable suppressions:
+
+| Rule | Why suppressed |
+|------|----------------|
+| `reportMissingImports` | Optional GPU and backend dependencies are not always installed |
+| `reportAttributeAccessIssue` | OpenAI response models and runtime message objects gain dynamic attrs such as `usage`, `reasoning_content`, and `call_count` |
+| `reportUnsupportedDunderAll` | Some modules rely on broad export patterns that are noisy for pyright |
+
+### Common annotation patterns in this repo
+
+- use string literal `"tqdm"` when needed in type hints
+- put `Awaitable[R]` overloads before generic `R` overloads
+- use `# type: ignore[attr-defined]` for dynamic OpenAI message attrs where necessary
+- keep dataset `__getitem__` overrides narrow and explicit
+
+## Version Management
+
+Version lives in `pyproject.toml`. `./bumpversion.sh` currently:
+
+1. runs tests
+2. bumps the package version
+3. commits and pushes